SSL Session Reuse Plugin

This plugin coordinates session state data between ATS instances running in a group. This should improve TLS session reuse (both ticket and ID based) for a set of machines fronted by some form of layer 4 connection load balancer.

How It Works

The plugin coordinates TLS session reuse for both Session ID based resumption and ticket based resumption. For Session ID base resumption in uses the ATS SSL Session Cache for the local store of TLS sessions. It uses Redis to communication new sessions with its peers. When a new session is seen by an ATS instances it publishes an encrypted copy of the session state to the local Redis channel. When a new session is received on the Redis channel, the plugin stores that session state into its local ATS SSL session cache. Once the session state is in the local ATS SSL session cache it is available to the OpenSSL library for future TLS handshakes.

For the ticket based session resumption, the plugin implements logic to decide on a Session Ticket Encryption Key (STEK) master. The master will periodically create a new STEK key and use the Redis channel to publish the new STEK key to the other ATS boxes in the group. When the plugin starts up, it will publish a Redis message requesting the master to resend the STEK key. The plugin uses the TSSslTicketKeyUpdate call to update ATS with the last two STEK’s it has received.

All communication over the Redis channel is encrypted with a preshared key. All the ATS boxes participating in the session reuse must have access to that preshared key.

Building

This plugin uses Redis for communication. The hiredis client development library must be installed for this plugin to build. It can be installed in the standard system location or the install location can be specified by the –with-hiredis argument to configure.

As part of the experimental plugs, the –enable-experimental-plugins option must also be given to configure to build this plugin.

Deploying

The SSL Session Reuse plugin relies on Redis for communication. To deploy build your own redis server or use a standard rpm package. It must be installed on at least one box in the ATS group. We have it installed on two boxes in a failover scenario. The SSL Session Reuse configuration file describes how to communicate with the redis servers.

Config File

SSL Session Reuse is a global plugin. Its configuration file is given as a argument to the plugin.

  • redis.RedisEndpoints - This is a comma separated list of Redis servers to connect to. The description of the redis server may include a port

  • redis.RedisConnectTimeout - Timeout on the redis connect attempt in milliseconds.

  • redis.RedisRetryDelay - Timeout on retrying redis operations in milliseconds.

  • pubconfig.PubNumWorkers - Number of worker threads. Must be at least as many as the number of redis servers.

  • pubconfig.PubRedisPublishTries - Number of times to attempt publishing data

  • pubconfig.PubRedisConnectTries - Number of times to retry a redis connection attempt

  • pubconfig.PubMaxQueuedMessages - Maximum number of undelivered messages to leave in the queue

  • ssl_session.ClusterName - Name associated with the group of machines. Used to form basis of the redis channel name, e.g. Pool1

  • ssl_session.KeyUpdateInterval - How often to update the STEK key in seconds.

  • ssl_session.STEKMaster - If set to 1, the machine will assume it is the STEK master on startup

  • ssl_session.redis_auth_key_file - The location of the file containing the redis preshared secret.

  • subconfig.SubColoChannel - The redis channels to subscribe to, e.g. Pool1.*

Example Config File

#  Licensed to the Apache Software Foundation (ASF) under one
#  or more contributor license agreements.  See the NOTICE file
#  distributed with this work for additional information
#  regarding copyright ownership.  The ASF licenses this file
#  to you under the Apache License, Version 2.0 (the
#  "License"); you may not use this file except in compliance
#  with the License.  You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
#  Unless required by applicable law or agreed to in writing, software
#  distributed under the License is distributed on an "AS IS" BASIS,
#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#  See the License for the specific language governing permissions and
#  limitations under the License.

#
## start generic redis config parameters
# endpoints
redis.RedisEndpoints=host1.com:6379,host2.com:6379
# in milliseconds
redis.RedisConnectTimeout=20000
# in milliseconds
redis.RedisRetryDelay=5000000
## end generic redis config parameters

## start pub config settings
pubconfig.PubNumWorkers=5
pubconfig.PubRedisPublishTries=3
pubconfig.PubRedisConnectTries=3
pubconfig.PubMaxQueuedMessages=10000
pubconfig.PubColoChannelId=sja
## end pub config settings

## start subconfig settings
subconfig.SubColoChannel=sja.*
## end subconfig settings

#############################################################
# This config file contains the starting values for the
#  ATS plugin ats_ssl_session_reuse.
#  Upon pkg install, settings may have been derived from yinst settings
#############################################################
## start ssl_session settings
ssl_session.ClusterName=sja

#############################################################
# session-ticket-encryption-key (STEK) configs
# KeyUpdateInterval (in seconds)
#  Specifies frequency of STEK rotation in POD, if I am STEK Master
#  maximum is 86400 (24 hours),  default is 25200 (7 hours)

ssl_session.KeyUpdateInterval=25200

# STEKMaster= 1 (This instance will start as the STEK Master, initiating rotation)
#          or 0 (start as STEK slave)
ssl_session.STEKMaster=0

ssl_session.redis_auth_key_file=/path/to/key/file

## end ssl_session settings