SSL DataScript Events and APIs

Overview

SSL DataScript Events and APIS are introduced to add SSL Handshake level events to read/write parameters to control the SSL handshake and change attributes like SSL profile, certificates, PKI settings, renegotiate, and more.

With this feature, for a specific client IP/ port, you can:

  • Change SSL handshake attributes like restricting TLS protocol versions and/or ciphers and other configuration parameters.
  • Change PKI settings like mode or CA certificates used for the TLS connection.
  • Change server certificate for the connection
  • Read and/or ignore Client mutual authentication for specific errors.
  • Trigger client authentication based on URI requested using renegotiation.
  • Fetch SSL handshake attributes like SSL server name, session-id, master key, next proto, etc for use within the DataScript.

SSL handshake events allow writing event-specific data scripts to control the flow of SSL handshakes such as change SSL profile settings, server certificates, and other operations such as IP/URI-based client authentication, SSL header insertion, and more.

SSL Handshake Flow

The following key events facilitate customizing the flow of the SSL handshake through SSL DataScript API. The APIs are specific only to the respective events:

  • SSL_PRE_CONNECT: This event is triggered at the beginning of TLS handshake. This event can be used for changing the SSL settings like SSL profile, SSLKeyandCertificate and PKI profile based on Client IP or VS service port etc.

  • SSL_Client_Hello: This event is triggered after client hello pre-processing is done. This event is used for changing the SSL settings like SSL profile, SSLKeyandCertificate and PKI profile based on Client IP or VS service port etc.

  • SSL_HANDSHAKE_DONE: This event is triggered after the TLS handshake is complete. This event can be used for getting client certificate authentication errors and logging

The virtual service DataScript events in the flow are as below:

  • VS_DATASCRIPT_EVT_CLIENT_SSL_PRE_CONNECT

  • VS_DATASCRIPT_EVT_CLIENT_SSL_CLIENT_HELLO

  • VS_DATASCRIPT_EVT_SSL_HANDSHAKE_DONE

handshake

The following DataScript APIs are introduced to be executed within the events listed above:

API Description
avi.ssl.set_ssl_profile() This API can be used to change the SSL profile to a different profile based on some factors like Client IP, TLS servername, and more
avi.ssl.set_ssl_certificate This API can be used to change the SSL key and certificate to a different object based on factors like Client IP, TLS servername, and more
avi.ssl.set_pki_profile This API can be used to change the PKI profile of the initial or the renegotiated TLS session based on factors like Client IP, TLS servername, HTTP host or URI etc.
avi.ssl.renegotiate() This API can be used to renegotiate TLS connection with the client after changing the PKI profile, mode and frequency based on factors like Client IP, TLS servername, HTTP host or URI and more
avi.ssl.client_cert_verify_error() This API is used to get the result of the client certificate authentication and CRL checks.
avi.ssl.client_cert_verify_error_string() This API accepts a verify error code and returns an error string associated with that error code
avi.ssl.get_client_cert_verify_mode() This API is used to get the client certificate authentication mode.
avi.ssl.client_cert_verified() This API is used to find out whether if client certificate verification is complete.
avi.ssl.clear_client_cert_verify_error() This API is used to clear SSL client certificate verification error on the TLS connection
avi.ssl.log_client_cert_verify_error() This API is used to log the client certificate authentication failure. The error is added to the application log as a significance.
avi.ssl.remove_session() This API is used to clear SSL session cache entry of the TLS connection

Caveats

  • These events and APIs are supported only on L7 virtual services

  • Enhanced Virtual Hosting (EVH) child does not support the SSL events

  • FIPS does not support SSL Client Hello events

  • Avi.ssl.renegotiate() is not supported on the following connections:

    • TLS1.3 connection.
    • HTTP/2.0

In the event of execution of the API, the TLS or HTTP/2.0 connection will fail.

Date Change Summary
August 06, 2020 Published the SSL DataScript Events and APIs Guide