June 4, 2015
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.
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 (
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
SSLStaplingCache parameter. On Debian-derived distros, place the
On RedHat-derived distros, place the following in
On other distros, you need to specify a path to a runtime directory
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
...then use the following for
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:
Add the following option to your configuration file (requires SSLMate 1.3.0 or higher):
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
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_stapling on; ssl_stapling_verify on; ssl_trusted_certificate /etc/sslmate/www.example.com.chain+root.crt; resolver 188.8.131.52;
(Be sure to to replace the value of
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
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
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
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
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.
- 2015-06-18: updated nginx instructions to enable OCSP stapling verification