Product Documentation

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 may 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 might want to 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)"

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 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.

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 cryptograhic 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 TLSv1.1.; 0x303. The transaction is TLSv1.2.

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, with the exception of expressions that examine certificate expiration. Time-based operations are described in Advanced Policy Expressions: Working with Dates, Times, and Numbers.

The following table describes 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_headerName: insert_sslOperation: 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

Parse SSL client hello

You can parse the SSL client hello 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 initiate 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  

For a list of the actions that support these expressions, see Configure an SSL action to forward client traffic to another virtual server.