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