Document verifying X509 certificates, methods on generating certificates

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`