HAProxy Enterprise Documentation 2.2r1

set ssl tls-key

Rotate the load balancer's session ticket encryption key used to encrypt TLS session tickets.

Description

When the load balancer and a client exchange messages over TLS, they share a secret key to encrypt their communication. This key is called a session key and it lasts only as long as the TLS session. Each new TLS session uses a unique key, which makes it difficult for an attacker to exploit.

Generating a session key costs the load balancer CPU time, which can add up when managing many clients. By asking each client to store their session key locally and reuse it between visits, the load balancer offloads some work and speeds up the time it takes to establish a TLS connection. The client can send their old session key to the load balancer to resume their session, negating the need to create a new one.

To make this secure, the load balancer uses a secret key known only to it to encrypt the session key in a package called a session ticket before sending it to the client. Only the load balancer can decrypt the ticket. The load balancer's secret key should be changed at least every 24 hours in case an attacker steals it.

The set ssl tls-key command rotates in a new secret key to replace the current one.

Examples

TLS session tickets are enabled by default in HAProxy Enterprise because they are enabled by default in the underlying OpenSSL library, which provides the load balancer's TLS features. Without any tuning, OpenSSL uses its own secret key, which it stores in memory, to encrypt session tickets. By defining your own secret key, you can share it across a cluster of load balancers, making it possible to operate in an active-active state. You also gain the ability to rotate the key using the set ssl tls-key command.

Generate initial secret keys

In this example, we generate secret keys for a website named test.local.

  1. Create a directory to hold your secret keys:

    $ sudo mkdir /etc/ssl/tls-ticket-keys

  2. Generate three secret keys and store them in the file /etc/ssl/tls-ticket-keys/test.local.key by calling the following command three times:

    $ echo "`openssl rand 80 | openssl base64 -A`" | \
   sudo tee -a /etc/ssl/tls-ticket-keys/test.local.key > /dev/null

  3. Add the tls-ticket-keys parameter to the bind line in the frontend or listen section of your configuration.

    This points to the file containing a list of secret keys to use upon startup.

    frontend fe_main
   bind :80
   bind :443 ssl  crt /etc/hapee-2.2/certs/site.pem  tls-ticket-keys /etc/ssl/tls-ticket-keys/test.local.key
   http-request redirect scheme https unless { ssl_fc }
   default_backend webservers

Rotate the secret key

Follow these steps to rotate in a new secret key for encrypting TLS session tickets:

  1. To view the current list of keys, call show tls-keys with the path to the key file:

    $ echo "show tls-keys /etc/ssl/tls-ticket-keys/test.local.key" | \
   sudo socat stdio unix-connect:/var/run/hapee-2.2/hapee-lb.sock
    # id secret
# 0 (/etc/ssl/tls-ticket-keys/test.local.key)
0.0 foNecGaN+zlgI3TlsT/pLJ9d7ZRoSZ2nmXZq29BSRWIErYTwK1RfZs3XfImaruR8ovJ1lAmZxiE2+tHSwypa7Cqq01hczTn2EN1C3anecys=
0.1 7VsH1P4H/N8MOLewQMOMOPjDa8ZCddHzLYe7JH/ydhg8JIO8yf1rg7JqAUbN2WoTzFlY0MhQKQSibARLQk1Ff0Ki12dma1/L7/W5xtgQANQ=
0.2 BiSBxvngSPguqzteXXxCk8WrnimwCSuOapx4koBv01Bei8N00HuJIBce8w324xsYhiUpxcF4RbR6nGoMXOf1LkboQykFPnohTYOgfy4SPFE=

  2. Create a new key by calling the set ssl tls-key command with two parameters:

    • the path to the key file

    • the openssl command to generate a new key

    $ echo "set ssl tls-key /etc/ssl/tls-ticket-keys/test.local.key $(openssl rand 80 | openssl base64 -A)" | \
   sudo socat stdio unix-connect:/var/run/hapee-2.2/hapee-lb.sock
    TLS ticket key updated!

  3. Call show tls-keys again to see that a new key has been added to the third row and the first two rows rotated down:

    $ echo "show tls-keys /etc/ssl/tls-ticket-keys/test.local.key" | \
   sudo socat stdio unix-connect:/var/run/hapee-2.2/hapee-lb.sock
    # id secret
# 0 (/etc/ssl/tls-ticket-keys/test.local.key)
0.0 7VsH1P4H/N8MOLewQMOMOPjDa8ZCddHzLYe7JH/ydhg8JIO8yf1rg7JqAUbN2WoTzFlY0MhQKQSibARLQk1Ff0Ki12dma1/L7/W5xtgQANQ=
0.1 BiSBxvngSPguqzteXXxCk8WrnimwCSuOapx4koBv01Bei8N00HuJIBce8w324xsYhiUpxcF4RbR6nGoMXOf1LkboQykFPnohTYOgfy4SPFE=
0.2 Miorn+tJ9KsYIgmNr4xQoJyBu6gcSe63BBXDTqSCEgUtIG8aGjiwnI+i3G4QcacFFBHZv0SY7EaIu5mhR++ECeoZENxoe4nSUQ0f+Cxlk1w=

    HAProxy Enterprise uses the second from the last key (the middle one) to encrypt new session tickets. The others are still used to decrypt older session tickets. If the key used to encrypt a session ticket no longer exists, the client creates a new session.

See also

Next up

set table