Project

General

Profile

WARNING! This is only a suggestion, and not keywords supported by Suricata

TLS keyword expansion

This page describes my suggestions to expand the TLS rule keywords supported by Suricata. The TLS Lua functions supported should also be expanded, but the keyword work will make that easier to do later.

Please add comments to #1766 :)

The rule keywords for TLS should be splitted in two. My suggestion is to prefix all keywords related to the certificate with “tls_cert_”, and just use “tls_” for the keywords related to the TLS session. All existing keywords should be kept to avoid breaking rulesets already using the keywords, but a deprecated warning should be issued to the user.

TLS Certificate Keywords

All the certificate keywords should work with both client and server certificates. Both “ssl_state” and “flow” keywords could be used to match on either the client or the server certificate.

tls_cert_version

This keyword matches on the version field in the TLS certificate.

alert tls any any ­> any any (msg:”match client cert version”; flow:established,to_server; tls_cert_version:3; sid:20001;)

This keyword should support the following operators: “<”, “>”, “<>”, “!”.

tls_cert_serial

This keyword matches on the serial field in the TLS certificate.

alert tls any any ­> any any (msg:”match serial of any certificate”; tls_cert_serial:”12:A4:51:90:BA:FE:81:AA:06”; sid:20002;)

This keyword should support the “!” operator.

tls_cert_issuer

This keyword matches on the TLS certificate issuer.

alert tls any any ­> any any (msg:”match cert issuer”; tls_cert_issuer; content:”example.com”; sid:20003;)

This is a mpm keyword.

tls_cert_subject

This keyword matches on the TLS certificate subject.

alert tls any any ­> any any (msg:”match cert subject”; tls_cert_subject; content:”example.com”; sid:200004;)

This is a mpm keyword.

tls_cert_notbefore

This keyword matches on the NotBefore field in the TLS certificate.

alert tls any any ­> any any (msg:”match cert NotBefore”; tls_cert_notbefore:1998­-05­-01<>2008­-05­-01; sid:200005;)

This keyword should support the following operators: “<”, “>”, “<>”, “!”.

tls_cert_notafter

This keyword matches on the NotAfter field in the TLS certificate.

alert tls any any ­> any any (msg:”match cert NotAfter”; tls_cert_notafter:>2015; sid:200006;)

This keyword should support the following operators: “<”, “>”, “<>”, “!”.

tls_cert_sig_algo

This keyword matches on the signature algorithm field in the TLS certificate.

alert tls any any ­> any any (msg:”match cert signature algorithm”; tls_cert_sig_algo:”sha1withRsa”; sid:200007;)

This keyword should support the “!” operator.

tls_cert_subject_pubkey_algo

This keyword matches on the subject public key algorithm field in the TLS certificate.

alert tls any any ­> any any (msg:”match subject pubkey algorithm”; tls_cert_subject_pubkey_algo:”RSA”; sid:200008;)

This keyword should support the “!” operator.

tls_cert_extension

Match if a certain extension is present in the TLS certificate.

alert tls any any ­> any any (msg:”match cert extension”; tls_cert_extension:”SubjectAltNames”; sid:200009;)

This keyword should support the “!” operator.

tls_cert_sub_alt_name

Match the subject alternative name extension in the TLS certificate.

alert tls any any ­> any any (msg:”match cert SubAltName”; tls_cert_sub_alt_name; content:”example.com”; sid:200010;)

This is a mpm keyword.

TLS Session Keywords

Most of the session keywords should work both ways, matching either on fields in CLIENT_HELLO or in SERVER_HELLO. The “ssl_state” and “flow” keyword can be used to determine if we want to match on the client or the server traffic.

tls_version / ssl_version

Match the version of the TLS session. If we match the version of the CLIENT_HELLO, then we get the maximum version supported for the client. If we however match the version of the SERVER_HELLO, then we get the version used in the TLS session.

alert tls any any ­> any any (msg:”match tls session version”; ssl_state:server_hello; tls_version:>SSLv3; sid:200011;)

“ssl_version” is a keyword supported by Snort. We must remember to offer the same functionality.

This keyword should support the following operators: “<”, “>”, “<>”, “!”.

tls_state / ssl_state

Match which TLS packet in the session we are processing “client_hello”, “server_hello”, etc.

alert tls any any ­> any any (msg:”match server_hello”; tls_state:server_hello; sid:200012;)

“ssl_state” is a keyword supported by Snort. We must remember to offer the same functionality.

This keyword should support the “!” operator.

tls_ciphersuite

Match the TLS cipher suite. If we match the cipher suite in the CLIENT_HELLO, then we match if the cipher suite is amongst the cipher suites supported by the client. If we match the cipher suite in the SERVER_HELLO, then we match the cipher suite used by the TLS session.

alert tls any any ­> any any (msg:”match client cipher suite support”; tls_state:client_hello; tls_ciphersuite; content:”TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256”; sid:200013;)

This is a mpm keyword.

tls_keyex_algo

Match the key exchange algorithm in the cipher suite (see tls_ciphersuite).

alert tls any any ­> any any (msg:”match session key exchange algorithm”; tls_state:server_hello; tls_keyex_algo:”ECDHE_RSA”; sid:200014;)

This keyword should support the “!” operator.

tls_enc_algo

Match the encryption algorithm in the cipher suite (see tls_ciphersuite).

alert tls any any ­> any any (msg:”match session encryption algorithm”; tls_state:server_hello; tls_enc_algo:”AES_128_GCM”; sid:200015;)

This keyword should support the “!” operator.

tls_mac_algo

Match the MAC algorithm in the cipher suite (see tls_ciphersuite).

alert tls any any ­> any any (msg:”match session mac algorithm”; tls_state:server_hello; tls_mac_algo:”SHA256”; sid:200016;)

This keyword should support the “!” operator.

tls_random

Match the random field in the client_hello/server_hello.

alert tls any any -> any any (msg:"match client_hello random"; tls_state:client_hello; tls_random; content:|DE AD BE EF|; sid:20099;)

This is a mpm keyword.

tls_compression

Match the compression algorithm. If we match the compression algorithm in the CLIENT_HELLO, then we match if the compression algorithms is supported by the client. If we match the compression algorithm in the SERVER_HELLO, then we match the compression algorithm used by the TLS session.

alert tls any any ­> any any (msg:”compression algorithm supported”; tls_state:client_hello; tls_compression:”DEFLATE”; sid:200017;)

This keyword should support the “!” operator.

tls_sni

Match the server name indication extension in the CLIENT_HELLO.

alert tls any any ­> any any (msg:”example.com SNI”; tls_sni; content:”example.com”; sid:200018;)

This is a mpm keyword.

tls_extension

Match if a certain extension is present. This should work for both CLIENT_HELLO and SERVER_HELLO.

alert tls any any ­> any any (msg:”match server_name extension”; tls_state:client_hello; tls_extension:”server_name”; sid:200019;)

This keyword should support the “!” operator.

Other TLS Keywords

tls_store / ssl_store

Indicate that the certificate should be stored to disk if the rule triggers.

alert tls any any ­> any any (msg:”store all certs”; tls_store; noalert; sid:200020;)