ADC

Advanced policy expressions: parsing SSL

August 1, 2023

Contributed by:

There are advanced policy expressions to parse SSL certificates and SSL client hello messages.

Parse SSL certificates

You can use advanced policy expressions to evaluate X.509 Secure Sockets Layer (SSL) client certificates. A client certificate is an electronic document that can be used to authenticate a user’s identity. A client certificate contains (at a minimum) version information, a serial number, a signature algorithm ID, an issuer name, a validity period, a subject (user) name, a public key, and signatures.

You can examine both SSL connections and data in client certificates. For example, you might want to send SSL requests that use low-strength ciphers to a particular load balancing virtual server farm. The following command is an example of a Content Switching policy that parses the cipher strength in a request and matches cipher strengths that are less than or equal to 40:

add cs policy p1 -rule "client.ssl.cipher_bits.le(40)"

As another example, you can configure a policy that determines whether a request contains a client certificate:

add cs policy p2 -rule "client.ssl.client_cert exists"

Or, you can configure a policy that examines particular information in a client certificate. For example, the following policy verifies that the certificate has one or more days before expiration:

add cs policy p2 -rule "client.ssl.client_cert exists && client.ssl.client_cert.days_to_expire.ge(1)"

An example for JA3 fingerprint usage:

add ssl policy ja3_pol -rule "CLIENT.SSL.JA3_FINGERPRINT.EQ(bb4c15a90e93a25ddc16274395bce4c6)" -action reset

Or, an example for JA3 fingerprint usage with patset:

add policy patset pat1
bind policy patset pat1 bb4c15a90e93a25ddc16274395bce4c6 -index 1
bind policy patset pat1 cd3c15a90e93a25ddc16274395bce6b4 -index 2
add ssl policy ssl_ja3_pol -rule CLIENT.SSL.JA3_FINGERPRINT.contains_any(\"pat1\") -action reset
<!--NeedCopy-->

Note

For information on parsing dates and times in a certificate, see Format of Dates and Times in an Expression and Expressions for SSL Certificate Dates.

Prefixes for text-based SSL and certificate data

The following table describes expression prefixes that identify text-based items in SSL transactions and client certificates.

Table 1. Prefixes That Return Text or Boolean Values for SSL and Client Certificate Data

Prefix	Description
CLIENT.SSL.CLIENT_CERT	Returns the SSL client certificate in the current SSL transaction.
CLIENT.SSL.CLIENT_CERT.TO_PEM	Returns the SSL client certificate in binary format.
CLIENT.SSL.CIPHER_EXPORTABLE	Returns a Boolean TRUE if the SSL cryptographic cipher is exportable.
CLIENT.SSL.CIPHER_NAME	Returns the name of the SSL Cipher if invoked from an SSL connection, and a NULL string if invoked from a non-SSL connection.
CLIENT.SSL.IS_SSL	Returns a Boolean TRUE if the current connection is SSL-based.
CLIENT.SSL.JA3_FINGERPRINT	Returns a Boolean TRUE if the configured JA3 fingerprint matches the JA3 fingerprint in the client hello message. Note: This expression is available in release 13.1 build 12.x and later.

Prefixes for numeric data in SSL certificates

The following table describes prefixes that evaluate numeric data other than dates in SSL certificates. These prefixes can be used with the operations that are described in Basic Operations on Expression Prefixes and Compound Operations for Numbers.

Table 2. Prefixes That Evaluate Numeric Data Other Than Dates in SSL Certificates

Prefix	Description
CLIENT.SSL.CLIENT_CERT.DAYS_TO_EXPIRE	Returns the number of days that the certificate is valid, or returns -1 for expired certificates.
CLIENT.SSL.CLIENT_CERT.PK_SIZE	Returns the size of the public key used in the certificate.
CLIENT.SSL.CLIENT_CERT.VERSION	Returns the version number of the certificate. If the connection is not SSL-based, returns zero (0).
CLIENT.SSL.CIPHER_BITS	Returns the number of bits in the cryptographic key. Returns 0 if the connection is not SSL-based.
CLIENT.SSL.VERSION	Returns a number that represents the SSL protocol version, as follows: 0. The transaction is not SSL-based: 0x002. The transaction is SSLv2: 0x300. The transaction is SSLv3: 0x301. The transaction is TLSv1: 0x302. The transaction is TLS 1.1: 0x303. The transaction is TLS 1.2: 0x304. The transaction is TLS 1.3.

Note

For expressions related to expiration dates in a certificate, see Expressions for SSL Certificate Dates.

Expressions for SSL certificates

You can parse SSL certificates by configuring expressions that use the following prefix:

CLIENT.SSL.CLIENT_CERT

This section discusses the expressions that you can configure for certificates, except expressions that examine certificate expiration. Time-based operations are described in Advanced Policy Expressions: Working with Dates, Times, and Numbers.

The following table describes the operations that you can specify for the CLIENT.SSL.CLIENT_CERT prefix.

Table 3. Operations That Can Be Specified with the CLIENT.SSL.CLIENT_CERT Prefix

SSL Certificate Operation	Description
`<certificate>.EXISTS`	Returns a Boolean TRUE if the client has an SSL certificate.
`<certificate>.ISSUER`	Returns the Distinguished Name (DN) of the Issuer in the certificate as a name-value list. An equals sign (“=”) is the delimiter for the name and the value, and the slash (“/”) is the delimiter that separates the name-value pairs. Following is an example of the returned DN: `/C=US/O=myCompany/OU=www.mycompany.com/CN=www.mycompany.com/emailAddress=myuserid@mycompany.com`
`<certificate>.ISSUER. IGNORE_EMPTY_ELEMENTS`	Returns the Issuer and ignores the empty elements in a name-value list. For example, consider the following: `Cert-Issuer: /c=in/st=kar//l=bangelore //o=mycompany/ou=sales/ /emailAddress=myuserid@mycompany.com`. The following Rewrite action returns a count of 6 based on the preceding Issuer definition: `sh rewrite action insert_ssl_header` `Name: insert_ssl` `Operation: insert_http_header Target:Cert-Issuer` `Value:CLIENT.SSL.CLIENT_CERT.ISSUER.COUNT`. However, if you change the value to the following, the returned count is 9: `CLIENT.SSL.CLIENT_CERT.ISSUER.IGNORE_EMPTY_ELEMENTS.COUNT`
`<certificate>. SERIALNUMBER`	Returns the serial number of the certificate as an upper case hexadecimal string with no leading zeroes. For example, if the serial number of the certificate is 04daa1e44bd2e7769638a0058b4964bd, the following expression helps match the serial number `CLIENT.SSL.CLIENT_CERT.SERIALNUMBER.SET_TEXT_MODE(IGNORECASE).CONTAINS(\"4daa1e44bd2e7769638a0058b4964bd\")`

Parse SSL client hello

You can parse the SSL client hello message by configuring expressions that use the following prefix:

Prefix	Description
CLIENT.SSL.CLIENT_HELLO.CIPHERS.HAS_HEXCODE	Matches the hex code provided in the expression with the hex codes of cipher suites received in the client hello message.
CLIENT.SSL.CLIENT_HELLO.CLIENT_VERSION	Version received in the client hello message header.
CLIENT.SSL.CLIENT_HELLO.IS_RENEGOTIATE	Returns true if a client or server initiates session renegotiation.
CLIENT.SSL.CLIENT_HELLO.IS_REUSE	Returns true if the appliance reuses the SSL session based on the non-zero session-ID received in the client-hello message.
CLIENT.SSL.CLIENT_HELLO.IS_SCSV	Returns true if Signaling Cipher Suite Value (SCSV) capability is advertised in the client hello message. The hex code for fallback SCSV is 0x5600.
CLIENT.SSL.CLIENT_HELLO.IS_SESSION_TICKET	Returns true if session ticket extension with non-zero length is advertised in the client-hello message.
CLIENT.SSL.CLIENT_HELLO.LENGTH	Length received in the client hello message header.
CLIENT.SSL.CLIENT_HELLO.SNI	Returns the server name received in the Server Name extension of the client hello message.
CLIENT.SSL.CLIENT_HELLO.ALPN.HAS_NEXTPROTOCOL	Returns true if the application protocol in the ALPN extension received in the client hello message matches the protocol provided in the expression.

These expressions can be used at the CLIENTHELLO_REQ bind point. For more information, see SSL policy binding.

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Advanced policy expressions: parsing SSL

August 1, 2023

Contributed by:

August 1, 2023

Contributed by:

Advanced policy expressions: parsing SSL

Parse SSL certificates

Prefixes for text-based SSL and certificate data

Prefixes for numeric data in SSL certificates

Expressions for SSL certificates

Parse SSL client hello

In this article