Modernize the SSL documentation for creating certificates

docs/source/gearmand/ssl.rst

@@ -2,35 +2,53 @@
 Using SSL with Gearman
 ======================
 
-If you are not paying a certificate authority to generate a certificate for you, you will first need a certificate authority (CA) for gearmand:
+If you are not paying a certificate authority to generate a certificate for you, you will first need a certificate authority (CA) for gearmand::
 
-   openssl req -config /etc/pki/tls/openssl.cnf -new -x509 -keyout gearmand-ca.key -out gearmand-ca.pem -days 3650 
+   openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:4096 -out gearmand-ca.key
 
-   echo "00" > gearmand.srl
+   openssl req -x509 -new -key gearmand-ca.key -sha256 -days 3650 -subj "/CN=Internal Gearman Root CA" -out gearmand-ca.pem
 
 You then need to place your CA certificate into the directory from which the server will read it.
 
-Generate a server certificate for the server to use:
+Generate a server certificate for the server to use. You will need to create an extension file named "gearmand_server_ext.cnf" in order to support Subject Alternative Names (SAN), which are required by modern TLS clients. It should look something like the following (add and/or replace the hostnames and IP addresses under "[alt_names]" as needed)::
 
-   openssl genrsa -out gearmand.key 1024 
+   authorityKeyIdentifier=keyid,issuer
+   basicConstraints=CA:FALSE
+   keyUsage = digitalSignature, keyEncipherment
+   extendedKeyUsage = serverAuth, clientAuth
+   subjectAltName = @alt_names
 
-   openssl req -key gearmand.key -new -out gearmand.req
+   [alt_names]
+   DNS.1 = gearmand-server.local
+   DNS.2 = localhost
+   IP.1 = 127.0.0.1
+   # Add your internal server IP if clients connect directly via IP
+   # IP.2 = 10.x.x.x
 
-   openssl x509 -req -in gearmand.req -CA gearmand-ca.pem -CAkey gearmand-ca.key -CAserial gearmand.srl -out gearmand.pem 
+Then, generate the key, the request, and the signed certificate (valid for 2 years or 730 days)::
 
-Generate a client certificate for client/workers to use:
+   openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out gearmand.key
 
-  openssl genrsa -out gearman.key 1024 
+   openssl req -new -key gearmand.key -subj "/CN=gearmand-server.local" -out gearmand.req
 
-  openssl req -key gearman.key -new -out gearman.req 
+   openssl x509 -req -in gearmand.req -CA gearmand-ca.pem -CAkey gearmand-ca.key -CAcreateserial -out gearmand.pem -days 730 -sha256 -extfile gearmand_server_ext.cnf
 
-  openssl x509 -req -in gearman.req -CA gearmand-ca.pem -CAkey gearmand-ca.key -CAserial gearmand.srl  -out gearman.pem
+Note that the :option:`-CAcreateserial` argument in that last command will cause a :file:`gearmand-ca.srl` file to be automatically created in the current working directory the first time you execute it.
 
+Finally, generate a certificate for clients and workers to use::
+
+   openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out gearman.key
+
+   openssl req -new -key gearman.key -subj "/CN=gearman-client" -out gearman.req
+
+   openssl x509 -req -in gearman.req -CA gearmand-ca.pem -CAkey gearmand-ca.key -CAcreateserial -out gearman.pem -days 730 -sha256
+
+Specifying Subject Alternative Names (SAN) is not needed for clients/workers since they are not hostname-verified.
 
 Caveats:
 
-  1. Make sure your gearmand was configured with '--enable-ssl'. You will likely need to compile from source.
+  1. Make sure your gearmand was configured with '--enable-ssl'. You will likely need to compile from source as packagers tend to not enable that option.
 
-  2. Unless you want your server and client certificates to expire in 30 days (the default), you should add the arguments '-days X' to the 'open req' commands for generating those certificates, where X is the number of days after which your certificates will expire. It should be less than or equal to the number of days until the CA certificate expires (3650 in the commands above).
+  2. The commands above generate server and client certificates valid for 730 days (2 years). If you want a different lifetime, adjust the '-days' parameters in the commands accordingly. The lifetimes of the server and client certificates should be less than or equal to the number of days until the CA certificate expires (3650 in the commands above).
 
-  3. Make sure you specify different "Common Name" values when generating the certificates for the CA, server, and client. OpenSSL does not like them being the same.
+  3. Make sure you specify different "Common Name" ("/CN=...") values when generating the certificates for the CA, server, and client. OpenSSL does not like them being the same.