SSL/TLS
Global TLS settings
Some TLS settings should apply to your entire load balancer, such as whether to allow older TLS versions or set a list of preferred ciphers. Although it’s possible to set these settings at the bind or server level, you will often want to apply them globally. 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
haproxy
To set this on an individual bind line, use the ssl-min-ver argument.
Set the TLS ciphers Jump to heading
When establishing a TLS connection, the client and load balancer automatically select an encryption cipher that both support. You can configure a list of ciphers in order of preference.
Ciphers in TLS 1.2 Jump to heading
Use the ssl-default-bind-ciphers directive to set a colon-separated list of TLS ciphers for bind lines, in order of preference:
haproxy
haproxy
To use the client’s preferred cipher instead, specify the prefer-client-ciphers directive.
To set this on an individual bind line, use the ciphers argument.
To see a list the cipher strings supported by OpenSSL, see Cipher Strings in the OpenSSL documentation.
Cipher suites in TLS 1.3 and newer Jump to heading
For TLS versions 1.3 and newer, set the preferred encryption ciphers in your global section using the ssl-default-bind-ciphersuites directive. You can override this value on each bind line, including bind lines in crt-list files.
haproxy
haproxy
To set this on an individual bind line, use the ciphersuites argument.
To see a list of cipher suites supported by OpenSSL, see TLS v1.3 cipher suites in the OpenSSL documentation.
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
haproxy
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
haproxy
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
haproxy
Unlock passphrase-protected private keys Jump to heading
This section applies to:
- HAProxy 3.3 and newer
- HAProxy Enterprise 3.3r1 and newer
- HAProxy ALOHA 18.0 and newer
If your TLS private key is protected by a passphrase, you can use the global directive ssl-passphrase-cmd to invoke a script that returns the passphrase, which the load balancer will use to unlock the key.
In the following example, we create a shell script that will prompt the user for the passphrase when starting the load balancer. This is only an example; you can devise a more advanced solution that gets the passphrase from a secure key vault.
-
For testing, create a certificate and private key that has a passphrase:
nixopenssl genrsa -des3 -out example.key 2048openssl req -key example.key -nodes -x509 -days 365 -out example.crtnixopenssl genrsa -des3 -out example.key 2048openssl req -key example.key -nodes -x509 -days 365 -out example.crt -
Create the script
get-passphrase.sh. We’re passing the-noption to theechocommand to ensure that there’s no newline returned. The passphrase will be dumped to standard out.get-passphrase.shbash#! /bin/bashpass=$(systemd-ask-password)echo -n $passget-passphrase.shbash#! /bin/bashpass=$(systemd-ask-password)echo -n $pass -
Update the load balancer configuration accordingly:
-
Add the
ssl-passphrase-cmddirective to theglobalsection. For example:haproxyglobalssl-passphrase-cmd /etc/haproxy/get-passphrase.shhaproxyglobalssl-passphrase-cmd /etc/haproxy/get-passphrase.sh -
Load the TLS certificate and key. For example:
haproxycrt-store my_filescrt-base /etc/haproxykey-base /etc/haproxyload crt "example.crt" key "example.key" alias "example"haproxycrt-store my_filescrt-base /etc/haproxykey-base /etc/haproxyload crt "example.crt" key "example.key" alias "example"
-
-
When starting the load balancer, you’ll be prompted to enter the passphrase.
See also Jump to heading
- 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.