OCSP Stapling on Nginx

CRL and OCSP

Here is how certificate validation is supposed to work: Browers and other clients are supposed to check somehow if the certificate some HTTPS website presents to them is still valid or was already revoked for some reason. In case of CRLs the client downloads a list, which contains a number of serial numbers of certificates which are no longer valid. The problem here is, that in order to access an HTTPS website, the client first has to download a current CRL. Those lists can get quite large, especially if a lot of certificates are getting revoked.

If the certificate validation fails, the client has two choices: hard or soft-fail. Either it defaults to the revoked-state (hard-fail) and thus effectively blocking the website or it defaults to validated-state (soft-fail), which let’s you access the site, although it might be using a revoked certificate. Since using the strict method would open the door to denial of service attacks, most clients use the soft-fail method. Some browsers allow the user to change this behavior, but that’s maybe not the best idea.

OCSP aims to improve the performance of this process by reducing the bandwith costs (the browser pings the CA for every single certificate and does not download a complete list of all revoked certificates), but does this at a cost of a higher number of requests. Most modern browsers support OCPS (with the notable exception of Chrome which disabled OCSP in 2012).

About OCSP stapling

So, there are two major issues with OCSP: privacy and performance.

OCSP requires the client to contact a third party (typically a CA) to check for certificate validity and thus exposing private information (which website is being visited and who visited it). The second issue is an increased load on the CA servers, since the client needs to access them to confirm certificate validity for every visit to an HTTPS website.

OCPS stapling addresses both problems: When OCPS stapling is implemented the web server queries the CA server and caches the response (usually for a day). When the clients attempts to connect, this response is included in (or „stapled with“) the TLS/SSL Handshake. As a result the client doesn’t have to disclose it’s intended target to a third party and the number of queries to the CA server is reduced.

Configuring Nginx

Check for OCSP stapling support

Nginx supports OCSP stapling since version 1.3.7, so let’s check that first:

$ nginx -v
nginx version: nginx/1.7.4

Retrieve the CA bundle

Next we need to get the root and intermediate certificate of your CA in PEM format and save them in a file. For the remainder of this I’ll assume that you’re using StartSSL Class 1 certificates. For StartSSL you can get both of those certificates here.

$ cd /etc/ssl/nginx
$ wget https://startssl.com/certs/ca.pem
$ wget https://startssl.com/certs/class1/sha2/pem/sub.class1.server.sha2.ca.pem
$ cat ca.pem sub.class1.server.sha2.ca.pem > startssl.ca-bundle.pem
$ rm ca.pem sub.class1.server.sha2.ca.pem

Configure OCSP stapling

To activate OCSP stapling for your site, you need to add the following parameters inside the server-section of your nginx config:

$ vi /etc/nginx/sites-enabled/your-website.com

ssl_stapling on;
ssl_stapling_verify on;
ssl_trusted_certificate /etc/ssl/nginx/startssl.ca-bundle.pem;

An example config could look like this:

server {
    listen 443 ssl;
    listen 
[::]:443 ssl;
    server_name example.com;

    ssl_certificate /etc/ssl/nginx/example.com.crt;
    ssl_certificate_key /etc/ssl/nginx/example.com.key;
    ssl_trusted_certificate /etc/ssl/nginx/startssl.ca-bundle.pem;
    
    ssl_stapling on;
    ssl_stapling_verify on;
}

Now run a configtest, reload nginx and you’re done.

$ /etc/init.d/nginx configtest
$ /etc/init.d/nginx reload

Test

To test if OCSP stapling is working like it should, you can either use an online test tool like Qualys SSL Test, or you can just use openssl from your command line:

$ $ echo QUIT | openssl s_client -connect \
awesome-it.de:443 -status 2> /dev/null | \
grep 'OCSP Response Status:'

The response should look like this:

OCSP Response Status: successful (0x0)

That’s it. If you run into some problems or find errors, please let me know. I’ll be happy to help.