HAProxy Enterprise Documentation 2.3r1

TLS session ticket keys

After a TLS session is established HAProxy Enterprise can send a "ticket" to the client; this is a blob of data that is encrypted with a key that only HAProxy knows. When a client wants to make a new connection after keep-alive has ended it can send this blob back. If the HAProxy Enterprise server can decrypt this blob it will get the keys exchanged for a previous session and avoid the expensive TLS negotiation process.

When you have multiple load balancers terminating TLS, you must ensure that TLS ticket keys are distributed across all of the load balancers. Otherwise, if a client makes a new connection with another HAProxy Enterprise server in the same cluster, a new key will need to be exchanged (with the associated CPU work).

You can use the Update module - which is also used for updating maps and ACLs - to keep all HAProxy Enterprise instances in a cluster updated with the latest TLS ticket keys.

Setup your webserver

Perform these steps on a web server that's accessible to your HAProxy Enterprise servers.

  1. Make the hapee_ticket_keys.txt file on a web server only accessible to these HAProxy Enterprise servers.

    If anyone else can get the contents of this file they will be able to launch man-in-the-middle attacks against TLS connections to your load balancer servers.

    If you are transferring these keys over an untrusted network, the Update module supports HTTPS. Simply add the ssl option and add ca-file /etc/ssl/certs/ca-bundle.trust.crt to the update line added in the next section.

  2. Add the following shell script as /etc/hapee-2.3/update_hapee_tls_tickets.sh to update the hapee_ticket_keys.txt file on the web server. Change the HAPEE_KEY_PATH variable for your environment:

    #!/bin/bash
HAPEE_KEY_PATH=/var/www
openssl rand 48 -base64 >> $HAPEE_KEY_PATH/hapee_ticket_keys.txt
new_keys=$(tail -n3 $HAPEE_KEY_PATH/hapee_ticket_keys.txt)
echo "$new_keys" > $HAPEE_KEY_PATH/hapee_ticket_keys.txt

    Then run crontab -e (as root) and add the following cron:

    */5 * * * * /bin/bash /etc/hapee-2.3/update_hapee_tls_tickets.sh >>/dev/null 2>&1

Set up your HAProxy Enterprise instances

Perform these steps on your HAProxy Enterprise servers.

  1. Make the /etc/ssl/hapee_ticket_keys.txt file with three ticket keys in it. Run the following command three times to initialize that file with keys:

    openssl rand -base64 48 >> /etc/ssl/hapee_ticket_keys.txt

  2. Make your TLS bind line look like the following, which configures a frontend with the tls-ticket-keys option as defined here:

    frontend ft
   bind 0.0.0.0:443 ssl  crt /etc/ssl/ft_cert.pem  tls-ticket-keys /etc/ssl/hapee_ticket_keys.txt

  3. Add the following to the global section to load the Update module:

    global
   module-path /opt/hapee-2.3/modules
   module-load hapee-lb-update.so

  4. After the first defaults section add the following configuration:

    dynamic-update
   update tls-ticket-keys id /etc/ssl/hapee_ticket_keys.txt url http://127.0.0.1/hapee_ticket_keys.txt delay 60s

At this point, the HAProxy Enterprise servers will query the above web server once every 60 seconds and update the three keys in memory.

As HAProxy Enterprise will use the middle of the three keys for encryption, slight variances in timing are acceptable, as the other HAProxy Enterprise servers will still be able to decrypt tickets from the other servers unless they miss two updates (since it's running every minute, even in unfavorable conditions this should not happen).

Next up

Update Module Reference