9 OpenSSL Commands To Keep Handy

With the recent Heartbleed fiasco, I found myself frequently generating new SSL keys and certificates for Atomic and our customers. Even though the OpenSSL implementation of the TLS heartbeat protocol was broken, the openssl utility itself is still extremely useful for working with SSL certificates. The number of sub-commands and options for the openssl command is rather daunting. However, there are a few key commands and patterns which I use most often and find very handy.

1. Generating a New CSR and Key

When generating (or regenerating) a SSL certificate, the first step is to create a new CSR (certificate signing request) with a new public/private key pair:

openssl req -nodes -new -newkey rsa: -out -keyout

e.g. openssl req -nodes -new -newkey rsa:4096 -out www.example.com.csr -keyout www.example.com.key

2. Generating a New CSR from Existing Key

If the private key already exists, it can be used to generate a new CSR also:

openssl req -nodes -new -key -out

e.g. openssl req -nodes -new -key www.example.com.old.key -out www.example.com.new.csr

3. Generating a New CSR from Existing CRT and Key

If there is an existing certificate and an existing key, a new CSR with the same information (organizational information, FQDN, etc.) can be easily generated:

openssl x509 -x509toreq -in -signkey -out

e.g. openssl x509 -x509toreq -in www.example.com.old.crt -signkey www.example.com.key -out www.example.com.csr

4. Generating a CSR with SANs

SANs (subject alternative names) allow a single CRT to refer to multiple FQDNs. This differs from a wildcard certificate, which refers to all sub-domains of a given domain. The SANs can refer to wildly different domains, like www.example.com and www.example.net.

Generating a CSR with SANs requires using a separate configuration file to list the SANs. The file contains the following default openssl template, plus an additional section for subjectAltNames:

[ req ]
distinguished_name  = req_distinguished_name
req_extensions = v3_req

[ req_distinguished_name ]
countryName     = Country Name (2 letter code)
countryName_default   = AU
countryName_min     = 2
countryName_max     = 2

stateOrProvinceName   = State or Province Name (full name)
stateOrProvinceName_default = Some-State

localityName      = Locality Name (eg, city)

0.organizationName    = Organization Name (eg, company)
0.organizationName_default  = Internet Widgits Pty Ltd

organizationalUnitName    = Organizational Unit Name (eg, section)

commonName      = Common Name (e.g. server FQDN or YOUR name)
commonName_max      = 64

emailAddress      = Email Address
emailAddress_max    = 64

[ v3_req ]
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
subjectAltName = @alt_names

[alt_names]
DNS.1 = www.example.net
DNS.2 = www.example.org

This file is then passed into the openssl command when generating the new CSR:

openssl req -config -nodes -new -newkey rsa: -out -keyout

e.g. openssl req -config openssl.conf -nodes -new -newkey rsa:4096 -out www.example.com.csr -keyout www.example.com.key

5. Reading a CSR

Sometimes, it’s helpful to examine an existing CSR to determine what information it contains (such as organizational information, FQDN, etc.):

openssl req -text -noout -in

e.g. openssl req -text -noout -in www.example.com.csr

This outputs the information in a form similar to:

Certificate Request:
    Data:
        Version: 0 (0x0)
        Subject: C=US, ST=Michigan, L=Grand Rapids, O=Internet Widgits Pty Ltd, CN=www.example.com
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
            RSA Public Key: (2014 bit)
                Modulus (2014 bit):
                    2f:40:9b:bb:fa:3f:2e:0a:71:7c:f7:7a:57:2c:09:
                            [...]
                Exponent: 65537 (0x10001)
        Attributes:
        Requested Extensions:
            X509v3 Basic Constraints:
                CA:FALSE
            X509v3 Key Usage:
                Digital Signature, Non Repudiation, Key Encipherment
            X509v3 Subject Alternative Name:
                DNS:www.example.net, DNS:www.example.org
    Signature Algorithm: sha1WithRSAEncryption
        06:40:f5:c8:38:d9:f8:52:8d:62:3c:12:0c:b3:12:e4:64:88:
            [...]

6. Reading a CRT

After a CSR has been sent to the CA (certificate authority) to be digitally signed, a certificate is issued and returned. It is often helpful to examine a certificate to verify dates of validity, and match it with organizational information.

openssl x509 -text -noout -in

e.g. openssl x509 -text -noout -in www.example.com.crt

This provides output similar to:

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            13:97:96:04:76
        Signature Algorithm: sha1WithRSAEncryption
        Issuer: C=US, ST=Michigan, O=Internet Widgits Pty Ltd, CN=www.example.com
        Validity
            Not Before: Apr 20 02:21:30 2014 GMT
            Not After : Apr 20 02:21:30 2015 GMT
        Subject: C=US, ST=Michigan, O=Internet Widgits Pty Ltd, CN=www.example.com
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
            RSA Public Key: (2014 bit)
                Modulus (2014 bit):
                    2f:40:9b:bb:fa:3f:2e:0a:71:7c:f7:7a:57:2c:09:
                            [...]
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Basic Constraints: 
                CA:FALSE
            Netscape Comment: 
                OpenSSL Generated Certificate
            X509v3 Subject Key Identifier: 
                57:85:26:A5:29:41:06:6C:29:74:EC:10:7B:31:1D:E2:78:09:74:54
            X509v3 Authority Key Identifier: 
                keyid:57:85:26:A5:29:41:06:6C:29:74:EC:10:7B:31:1D:E2:78:09:74:54

    Signature Algorithm: sha1WithRSAEncryption
        28:cc:5c:25:d0:2e:5b:45:16:f0:fc:75:7d:cd:22:d5:2b:e0:
            [...]

7. Verifying a CRT Matches a Private Key

Updating the private keys and certificates on server can get confusing, especially if poorly named files for previous years exist. If the private key and certificate do not match, web servers usually fail to start, or will not start with SSL. This can lead to all sorts of bad things (like outages). Fortunately, it is easy to sanity check that a key and certificate are matched by comparing their moduli. (The modulus is a component shared between the public key in the CRT and the private key). If the modulus from the CRT and private key match, it is likely that the public and private key are paired.

openssl x509 -noout -modulus -in

openssl rsa -noout -modulus -in

Example:

openssl rsa -noout -modulus -in www.example.com.key

Modulus=2F409BBBFA3F2E0A717CF77A572C0922BF95439CFF555627B887D88E6B302730779E6E744476C35AC065394385789AC6C3849B197EDF02C8C311C7F1E070362B4140B09CD50963192DE288E87D89156A1A90F6D0CC18F33B555114B48E77BF203BBD2F9EDB485B55E78A86760F782032DE7169EEA8DBD74AB3D816E612E940268A75D7221AF948728DAD9AFFEAEF13648E49304E86BAA39F39A7936F396BBA168C4C15A274CAED9B647273DF5E9ABC98EDFAE689D4BD6661B2A36324FCD9DAF85F0479D523FF845B46A09776BC87A7877C3646D0BFBC86934CDF9C2E79A2BA0ECF04CB72C349DFCB8BDDD36A6D66BE447426076BD6E2FD790AA82991

openssl x509 -noout -modulus -in www.example.com.crt

Modulus=2F409BBBFA3F2E0A717CF77A572C0922BF95439CFF555627B887D88E6B302730779E6E744476C35AC065394385789AC6C3849B197EDF02C8C311C7F1E070362B4140B09CD50963192DE288E87D89156A1A90F6D0CC18F33B555114B48E77BF203BBD2F9EDB485B55E78A86760F782032DE7169EEA8DBD74AB3D816E612E940268A75D7221AF948728DAD9AFFEAEF13648E49304E86BAA39F39A7936F396BBA168C4C15A274CAED9B647273DF5E9ABC98EDFAE689D4BD6661B2A36324FCD9DAF85F0479D523FF845B46A09776BC87A7877C3646D0BFBC86934CDF9C2E79A2BA0ECF04CB72C349DFCB8BDDD36A6D66BE447426076BD6E2FD790AA82991

The moduli can be visually compared, or can be compared programmatically:

#!/bin/bash
test `openssl rsa -noout -modulus -in $1.key` = \
 `openssl x509 -noout -modulus -in $1.crt`
if [ $? = 0 ]
    then echo "Match!"
else
    echo "Not a match!"
fi

8. Fingerprinting a CRT

It can be helpful to compare a certificate’s digital fingerprint with what it is expected to be (either from records, or published statements). For instance, if a new SSL certificate is added to a server, a client might receive a message about an unrecognized or untrusted certificate, along with the certificate’s fingerprint. The user can independently verify the validity of the certificate by comparing the provided fingerprint with the known fingerprint (which should be determined and published beforehand).

openssl x509 -fingerprint -noout -in

e.g. openssl x509 -fingerprint -noout -in www.example.com.crt

The digest algorithm for the fingerprint can be specified as well:

openssl x509 -fingerprint -noout -in -sha1

openssl x509 -fingerprint -noout -in -md5

This gives output similar to:

openssl x509 -noout -fingerprint -in www.example.com.crt -md5

MD5 Fingerprint=39:3D:ED:5D:36:88:47:BB:0F:56:75:3F:8F:3E:61:1F

openssl x509 -noout -fingerprint -in www.example.com.crt -sha1

SHA1 Fingerprint=F1:27:CC:F4:0E:61:42:2F:CF:7D:8E:7F:1F:34:21:36:B8:22:4E:A1

9. Making it Automated

It is possible to add all necessary information for a CSR to a configuration file so that it can be read in by openssl instead of using prompts. The following is an example of a file that contains all the necessary information to generate a new CSR:

[ req ]
prompt = no
default_bits = 2048
default_keyfile = www.example.com.key
encrypt_key = no
distinguished_name = req_distinguished_name

string_mask = utf8only

req_extensions = v3_req

[ req_distinguished_name ]
O=Internet Widgits Pty Ltd
L=Grand Rapids
ST=Michigan
C=US
CN=www.example.com

[ v3_req ]

basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

Now, a new CSR can be created with: openssl req -new -config -out

e.g. openssl req -new -config openssl.conf -out www.example.com.csr

Conclusion

There are, of course, many more sub-commands and options that openssl is capable of handling. However, in practice, the above are the commands I find myself using the vast majority of the time. Before becoming familiar with the openssl utility, I would need to do research across a variety of different sites to figure out how to achieve more complex operations (like generating a certificate with SAN’s). Hopefully this will be a useful reference for people finding themselves needing to do similar research. Any other openssl commands you find that you use frequently? Let me know in the comments below.