set ssl tls-key

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

The load balancer supports this command and TLS session tickets only up to TLS 1.2. TLS 1.3 uses a different mechanism called Pre-shared Keys (PKS). During the TLS handshake, the client and load balancer agree on which version of TLS to use based on their mutual support.

Description Jump to heading #

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 Jump to heading #

TLS session tickets are enabled by default in the load balancer 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 Jump to heading #

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

1. Create a directory to hold your secret keys:

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

   nix
   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:

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

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

   For versions 1.7r2 and earlier, use rand 48.

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.

   haproxy
   frontend fe_main
     bind :80
     bind :443 ssl  crt /etc/hapee-3.0/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

   haproxy
   frontend fe_main
     bind :80
     bind :443 ssl  crt /etc/hapee-3.0/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 Jump to heading #

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:

   nix
   echo "show tls-keys /etc/ssl/tls-ticket-keys/test.local.key" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "show tls-keys /etc/ssl/tls-ticket-keys/test.local.key" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   output
   text
   # 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=

   output
   text
   # 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

   nix
   echo "set ssl tls-key /etc/ssl/tls-ticket-keys/test.local.key $(openssl rand 80 | openssl base64 -A)" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "set ssl tls-key /etc/ssl/tls-ticket-keys/test.local.key $(openssl rand 80 | openssl base64 -A)" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   output
   text
   TLS ticket key updated!

   output
   text
   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:

   nix
   echo "show tls-keys /etc/ssl/tls-ticket-keys/test.local.key" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "show tls-keys /etc/ssl/tls-ticket-keys/test.local.key" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   output
   text
   # 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=

   output
   text
   # 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=

   The load balancer 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 Jump to heading #

• set ssl cert
• set ssl ocsp-response
• show tls-keys