| .. 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. |
| |
| .. include:: ../../common.defs |
| |
| .. _admin-plugins-ssl_session_reuse: |
| |
| 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. |
| |
| * :ts:cv:`proxy.config.ssl.session_cache` should be set to 2 to enable the ATS implementation of session cache |
| * :ts:cv:`proxy.config.ssl.session_cache.size` and :ts:cv:`proxy.config.ssl.session_cache.num_buckets` may need to be adjusted to ensure good hash table performance for your workload. For example, we needed to increase the number of buckets to avoid long hash chains. |
| * :ts:cv:`proxy.config.ssl.server.session_ticket.enable` should be set to 1 to enable session ticket support. |
| |
| |
| 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 |
| =================== |
| |
| .. literalinclude:: ../../../plugins/experimental/ssl_session_reuse/example_config.config |