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.
您可以检查SSL连接和数据在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 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)"
Note
For information on parsing dates and times in a certificate, seeFormat of Dates and Times in an ExpressionandExpressions 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 inBasic Operations on Expression PrefixesandCompound 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, seeExpressions 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 inAdvanced 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 |
---|---|
|
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:/C=US/O=myCompany/OU=www.mycompany.com/CN=www.mycompany.com/emailAddress=myuserid@mycompany.com |
|
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 |
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 | 如果信号密码组合值(SCSV返回true) 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 CLIENTHELLO_REQ bind point. For more information, seeSSL policy binding.