OCSP stapling is a relatively new feature in SSL, and resources for it still leave much to be desired. Official documentation is often lacking, and many tutorials contain inaccuracies or recommend less-than-optimal config. So, SSLMate dove into the source code of Apache, nginx, and OpenSSL to learn how things really work to bring you this definitive guide to configuring OCSP stapling.

What is OCSP Stapling?

To understand OCSP stapling, it is necessary to understand OCSP, the Online Certificate Status Protocol. OCSP is a protocol for determining whether a certificate is revoked (for instance, because its private key was compromised). Every time a browser connects to an HTTPS website, it contacts the OCSP responder specified in the SSL certificate, and asks if the certificate is revoked (except for Chrome, where OCSP is disabled by default). If the responder replies that the certificate is revoked, the browser blocks the page from loading.

There are a number of problems with OCSP. One is that it slows down page load times, since browsers have to wait for the OCSP response before loading the page, and another is that it violates privacy by reporting to the OCSP responder every time someone visits an HTTPS website. OCSP stapling fixes these problems by having the web server make the OCSP request and including ("stapling") the response along with the certificate in the SSL handshake. The browser can use the response from the server instead of making its own OCSP request, and since the server can cache the OCSP response and reuse it with future connections, it doesn't slow down page load times. (Apache and nginx both cache OCSP responses for an hour by default.)

At the moment OCSP stapling is optional, but enabling it is a good idea because it gives you an extra boost to your page load times and protects the privacy of your visitors. Also, in the future it may be possible to opt your site into mandatory OCSP stapling ("OCSP Must-Staple"), which will improve security by letting you effectively revoke your certificate if its private key is compromised (at the moment, there is no airtight way to revoke SSL certificates). If you configure OCSP stapling now, you'll be able to easily opt into mandatory stapling in the future.

Apache

You need Apache 2.4 or higher for OCSP stapling.

Inside the virtual host for your SSL site, add the following options, alongside your existing SSL options (SSLCertificateFile, SSLCertificateKeyFile, etc.):

SSLUseStapling on
SSLStaplingReturnResponderErrors off
SSLStaplingResponderTimeout 5

Note that, contrary to some tutorials, you do not need to configure a root certificate, either via SSLCACertificateFile or by appending it to your existing certificate or chain certificate files.

In the global configuration (not a virtual host), you need to configure the SSLStaplingCache parameter. On Debian-derived distros, place the following in /etc/apache2/mods-enabled/ssl.conf:

SSLStaplingCache shmcb:${APACHE_RUN_DIR}/ssl_stapling_cache(128000)

On RedHat-derived distros, place the following in /etc/httpd/conf.d/ssl.conf:

SSLStaplingCache shmcb:/run/httpd/ssl_stapling_cache(128000)

On other distros, you need to specify a path to a runtime directory for SSLStaplingCache. Avoid world-writable directories such as /tmp; the directory should be writable by root only. If you're not sure what directory to use, you can look for the SSLSessionCache option that should already be in your config, and use the same directory for SSLStaplingCache. For example, if your SSLSessionCache is:

SSLSessionCache shmcb:/var/run/apache/sslcache(512000)

...then use the following for SSLStaplingCache:

SSLStaplingCache shmcb:/var/run/apache/ssl_stapling_cache(128000)

nginx

You need nginx 1.3.7 or higher for OCSP stapling.

In order to validate OCSP responses before stapling them, nginx requires you to provide it with a file containing your certificate's entire intermediate certificate chain, including the root certificate. If you use SSLMate to manage your certificates, you can create this file as follows:

1. Add the following option to your configuration file (requires SSLMate 1.3.0 or higher):

   cert_format.chain+root yes

2. Run sslmate download --all

The file will be called /etc/sslmate/www.example.com.chain+root.crt, where www.example.com is the name of your certificate.

If you don't use SSLMate, you can use whatsmychaincert.com to generate this file. Be sure to check the "Include Root Certificate" box. Of course, whenever you renew your certificate, you'll need to regenerate this file, so you should really just use SSLMate, which automatically keeps the chain+root file up-to-date as your certificate changes.

You do not need to modify any of the other certificate files passed to nginx. In particular, do not add a root certificate to the ssl_certificate file.

Once you've generated your chain+root file, add the following options to the server config for your SSL site, alongside your existing SSL options (ssl_certificate, ssl_certificate_key, etc.):

ssl_stapling on;
ssl_stapling_verify on;
ssl_trusted_certificate /etc/sslmate/www.example.com.chain+root.crt;
resolver 8.8.8.8;

(Be sure to replace the value of ssl_trusted_certificate with the path to the chain+root file created above.)

Note that this configuration tells nginx to use Google Public DNS for resolving the hostname of your certificate's OCSP responder. If you'd rather not use Google Public DNS, you can replace 8.8.8.8 with the IP address of a different resolver. If you omit the resolver line, nginx will resolve the hostname only once, when nginx starts, using the system resolver (i.e. gethostbyname). Omitting the resolver is not recommended, since it would cause OCSP stapling to stop working if the OCSP responder's IP address changed.

Also note that this configuration requires you to set the ssl_trusted_certificate option. This may conflict with the configuration for client certificates. Since client certificates are such an unusual configuration, making OCSP stapling work alongside client certificates is beyond the scope of this guide. (If you're not sure if you use client certificates, you almost certainly don't.)

Testing OCSP Stapling

First, as with any configuration change, be sure to restart Apache or nginx before testing!

Second, if you're using nginx, be aware that the first SSL connection handled by an nginx worker process never has a stapled OCSP response. If you don't see a stapled response when testing, wait a second and try again, repeating until you get a response. If you're unlucky, you might have to repeat the test as many times as there are nginx worker processes (as specified by the worker_processes option, which is often set to the number of CPU cores you have). (Why does nginx have this quirk? The OCSP stapling cache is per-process, and nginx doesn't initiate an OCSP request until it receives the first SSL connection to a site. However, nginx doesn't wait for the OCSP response to complete before servicing the connection, so the first connection never gets a stapled response. Apache also initiates OCSP requests on-demand, but unlike nginx, it blocks the SSL connection until the OCSP response completes, waiting at most the number of seconds specified by the SSLStaplingResponderTimeout option.)

A quick way to test OCSP stapling is with the openssl s_client command. Run the following, replacing www.example.com with your hostname (in both places):

openssl s_client -connect www.example.com:443 -servername www.example.com -status < /dev/null

If OCSP stapling is working, you'll see output similar to the following:

OCSP response: 
======================================
OCSP Response Data:
    OCSP Response Status: successful (0x0)
    Response Type: Basic OCSP Response
    Version: 1 (0x0)
    Responder Id: 90AF6A3A945A0BD890EA125673DF43B43A28DAE7
    Produced At: Jun  1 19:02:17 2015 GMT
    Responses:
    Certificate ID:
      Hash Algorithm: sha1
      Issuer Name Hash: 7AE13EE8A0C42A2CB428CBE7A605461940E2A1E9
      Issuer Key Hash: 90AF6A3A945A0BD890EA125673DF43B43A28DAE7
      Serial Number: 5F599C7AB96640FC797C2CE64A092741
    Cert Status: good
    This Update: Jun  1 19:02:17 2015 GMT
    Next Update: Jun  5 19:02:17 2015 GMT

You won't see any OCSP response data in the output if stapling isn't working.

You can also use the SSL Labs Server Test to test OCSP stapling. Look for "OCSP stapling" near the bottom of the report, in the "Protocol Details" section.

Updates

• 2015-06-18: updated nginx instructions to enable OCSP stapling verification