Client-side encryption

You can use TLS (Transport Layer Security) for encrypting traffic between the load balancer and clients. TLS is the successor to the deprecated SSL (Secure Sockets Layer) protocol.

Enable TLS Jump to heading #

The load balancer offers you flexibility in regards to enabling TLS for your frontends. The needs of your application, configuration, and certificate storage (where you store your certificates, keys, and other related files on your filesystem) may determine which configuration concept you should use. There are three configuration concepts to consider.

1. crt. This setting indicates that you will use either:

   • a single PEM file containing both the required certificates and any associated private keys.
   • multiple files that are co-located in a single directory and share a name, for example site1.crt, site1.key, site1.ocsp, and so on.

   The load balancer will load the PEM file or a directory containing the files that you specify as the crt. Additional configuration options are available for this setting, and they apply to all crt entries on the same bind line. If a file doesn’t contain a private key, HAProxy will try to load the key at the same path suffixed by a .key.

2. crt-list. You can specify a crt-list file in place of multiple crt declarations if you need to apply different SSL configuration options per certificate. All of the certificate files, key files, and OCSP files must be co-located, as is the case with crt.

3. crt-store. Available as of version 3.0, the crt-store provides additional flexibility regarding the location of related certificate files, key files, and so on. You can use a crt-store to specify different filesystem locations for certificate and key files and assign aliases to certificates for easier readability when referenced in the load balancer configuration or in crt-list files.

See Configuration considerations to help you decide which configuration concept is best suited for your application.

Use crt to enable TLS Jump to heading #

For HTTPS, you will typically bind to port 443. In the following setups, the load balancer handles encrypting and decrypting traffic, and sends traffic in the clear to backend servers. The backend servers can then listen on port 80 (HTTP port).

You can configure the crt setting either using a single PEM file or a directory with multiple files.

Configure crt to use a single PEM file Jump to heading #

haproxy
frontend www
  bind :443 ssl crt /certs/site.pem
  default_backend webservers

haproxy
frontend www
  bind :443 ssl crt /certs/site.pem
  default_backend webservers

In this example:

• The ssl argument enables TLS encryption.
• The crt argument indicates the file path to a .pem file that contains both your server’s PEM-formatted TLS certificate and its private key. You will typically need to concatenate these two things manually into a single file. Simply copy and paste them into the file.

Configure crt to use a directory Jump to heading #

You can also set the crt argument to a directory to use separate certificate and key files, instead of a single PEM file. When set to a directory, the load balancer will use Server Name Indication (SNI) to search the directory for a certificate that has a Common Name (CN) or Subject Alternative Name (SAN) field that matches the requested domain, which the client sends during the TLS handshake.

This allows you to host multiple websites with different domain names at the same IP address and port. Each will use the certificate that matches the domain name being requested. In the example below, we set crt to a directory that contains TLS certificates:

haproxy
frontend www
  mode http
  bind :443 ssl crt /certs
  default_backend webservers

haproxy
frontend www
  mode http
  bind :443 ssl crt /certs
  default_backend webservers

Use crt-store to enable TLS Jump to heading #

You can configure the load balancer’s internal certificate storage mechanism using a crt-store. The crt-store separates certificate storage from their use in a frontend and provides better visibility for certificate information by moving it from external files, such as within a crt-list, and placing it into the main HAProxy configuration. The crt-store section allows you to individually specify the locations of each certificate component, for example certificates files, key files, and OCSP response files.

To use a crt-store:

1. Define a crt-store section in your load balancer configuration. Consider the following example.

   haproxy
   crt-store web
     crt-base /etc/haproxy/ssl/certs/
     key-base /etc/haproxy/ssl/private/
     load crt "site1.crt"
     load crt "site2.crt" key "site2.key"

   haproxy
   crt-store web
     crt-base /etc/haproxy/ssl/certs/
     key-base /etc/haproxy/ssl/private/
     load crt "site1.crt"
     load crt "site2.crt" key "site2.key"

   In this example:

   • The crt-store section named web indicates the TLS certificates that the load balancer will use.
   • The crt-base directive specifies the directory to search for TLS certificate files. In this example, files are located at /etc/haproxy/ssl/certs.
   • The key-base directive specifies the directory to search for key files. In this example, files are located at /etc/haproxy/ssl/private.
   • Each load directive indicates a certificate file and options that pertain to it.

2. Use this crt-store definition in a frontend by referencing it by name via a bind directive’s crt argument. The format for the name is @<crt-store name>/<certificate name or alias>, or in this case, @web/site1.crt and @web/site2.crt:

   haproxy
   frontend main
     bind *:443 ssl crt "@web/site1.crt" crt "@web/site2.crt"

   haproxy
   frontend main
     bind *:443 ssl crt "@web/site1.crt" crt "@web/site2.crt"

You can also specify the crt-base and key-base in your global settings. Note that including crt-base or key-base in a crt-store take precedence over the global settings. The same is true for using absolute paths when specifying your certificates and keys.

See the load reference for options available for the load directive.

Use aliases to reference certificate components Jump to heading #

Aliases provide support for human-friendly names for referencing the certificates more easily on bind lines. To use aliases:

1. Define a crt-store in your configuration. In the example below, we name our crt-store web and reference this crt-store by name using @web.

   haproxy
   crt-store web
     crt-base /etc/haproxy/ssl/certs
     load crt "site1.pem" ocsp "site1.ocsp" alias "site1" ocsp-update on

   haproxy
   crt-store web
     crt-base /etc/haproxy/ssl/certs
     load crt "site1.pem" ocsp "site1.ocsp" alias "site1" ocsp-update on

2. In your load directive in your crt-store, give your crt an alias using the alias option. In this example, we give the certificate named site1.pem an alias of site1.

   haproxy
   crt-store web
     crt-base /etc/haproxy/ssl/certs
     load crt "site1.pem" ocsp "site1.ocsp" alias "site1" ocsp-update on

   haproxy
   crt-store web
     crt-base /etc/haproxy/ssl/certs
     load crt "site1.pem" ocsp "site1.ocsp" alias "site1" ocsp-update on

   Note that in this example we also specify that the certificate’s corresponding OCSP response file is named site1.ocsp. We enable OCSP stapling for this certificate by including the option ocsp-update and setting it to on.

3. Reference the certificate components defined in the crt-store by the alias site1 in a frontend:

   haproxy
   frontend  main
     bind *:443 ssl crt "@web/site1"
     default_backend app

   haproxy
   frontend  main
     bind *:443 ssl crt "@web/site1"
     default_backend app

   In this frontend, we set the crt as @web/site1. This means that:

   • we are using the crt-store named web.
   • from the crt-store named web, we want the certificate components having the alias site1. In this case, as we defined in the crt-store, that is the certificate site1.pem and OCSP response file site1.ocsp.

Redirect HTTP to HTTPS Jump to heading #

To enable an HTTP to HTTPS redirect, use the http-request redirect scheme directive:

haproxy
frontend www
  mode http
  bind :80
  bind :443 ssl crt /certs/site.pem
  http-request redirect scheme https unless { ssl_fc }
  default_backend webservers

haproxy
frontend www
  mode http
  bind :80
  bind :443 ssl crt /certs/site.pem
  http-request redirect scheme https unless { ssl_fc }
  default_backend webservers

In this example:

• We set mode to http.
• We enable TLS with the ssl and crt arguments on the second bind line. Notice that this frontend listens on both ports 80 for HTTP and 443 for HTTPS. Traffic that is received at HTTP port 80 is redirected to HTTPS port 443.
• Use the http-request redirect scheme directive to redirect HTTP traffic to the HTTPS scheme, unless it is already HTTPS as indicated by the ssl_fc fetch method.

Set default certificates Jump to heading #

If you specify the crt as a directory, the load balancer will use Server Name Indication (SNI) to search the directory for a certificate that has a Common Name (CN) or Subject Alternative Name (SAN) field that matches the requested domain, which the client sends during the TLS handshake. If the client doesn’t provide an SNI or if the SNI hostname doesn’t match any certificate, the load balancer will present a default certificate. You can specify default certificates on your bind line using the default-crt option. To set a default certificate:

1. Add the default-crt option to the bind line in your frontend, specifying the names of your default certificates. Note that you can specify multiple default certificates, for example, an ECDSA certificate and an RSA certificate. Specifying multiple certificates in this way will allows you to give precedence to the ECDSA certificate, presenting the RSA certificate otherwise.

   haproxy
   frontend fe_main
     bind :80
     bind :443 ssl default-crt /certs/default.pem.ecdsa /certs/default.pem.rsa crt /certs/
     # Redirects to HTTPS
     http-request redirect scheme https unless { ssl_fc }

   haproxy
   frontend fe_main
     bind :80
     bind :443 ssl default-crt /certs/default.pem.ecdsa /certs/default.pem.rsa crt /certs/
     # Redirects to HTTPS
     http-request redirect scheme https unless { ssl_fc }

   In this example:

   • We specify the default certificates as /certs/default.pem.ecdsa and /certs/default.pem.rsa. The load balancer will try to use the ECDSA certificate first, and if unsupported by the client, use the RSA certificate.
   • We set the directory for our certificates as /certs/. The load balancer will select the appropriate certificate from this directory based on the SNI. If it cannot find a matching certificate, it will use the default certificates.

Note that the load balancer will use default certificates only when you aren’t also using the strict-sni option.

HTTP Strict Transport Security Jump to heading #

Use HTTP Strict Transport Security (HSTS) to prevent a man-in-the-middle attack.

The HSTS policy directs clients to communicate over secure transport. This policy can prevent man-in-the-middle attacks, where the redirected traffic is intercepted by a malicious party.

HSTS works by sending the response header Strict-Transport-Security to clients. This header directs the client browser to use HTTPS instead of HTTP for this domain and, optionally, its subdomains.

Load balancer applications use the redirect scheme https directive to direct HTTP traffic to HTTPS, but that directive alone doesn’t prevent a man-in-the-middle attack. Adding the HSTS header, however, prevents the man-in-the-middle attack by requiring the client to direct traffic to the secure site without relying on redirects. The client browser caches your domain’s HSTS policy so that for future HTTP requests, it automatically uses secure transport instead of HTTP.

The Strict-Transport-Security header fields are:

Enable HSTS Jump to heading #

To enable HSTS:

1. Configure the redirect to HTTPS in your frontend section.

2. Insert the Strict-Transport-Security header into every response using the http-response set-header directive, as shown here:

   haproxy
   frontend www.mywebsite.com
     bind :80
     bind :443 ssl crt /etc/ssl/certs/mywebsite.com.pem
     http-request redirect scheme https code 301 unless { ssl_fc }
     # max-age is mandatory. 16000000 seconds is approximately 6 months. Use a low value during testing.
     http-response set-header Strict-Transport-Security "max-age=16000000; includeSubDomains; preload;"
     default_backend servers

   haproxy
   frontend www.mywebsite.com
     bind :80
     bind :443 ssl crt /etc/ssl/certs/mywebsite.com.pem
     http-request redirect scheme https code 301 unless { ssl_fc }
     # max-age is mandatory. 16000000 seconds is approximately 6 months. Use a low value during testing.
     http-response set-header Strict-Transport-Security "max-age=16000000; includeSubDomains; preload;"
     default_backend servers

With this configuration, HAProxy returns the Strict-Transport-Security header, which instructs the browser to route messages to this website using HTTPS from the start. This rule lasts for 16,000,000 seconds (approximately six months) after the user has visited your website at least once. From then on, attackers will no longer get a chance to intercept your user’s messages. As a side effect, it also avoids one round trip between the user and server, improving response times.

Global settings Jump to heading #

Some TLS settings should apply to your entire load balancer, such as whether to allow older versions of TLS or whether to set a list of preferred ciphers. Although it’s possible to set these things at the bind or server level, you will often want to apply them across the board. In that case, you can add them to the global section of your configuration.

Set the minimum TLS version Jump to heading #

The following example uses ssl-default-bind-options to allow only version TLS 1.2 or newer on all bind lines:

haproxy
global
  ssl-default-bind-options ssl-min-ver TLSv1.2

haproxy
global
  ssl-default-bind-options ssl-min-ver TLSv1.2

To set this on an individual bind line, use the ssl-min-ver argument.

Set the TLS ciphers Jump to heading #

Use the ssl-default-bind-ciphers directive to set a list of TLS ciphers for bind lines, in order of preference:

haproxy
global 
  ssl-default-bind-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384

haproxy
global 
  ssl-default-bind-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384

To use the client’s preferred cipher instead, specify the prefer-client-ciphers parameter.

To set this on an individual bind line, use the ciphers argument.

For TLS versions 1.3 and later, set the preferred encryption ciphers in your global section using the ssl-default-bind-ciphersuites option. Note that you can override this value on each bind line (including bind lines in crt-list files).

haproxy
global
  ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256

haproxy
global
  ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256

To set this on an individual bind line, use the ciphersuites argument.

Disable validation of certificates Jump to heading #

When the load balancer connects to a backend server over HTTPS, the server presents its own certificate. To disable validation of server certificates, such as when using self-signed certificates, set the ssl-server-verify directive to none:

haproxy
global
  ssl-server-verify none

haproxy
global
  ssl-server-verify none

To set this on an individual server line, use the verify argument.

Optimize startup time with ssl-load-extra-files Jump to heading #

The ssl-load-extra-files directive, by default set to all, configures the load balancer to automatically load all extra certificate bundles, Signed Certificate Timestamp List (sctl) files, OCSP files, OCSP issuer files, and key files that you may have when using crt. For example, if you set crt to load site1.crt, and depending on the contents of this certificate, the load balancer may try to load files such as site1.ocsp, site1.sctl, site1.issuer, and site1.key.

Change this directive’s default behavior to optimize the startup time with its many available arguments. You can specify which types of files you want the load balancer to load automatically in the ssl-load-extra-files reference. In the following example, ssl-load-extra-files is set to none, which will only load the file specified by crt; it won’t load any other extra files related to it.

haproxy
global
  ssl-load-extra-files none
frontend www
  bind :443 ssl crt /certs/site1.crt
  default_backend webservers

haproxy
global
  ssl-load-extra-files none
frontend www
  bind :443 ssl crt /certs/site1.crt
  default_backend webservers

Remove .crt filename extension from key lookups Jump to heading #

By default, the load balancer appends a .key extension to certificate filenames on lookups for keys. For example, with a certificate you named foobar.crt, the load balancer attempts to load a key file named foobar.crt.key.

Use the ssl-load-extra-del-ext directive to configure the load balancer to remove the .crt extension before it appends .key. For example, with a certificate you named foobar.crt, the load balancer will look for a key named foobar.key instead of foobar.crt.key. This directive only removes .crt, so the load balancer doesn’t remove bundle extensions like .ecdsa, .rsa, and .dsa.

haproxy
global
  ssl-load-extra-del-ext

haproxy
global
  ssl-load-extra-del-ext

Performance considerations Jump to heading #

Consider these factors when estimating TLS encryption performance:

• Encryption with an ECC certificate uses about 1/8 of the CPU of an RSA certificate of an equivalent cryptographic strength.

  If you have both an ECC and RSA certificate, you can use both at the same time by using the file name extensions. Name the RSA certificate file with an .rsa extension, such as example.pem.rsa. Name the ECC certificate with an .ecdsa extension, such as example.pem.ecdsa. In your configuration, set the crt argument to load the file with only the .pem extension, omitting the .rsa or .ecdsa extension, such as crt example.pem.

• How large are your RSA keys? 2048 is typical, 4096 will be substantially slower. The older 1024 is considered insecure and will no longer be signed by public CAs.

• Are TLS session tickets enabled on the load balancer server? This can increase the speed of the TLS handshake.

The following guidelines can help you decide how many cores you need:

• A 3.7GHz CPU core will take about 1ms to process a 2048 bit key exchange, meaning you can do 1000 key exchanges per second.
• 1 GB of RAM can support 8000 open TLS connections.

If you decide that your use case will likely require more than one core, you can use the cpu-map options with nbthread to pin threads to specific cores.

For example:

haproxy
global
  nbthread 4
  cpu-map auto:1/1-4 0-3

haproxy
global
  nbthread 4
  cpu-map auto:1/1-4 0-3

Configuration considerations Jump to heading #

In some cases, you can use either a crt-list or a crt-store depending on your configuration needs. You can also provide some of the same options those settings provide when defining a crt on the bind line. With multiple options for configuration, which one should you choose? The answer depends on the needs of your application, configuration, and certificate storage.

Here are some common use cases with which setting you should consider using:

• You want to specify different filesystem locations for certificates and keys.

  • Consider using a crt-store, as it allows you to specify independent locations for related certificate files, key files, OCSP response files, and so on. If you use only crt without crt-store or use crt-list, the load balancer assumes all of the files are co-located with the certificate.

• You want to set specific SSL options per certificate.

  • Consider using a crt-list, as it allows you to specify different options per certificate. The crt-list also supports several parameters from the crt-store load directive.

• You want to use aliases but also want to be able to set specific SSL options per certificate.

  • Consider using crt-store in combination with a crt-list. In this way, you can specify the storage locations for your certificate components and give the certificates aliases. Using the aliases you defined in the crt-store, you can then add additional SSL options to each certificate entry in the crt-list, referenced by aliases. For example:

    haproxy
    frontend www
      bind :443 ssl crt-list /etc/haproxy/certs/crt-list.txt
      default_backend webservers
    crt-store
      crt-base /etc/haproxy/ssl/certs/
      key-base /etc/haproxy/ssl/private/
      load crt "site1.crt" key "site1.key" ocsp "site1.ocsp" alias "site1"
      load crt "site2.crt" key "site2.key" alias "site2"
      load crt "site3.crt" key "site3.key" alias "site3"

    haproxy
    frontend www
      bind :443 ssl crt-list /etc/haproxy/certs/crt-list.txt
      default_backend webservers
    crt-store
      crt-base /etc/haproxy/ssl/certs/
      key-base /etc/haproxy/ssl/private/
      load crt "site1.crt" key "site1.key" ocsp "site1.ocsp" alias "site1"
      load crt "site2.crt" key "site2.key" alias "site2"
      load crt "site3.crt" key "site3.key" alias "site3"

    crt-list.txt
    haproxy
    @/site1 [ciphers ECDHE-ECDSA-AES256-GCM-SHA384 ssl-min-ver TLSv1.2]
    @/site2 [ciphersuites TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256 ssl-min-ver TLSv1.3]
    @/site3 [ciphers ECDHE-RSA-AES128-GCM-SHA256]

    crt-list.txt
    haproxy
    @/site1 [ciphers ECDHE-ECDSA-AES256-GCM-SHA384 ssl-min-ver TLSv1.2]
    @/site2 [ciphersuites TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256 ssl-min-ver TLSv1.3]
    @/site3 [ciphers ECDHE-RSA-AES128-GCM-SHA256]

    Each certificate is referenced by alias in the crt-list. The frontend configuration references the crt-list rather than each certificate individually.

• You have multiple certificates but don’t want to define your certificates in an external file, as would be the case with a crt-list, and you don’t need to use the SSL options supported by crt-list.

  • Consider using a crt-store. It enables you to put all of your certificate definitions into your main load balancer configuration file rather than list them in an external crt-list file.

• You have a single certificate per frontend, don’t require OCSP stapling, and your related certificate and key files are co-located and share a name like site1.crt and site1.key for example.

  • Consider using crt on your bind line. It may be unnecessary for you to use a crt-store or crt-list if you don’t require additional options regarding storage or SSL configuration options.

See also Jump to heading #

• To bind a thread or thread group to a CPU, see cpu-map.
• To specify a PEM file for a bind, or the directory containing the certificate and associated private keys, see crt.
• To specify a file containing a list of certs, see crt-list.
• For enhanced flexibility in managing certificates, see crt-store.
• To perform redirects such as redirecting HTTP requests to HTTPS, see http-request redirect.
• To control the number of threads that HAProxy runs on, see nbthread.
• To enable SSL deciphering, see ssl.
• To define the default list of cipher algorithms on TLS versions 1.2 and older, see ssl-default-bind-ciphers.
• To define the default list of cipher algorithms on TLS versions 1.3 and later, see ssl-default-bind-ciphersuites.
• To set SSL options for binds, see ssl-default-bind-options.