blog.kempkens.io/content/posts/2014-03-30-ocsp-stapling-with-nginx.md

date	description	modified	tags	slug	title
2014-03-30T21:30:00Z	A general explanation of how to set up OCSP stapling with nginx.	2015-08-03T22:55:00Z	nginx ocsp ssl ops english	ocsp-stapling-with-nginx	OCSP Stapling with nginx

Setting up OCSP stapling with nginx is more or less straightforward, but depending on what's in your ssl_certificate you might run into some issues with it silently failing. So I've decided to write about how I set up OCSP stapling with certificates from StartSSL and CAcert.

I have only tested this using nginx version 1.5.12, but the configuration options I'm using have been in nginx since version 1.3.7. If it does not work for some reason, feel free to leave a comment below.

To enable OCSP stapling, you simply have to add the following lines to your (already SSL enabled) site:

{{< highlight nginx >}} resolver 8.8.8.8 8.8.4.4 208.67.222.222 208.67.220.220 valid=300s; resolver_timeout 10s;

ssl_stapling on; ssl_stapling_verify on; ssl_trusted_certificate /etc/nginx/certs/startssl.stapling.crt; {{< / highlight >}}

The important thing here is the usage of ssl_trusted_certificate. The nginx documentation states that:

For verification to work, the certificate of the server certificate issuer, the root certificate, and all intermediate certificates should be configured as trusted using the ssl_trusted_certificate directive.

You have to include the root certificate (and intermediate certificates) for OCSP stapling to work, which is why ssl_trusted_certificate will be set to a special certificate file that includes those. If your ssl_certificate already does, you might be able to skip using ssl_trusted_certificate.

CAcert

For CAcert (and unless you have a Class 3 certificate) you only have to include the Class 1 certificate in your stapling file.

{{< highlight text >}} 03/08/2015 Removed. Get the Class 1 certificate here: http://www.cacert.org/index.php?id=3 {{< / highlight >}}

StartSSL

StartSSL - using a Class 1 certificate again - has an intermediate certificate in their chain, so you have to include this one in your stapling file, too.

{{< highlight text >}} 03/08/2015: Removed. Get the root certificate and the intermediate certificate here: https://www.startssl.com/certs/ {{< / highlight >}}

After you've done all that, you can restart nginx or reload the configuration and you should be good to go!

You can verify that everything works using the openssl command line tool.

{{< highlight bash >}} openssl s_client -servername blog.kempkens.io -connect blog.kempkens.io:443 -tls1 -tlsextdebug -status {{< / highlight >}}

Both of those should include a section (with data) named "OCSP Response Data".

An alternative way to test if OCSP stapling is supported, is by using Qualys SSL Labs.

Keep in mind that nginx does not include OCSP data in the first response, because it has to fetch it, too. So you probably have to try at least two times to verify if it works or not.

Update #1

If you have more than one virtual host with SSL enabled, you have to enable OCSP stapling for every single one. Otherwise nginx will fail silently and not include any stapled OCSP data. (Thanks to @rmoriz for figuring this out)

Update #2

This post has been quite popular, so I decided to update it a little bit. The biggest change is that I have removed the certificate chains that were originally included in this post. I did this to not confuse people too much and because I don't want to keep these chains up to date.

The most important thing to remember when setting up OCSP stapling with any CA is to make sure that the entire trust chain (including the root certificate) is included in the ssl_trusted_certificate file.