OCSP stapling

Available since

HAProxy 2.8
HAProxy Enterprise 2.8r1
Not available in HAProxy ALOHA

Note: As of version 2.8r1, when OCSP stapling is enabled, the load balancer will automatically update the OCSP response for its configured certificates. It will fetch the OCSP response from the URI contained within the certificate. For earlier versions, the OCSP response can be set manually using the set ssl ocsp-response command.

OCSP stapling is not available for HAProxy ALOHA.

The Online Certificate Status Protocol (OCSP) allows a client (browser) to see the revocation status of an SSL/TLS certificate in real time. A client contacts an OCSP Responder server to get the OCSP response, which contains the certificate’s revocation status. The Responder server is often managed by the certificate issuer.

Because the browser must make a separate call to the OCSP Responder server to fetch the certificate’s revocation status, OCSP adds a small delay to a user’s request. OCSP stapling is a mechanism that allows you to fetch the revocation status ahead of time and attach it to the certificate, saving the client from needing to make that request to the OCSP Responder server. The OCSP response contains a revocation status for the certificate of either good, revoked, or unknown.

Enable OCSP stapling Jump to heading

When OCSP stapling is enabled, the load balancer will automatically retrieve and update the OCSP response for each of its configured certificates.

Use crt-store

Starting in HAProxy version 3.0 and HAProxy Enterprise version 3.0r1 you can use a crt-store section in place of a crt-list to enable OCSP stapling. Prior to these versions, you must declare your OCSP settings in a crt-list. OCSP stapling is not available in HAProxy ALOHA. For more information, see Use crt-store to enable TLS.

To enable OCSP stapling:

Verify that the certificate contains an OCSP URI using the openssl x509 command. The output from this command shows the contents of the certificate. The output should contain a value named OCSP - URI under the section Authority Information Access.

To see the entire contents of the certificate:

nix
openssl x509 -in /etc/hapee-3.0/certs/newcert.pem -noout -text

nix
openssl x509 -in /etc/hapee-3.0/certs/newcert.pem -noout -text

output
text
Certificate:
 Data:
     Version: 3 (0x2)
     Serial Number: 4104 (0x1008)
     Signature Algorithm: sha256WithRSAEncryption
     Issuer: C = AR, ST = AR, L = AR, O = AR, OU = AR, CN = AR, emailAddress = AR
     Validity
         Not Before: Aug 13 08:00:00 2015 GMT
         Not After : Aug 13 09:00:00 2025 GMT
[...]
     X509v3 extensions:
         Authority Information Access: 
             OCSP - URI:http://ocsp.issuer.com
         X509v3 Basic Constraints: 
             CA:FALSE
         X509v3 Subject Key Identifier: 
             88:40:3C:69:8F:93:0A:F6:62:CA:32:A8:D6:AA:0E:01:29:A3:6B:55
         X509v3 Authority Key Identifier: 
             19:8C:C3:43:9A:02:8C:63:49:AA:AD:77:C9:68:06:B6:66:32:86:02
[...]

output
text
Certificate:
 Data:
     Version: 3 (0x2)
     Serial Number: 4104 (0x1008)
     Signature Algorithm: sha256WithRSAEncryption
     Issuer: C = AR, ST = AR, L = AR, O = AR, OU = AR, CN = AR, emailAddress = AR
     Validity
         Not Before: Aug 13 08:00:00 2015 GMT
         Not After : Aug 13 09:00:00 2025 GMT
[...]
     X509v3 extensions:
         Authority Information Access: 
             OCSP - URI:http://ocsp.issuer.com
         X509v3 Basic Constraints: 
             CA:FALSE
         X509v3 Subject Key Identifier: 
             88:40:3C:69:8F:93:0A:F6:62:CA:32:A8:D6:AA:0E:01:29:A3:6B:55
         X509v3 Authority Key Identifier: 
             19:8C:C3:43:9A:02:8C:63:49:AA:AD:77:C9:68:06:B6:66:32:86:02
[...]

To see only the value for OCSP - URI:

nix
openssl x509 -in /etc/hapee-3.0/certs/newcert.pem -text | grep "OCSP - URI"

nix
openssl x509 -in /etc/hapee-3.0/certs/newcert.pem -text | grep "OCSP - URI"

output
text
OCSP - URI:http://ocsp.issuer.com

output
text
OCSP - URI:http://ocsp.issuer.com

Use either a crt-list or a crt-store to specify your OCSP stapling settings:
Use a crt-list to enable OCSP stapling
1. A crt-list file enumerates the certificates bound to a listener and describes metadata about each certificate, such as ALPN, minimum TLS version, and OCSP. You can create a crt-list file, for example crt-list.txt, that has one line for each of the certificates you want to bind to. For example, if you host multiple websites at the same IP address, then you will add a line for each TLS certificate. Each line includes the path to the certificate. Your corresponding .ocsp file and issuer certificates should reside at this path as well.
  
  Note that the issuer certificate may be present in one of two ways:
  - It may have been issued with the certificate from your server chain, and so it will exist within your .pem file.
  - It may be its own file (sharing the same name as the server certificate and .ocsp files, but with the suffix .issuer).
  Your certificate (.pem) file should contain the following in this order:
  - public certificate
  - any intermediate certificates
  - private key
2. Copy the certificate, corresponding issuer certificate (if it is a separate file), and corresponding .ocsp file to the directory you will specify in the crt-list (for example /etc/hapee-3.0/certs). You may need to create the directory if it does not already exist.
3. Using the text editor of your choice, create the crt-list file. In this example, we will create a file named crt-list.txt in /etc/hapee-3.0/certs. For this example, we will specify one certificate.
  
  In the example crt-list file below, our PEM file is located at /etc/hapee-3.0/certs, as are our .ocsp and .issuer files. We are specifying our ALPN options here as well, alpn h2, and enabling OCSP with ocsp-update on. Note that the ocsp-update on parameter can be included only in a crt-list. It cannot be added to a bind line.
```
crt-list.txt
nix
/etc/hapee-3.0/certs/newcert.pem [alpn h2 ocsp-update on]
```
```
crt-list.txt
nix
/etc/hapee-3.0/certs/newcert.pem [alpn h2 ocsp-update on]
```
4. Add a bind line to your frontend that specifies the path to the crt-list. The load balancer will load the certificates according to the options specified in the crt-list.
```
haproxy
frontend www
  bind :443 ssl crt-list /etc/hapee-3.0/certs/crt-list.txt
  default_backend webservers
```
```
haproxy
frontend www
  bind :443 ssl crt-list /etc/hapee-3.0/certs/crt-list.txt
  default_backend webservers
```
5. Optional: set the global configuration parameters ocsp-update.maxdelay and ocsp-update.mindelay to specify the minimum and maximum intervals between automatic updates of the same OCSP response. Their defaults are 3600 seconds (1 hour) and 300 seconds (5 minutes), respectively. ocsp-update.mindelay must be set to a value lower than that specified for ocsp-update.maxdelay.
  
  Name of directive changed
  
  Prior to HAProxy 3.0, the ocsp-update directives were named tune.ssl.ocsp-update.
```
haproxy
global
  ocsp-update.mindelay 300
  ocsp-update.maxdelay 3600
```
```
haproxy
global
  ocsp-update.mindelay 300
  ocsp-update.maxdelay 3600
```
6. Reload the load balancer configuration.
```
nix
sudo systemctl reload hapee-3.0-lb
```
```
nix
sudo systemctl reload hapee-3.0-lb
```
Use a crt-store to enable OCSP stapling

Instead of placing certificate definitions in files separate to the load balancer configuration, as would be the case when using a crt-list, we will place them within the configuration file itself using a crt-store section. To use a crt-store:
1. Define a crt-store in your configuration section.
```
haproxy
crt-store web
  crt-base /etc/hapee-3.0/certs/
  load crt "newcert.pem" ocsp "newcert.ocsp" ocsp-update on
```
```
haproxy
crt-store web
  crt-base /etc/hapee-3.0/certs/
  load crt "newcert.pem" ocsp "newcert.ocsp" ocsp-update on
```
  - Specify a location for crt-base. The load balancer will look for the files at this location.
  - Set ocsp-update to on to enable OCSP stapling for your certificate. In this example, the OCSP response file is named newcert.ocsp so we specify that using the ocsp option.
2. Reference the certificate files by their name and the name of the crt-store, in this case @web/newcert.pem, in your frontend:
```
haproxy
frontend www
  bind :443 ssl crt "@web/newcert.pem"
  default_backend webservers
```
```
haproxy
frontend www
  bind :443 ssl crt "@web/newcert.pem"
  default_backend webservers
```
3. Optional: set the global configuration parameters ocsp-update.maxdelay and ocsp-update.mindelay to specify the minimum and maximum intervals between automatic updates of the same OCSP response. Their defaults are 3600 seconds (1 hour) and 300 seconds (5 minutes), respectively. ocsp-update.mindelay must be set to a value lower than that specified for ocsp-update.maxdelay.
  
  Name of directive changed
  
  Prior to HAProxy 3.0, the ocsp-update directives were named tune.ssl.ocsp-update.
```
haproxy
global
  ocsp-update.mindelay 300
  ocsp-update.maxdelay 3600
```
```
haproxy
global
  ocsp-update.mindelay 300
  ocsp-update.maxdelay 3600
```
4. Reload the load balancer configuration.
```
nix
sudo systemctl reload hapee-3.0-lb
```
```
nix
sudo systemctl reload hapee-3.0-lb
```

Add an HTTP proxy for OCSP Jump to heading

Available since

HAProxy 3.0
HAProxy Enterprise 3.0r1

When you enable OCSP stapling, the load balancer periodically connects to an OCSP Responder server to fetch the revocation status of your SSL/TLS certificates. If your load balancer is in an air-gapped environment without direct Internet access, then you’ll need a way to connect to the OCSP Responder server. You can indicate an HTTP proxy to route OCSP update requests through by setting the global directive ocsp-update.httpproxy.

Below we set the IP address and port of our HTTP proxy:

haproxy
global
  ocsp-update.httpproxy 192.168.0.10:8000

haproxy
global
  ocsp-update.httpproxy 192.168.0.10:8000

Product Documentation

API Documentation

Configuration Documentation

OCSP stapling

Enable OCSP stapling Jump to heading

Add an HTTP proxy for OCSP Jump to heading

See also Jump to heading

Product Documentation

API Documentation

Configuration Documentation

Enable OCSP stapling Jump to heading #

Add an HTTP proxy for OCSP Jump to heading #

See also Jump to heading #

Privacy Settings

Enable OCSP stapling Jump to heading

Add an HTTP proxy for OCSP Jump to heading

See also Jump to heading