TLS User Agent Hooks

In addition to the HTTP oriented hooks, a plugin can add hooks to trigger code during the TLS handshake with the user agent. This TLS handshake occurs well before the HTTP transaction is available, so a separate state machine is required to track the TLS hooks.

TLS Hooks

In all cases, the hook callback has the following signature.

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

The edata parameter is a TSVConn object.

The following actions are valid from these callbacks.

TS_VCONN_START_HOOK

This hook is invoked after the client has connected to ATS and before the SSL handshake is started, i.e., before any bytes have been read from the client. The data for the callback is a TSVConn instance which represents the client connection. There is no HTTP transaction as no headers have been read.

In theory this hook could apply and be useful for non-SSL connections as well, but at this point this hook is only called in the SSL sequence.

The TLS handshake processing will not proceed until TSSslVConnReenable() is called either from within the hook callback or from another piece of code.

TS_VCONN_CLOSE_HOOK

This hook is invoked after the SSL handshake is done and when the IO is closing. The TSVConnArgs should be cleaned up here.

TS_SSL_SERVERNAME_HOOK

This hook is called if the client provides SNI information in the SSL handshake. If called it will always be called after TS_VCONN_START_HOOK.

The Traffic Server core first evaluates the settings in the ssl_multicert.config file based on the server name. Then the core SNI callback executes the plugin registered SNI callback code. The plugin callback can access the servername by calling the openssl function SSL_get_servername().

Processing will continue regardless of whether the hook callback executes TSSslVConnReenable() since the openssl implementation does not allow for pausing processing during the openssl servername callback.

TS_SSL_CERT_HOOK

This hook is called as the server certificate is selected for the TLS handshake. The plugin callback can execute code to create or select the certificate that should be used for the TLS handshake. This will override the default Traffic Server certificate selection.

If you are running with openssl 1.0.2 or later, you can control whether the TLS handshake processing will continue after the certificate hook callback execute by calling TSSslVConnReenable() or not. The TLS handshake processing will not proceed until TSSslVConnReenable() is called.

It may be useful to delay the TLS handshake processing if other resources must be consulted to select or create a certificate.

TS_SSL_VERIFY_CLIENT_HOOK

This hook is called when a client connects to Traffic Server and presents a client certificate in the case of a mutual TLS handshake. The callback can get the SSL object from the TSVConn argument and use that to access the client certificate and make any additional checks.

Processing will continue regardless of whether the hook callback executes TSSslVConnReenable() since the openssl implementation does not allow for pausing processing during the certificate verify callback.

TS_SSL_VERIFY_SERVER_HOOK

This hooks is called when a Traffic Server connects to an origin and the origin presents a certificate. The callback can get the SSL object from the TSVConn argument and use that to access the origin certificate and make any additional checks.

Processing will continue regardless of whether the hook callback executes TSSslVConnReenable() since the openssl implementation does not allow for pausing processing during the certificate verify callback.

TLS Hook State Diagram

TLS Hook State Diagram