Product Documentation

Default Syntax Expressions: Parsing SSL Certificates

Sep 27, 2017

You can use default syntax 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

Updated: 2015-06-17

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

Updated: 2013-09-02

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 "Default Syntax 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_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>.AUTH_KEYID

Returns a string that contains the Authority Key Identifier extension of the X.509 V3 certificate.

<certificate>.AUTH_KEYID.CERT_SERIALNUMBER

Returns the SerialNumber field of the Authority Key Identifier as a blob.

<certificate>.AUTH_KEYID.EXISTS

Returns a Boolean TRUE if the certificate contains an Authority Key Identifier extension.

<certificate>.AUTH_KEYID.ISSUER_NAME

Returns the Issuer Distinguished Name 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:

/C=US/O=myCompany/OU=www.mycompany.com/CN=www.mycompany.com/emailAddress=myuserid@mycompany.com

<certificate>.AUTH_KEYID.ISSUER_NAME.IGNORE_EMPTY_ELEMENTS

Returns the Issuer Distinguished Name in the certificate as a name-value list and ignores the empty elements in the list.

For example, the following name-value list has an empty element following “a=10”:

a=10;;b=11; ;c=89

The element following b=11 is not considered an empty element.

<certificate>.AUTH_KEYID.KEYID

Returns the keyIdentifier field of the Authority Key Identifier as a blob.

<certificate>.CERT_POLICY

Returns a string that contains the client certificate policy. Note that this represents a sequence of certificate policies.

<certificate>.KEY_USAGE(string)

Returns a Boolean value to indicate whether the specified key usage extension bit value in the

X.509 certificate is set. The string argument specifies which bit is checked. Following are valid arguments:

  • DIGITAL_SIGNATURE. Returns TRUE if the digital signature bit is set; otherwise, it returns FALSE.
  • NONREPUDIATION. Returns TRUE if the nonrepudiation bit is set; otherwise, it returns FALSE.
  • KEYENCIPHERMENT. Returns TRUE if the key encipherment bit is set; otherwise, it returns FALSE.
  • DATAENCIPHERMENT. Returns TRUE if the data encipherment bit is set; otherwise, it returns FALSE.
  • KEYAGREEMENT. Returns TRUE if the key agreement bit is set; otherwise, it returns FALSE.
  • KEYCERTSIGN. Returns TRUE if the key cert sign bit is set; otherwise, it returns FALSE.
  • CRLSIGN. Returns TRUE if the CRL bit is set; otherwise, it returns FALSE.
  • ENCIPHERONLY. Returns TRUE if the encipher only bit is set; otherwise, it returns FALSE.
  • DECIPHERONLY. Returns TRUE if the decipher only bit is set; otherwise, it returns FALSE.

<certificate>.PK_ALGORITHM

Returns the name of the public key algorithm used by the certificate.

<certificate>.PK_SIZE

Returns the size of the public key used in the certificate.

<certificate>.SERIALNUMBER

Returns the serial number of the client certificate. If this is a non-SSL transaction or there is an error in the certificate, this operation returns an empty string.

<certificate>.SIGNATURE_ALGORITHM

Returns the name of the cryptographic algorithm used by the CA to sign this certificate.

<certificate>.SUBJECT

Returns the Distinguished Name of the Subject as a name-value. An equals sign (“=”) separates names and values and a slash (“/”) delimits name-value pairs.

Following is an example:

/C=US/O=myCompany/OU=www.mycompany.com/CN=www.mycompany.com/emailAddress=myuserid@mycompany.com

<certificate>.SUBJECT.IGNORE_EMPTY_ELEMENTS

Returns the Subject as a name-value list, but ignores the empty elements in the 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>.SUBJECT_KEYID

Returns the Subject KeyID of the client certificate. If there is no Subject KeyID, this operation returns a zero-length text object.