SSL / TLS

OCSP stapling

On this page

Available since

  • HAProxy 2.8
  • HAProxy Enterprise 2.8r1
  • Not available in 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.

As of HAProxy version 2.8, when OCSP stapling is enabled, the load balancer will automatically update the OCSP response for its configured certificates by contacting the OCSP Responder server at the URI contained within the certificate.

For earlier versions of HAProxy, you can must retrieve the OCSP response manually and load it into HAProxy’s memory using the Runtime API’s set ssl ocsp-response command.

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.

To enable OCSP stapling:

  1. Verify that your server TLS certificate contains an OCSP URI by using the openssl x509 command with -ocsp_uri argument:

    nix
    openssl x509 -in /etc/hapee-3.0/certs/mysite.pem -noout -ocsp_uri
    nix
    openssl x509 -in /etc/hapee-3.0/certs/mysite.pem -noout -ocsp_uri
    output
    text
    http://ocsp.issuer.com 
    output
    text
    http://ocsp.issuer.com

  2. Ensure that the issuer’s intermediate certificate is present on your load balancer server in one of two ways:

    • Append it within your server TLS certificate .pem file. Your server certificate .pem file should contain the following, in any order:

      • public certificate
      • private key
      • any intermediate certificates

    • Save it to its own file in the same directory as the server certificate, sharing the same name as the server certificate but with the suffix .issuer.

  3. Enable OCSP stapling either:

Enable for all certificates Jump to heading

Available since

  • HAProxy 3.0
  • HAProxy Enterprise 3.0

To Enable OCSP stapling at the global level for all certificates in the configuration:

  1. Set the ocsp-update.mode global directive to on.

    haproxy
    global
      ocsp-update.mode on
    haproxy
    global
      ocsp-update.mode on

  2. 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.

    haproxy
    global
      ocsp-update.mode on
      ocsp-update.mindelay 300
      ocsp-update.maxdelay 3600
    haproxy
    global
      ocsp-update.mode on
      ocsp-update.mindelay 300
      ocsp-update.maxdelay 3600

  3. Reload the load balancer configuration.

    nix
    sudo systemctl reload hapee-3.0-lb
    nix
    sudo systemctl reload hapee-3.0-lb

Enable for specific certificates Jump to heading

To Enable OCSP stapling for one or more specific certificates, use either a crt-list or a crt-store to specify your OCSP stapling settings.

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 on crt-store, see Use crt-store to enable TLS.

Choose one of:

Use a crt-list to enable OCSP stapling

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 issuer certificates should reside at this path as well.

  1. 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. We are specifying our ALPN options here as well, alpn h2, and enabling OCSP with ocsp-update on. Note that the ocsp-update on argument 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/mysite.pem [alpn h2 ocsp-update on]
    crt-list.txt
    nix
    /etc/hapee-3.0/certs/mysite.pem [alpn h2 ocsp-update on]

  2. 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

  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
Use a crt-store to enable OCSP stapling

Instead of placing certificate definitions in files separate from 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 mysite.pem ocsp-update on
    haproxy
    crt-store web
      crt-base /etc/hapee-3.0/certs/
      load crt mysite.pem 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.

  2. Reference the certificate files by their name and the name of the crt-store, in this case @web/mysite.pem, in your frontend:

    haproxy
    frontend www
      bind :443 ssl crt "@web/mysite.pem"
      default_backend webservers
    haproxy
    frontend www
      bind :443 ssl crt "@web/mysite.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

Save the OCSP response to a file Jump to heading

As an optional step, you can save the OCSP response to a file so that HAProxy loads it during startup. That will improve startup time. Otherwise, HAProxy keeps the response in memory only and will fetch the data again after a restart. Name the file the same as your TLS server certificate, but with a .ocsp file extension, for example mysite.ocsp. Save it to the same directory as your TLS server certificate.

  1. To save the response data to a file, do one of the following:

    • Call the Runtime API’s show ssl ocsp-response command to get the data already stored in memory and then save the result to a file.

    • Call the openssl ocsp command, replacing the values with your own:

      nix
      openssl ocsp \
        -issuer issuer.pem \
        -cert mysite.pem \
        -url http://ocsp.issuer.com \
        -host ocsp.issuer.com:80 \
        -respout mysite.ocsp
      nix
      openssl ocsp \
        -issuer issuer.pem \
        -cert mysite.pem \
        -url http://ocsp.issuer.com \
        -host ocsp.issuer.com:80 \
        -respout mysite.ocsp

  2. Add an ocsp argument to indicate the file to load.

    • If using crt-list, add an ocsp argument for each certificate:

      crt-list.txt
      nix
      /etc/hapee-3.0/certs/mysite.pem [alpn h2 ocsp-update on ocsp /etc/hapee-3.0/certs/mysite.ocsp]
      crt-list.txt
      nix
      /etc/hapee-3.0/certs/mysite.pem [alpn h2 ocsp-update on ocsp /etc/hapee-3.0/certs/mysite.ocsp]

    • If using crt-store, add an ocsp argument to the load directive:

      haproxy
      crt-store web
        crt-base /etc/hapee-3.0/certs/
        load crt mysite.pem ocsp-update on ocsp mysite.ocsp
      haproxy
      crt-store web
        crt-base /etc/hapee-3.0/certs/
        load crt mysite.pem ocsp-update on ocsp mysite.ocsp

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

See also Jump to heading

Do you have any suggestions on how we can improve the content of this page?

Previous page Client-side encryption Next page Server-side encryption
© 2024 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences