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;)