1SSL/TLS Keywords 2================ 3 4Suricata comes with several rule keywords to match on various properties of TLS/SSL handshake. Matches are string inclusion matches. 5 6tls.cert_subject 7---------------- 8 9Match TLS/SSL certificate Subject field. 10 11Examples:: 12 13 tls.cert_subject; content:"CN=*.googleusercontent.com"; isdataat:!1,relative; 14 tls.cert_subject; content:"google.com"; nocase; pcre:"/google.com$/"; 15 16``tls.cert_subject`` is a 'sticky buffer'. 17 18``tls.cert_subject`` can be used as ``fast_pattern``. 19 20``tls.cert_subject`` replaces the previous keyword name: ``tls_cert_subject``. You may continue 21to use the previous name, but it's recommended that rules be converted to use 22the new name. 23 24tls.cert_issuer 25--------------- 26 27Match TLS/SSL certificate Issuer field. 28 29Examples:: 30 31 tls.cert_issuer; content:"WoSign"; nocase; isdataat:!1,relative; 32 tls.cert_issuer; content:"StartCom"; nocase; pcre:"/StartCom$/"; 33 34``tls.cert_issuer`` is a 'sticky buffer'. 35 36``tls.cert_issuer`` can be used as ``fast_pattern``. 37 38``tls.cert_issuer`` replaces the previous keyword name: ``tls_cert_issuer``. You may continue 39to use the previous name, but it's recommended that rules be converted to use 40the new name. 41 42tls.cert_serial 43--------------- 44 45Match on the serial number in a certificate. 46 47Example:: 48 49 alert tls any any -> any any (msg:"match cert serial"; \ 50 tls.cert_serial; content:"5C:19:B7:B1:32:3B:1C:A1"; sid:200012;) 51 52``tls.cert_serial`` is a 'sticky buffer'. 53 54``tls.cert_serial`` can be used as ``fast_pattern``. 55 56``tls.cert_serial`` replaces the previous keyword name: ``tls_cert_serial``. You may continue 57to use the previous name, but it's recommended that rules be converted to use 58the new name. 59 60tls.cert_fingerprint 61-------------------- 62 63Match on the SHA-1 fingerprint of the certificate. 64 65Example:: 66 67 alert tls any any -> any any (msg:"match cert fingerprint"; \ 68 tls.cert_fingerprint; \ 69 content:"4a:a3:66:76:82:cb:6b:23:bb:c3:58:47:23:a4:63:a7:78:a4:a1:18"; \ 70 sid:200023;) 71 72``tls.cert_fingerprint`` is a 'sticky buffer'. 73 74``tls.cert_fingerprint`` can be used as ``fast_pattern``. 75 76``tls.cert_fingerprint`` replaces the previous keyword name: ``tls_cert_fingerprint`` may continue 77to use the previous name, but it's recommended that rules be converted to use 78the new name. 79 80tls.sni 81------- 82 83Match TLS/SSL Server Name Indication field. 84 85Examples:: 86 87 tls.sni; content:"oisf.net"; nocase; isdataat:!1,relative; 88 tls.sni; content:"oisf.net"; nocase; pcre:"/oisf.net$/"; 89 90``tls.sni`` is a 'sticky buffer'. 91 92``tls.sni`` can be used as ``fast_pattern``. 93 94``tls.sni`` replaces the previous keyword name: ``tls_sni``. You may continue 95to use the previous name, but it's recommended that rules be converted to use 96the new name. 97 98tls_cert_notbefore 99------------------ 100 101Match on the NotBefore field in a certificate. 102 103Example:: 104 105 alert tls any any -> any any (msg:"match cert NotBefore"; \ 106 tls_cert_notbefore:1998-05-01<>2008-05-01; sid:200005;) 107 108tls_cert_notafter 109----------------- 110 111Match on the NotAfter field in a certificate. 112 113Example:: 114 115 alert tls any any -> any any (msg:"match cert NotAfter"; \ 116 tls_cert_notafter:>2015; sid:200006;) 117 118tls_cert_expired 119---------------- 120 121Match returns true if certificate is expired. It evaluates the validity date 122from the certificate. 123 124Usage:: 125 126 tls_cert_expired; 127 128tls_cert_valid 129-------------- 130 131Match returns true if certificate is not expired. It only evaluates the 132validity date. It does *not* do cert chain validation. It is the opposite 133of ``tls_cert_expired``. 134 135Usage:: 136 137 tls_cert_valid; 138 139tls.certs 140--------- 141 142Do a "raw" match on each of the certificates in the TLS certificate chain. 143 144Example:: 145 146 alert tls any any -> any any (msg:"match bytes in TLS cert"; tls.certs; \ 147 content:"|06 09 2a 86|"; sid:200070;) 148 149``tls.certs`` is a 'sticky buffer'. 150 151``tls.certs`` can be used as ``fast_pattern``. 152 153tls.version 154----------- 155 156Match on negotiated TLS/SSL version. 157 158Supported values: "1.0", "1.1", "1.2", "1.3" 159 160It is also possible to match versions using a hex string. 161 162Examples:: 163 164 tls.version:1.2; 165 tls.version:0x7f12; 166 167The first example matches TLSv1.2, whilst the last example matches TLSv1.3 168draft 16. 169 170ssl_version 171----------- 172 173Match version of SSL/TLS record. 174 175Supported values "sslv2", "sslv3", "tls1.0", "tls1.1", "tls1.2", "tls1.3" 176 177Example:: 178 179 alert tls any any -> any any (msg:"match TLSv1.2"; \ 180 ssl_version:tls1.2; sid:200030;) 181 182It is also possible to match on several versions at the same time. 183 184Example:: 185 186 alert tls any any -> any any (msg:"match SSLv2 and SSLv3"; \ 187 ssl_version:sslv2,sslv3; sid:200031;) 188 189tls.subject 190----------- 191 192Match TLS/SSL certificate Subject field. 193 194example: 195 196 197:: 198 199 tls.subject:"CN=*.googleusercontent.com" 200 201Case sensitive, can't use 'nocase'. 202 203Legacy keyword. ``tls.cert_subject`` is the replacement. 204 205tls.issuerdn 206------------ 207 208match TLS/SSL certificate IssuerDN field 209 210example: 211 212 213:: 214 215 tls.issuerdn:!"CN=Google-Internet-Authority" 216 217Case sensitive, can't use 'nocase'. 218 219Legacy keyword. ``tls.cert_issuer`` is the replacement. 220 221tls.fingerprint 222--------------- 223 224match TLS/SSL certificate SHA1 fingerprint 225 226example: 227 228 229:: 230 231 tls.fingerprint:!"f3:40:21:48:70:2c:31:bc:b5:aa:22:ad:63:d6:bc:2e:b3:46:e2:5a" 232 233Case sensitive, can't use 'nocase'. 234 235The tls.fingerprint buffer is lower case so you must use lower case letters for this to match. 236 237tls.store 238--------- 239 240store TLS/SSL certificate on disk 241 242ssl_state 243--------- 244 245The ``ssl_state`` keyword matches the state of the SSL connection. The possible states 246are ``client_hello``, ``server_hello``, ``client_keyx``, ``server_keyx`` and ``unknown``. 247You can specify several states with ``|`` (OR) to check for any of the specified states. 248 249Negation support is not available yet, see https://redmine.openinfosecfoundation.org/issues/1231 250 251