Skip to main content Logo (IEC resistor symbol)logo

Quis custodiet ipsos custodes?
Home | About | All pages | RSS Feed | Gopher

OCSP Stapling on nginx

Published: 03-02-2014 | Author: Remy van Elst | Text only version of this article

Table of Contents

When connecting to a server, clients should verify the validity of the servercertificate using either a Certificate Revocation List (CRL), or an OnlineCertificate Status Protocol (OCSP) record. The problem with CRL is that thelists have grown huge and takes forever to download.

OCSP is much more lightweight, as only one record is retrieved at a time. Butthe side effect is that OCSP requests must be made to a 3rd party OCSP responderwhen connecting to a server, which adds latency and potential failures. In fact,the OCSP responders operated by CAs are often so unreliable that browser willfail silently if no response is received in a timely manner. This reducessecurity, by allowing an attacker to DoS an OCSP responder to disable thevalidation.

If you like this article, consider sponsoring me by trying out a Digital OceanVPS. With this link you'll get $100 credit for 60 days). (referral link)

The solution is to allow the server to send its cached OCSP record during theTLS handshake, therefore bypassing the OCSP responder. This mechanism saves aroundtrip between the client and the OCSP responder, and is called OCSPStapling.

The server will send a cached OCSP response only if the client requests it, byannouncing support for the status_request TLS extension in its CLIENT HELLO.

Most servers will cache OCSP response for up to 48 hours. At regular intervals,the server will connect to the OCSP responder of the CA to retrieve a fresh OCSPrecord. The location of the OCSP responder is taken from the AuthorityInformation Access field of the signed certificate.

This tutorial is also available for Apache

What is OCSP Stapling

OCSP stapling is defined in the IETF RFC 6066. The term "stapling" is apopular term used to describe how the OCSP response is obtained by the webserver. The web server caches the response from the CA that issued thecertificate. When an SSL/TLS handshake is initiated, the response is returned bythe web server to the client by attaching the cached OCSP response to theCertificateStatus message. To make use of OCSP stapling, a client must includethe "status_request" extension with its SSL/TSL Client "Hello" message.

OCSP stapling presents several advantages including the following:

Readoneofthefollowinglinks for moreinformation on OCSP and OCSP stapling.


You need at least nginx 1.3.7 for this to work. This is not available in thecurrent Ubuntu LTS releases (12.04), it has 1.1.19 and on CentOS you needEPEL or the official repositories. However, it is easy to install the latestversion of nginx.

You also need create a firewall exception to allow your server to make outboundconnections to the upstream OCSP's. You can view all OCSP URI's from a websiteusing this one liner:

OLDIFS=$IFS; IFS=':' certificates=$(openssl s_client -connect -showcerts -tlsextdebug -tls1 2>&1 </dev/null | sed -n '/-----BEGIN/,/-----END/ {/-----BEGIN/ s/^/:/; p}'); for certificate in ${certificates#:}; do echo $certificate | openssl x509 -noout -ocsp_uri; done; IFS=$OLDIFS

It results for in:

nginx Configuration

Add the below configuration to your https (443) server block:

ssl_stapling on;ssl_stapling_verify on;resolver valid=300s;resolver_timeout 5s;

For the OCSP stapling to work, the certificate of the server certificate issuershould be known. If the ssl_certificate file does not contain intermediatecertificates, the certificate of the server certificate issuer should be presentin the ssl_trusted_certificate file.

My certificate for is issues by Positive CA 2. That certificate isissued by Addtrust External CA Root. In my nginx ssl_certificate file allthese certificates are present. If that for you is not the case, create a filewith the certificate chain and use it like so:

  ssl_trusted_certificate /etc/ssl/certs/domain.chain.stapling.pem;

Before version 1.1.7, only a single name server could be configured. Specifyingname servers using IPv6 addresses is supported starting from versions 1.3.1 and1.2.2. By default, nginx will look up both IPv4 and IPv6 addresses whileresolving. If looking up of IPv6 addresses is not desired, the ipv6=offparameter can be specified. Resolving of names into IPv6 addresses is supportedstarting from version 1.5.8.

By default, nginx caches answers using the TTL value of a response. The(optional) valid parameter allows overrides it to be 5 minutes. Before version1.1.9, tuning of caching time was not possible, and nginx always cached answersfor the duration of 5 minutes.

Restart your nginx to load the new configuration:

service nginx restart

And it should work. Let's test it.

Testing it

Fire up a terminal and use the following OpenSSL command to connect to yourwebsite:

openssl s_client -connect -tls1 -tlsextdebug -status

In the response, look for the following:

OCSP response:======================================OCSP Response Data:    OCSP Response Status: successful (0x0)    Response Type: Basic OCSP Response    Version: 1 (0x0)    Responder Id: 99E4405F6B145E3E05D9DDD36354FC62B8F700AC    Produced At: Feb  3 04:25:39 2014 GMT    Responses:    Certificate ID:      Hash Algorithm: sha1      Issuer Name Hash: 0226EE2F5FA2810834DACC3380E680ACE827F604      Issuer Key Hash: 99E4405F6B145E3E05D9DDD36354FC62B8F700AC      Serial Number: C1A3D8D00D72FCE483CD84759E9EC0BC    Cert Status: good    This Update: Feb  3 04:25:39 2014 GMT    Next Update: Feb  7 04:25:39 2014 GMT

That means it is working. If you get a response like below, it is not working:

OCSP response: no response sent

You can also use the SSL Labs test to see if OCSP stapling works.


Tags: crl, nginx, ocsp, ocsp-stapling, revocation, ssl, ssl-labs, tls, tutorials