This topic details the specifications for DataScript SSL functions available on NSX Advanced Load Balancer .

Function

Description

avi.ssl.cipher( [true] )

Return the SSL ciphers and settings.

#GUID-461EA45A-175C-41F8-BD58-FE8E59FD72D0__SECTION_233498DF-AE60-4D61-A518-ABDFD5174105

 Terminates the request or closes the connection when using the allow_invalid_client_cert flag set to True.

avi.ssl.client_cert( [ [avi.CLIENT_CERT] [, avi.CLIENT_CERT_FINGERPRINT] [, avi.CLIENT_CERT_SUBJECT] [, avi.CLIENT_CERT_ISSUER] [, avi.CLIENT_CERT_SERIAL]] )

Returns the client's certificate, or part of it.

avi.ssl.protocol()

Return the SSL version.

avi.ssl.server_name()

Return SNI name field.

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 server name, 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.clear_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.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 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 log.

avi.ssl.remove_session()

This API is used to clear SSL session cache entry of the TLS connection.

datascript-avi-ssl-client-cert-verify-error()

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

avi.ssl.cipher_len()

This API is used to determine the length of the cipher suite negotiated for the SSL or TLS connection between the client and the virtual service.

avi.ssl.client_cert()

This API is used to get the client certificate in the PEM format for an established SSL connection.

avi.ssl.cipher

Function

avi.ssl.cipher( [true] )

Description

Returns the name of the cipher suite negotiated for the SSL/TLS connection between the client and the virtual service and may optionally include the version, key exchange method (Kx), authentication method (Au), encryption method (Enc), and MAC selected (Mac). The returned cipher suite information is in OpenSSL format. See www.openssl.org/docs/manmaster/apps/ciphers.html for examples of OpenSSL formatted cipher suites.

Events

HTTP_REQ

HTTP_RESP

Parameter

Optional boolean true. When this parameter is not specified, only the cipher suite name is returned. When the true flag is set, this function returns cipher suite, version, authentication method, encryption method, and MAC selected. These values are presented as a space-separated string.

Returns

A string value containing the cipher information for the SSL/TLS connection. When the true flag is set, values are returned as a space-separated string.

Example 1

Deny clients connecting with unsupported ciphers.

cipher_name = avi.ssl.cipher() 
if cipher_name == "RC4-SHA" then
   avi.http.response(200, {content_type="text/html"}, 
      "Upgrade your client to use modern and secure ciphers."
   )
end

Example 2

Insert a header to the server indicating the key exchange method negotiated with the client.

cipher = avi.ssl.cipher(true)
   ­­-- get the key exchange method from the cipher detail using pattern matching
   ­­-- %w matches alphanumeric characters
kx = string.match(cipher, "Kx=(%w+)")

if kx then
   avi.http.add_header("X-­KeyExchange", kx)
end

avi.ssl.check_client_cert_validity()

Function avi.ssl.check_client_cert_validity()
Description Reports the client certifivcate validation outcomes.
Parameter None
Returns
This DataScript function returns one of the following values :
  • 0 indicates when the certificate is not presented by the client.
  • 1 indicates when the certificate is presented by the client and gets successfully validated.
  • 2 indicates when the certificate is presented by the client but is not valid.
Example 
if avi.ssl.check_client_cert_validity()==1 then 
    avi.http.response(200, {}, "cert_presented_and_valid") 
end

if avi.ssl.check_client_cert_validity()==0 then 
    avi.http.response(200, {}, "cert_not_presented") 
end 

if avi.ssl.check_client_cert_validity()>=2 then 
    avi.http.response(200,{},"Invalid Certificate presented") 
end

avi.ssl.client_cert

Function

avi.ssl.client_cert( [ [avi.CLIENT_CERT], [avi.CLIENT_CERT_FINGERPRINT], [avi.CLIENT_CERT_SUBJECT], [avi.CLIENT_CERT_ISSUER], [avi.CLIENT_CERT_SERIAL], [avi.CLIENT_CERT_NOTVALIDBEFORE], [avi.CLIENT_CERT_NOTVALIDAFTER], [avi.CLIENT_CERT_VERSION], [avi.CLIENT_CERT_SIGALG], [avi.CLIENT_CERT_ESCAPED], [avi.CLIENT_CERT_SAN_EXTENSION], [avi.CLIENT_CERT_X509_EXTENSIONS] ] )

Description

Returns the client certificate in the PEM format for an established SSL connection. Optional parameters will filter the fields returned from the client certificate.

Events

HTTP_REQ

HTTP_RESP

Parameter

Returns the client certificate in the PEM format for an established SSL connection from the client to the virtual service when no argument or avi.CLIENT_CERT is specified, with each line except the first prepended with the tab character.

  • avi.CLIENT_CERT_NOTVALIDBEFORE: Returns the not valid before time from the client certificate.

  • avi.CLIENT_CERT_NOTVALIDAFTER: Returns the not valid after time from the client certificate.

  • avi.CLIENT_CERT_VERSION: Returns the version number of the client certificate.

  • avi.CLIENT_CERT_SIGALG: Returns the signature algorithm of the client certificate.

  • avi.CLIENT_CERT_SUBJECT: Returns the subject DN string.

  • avi.CLIENT_CERT_ISSUER: Returns the issuer DN string.

  • avi.CLIENT_CERT_SERIAL: Returns the serial number.

  • avi.CLIENT_CERT_FINGERPRINT: Returns the SHA1 fingerprint (hash) of the certificate.

Returns

Up to nine arguments pertaining to the client certificate and its fields.

Example 1

If the certificate's issuer is not correct, add the issuer to a header and forward to a quarantine server pool.

 if avi.ssl.client_cert(avi.CLIENT_CERT_ISSUER) ~=
    "/C=US/O=foo/OU=www.foo.com/CN=www.foo.com/[email protected]" then
    avi.http.add_header("client_cert_issuer", 
       avi.ssl.client_cert(avi.CLIENT_CERT_ISSUER))
    avi.pool.select("Quarantine-Pool")
 end

Example 2

Logs the client certificate attributes for the SSL connection.

if avi.http.secure() then -- test if the connection is secure
   fingerprint = avi.ssl.client_cert(avi.CLIENT_CERT_FINGERPRINT)
   avi.vs.log(fingerprint)
end

avi.ssl.protocol

Function

avi.ssl.protocol()

Description

Returns the protocol of an established SSL connection. For example: TLSv1.1.

Events

HTTP_REQ

HTTP_RESP

Parameter

None

Returns

Returns a string of the SSL/TLS version or unknown

Example

 
if avi.ssl.protocol() == "TLSv1.0" then
   avi.http.response(404, {content_type="text/html"},
   "Your browser's SSL version, " .. avi.ssl.protocol() .. " is old. Upgrade your browser and try again.")
end

avi.ssl.server_name

Function

avi.ssl.protocol()

Description

Returns the protocol of an established SSL connection. For example: TLSv1.1.

Events

HTTP_REQ

HTTP_RESP

Parameter

None

Returns

A string of the requested SNI name.

Example

Insert a header declaring the SNI name requested by the client.

avi.http.add_header("X-SNI ", avi.ssl.server_name())

avi.ssl.set_ssl_profile

Function

avi.ssl.set_ssl_profile(<SSL Profile Name>)

Description

This function is used to change the SSL profile to a different profile based on some factors like Client IP address, TLS servername, and more.

Events

VS_DATASCRIPT_EVT_CLIENT_SSL_PRE_CONNECTVS_DATASCRIPT_EVT_CLIENT_SSL_CLIENT_HELLO

Parameter

Name of the SSL parameter

Returns

None

Example

 
if avi.ssl.server_name() == "legacy.example.com" then
 avi.ssl.set_ssl_profile("legacy_ssl_profile") end

If avi.ssl.server_name() points to legacy.example.com, then the profiles for those TLS connections will be changed to legacy_ssl_profile.

avi.ssl.set_ssl_certificate

Function

avi.ssl.set_ssl_certificate(<SSLKeyAndCertificate>)

Description

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

Events

VS_DATASCRIPT_EVT_CLIENT_SSL_PRE_CONNECTVS_DATASCRIPT_EVT_CLIENT_SSL_CLIENT_HELLO

Parameter

Name of the SSL Key and certificate object.

Returns

None

Example

 
if avi.ssl.server_name() == "legacy.example.com" then 
    avi.ssl.set_ssl_certificate("RSACertificate")
    avi.ssl.set_ssl_certificate("ECCertificate")
end

avi.ssl.set_pki_profile

Function

avi.ssl.set_pki_profile{(<Mode>[<pkiprofilename><frequency>)

Description

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

  • avi.CLIENT_VERIFY_DISABLE must be used without PKI profile name and frequency parameters in the API call.

  • avi.CLIENT_VERIFY_REQUEST can be used without PKI profile name and frequency parameters in the API call.

  • avi.CLIENT_VERIFY_REQUIREmust be used with the PKI Profile name and optionally with frequency parameters in the API call.

PKI configuration from the DataScript takes precedence over the configuration from the application profile.

Events

VS_DATASCRIPT_EVT_CLIENT_SSL_PRE_CONNECT​VS_DATASCRIPT_EVT_CLIENT_SSL_CLIENT_HELLO​​VS_DATASCRIPT_EVT_HTTP_REQVS_DATASCRIPT_EVT_HTTP_REQ_DATA

Parameter

Currently, in the application profile, there are two knobs. One knob controls the mode, and the other knob controls the PKI profile object.

The API is a mode (mandatory) with a profile name (optional) and frequency of authentication (optional) parameter. The following are the three modes supported:

  • Mode of Client Authentication: avi.CLIENT_VERIFY_NONEavi.CLIENT_VERIFY_REQUESTavi.CLIENT_VERIFY_REQUIRE

  • Name of the PKI profile object

  • Frequency of the authentication avi.AUTHENTICATE_ONLY_ONCEavi.AUTHENTICATE_ONLY_ALWAYS

Returns

None

Example

 
To disable client certificate authentication

if avi.ssl.server_name() == "legacy.example.com" then 
    avi.ssl.set_pki_profile(avi.CLIENT_VERIFY_DISABLE) 
end

Here, the client verififcation for the PKI profile is disabled on this TLS server connections. To change client certificate authentication settings.

if avi.ssl.server_name() == "secure.example.com" then 
    avi.ssl.set_pki_profile(avi.CLIENT_VERIFY_REQUIRE, "pkiprofile-crl", avi.AUTHENTICATE_ONLY_ONCE) 
else
    avi.ssl.set_pki_profile(avi.CLIENT_VERIFY_REQUEST) 
end

If the TLS Server name is secure.example.com and the PKI profile is mandatory, then the client verification is marked as required, the PKI profile as CRL, and authenticated once. Use avi.ssl.set_pki_profile with just avi.CLIENT_VERIFY_REQUEST if you want to request a certificate from the client and log the details in further events like an HTTP request.
Note:

Since the PKI configuration can be done through the application profile and DataScripts, during execution, the PKI profile configured through DataScript takes precedence over the configuration made through the Application Profile.

For example, if the PKI profile is configured to mark the certificate as required, but if through DataScripts the PKI profile for a specific server name is marked to be disabled, this will override the application profile configuration.

avi.ssl.renegotiate

Function

avi.ssl.renegotiate()

Description

This function renegotiates 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, etc.​ If client certificate authentication is enabled before the renegotiate API call, the PKI settings are applied to the SSL session renegotiation. HTTP requests will be parked until renegotiation is complete.

SSL renegotiation will disable SSL session resumption on the connection.

Note:

If using renegotiation after changing PKI settings on the connection, the user's script must handle the result of the client authentication. Otherwise, the subsequent request on the TLS connection could fail. The script could either choose to clear the error or close the connection.

Events

VS_DATASCRIPT_EVT_HTTP_REQ

VS_DATASCRIPT_EVT_HTTP_REQ_DATA

Parameter

None

Returns

None

Example

To disable client certificate authentication:

if string.contains(avi.http.get_uri(), \"secure\") then 
   avi.ssl.set_pki_profile(avi.CLIENT_VERIFY_REQUIRE, "pkiprofile-ca", avi.AUTHENTICATE_ONLY_ONCE) 
   avi.ssl.renegotiate() 
   verify_err, error_code = avi.ssl.client_cert_verify_error()
    if  verify_err == 0 or (verify_err == 2 and error_code ~= 0) then
       avi.http.close_connection()
 end 
end

Here, we are checking for a specific URI, then changing the PKI attributes and doing an SSL renegotiate. Then, if there is an error, close the connections.
Caution:

  • In case there is an error but you have decided not to close the connection, then rectify the error. If you do not clear the error, subsequent requests might go into a path where the DataScript is not chit considered, and the native request flow closes the connection due to the error.

  • Renegotiation does not work with HTTP2 Protocol and TLS1.3 protocol.

avi.ssl.clear_client_cert_verify_error

Function

avi.ssl.clear_client_cert_verify_error()

Description

This function can be used to clear the SSL client certificate verification error on the TLS connection. Internally, the API sets 'X509_V_OK' for verify_result on the TLS connection.

Events

VS_DATASCRIPT_EVT_SSL_HANDSHAKE_DONE

VS_DATASCRIPT_EVT_HTTP_REQ

VS_DATASCRIPT_EVT_HTTP_REQ_DATA

Parameter

None

Returns

No value

Example

 
if avi.ssl.server_name() == "secure.example.com" && avi.ssl.get_client_cert_verify_mode() == 0 then ​

   avi.ssl.set_pki_profile(avi.CLIENT_VERIFY_REQUIRE, "pkiprofile-ca", avi.AUTHENTICATE_ONLY_ONCE)​

   avi.ssl.renegotiate()​

   verify_err, err_code = avi.ssl.client_cert_verify_error()​

   if err_code ~= 0 and avi.ssl.client_cert_verify_error_string(err_code) == 'X509_V_ERR_CRL_HAS_EXPIRED' then ​

         avi.ssl.clear_client_cert_verify_error()​

   end​

end​

avi.ssl.client_cert_verify_error_string

Function

avi.ssl.clear_client_cert_verify_error_string()

Description

This API accepts a verify error code and returns an error string associated with that error code

Events

VS_DATASCRIPT_EVT_SSL_HANDSHAKE_DONE

VS_DATASCRIPT_EVT_HTTP_REQ

VS_DATASCRIPT_EVT_HTTP_REQ_DATA

Parameter

One integer argument as client cert verify error()

Returns

This DataScript function returns error strings given the verify error code from OpenSSL verify documentation to understand the specific meaning of these error codes returned by SSL stack.

Example

 
if avi.ssl.server_name() == "secure.example.com" then 
    avi.ssl.set_pki_profile(avi.CLIENT_VERIFY_REQUIRE, "pkiprofile-ca", avi.AUTHENTICATE_ONLY_ONCE)
    avi.ssl.renegotiate()
    verify_err, error_code = avi.ssl.client_cert_verify_error()
    if  verify_err == 0 or (verify_err == 2 and avi.ssl.client_cert_verify_error_string(error_code) ~= 'X509_V_OK') then
        avi.http.close_connection()   
    end
end

avi.ssl.client_cert_verify_mode

Function

avi.ssl.get_client_cert_verify_mode()

Description

This DataScript function is used to get the client certificate authentication mode

Events

VS_DATASCRIPT_EVT_SSL_HANDSHAKE_DONE

VS_DATASCRIPT_EVT_HTTP_REQ

VS_DATASCRIPT_EVT_HTTP_REQ_DATA

Parameter

None

Returns

This DataScript function returns one of the following values :

  • 0 indicates the client certificate authentication is either not activated or deactivated.

  • 1 indicates that the client certificate authentication is in REQUIRE mode

  • 2 indicates that the client certificate authentication is in REQUEST mode with the PKI profile

  • 3 indicates that the client certificate authentication is in REQUEST mode without the PKI profile

Example

 
if avi.ssl.server_name() == "secure.example.com" && avi.ssl.get_client_cert_verify_mode() == 0 then
     avi.ssl.set_pki_profile(avi.CLIENT_VERIFY_REQUIRE, "pkiprofile-ca", avi.AUTHENTICATE_ONLY_ONCE)
     avi.ssl.renegotiate()
end

avi.ssl.client_cert_verified

Function

avi.ssl.client_cert_verified()

Description

This DataScript function is used to find if the client certificate verification is completed.

Events

VS_DATASCRIPT_EVT_SSL_HANDSHAKE_DONE

VS_DATASCRIPT_EVT_HTTP_REQ

VS_DATASCRIPT_EVT_HTTP_REQ_DATA

Parameter

None

Returns

This DataScript function returns one of the following values:

  • 0 indicates

    • The connection is not SSL enabled.

    • NSX Advanced Load Balancer did not request for a client certificate.

    • The client did not present a certificate.

    • Client certificate validation has failed.

  • 1 indicates that the client certificate validation has passed.

Example

 
if avi.ssl.server_name() == "secure.example.com" && avi.ssl.client_cert_verified() == 0 then 
   avi.ssl.set_pki_profile(avi.CLIENT_VERIFY_REQUIRE, "pkiprofile-ca", avi.AUTHENTICATE_ONLY_ONCE)
   avi.ssl.renegotiate()
end

avi.ssl.clear_client_cert_verify_error

Function

avi.ssl.clear_client_cert_verify_error()

Description

This function can be used to clear the SSL client certificate verification error on the TLS connection. Internally, the API sets 'X509_V_OK' for verify_result on the TLS connection.

Events

VS_DATASCRIPT_EVT_SSL_HANDSHAKE_DONE

VS_DATASCRIPT_EVT_HTTP_REQ

VS_DATASCRIPT_EVT_HTTP_REQ_DATA

Parameter

None

Returns

No Value

Example

 
if avi.ssl.server_name() == "secure.example.com" && avi.ssl.get_client_cert_verify_mode() == 0 then ​

   avi.ssl.set_pki_profile(avi.CLIENT_VERIFY_REQUIRE, "pkiprofile-ca", avi.AUTHENTICATE_ONLY_ONCE)​

   avi.ssl.renegotiate()​

   verify_err, err_code = avi.ssl.client_cert_verify_error()​

   if err_code ~= 0 and avi.ssl.client_cert_verify_error_string(err_code) == 'X509_V_ERR_CRL_HAS_EXPIRED' then ​

         avi.ssl.clear_client_cert_verify_error()​

   end​

end​

avi.ssl.log_client_cert_verify_error

Function

avi.ssl.log_client_cert_verify_error()

Description

This DataScript function is used for logging the client certificate authentication failure. The error is added to the application log as a significance log.

For example, client certificate verification failed: client x509 certificate verification failed.

Events

VS_DATASCRIPT_EVT_SSL_HANDSHAKE_DONE

VS_DATASCRIPT_EVT_HTTP_REQ

VS_DATASCRIPT_EVT_HTTP_REQ_DATA

Parameter

None

Returns

None

Example

 
if avi.ssl.server_name() == "secure.example.com" &&
avi.ssl.get_client_cert_verify_mode() ~= 0 then
     avi.ssl.log_client_cert_verify_error()
end

avi.ssl.remove_session

Function

avi.ssl.remove_session()

Description

This API is be used to clear SSL session cache entry of the TLS connection.

Events

VS_DATASCRIPT_EVT_SSL_HANDSHAKE_DONEVS_DATASCRIPT_EVT_HTTP_REQVS_DATASCRIPT_EVT_HTTP_REQ_DATA

Parameter

None

Returns

None

Example

 
if string.contains(avi.http.get_uri(), \"logout.html\") then 
          avi.ssl.remove_session()
end

avi.ssl.get_client_cert_verify_mode

Function

avi.ssl.get_client_cert_verify_mode()

Events

VS_DATASCRIPT_EVT_SSL_HANDSHAKE_DONEVS_DATASCRIPT_EVT_HTTP_REQVS_DATASCRIPT_EVT_HTTP_REQ_DATA

Parameter

None

Returns

This DataScript function returns one of the following values:

  • 0 indicates the client certificate authentication is either not enabled or disabled.

  • 1 indicates that the client certificate authentication is in REQUIRE mode

  • 2 indicates that the client certificate authentication is in REQUEST mode with the PKI profile

  • 3 indicates that the client certificate authentication is in REQUEST mode without PKI profile

Example

 
if avi.ssl.server_name() == "secure.example.com" && avi.ssl.get_client_cert_verify_mode() == 0 then
     avi.ssl.set_pki_profile(avi.CLIENT_VERIFY_REQUIRE, "pkiprofile-ca", avi.AUTHENTICATE_ONLY_ONCE)
     avi.ssl.renegotiate()
end

avi.ssl.cipher_len

Function

avi.ssl.cipher_len()

Description

Returns the length of the cipher suite negotiated for the SSL/TLS connection between the client and the virtual service.

Parameter

None

Events

  • SSL_HANDSHAKE_DONE

  • L4_REQUEST

  • HTTP_AUTH

  • HTTP_POST_AUTH

  • HTTP_REQ

  • HTTP_REQ_BODY

  • LB_DONE

  • HTTP_RESP

  • HTTP_RESP_FAILED

  • HTTP_RESP_BODY

Example

 
-- Cipher selected is ECDHE-RSA-AES128-GCM-SHA256
cipher_len = avi.ssl.cipher_len()

-- cipher_len = 128
avi.vs.log("Cipher length: "..cipher_len)
Note:

This API is not supported in the events SSL_PRECONNECT and SSL_CLIENTHELLO.

datascript-avi-ssl-client-cert-verify-error

Function

avi.ssl.client_cert_verify_error()

Description

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

Parameter

None

Events

  • VS_DATASCRIPT_EVT_SSL_HANDSHAKE_DONE

  • VS_DATASCRIPT_EVT_HTTP_REQ

  • VS_DATASCRIPT_EVT_HTTP_REQ_DATA

Returns

This API returns two values:

  1. First return value of:

    1. 0 - indicates client did not present a certificate

    2. 1 - indicates client's certificate is valid

    3. 2 - indicates client's certificate is invalid

  2. Second return value is for a specific error code. If first return value is 2, see OpenSSL verify documentation to understand the specific meaning of these error codes returned by SSL stack.

Example

 
if avi.ssl.server_name() == "secure.example.com" then 
    avi.ssl.set_pki_profile(avi.CLIENT_VERIFY_REQUEST, "pkiprofile-ca", avi.AUTHENTICATE_ONLY_ONCE)
    avi.ssl.renegotiate()
    verify_err, error_code = avi.ssl.client_cert_verify_error()
    if  verify_err == 0 or (verify_err == 2 and error_code ~= 0) then
        avi.http.close_connection()
    end
end

avi.ssl.client_cert

Function

avi.ssl.client_cert( [[avi.CLIENT_CERT] [, avi.CLIENT_CERT_FINGERPRINT] [, avi.CLIENT_CERT_SUBJECT] [, avi.CLIENT_CERT_ISSUER] [, avi.CLIENT_CERT_SERIAL][, avi.CLIENT_CERT_NOTVALIDBEFORE] [, avi.CLIENT_CERT_NOTVALIDAFTER] [, avi.CLIENT_CERT_VERSION][, avi.CLIENT_CERT_SIGALG][, avi.CLIENT_CERT_ESCAPED] avi.CLIENT_CERT_SAN_EXTENSION] [, avi.CLIENT_CERT_X509_EXTENSIONS] ] )

Description

Returns the client certificate in the PEM format for an established SSL connection. Optional parameters will filter the fields returned from the client certificate.

Events

  • HTTP_REQ

  • HTTP_RESP

  • SSL_HANDSHAKE_DONE

  • HTTP LB Done

Parameters

When no argument or avi.CLIENT_CERT is specified, returns the client certificate in the PEM format for an established SSL connection from the client to the virtual service, with each line except the first prepended with the tab character.

  • avi.CLIENT_CERT_NOTVALIDBEFORE: Returns the not valid before time from the client certificate.

  • avi.CLIENT_CERT_NOTVALIDAFTER: Returns the not valid after time from the client certificate.

  • avi.CLIENT_CERT_VERSION: Returns the version number of the client certificate.

  • avi.CLIENT_CERT_SIGALG: Returns the signature algorithm of the client certificate.

  • avi.CLIENT_CERT_SUBJECT: Returns the subject DN string.

  • avi.CLIENT_CERT_ISSUER: Returns the issuer DN string.

  • avi.CLIENT_CERT_SERIAL: Returns the serial number.

  • avi.CLIENT_CERT_FINGERPRINT: Returns the SHA1 fingerprint (hash) of the cert.

  • avi.CLIENT_CERT_ESCAPED: Returns the encoded PEM certificate.

  • avi.CLIENT_CERT_SAN_EXTENSIONS: Returns the Subject Alternative Name (SAN) extension in the client certificate.

  • avi.CLIENT_CERT_X509_EXTENSIONS: Returns all x509 extensions in the client certificate.

Returns

Up to nine arguments, pertaining to the client cert and its fields.

Example 1

If the certificate issuer is not correct, add the issuer to a header and forward to a quarantine server pool.

if avi.ssl.client_cert(avi.CLIENT_CERT_ISSUER) ~=
    "/C=US/O=foo/OU=www.foo.com/CN=www.foo.com/[email protected]" then
    avi.http.add_header("client_cert_issuer", 
       avi.ssl.client_cert(avi.CLIENT_CERT_ISSUER))
    avi.pool.select("Quarantine-Pool")
 end

Example 2

Logs the client cert attributes for the SSL connection.

if avi.http.secure() then -- test if the connection is secure
   fingerprint = avi.ssl.client_cert(avi.CLIENT_CERT_FINGERPRINT)
   avi.vs.log(fingerprint)
end

Example 3

When you send a client certificate in a HTTP request, the client escaped certificate in displayed in the DS/HTTP policy header.

 escaped_cert = avi.ssl.client_cert(avi.CLIENT_CERT_ESCAPED)
  avi.vs.log(escaped_cert)
  avi.http.add_header("escaped_client_cert",escaped_cert)
Note:

This API is not supported in the events SSL_PRECONNECT and SSL_CLIENTHELLO.

avi.utils.get_ip_reputation

You can use Webroot DB for IP reputation check in L7 DataScript using Lua function.

is_good, reputation_type = avi.utils.get_ip_reputation(ip_addr)

First return value for is_good is true/false. This indicates if the given IP is of good reputation.

The second return value is a bitmap of IP reputation type and is valid only if is_good is false. For instance, value 1 indicates Spam Source (bit 0 set), and value 17 indicates Spam Source and Scanner (bits 0 and 4 sets).

For more information, see the IP Reputation topic in the VMware NSX Advanced Load Balancer WAF Guide.

The function will use the IP reputation database configured for a virtual service DataScript set.

Note:

You can use API or CLI to configure VSDataScriptSet to use IPReputationDB.

The Lua function will accept both IPv4 and IPv6 addresses. However, it will always return true for IPv6 addresses because the IP reputation database currently contains only IPv4 address information.

The format of the ip_addr parameters is expected to be as returned by avi.vs.client_ip(), which is a presentation format, for instance, 1.2.3.4.

message VSDataScriptSet {
  ...
  optional string ip_reputation_db_uuid = 58 [
    (refers_to) = "IPReputationDB",
    ...
  ]
  ...
}

Configuration Workflow

When a script uses the new avi.utils.get_ip_reputation(ip_addr) function, IPReputationDB should be configured at the VSDataScriptSet level.