diff options
Diffstat (limited to 'DOC_CHANGES.md')
| -rw-r--r-- | DOC_CHANGES.md | 97 |
1 files changed, 97 insertions, 0 deletions
diff --git a/DOC_CHANGES.md b/DOC_CHANGES.md index 8b70f40c5a..8b0e5da24a 100644 --- a/DOC_CHANGES.md +++ b/DOC_CHANGES.md @@ -145,3 +145,100 @@ $ knife search node "platform:ubuntu" --filter-result "c_version:languages.c.gcc $ ``` + +### `knife ssl check` will verify X509 properties of your trusted certificates + +When you run `knife ssl check URL (options)` knife will verify if the certificate files, with extensions `*.crt` and `*.pem` +in your `:trusted_certs_dir` have valid X509 certificate properties. Knife will generate warnings for certificates that +do not meet X509 standards. OpenSSL **will not** use these certificates in verifying SSL connections. + +#### Troubleshooting + +For each certificate that does not meet X509 specifications, a message will be displayed indicating why the certificate +failed to meet these specifications. You may see output similar to + +``` +There are invalid certificates in your trusted_certs_dir. +OpenSSL will not use the following certificates when verifying SSL connections: + +/path/to/your/invalid/certificate.crt: a message to help you debug +``` + +The documentation for resolving common issues with certificates is a work in progress. A few suggestions +are outlined in the following sections. If you would like to help expand this documentation, please +submit a pull request to [chef-docs](https://github.com/opscode/chef-docs) with your contribution. + +##### Fetch the certificate again + +If the certificate was generated by your chef server, you may want to try downloading the certificate again. +By default, the certificate is stored in the following location on the host where your chef-server runs: +`/var/opt/chef-server/nginx/ca/SERVER_HOSTNAME.crt`. Copy that file into your `:trusted_certs_dir` using SSH, +SCP, or some other secure method and run `knife ssl check URL (options)` again. + +##### Generate a new certificate + +You will need a 1024 bit RSA key. You can generate one using the `openssl` cli tool: +``` +openssl genrsa -des3 -out privkey.key 1024 +``` +You will be prompted for a passphrase for your new private key. + +Once you have private key, you can generate a Certificate Signing Request (CSR), which can either be sent to a +Certificate Authority (CA) for verification, or be self-signed. You can generate a CSR with +``` +openssl req -new -key privkey.key -out mycsr.csr +``` +When you create a CSR, you will be prompted for +information which is used to fill out the X509 attributes of the certificate. You will be asked to provide +a two-letter [Country Name](https://www.digicert.com/ssl-certificate-country-codes.htm), and a Common Name +which should be the FQDN of your server to be protected by SSL. + +(Optional) You may want to remove the passphrase from the key, otherwise you will be prompted to +type in the passphrase after system reboot or crash. It is recommended that you make this key +readable only by root once you remove the passphrase. +``` +cp privkey.key privkey.key.org +openssl rsa -in privkey.key.org -out privkey.key +``` + +(Optional) You can generate a self-signed certificate if you don't plan on having your certificate +signed by a CA, or as an interim certificate for testing while you wait for the CA to sign your +certificate. You can create a temporary certificate good for 365 days with the command +``` +openssl x509 -req -days 365 -in mycsr.csr -signkey privkey.key -out mycert.crt +``` + +##### Generate a certificate with SubjectAltName + +You will need an openssl configuration file which enables subject alternative names. This is usually +saved in your system as `openssl.cnf`, but you can create and use an alternative configuration file +if you find that easier. If you use an alternative configuration file, you will have to append the +command line option `-config CONFIG_FILE` to the commands shown below. + +The `[req]` section of your configuration file tells openssl how to handle certificate requests (CSRs). There +should be a line beginning with `req_extensions`. This section of your configuration file should look like +``` +[req] +distinguished_name = req_distinguished_name +req_extensions = v3_req +``` +`v3_req` tells openssl to include that section in CSRs. You should modify your `v3_req` section to include +`subjectAltName`. Your configuration file may look something like +``` +[ v3_req ] +# Extensions to add to a certificate request +basicConstraints = CA:FALSE +subjectAltName = @alt_names + +[alt_names] +DNS.1 = kb.example.com +DNS.2 = helpdesk.example.org +DNS.3 = systems.example.net +IP.1 = 192.168.1.1 +IP.2 = 192.168.69.14 +``` +It is important to note that what gets entered here will appear on all CSRs generated from this point on. If you want to change +the SANs you will have to manually edit this file again. + +Now you can follow the steps for generating a new certificate. Don't forget to append the `-config CONFIG_FILE` option +if your configuration file is not the default `openssl.cnf` |