SSL DataScript events and APIs are introduced to add SSL Handshake level events to read or 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 address or 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 the server certificate for the connection.

  • Read and/or ignore mutual client authentication for specific errors.

  • Trigger client authentication based on URI requested using renegotiation.

SSL handshake events allow writing event-specific DataScript to control the flow of SSL handshakes, such as changing 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:

Event

Description

SSL_PRE_CONNECT

This event is triggered at the beginning of the TLS handshake. This event can be used for changing the SSL settings like SSL profile, SSL Key and Certificate 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



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

API

Description

avi.ssl.set_ssl_profile()

This API is used to change the SSL profile to a different profile based on factors like Client IP, TLS server name, and more.

avi.ssl.set_ssl_certificate()

This API is used to change the SSL key and certificate to a different object based on factors like Client IP, TLS server name, and more.

avi.ssl.set_pki_profile()

This API is used to change the PKI profile of the initial or the renegotiated TLS session based on factors like client IP, TLS server name, HTTP host or URI etc.

avi.ssl.clear_client_cert_verify_error()

This API is used to get the result of the client certificate authentication and CRL checks.

avi.ssl.renegotiate()

This API is used to renegotiate the TLS connection with the client after changing the PKI profile, mode and frequency based on factors like Client IP, TLS server name, HTTP host or URI and more.

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.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 client certificate verification is complete.

avi.ssl.clear_client_cert_verify_error()

This API is used to clear the 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 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 Layer 7 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 for 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.