TLS Session Plugin API

These interfaces enable a plugin to hook into operations on the ATS TLS session cache. ATS also provides API's to enable the plugin to update the session cache based on outside information, e.g. peer servers.

enumerator TS_SSL_SESSION_HOOK

This hook is invoked when a change has been made to the ATS session cache or a session has been accessed from ATS via OpenSSL. These hooks are only activated if the ATS implementation of the session cache is in use. This means proxy.config.ssl.session_cache.enabled has been set to 2.

The hook callback has the following signature

int SSL_session_callback(TSCont contp, TSEvent event, void *edata)

The edata parameter is a pointer to a TSSslSessionID.

This callback in synchronous since the underlying OpenSSL callback is unable to pause processing.

The following events can be sent to this callback

enumerator TS_EVENT_SSL_SESSION_NEW

Sent after a new session has been inserted into the SSL session cache. The plugin can call 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.

enumerator TS_EVENT_SSL_SESSION_GET

Sent after a session has been fetched from the SSL session cache by a client request. The plugin could update additional logging and statistics.

enumerator TS_EVENT_SSL_SESSION_REMOVE

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.

Utility Functions

A number of API functions will likely be used with this hook.

• TSSslSessionGet()

• TSSslSessionGetBuffer()

• TSSslSessionInsert()

• TSSslSessionRemove()

• TSSslTicketKeyUpdate()

Example Use Case

Consider deploying a set of ATS servers as a farm behind a layer 4 load balancer. The load balancer does not guarantee that all the requests from a single client are directed to the same ATS box. Therefore, to maximize TLS session reuse, the servers should share session state via some external communication library like redis or rabbitmq.

To do this, they write a plugin that sets the TS_SSL_SESSION_HOOK. When the hook is triggered, the plugin function sends the updated session state to the other ATS servers via the communication library.

The plugin also has thread that listens for updates and calls TSSslSessionInsert() and TSSslSessionRemove() to update the local session cache accordingly.

The plugin can also engage in a protocol to periodically update the session ticket encryption key and communicate the new key to its peers. The plugin calls TSSslTicketKeyUpdate() to update the local ATS process with the newest keys and the last N keys.