how to obtain, deploy and verify an X.509 certificate

background

This guide demonstrates how to obtain, deploy and verify an X.509 certificate. While written specifically in the context of a domain-validation single-address certificate for www.obfuscate.xyz from Gandi, the OpenSSL commands are valid for other vendors (e.g.: Thawte), for other certificate types (e.g.: wildcard), and for other validation modes (e.g.: organization-validation or extended-validation).

When following this guide, replace www.obfuscate.xyz with the common name for your website. Similarly, if purchasing a certificate from another vendor, replace the URLs for the bundle of intermediate CA certificates and the root certificates, as necessary.

Note that when the single-address certificate signing request is for www.«domain», Gandi adds «domain» as a subject alternative name; and when the request is for «domain», Gandi adds www.«domain». Similarly, when the wildcard certificate signing request is for *.«domain», Gandi adds «domain» as a subject alternative name.

how to obtain an X.509 certificate

step 1: generate the configuration file (CFG)

Using a text editor, generate www.obfuscate.xyz.cfg containing the following configuration directives:

[ req ]
distinguished_name = req_distinguished_name
default_md = sha256
prompt = no

[ req_distinguished_name ]
C = CA
ST = British Columbia
L = Vancouver
O = The University of British Columbia
OU = Department of Obfuscation
CN = www.obfuscate.xyz

Notes:

Do not delete this file. If you inadvertently delete this file and are unable to restore it from an archive, then you may regenerate it manually using values extracted from the CSR or the CRT.
For DV (domain validation) certificates, it is not necessary to specify country (C), state (ST), locality (L), organization (O) or organizational unit (OU) in the Distinguished Name. These values are only used for OV (organization validation) and EV (extended validation) certificates.
To request a wildcard certificate, set the common name (CN) to *.obfuscate.xzy rather than a specific name such as www.obfuscate.xyz.

step 2: generate the private key file (KEY)

Using the following command, generate www.obfuscate.xyz.key containing a 2048-bit RSA private key.

openssl genrsa -out www.obfuscate.xyz.key 2048

Notes:

Do not delete this file as it contains the private key that underpins the identity presented by the end-entity certificate. If you are unable to restore it from an archive, then you will need to purchase a new certificate, discarding the previously created CSR and previously obtained CRT.
Do not lose control of www.obfuscate.xyz.key. In particular, do not store it in a location served by the web server. Further, the file permissions should read-write for user, read-only group, and none for other (i.e., 640); with user and group ownership set to 'root'.
Unless CA requirements regarding the private key change (e.g.: key length), you do not need to regenerate the private key on each renewal.

step 3: generate the certificate signing request (CSR)

Using the following command, generate www.obfuscate.xyz.csr containing a certificate signing request based on the private key and configuration files.

openssl req -config www.obfuscate.xyz.cfg -new -key www.obfuscate.xyz.key -out www.obfuscate.xyz.csr

Notes:

Do not delete this file. If you inadvertently delete this file and are unable to restore it from an archive, then you may re-run the command to generate a new CSR, which may be needed during renewals.
While it is possible to combine the generation of a private key and the generation of a certificate signing request into a single command, it is advantageous to keep them separate for clarity.
While it is possible to generate a certificate signing request using the default configuration, it is advantageous to capture, for future reference, the parameters used. Additionally, some CAs (although not Gandi) require the specification of subject alternative names via the CSR, which can only be accomplished via the configuration file.
Unless CA requirements regarding the certificate signing request change (e.g.: signature algorithm), you do not need to regenerate the CSR on each renewal.

step 4: obtain the end-entity certificate (CRT)

Submit the certificate signing request to UBC IT Security at security@ubc.ca, indicating that you used OpenSSL to create the CSR (i.e.: that you followed this guide). After domain control validation via SMTP, UBC IT Security will provide you with the end-entity certificate issued by Gandi. Save this as www.obfuscate.xyz.pem.

Notes:

Do not delete this file. If you inadvertently delete this file and are unable to restore it from an archive, then contact UBC IT Security asking for it to be re-issued.

step 5: obtain the bundle of intermediate CA certificates

Using the following command, obtain the bundle of intermediate CA certificates from Gandi.

wget -q -O - https://www.gandi.net/static/CAs/GandiStandardSSLCA2.pem > www.obfuscate.xyz-cacerts.pem

step 6: generate the chained certificate (for Apache httpd and nginx)

Using the following command, generate www.obfuscate.xyz-chained.pem containing the concatenation of the end-entity certificate and the intermediate CA certificates, ordered from leaf towards root.

cat www.obfuscate.xyz.pem www.obfuscate.xyz-cacerts.pem > www.obfuscate.xyz-chained.pem

Notes:

The order of certificates in this file is normally from leaf (i.e.: end-entity certificate) towards root.
This file should never contain root certificates.

step 7: generate the PKCS12 archive (for Microsoft IIS)

This step uses www.obfuscate.xyz-chained.pem, which was generated in the previous step.

Using the following command, generate www.obfuscate.xyz-pfxpass.txt containing a random 36-character string to be used as the passprase for the PKCS12 archive.

openssl rand -base64 36 > www.obfuscate.xyz-pfxpass.txt

Using the following command, generate www.obfuscate.xyz-chained.pfx a PKCS12 archive containing the private key, the end-entity certificate, and the intermediate CA certificates.

openssl pkcs12 -export -inkey www.obfuscate.xyz.key -in www.obfuscate.xyz-chained.pem -out www.obfuscate.xyz-chained.pfx -passout file:www.obfuscate.xyz-pfxpass.txt -name www.obfuscate.xyz

Notes:

Do not lose control of www.obfuscate.xyz-pfxpass.txt. Since the PKCS12 archive contains the private key, the passphrase securing the PKCS12 archive should be held as securely as the private key itself.

step 8: generate the Java keystore (for Apache Tomcat)

This step uses www.obfuscate.xyz-chained.pfx and www.obfuscate.xyz-pfxpass.txt, which were generated in the previous step.

Using the following command, generate www.obfuscate.xyz-jkspass.txt containing a random 36-character string to be used as the passphrase to secure the Java keystore.

openssl rand -base64 36 > www.obfuscate.xyz-jkspass.txt

Using the following command, generate www.obfuscate.xyz-keypass.txt containing a random 36-character string to be used as the passphrase to secure the key stored in the Java keystore.

openssl rand -base64 36 > www.obfuscate.xyz-keypass.txt

Using the following command, generate www.obfuscate.xyz-chained.jks, a Java keystore containing the private key, the end-entity certificate, and the intermediate CA certificates.

keytool -importkeystore \
  -srckeystore www.obfuscate.xyz-chained.pfx -srcstoretype pkcs12 -srcalias www.obfuscate.xyz \
  -destkeystore www.obfuscate.xyz-chained.jks -deststoretype jks -destalias www.obfuscate.xyz \
  -srcstorepass `cat www.obfuscate.xyz-pfxpass.txt` \
  -deststorepass `cat www.obfuscate.xyz-jkspass.txt` \
  -destkeypass `cat www.obfuscate.xyz-keypass.txt`

Notes:

Do not lose control of www.obfuscate.xzy-jkspass.txt and www.obfuscate.xyz-keypass.txt. Since the Java keystore contains the private key, the passphrases securing the Java keystore should be held as securely as the private key itself.

epilog: resulting files

Execution of the commands detailed in steps 1 through 8 will result in the generation of the following files:

www.obfuscate.xyz.cfg: OpenSSL configuration (CFG)
www.obfuscate.xyz.key: 2048-bit RSA private key (KEY)
www.obfuscate.xyz.csr: certificate signing request (CSR)
www.obfuscate.xyz.pem: end-entity certificate (CRT)
www.obfuscate.xyz-cacerts.pem: bundle of intermediate CA cerificates
www.obfuscate.xyz-chained.pem: concatenation of end-entity and intermediate CA certificates
www.obfuscate.xyz-pfxpass.txt: passphrase used to secure the PKCS12 archive
www.obfuscate.xyz-chained.pfx: PKCS12 archive containing the private key, the end-entity certificate and the intermediate CA certificates
www.obfuscate.xyz-jkspass.txt: passphrase used to secure the Java keystore
www.obfuscate.xyz-keypass.txt: passphrase used to secure the private key within the Java keystore
www.obfuscate.xyz-chained.jks: Java keystore containing the private key, the end-entity certificate and the intermediate CA certificates

Notes:

Do not lose control of the files marked as they either contain or grant access to the private key. Specifically, this means setting the file/group ownership and permission flags appropriately so that unauthorized users, locally and remotely, can not gain access to the private key.
By following a naming convention, all the files associated with a particular certificate are kept together. This includes the bundle of intermediate CA certificates, which was saved as www.obfuscate.xyz-cacerts.pem rather than as GandiStandardSSLCA2.pem.
One approach to managing these files is to store them outside of the context of the software that will use them (see next section on how to deploy an X.509 certificate). For example, these files could be kept in /root/ssl or /home/sysadmin/ssl and copied to locations needed by the software (with appropriate updates to ownership and permissions). In particular, software running on Linux machines configured with enhanced security policies, such as those employed by SELinux, will expect these files to be in specific locations.

how to deploy an X.509 certificate

Apache httpd

for versions up to 2.4.7 (inclusive)

Apache httpd versions up to 2.4.7 require the use of three configuration directives to specify the private key (SSLCertificateKeyFile), the end-entity certificate (SSLCertificateFile) and the bundle of intermediate CA certificates (SSLCertificateChainFile).

Example configuration:

<VirtualHost 192.168.1.1:443>
  ServerName www.obfuscate.xyz
  ServerAlias obfuscate.xyz

  SSLEngine on
  SSLCertificateFile       /path/to/www.obfuscate.xyz.pem
  SSLCertificateKeyFile    /path/to/www.obfuscate.xyz.key
  SSLCertificateChainFile  /path/to/www.obfuscate.xyz-cacerts.pem
  ...
</VirtualHost>

Notes:

The configuration snippet, above, does not provide guidance regarding configuration directives regarding protocols and cipher suites.
A common error is to use SSLCACertificateFile to specify the file containing the bundle of intermediate certificates. In Apache versions up to 2.4.7, use SSLCertificateChainFile for this purpose.

version 2.4.8 onwards

From Apache httpd version 2.4.8 onwards, the SSLCertificateChainFile configuration directive is deprecated and the SSLCertificateFile configuration directive accepts the chained certificate (similar to nginx).

Example configuration:

<VirtualHost 192.168.1.1:443>
  ServerName www.obfuscate.xyz
  ServerAlias obfuscate.xyz

  SSLEngine on
  SSLCertificateFile    /path/to/www.obfuscate.xyz-chained.pem
  SSLCertificateKeyFile /path/to/www.obfuscate.xyz.key
  ...
</VirtualHost>

Notes:

The configuration snippet, above, does not provide guidance regarding configuration directives regarding protocols and cipher suites.

nginx

Example configuration:

server {
  listen 192.168.1.1:443;
  server_name www.obfuscate.xyz obfuscate.xyz;

  ssl on;
  ssl_certificate     /path/to/www.obfuscate.xyz-chained.pem;
  ssl_certificate_key /path/to/www.obfuscate.xyz.key;
  ...
}

Notes:

The configuration snippet, above, does not provide guidance regarding configuration directives regarding protocols and cipher suites.

Microsoft IIS

Using IIS management tools (Start -> Administrative Tools -> IIS), import the PKCS12 archive (www.obfuscate.xyz-chained.pfx) and edit the bindings to use the new certificate.

The passphrase securing the PKCS12 archive is contained in www.obfuscate.xyz-pfxpass.txt.

Apache Tomcat

Apache Tomcat provides support for multiple SSL/TLS implementations. The server.xml configuration snippet, below, assumes the use of JSSE rather than APR.

<Connector address="192.168.1.1" port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="150" SSLEnabled="true" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS"
           keystoreFile="/path/to/www.obfuscate.xyz-chained.jks"
           keystorePass="«passphrase contained in www.obfuscate.xyz-jkspass.txt»"
           keyAlias="www.obfuscate.xyz"
           keyPass="«passphrase contained in www.obfuscate.xyz-keypass.txt»" />

Notes:

The passphrase securing the Java keystore which is contained in www.obfuscate.xyz-jkspass.txt. Use this passphrase with the keystorePass attribute.
The passphrase securing the key within the Java keystore is contained in www.obfuscate.xyz-keypass.txt. Use this passphrase with the keyPass attribute.
Do not lose control of Tomcat's server.xml. Since this configuration file contains the passphrases to the Java keystore and the key, it should be held as securely as the private key itself.
The configuration snippet, above, does not provide guidance regarding configuration directives regarding protocols and cipher suites.

how to verify an X.509 certificate

step 1: verify the certificate's integrity

Using the following commands, verify the integrity of the private key (KEY), the certificate signing request (CSR), and the end-entity certificate (CRT).

The SHA1 hash value output by the three commands should be identical, indicating that the end-entity certificate is based on the certificate signing request over the private key.

openssl rsa -noout -modulus -in www.obfuscate.xyz.key | openssl dgst -sha1 -binary | xxd -p