Set Up OCSP Stapling on OS X Server

Photo of Greg
Photo by JD Hancock - http://flic.kr/p/cVj27L

Unless you’re still using a version of the Server app released in 2013 or before, setting up OCSP stapling on OS X is very straightforward. Here’s how to boost performance by configuring OCSP stapling, plus an extra note to clear up some confusion about HSTS.

Of the two main ways for a browser to check the validity of a server’s certificate, Online Certificate Status Protocol (OCSP) is usually quicker and more lightweight than the alternative check on Certificate Revocation Lists (CRL). But when the user’s browser makes a separate OCSP request to a third party server run by the certificate authority in order to check up on your site’s certificate validity, that process creates an obvious source of latency and can cause outright failure should the CA’s server fail to respond promptly enough. For browsers which support it, OCSP stapling allows the server, during the initial setup of the secure connection, to send along its own cached OCSP response, signed by the CA, to demonstrate its validity. From a performance perspective, enabling OCSP stapling is nearly always a good move.

As of Server 5, where the reverse proxy layer handles all communication with the outside world, the relevant configuration file lives here:

/Library/Server/Web/Config/Proxy/apache_serviceproxy.conf

As I described in an earlier article, it’s useful to add performance tweaks to this file via a single include, and that’s where I would suggest dropping in the directives to enable OCSP stapling.

First, you’ll need to download and concatenate the relevant CA certificates. As an example, I described using StartCom in “The Nuts and Bolts of Setting Up SHA-1 and SHA-2 Certificates on OS X Server”, and to grab their Class 2 certificates:

curl https://www.startssl.com/certs/ca.pem https://www.startssl.com/certs/class2/sha2/pem/sub.class2.server.sha2.ca.pem | tee -a ca-certs.pem > /dev/null

The ca-certs.pem file can then be copied to a suitable location, such as:

/etc/certificates/ca-certs.pem

Then verify the relevant OCSP URL for your CA, which may need to be specified explicitly (which is the case for the StartCom example) and presto:

	SSLUseStapling on
	SSLCACertificateFile /etc/certificates/ca-certs.pem
	SSLStaplingCache shmcb:/var/run/stapling-cache(150000)
	SSLStaplingResponderTimeout 5
	SSLStaplingReturnResponderErrors off
	SSLStaplingStandardCacheTimeout 86400
	SSLStaplingErrorCacheTimeout 1200
	SSLStaplingForceURL http://ocsp.startssl.com/sub/class2/server/ca

Note that in the example above, I’ve specified a cache size of 150000, which is up from the default 32768; I would suggest this if your server includes many sites with certificates, but the default size is probably fine for just a few. There’s full documentation on each of these directives at the Apache site.

As I mentioned above, enabling OCSP stapling needs to happen in apache_serviceproxy.conf or, preferably, in an include referenced there, and not in VirtualHost containers. However, if there are any sites on the server which should not use OCSP stapling, it can be disabled on a per-site basis in the VirtualHost container with the following:

SSLUseStapling Off

Likewise, if a given virtual host needs a different certificate file, that too can be specified in the individual VirtualHost.

There’s one type of ‘gotcha’ to be aware of when using OCSP stapling, but while it’s significant, as of this writing it’s rarely a reason not to use it at all. Specifically, the stapled OCSP response may range in size from a few hundred up to a few thousand bytes, and this can cause problems with overflowing the TCP congestion window during the setup of the connection. You may have done a good job of keeping the certificate chain itself down to a reasonable size, and you may have addressed the specific chain bloat issues I mentioned at the end of “The Nuts and Bolts of Setting Up SHA-1 and SHA-2 Certificates on OS X Server”. You may have generally ensured that the connection can be set up without requiring extra round trips between server and client, and your connections are crisp and speedy as a result. Then you enable OCSP stapling, and instead of seeing a faster connection, you see a slower one — because the size of the certificate chain plus the stapled OCSP response is now significantly larger, overflowing the initial congestion window, or initcwnd. Analysing the overall impact on connection time, however, and specifically including the impact of a whole separate OCSP request which OCSP stapling obviates, it will almost always be the case that using OCSP stapling is still worthwhile.

One possible exception could be contexts where you know in advance that site visitors are overwhelmingly Chrome users. Chrome now relies on somewhat controversial (see pro and con, for example) CRLSets in preference to either CRL or OCSP, so the net effect of enabling OCSP stapling will be to slow HTTPS connection time specifically for that browser. In other cases, however — and especially for Firefox — OCSP should, on balance, be almost a no-brainer for TLS performance improvement.

For some reason, the idea that OS X Server can’t do OCSP stapling still seems to be fairly widespread, and Google search results on the topic frequently return old articles which weren’t even correct at the time they were first published. The idea that it is somehow incapable of HTTP Strict Transport Security, or HSTS, is out there too — but that’s even more silly, since HSTS requires nothing more from the server than sending a simple header. You can switch it on easily in an SSL-enabled virtual host’s config file — a web app is convenient — or alternatively in .htaccess files:

<IfModule mod_headers.c>
	Header set Strict-Transport-Security "max-age=15552000; includeSubdomains"
</IfModule>

That particular max-age corresponds to 6 months.

If you’re prepared to commit permanently to delivering a site only over HTTPS, you can also append the preload flag, like so:

<IfModule mod_headers.c>
	Header set Strict-Transport-Security "max-age=15552000; includeSubdomains; preload"
</IfModule>

Adding the flag makes the site eligible for inclusion in Google’s HSTS preload list of sites hardcoded into Chrome as being HTTPS-only; this will also lead to the site being included in hardcoded lists within Firefox, Safari, IE 11 and Edge. Since it’s hard to reverse this step, however, it should only be used for sites that are really really really going to remain HTTPS-only.

All material on this site is carefully reviewed, but its accuracy cannot be guaranteed, and some suggestions offered here might just be silly ideas. For best results, please do your own checking and verifying. This specific article was last reviewed or updated by Greg on .

This site is provided for informational and entertainment purposes only. It is not intended to provide advice of any kind.