1.. Licensed to the Apache Software Foundation (ASF) under one
2   or more contributor license agreements.  See the NOTICE file
3   distributed with this work for additional information
4   regarding copyright ownership.  The ASF licenses this file
5   to you under the Apache License, Version 2.0 (the
6   "License"); you may not use this file except in compliance
7   with the License.  You may obtain a copy of the License at
8
9   http://www.apache.org/licenses/LICENSE-2.0
10
11   Unless required by applicable law or agreed to in writing,
12   software distributed under the License is distributed on an
13   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14   KIND, either express or implied.  See the License for the
15   specific language governing permissions and limitations
16   under the License.
17
18.. include:: ../../../common.defs
19
20.. _developer-plugins-ssl-session-hooks:
21
22.. default-domain:: c
23
24TLS Session Plugin API
25**********************
26
27These interfaces enable a plugin to hook into operations on the ATS TLS session cache.  ATS also provides API's
28to enable the plugin to update the session cache based on outside information, e.g. peer servers.
29
30.. macro:: TS_SSL_SESSION_HOOK
31
32This hook is invoked when a change has been made to the ATS session cache or a session has been accessed
33from ATS via openssl.  These hooks are only activated if the ATS implementation of the session cache is in
34use.  This means :ts:cv:`proxy.config.ssl.session_cache` has been set to 2.
35
36The hook callback has the following signature
37
38.. function:: int SSL_session_callback(TSCont contp, TSEvent event, void * edata)
39
40The edata parameter is a pointer to a :type:`TSSslSessionID`.
41
42This callback in synchronous since the underlying openssl callback is unable to pause processing.
43
44The following events can be sent to this callback
45
46.. macro:: TS_EVENT_SSL_SESSION_NEW
47
48   Sent after a new session has been inserted into the SSL session cache.  The plugin can call :func:`TSSslSessionGet` to retrieve the actual session object.  The plugin could communicate information about the new session to other processes or update additional logging or statistics.
49
50.. macro:: TS_EVENT_SSL_SESSION_GET
51
52   Sent after a session has been fetched from the SSL session cache by a client request.  The plugin could update additional logging and statistics.
53
54.. macro:: TS_EVENT_SSL_SESSION_REMOVE
55
56   Sent after a session has been removed from the SSL session cache.  The plugin could communication information about the session removal to other processes or update additional logging and statistics.
57
58Utility Functions
59******************
60
61A number of API functions will likely be used with this hook.
62
63* :func:`TSSslSessionGet`
64* :func:`TSSslSessionGetBuffer`
65* :func:`TSSslSessionInsert`
66* :func:`TSSslSessionRemove`
67* :func:`TSSslTicketKeyUpdate`
68
69Example Use Case
70****************
71
72Consider deploying a set of ATS servers as a farm behind a layer 4 load balancer.  The load balancer does not
73guarantee that all the requests from a single client are directed to the same ATS box.  Therefore, to maximize TLS session
74reuse, the servers should share session state via some external communication library like redis or rabbitmq.
75
76To do this, they write a plugin that sets the :macro:`TS_SSL_SESSION_HOOK`.  When the hook is triggered, the plugin function sends the
77updated session state to the other ATS servers via the communication library.
78
79The plugin also has thread that listens for updates and calls :func:`TSSslSessionInsert` and :func:`TSSslSessionRemove` to update the local session cache accordingly.
80
81The plugin can also engage in a protocol to periodically update the session ticket encryption key and communicate the new key to its
82peers.  The plugin calls :func:`TSSslTicketKeyUpdate` to update the local ATS process with the newest keys and the last N keys.
83