Advanced policy expressions: Parsing SSL certificates

Last published : Sep 24, 2026
There are advanced policy expressions to parse SSL certificates and SSL client hello messages.
Related information

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
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\")
  • <certificate>.extensions.has_object
 Returns the Boolean value TRUE if the client certificate has the extension with a matching OID. For example, if the client certificate has the extension with the OID 2.16.756.5.4.2.1.2.13.2.7 then the expression client.ssl.client_cert.extensions.has_object (2.16.756.5.4.2.1.2.13.2.7), returns TRUE.
  • <certificate>.extensions.object(OID).has_value(value)
Returns the Boolean value TRUE if the client certificate has the extension with a matching OID and value. For example, if the client certificate has the extension with the OID 2.16.756.5.4.2.1.2.13.2.7 and a value XB then the expression client.ssl.client_cert.extensions.object("2.16.756.5.4.2.1.2.13.2.7").has_value("XB") returns TRUE.
Notes:
  • If an extension with a specified OID has a value of type other than IA5 or integer, policy evaluation would result in an undefined (UNDEF) event.
<certificate>.extensions.count Number of extensions received in the client certificate. For example, if the number of extensions in the client certificate is 16 then the expression client.ssl.client_cert.extensions.count.eq(16), returns TRUE
Note:
You can use a well-known short name instead of OID for standard extensions. For example, the Netscape comment extension has the OID 2.16.840.1.113730.1.13 and the short name nsComment. You can use nsComment in the extension instead of 2.16.840.1.113730.1.13
    - client.ssl.client_cert.extensions.has_object(nscomment).
    - client.ssl.client_cert.extensions.object("nscomment").has_value("OpenSSL Generated Client Certificate").

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.