Advanced policy expressions: parsing SSL
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-->
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
|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
|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.|
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:
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|
||Returns a Boolean TRUE if the client has an SSL certificate.|
||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:
||Returns the Issuer and ignores the empty elements in a name-value list. For example, consider the following:
||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
Parse SSL client hello
You can parse the SSL client hello message by configuring expressions that use the following prefix:
|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.