suricata
app-layer-ssl.h
Go to the documentation of this file.
1 /* Copyright (C) 2007-2012 Open Information Security Foundation
2  *
3  * You can copy, redistribute or modify this Program under the terms of
4  * the GNU General Public License version 2 as published by the Free
5  * Software Foundation.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * version 2 along with this program; if not, write to the Free Software
14  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
15  * 02110-1301, USA.
16  */
17 
18 /**
19  * \file
20  *
21  * \author Anoop Saldanha <anoopsaldanha@gmail.com>
22  * \author Pierre Chifflier <pierre.chifflier@ssi.gouv.fr>
23  *
24  */
25 
26 #ifndef __APP_LAYER_SSL_H__
27 #define __APP_LAYER_SSL_H__
28 
29 #include "app-layer-protos.h"
30 #include "app-layer-parser.h"
31 #include "decode-events.h"
32 #include "util-ja3.h"
33 #include "queue.h"
34 
36  TLS_FRAME_PDU = 0, /**< whole PDU, so header + data */
37  TLS_FRAME_HDR, /**< only header portion */
38  TLS_FRAME_DATA, /**< only data portion */
43 };
44 
45 enum {
46  /* TLS protocol messages */
61  /* Certificates decoding messages */
76 };
77 
78 enum {
83 };
84 
85 /* Flag to indicate that server will now on send encrypted msgs */
86 #define SSL_AL_FLAG_SERVER_CHANGE_CIPHER_SPEC BIT_U32(0)
87 /* Flag to indicate that client will now on send encrypted msgs */
88 #define SSL_AL_FLAG_CLIENT_CHANGE_CIPHER_SPEC BIT_U32(1)
89 #define SSL_AL_FLAG_CHANGE_CIPHER_SPEC BIT_U32(2)
90 
91 /* SSL related flags */
92 #define SSL_AL_FLAG_SSL_CLIENT_HS BIT_U32(3)
93 #define SSL_AL_FLAG_SSL_SERVER_HS BIT_U32(4)
94 #define SSL_AL_FLAG_SSL_CLIENT_MASTER_KEY BIT_U32(5)
95 #define SSL_AL_FLAG_SSL_CLIENT_SSN_ENCRYPTED BIT_U32(6)
96 #define SSL_AL_FLAG_SSL_SERVER_SSN_ENCRYPTED BIT_U32(7)
97 #define SSL_AL_FLAG_SSL_NO_SESSION_ID BIT_U32(8)
98 
99 /* flags specific to detect-ssl-state keyword */
100 #define SSL_AL_FLAG_STATE_CLIENT_HELLO BIT_U32(9)
101 #define SSL_AL_FLAG_STATE_SERVER_HELLO BIT_U32(10)
102 #define SSL_AL_FLAG_STATE_CLIENT_KEYX BIT_U32(11)
103 #define SSL_AL_FLAG_STATE_SERVER_KEYX BIT_U32(12)
104 #define SSL_AL_FLAG_STATE_UNKNOWN BIT_U32(13)
105 
106 /* flag to indicate that session is finished */
107 #define SSL_AL_FLAG_STATE_FINISHED BIT_U32(14)
108 
109 /* flags specific to HeartBeat state */
110 #define SSL_AL_FLAG_HB_INFLIGHT BIT_U32(15)
111 #define SSL_AL_FLAG_HB_CLIENT_INIT BIT_U32(16)
112 #define SSL_AL_FLAG_HB_SERVER_INIT BIT_U32(17)
113 
114 /* flag to indicate that handshake is done */
115 #define SSL_AL_FLAG_HANDSHAKE_DONE BIT_U32(18)
116 
117 /* A session ID in the Client Hello message, indicating the client
118  wants to resume a session */
119 #define SSL_AL_FLAG_SSL_CLIENT_SESSION_ID BIT_U32(19)
120 /* Session resumed without a full handshake */
121 #define SSL_AL_FLAG_SESSION_RESUMED BIT_U32(20)
122 
123 /* Encountered a supported_versions extension in client hello */
124 #define SSL_AL_FLAG_CH_VERSION_EXTENSION BIT_U32(21)
125 
126 /* Log the session even without ever seeing a certificate. This is used
127  to log TLSv1.3 sessions. */
128 #define SSL_AL_FLAG_LOG_WITHOUT_CERT BIT_U32(22)
129 
130 /* Encountered a early data extension in client hello. This extension is
131  used by 0-RTT. */
132 #define SSL_AL_FLAG_EARLY_DATA BIT_U32(23)
133 
134 /* config flags */
135 #define SSL_TLS_LOG_PEM (1 << 0)
136 
137 /* extensions */
138 #define SSL_EXTENSION_SNI 0x0000
139 #define SSL_EXTENSION_ELLIPTIC_CURVES 0x000a
140 #define SSL_EXTENSION_EC_POINT_FORMATS 0x000b
141 #define SSL_EXTENSION_SESSION_TICKET 0x0023
142 #define SSL_EXTENSION_EARLY_DATA 0x002a
143 #define SSL_EXTENSION_SUPPORTED_VERSIONS 0x002b
144 
145 /* SNI types */
146 #define SSL_SNI_TYPE_HOST_NAME 0
147 
148 /* Max string length of the TLS version string */
149 #define SSL_VERSION_MAX_STRLEN 20
150 
151 /* SSL versions. We'll use a unified format for all, with the top byte
152  * holding the major version and the lower byte the minor version */
153 enum {
155  SSL_VERSION_2 = 0x0200,
156  SSL_VERSION_3 = 0x0300,
157  TLS_VERSION_10 = 0x0301,
158  TLS_VERSION_11 = 0x0302,
159  TLS_VERSION_12 = 0x0303,
160  TLS_VERSION_13 = 0x0304,
180 };
181 
182 typedef struct SSLCertsChain_ {
183  uint8_t *cert_data;
184  uint32_t cert_len;
187 
188 
189 typedef struct SSLStateConnp_ {
190  /* record length */
191  uint32_t record_length;
192  /* record length's length for SSLv2 */
194 
195  /* offset of the beginning of the current message (including header) */
196  uint32_t message_start;
197  uint32_t message_length;
198 
199  uint16_t version;
200  uint8_t content_type;
201 
202  uint8_t handshake_type;
204 
205  /* the no of bytes processed in the currently parsed record */
206  uint32_t bytes_processed;
207  /* the no of bytes processed in the currently parsed handshake */
209 
211 
218 
219  /* ssl server name indication extension */
220  char *sni;
221 
222  char *session_id;
223 
225 
226  uint32_t cert_log_flag;
227 
229  char *ja3_hash;
230 
231  /* buffer for the tls record.
232  * We use a malloced buffer, if the record is fragmented */
233  uint8_t *trec;
234  uint32_t trec_len;
235  uint32_t trec_pos;
237 
238 /**
239  * \brief SSLv[2.0|3.[0|1|2|3]] state structure.
240  *
241  * Structure to store the SSL state values.
242  */
243 typedef struct SSLState_ {
244  Flow *f;
245 
246  AppLayerTxData tx_data;
247 
248  /* holds some state flags we need */
249  uint32_t flags;
250 
251  /* there might be a better place to store this*/
252  uint32_t hb_record_len;
253 
254  uint16_t events;
255 
256  uint32_t current_flags;
257 
259 
263 
264 void RegisterSSLParsers(void);
265 void SSLParserRegisterTests(void);
266 void SSLSetEvent(SSLState *ssl_state, uint8_t event);
267 void SSLVersionToString(uint16_t, char *);
268 void SSLEnableJA3(void);
269 bool SSLJA3IsEnabled(void);
270 
271 #endif /* __APP_LAYER_SSL_H__ */
SSLStateConnp_::cert0_not_before
time_t cert0_not_before
Definition: app-layer-ssl.h:215
SSLStateConnp_::cert0_subject
char * cert0_subject
Definition: app-layer-ssl.h:212
SSLState_
SSLv[2.0|3.[0|1|2|3]] state structure.
Definition: app-layer-ssl.h:243
TLS_VERSION_11
@ TLS_VERSION_11
Definition: app-layer-ssl.h:158
SSLParserRegisterTests
void SSLParserRegisterTests(void)
Definition: app-layer-ssl.c:5533
JA3Buffer_
Definition: util-ja3.h:29
TLS_VERSION_13_DRAFT26_FB
@ TLS_VERSION_13_DRAFT26_FB
Definition: app-layer-ssl.h:179
SSLCertsChain_::cert_len
uint32_t cert_len
Definition: app-layer-ssl.h:184
TLS_VERSION_12
@ TLS_VERSION_12
Definition: app-layer-ssl.h:159
SSLState_::hb_record_len
uint32_t hb_record_len
Definition: app-layer-ssl.h:252
TLS_VERSION_13_DRAFT21_FB
@ TLS_VERSION_13_DRAFT21_FB
Definition: app-layer-ssl.h:176
SSLStateConnp_::message_length
uint32_t message_length
Definition: app-layer-ssl.h:197
SSLState_::client_connp
SSLStateConnp client_connp
Definition: app-layer-ssl.h:260
TLS_VERSION_13_DRAFT21
@ TLS_VERSION_13_DRAFT21
Definition: app-layer-ssl.h:168
TLS_FRAME_DATA
@ TLS_FRAME_DATA
Definition: app-layer-ssl.h:38
SSLStateConnp_::bytes_processed
uint32_t bytes_processed
Definition: app-layer-ssl.h:206
TLS_DECODER_EVENT_INVALID_SNI_TYPE
@ TLS_DECODER_EVENT_INVALID_SNI_TYPE
Definition: app-layer-ssl.h:58
next
struct HtpBodyChunk_ * next
Definition: app-layer-htp.h:0
SSLState_::server_connp
SSLStateConnp server_connp
Definition: app-layer-ssl.h:261
SSLStateConnp_
Definition: app-layer-ssl.h:189
SSLStateConnp_::ja3_hash
char * ja3_hash
Definition: app-layer-ssl.h:229
SSLStateConnp_::session_id_length
uint16_t session_id_length
Definition: app-layer-ssl.h:210
TLS_STATE_FINISHED
@ TLS_STATE_FINISHED
Definition: app-layer-ssl.h:82
TLS_DECODER_EVENT_HEARTBEAT
@ TLS_DECODER_EVENT_HEARTBEAT
Definition: app-layer-ssl.h:52
Flow_
Flow data structure.
Definition: flow.h:353
SSLState_::f
Flow * f
Definition: app-layer-ssl.h:244
SSLState_::tx_data
AppLayerTxData tx_data
Definition: app-layer-ssl.h:246
SSLState_::curr_connp
SSLStateConnp * curr_connp
Definition: app-layer-ssl.h:258
TLS_DECODER_EVENT_INVALID_CERTIFICATE
@ TLS_DECODER_EVENT_INVALID_CERTIFICATE
Definition: app-layer-ssl.h:62
TLS_DECODER_EVENT_INVALID_SNI_LENGTH
@ TLS_DECODER_EVENT_INVALID_SNI_LENGTH
Definition: app-layer-ssl.h:59
TLS_VERSION_13_DRAFT18
@ TLS_VERSION_13_DRAFT18
Definition: app-layer-ssl.h:171
TLS_DECODER_EVENT_DATALEAK_HEARTBEAT_MISMATCH
@ TLS_DECODER_EVENT_DATALEAK_HEARTBEAT_MISMATCH
Definition: app-layer-ssl.h:55
util-ja3.h
TLS_DECODER_EVENT_INVALID_SSL_RECORD
@ TLS_DECODER_EVENT_INVALID_SSL_RECORD
Definition: app-layer-ssl.h:75
SSLStateConnp_::sni
char * sni
Definition: app-layer-ssl.h:220
SSLVersionToString
void SSLVersionToString(uint16_t, char *)
Definition: app-layer-ssl.c:323
TLS_STATE_CERT_READY
@ TLS_STATE_CERT_READY
Definition: app-layer-ssl.h:80
TLS_VERSION_13_DRAFT26
@ TLS_VERSION_13_DRAFT26
Definition: app-layer-ssl.h:163
SSLStateConnp_::record_lengths_length
uint32_t record_lengths_length
Definition: app-layer-ssl.h:193
TLS_FRAME_SSLV2_HDR
@ TLS_FRAME_SSLV2_HDR
Definition: app-layer-ssl.h:41
SSLStateConnp_::cert0_issuerdn
char * cert0_issuerdn
Definition: app-layer-ssl.h:213
TLS_FRAME_HB_DATA
@ TLS_FRAME_HB_DATA
Definition: app-layer-ssl.h:40
TLS_DECODER_EVENT_CERTIFICATE_INVALID_DER
@ TLS_DECODER_EVENT_CERTIFICATE_INVALID_DER
Definition: app-layer-ssl.h:70
SSLStateConnp_::message_start
uint32_t message_start
Definition: app-layer-ssl.h:196
SSLStateConnp
struct SSLStateConnp_ SSLStateConnp
SSLState_::current_flags
uint32_t current_flags
Definition: app-layer-ssl.h:256
TLS_DECODER_EVENT_MULTIPLE_SNI_EXTENSIONS
@ TLS_DECODER_EVENT_MULTIPLE_SNI_EXTENSIONS
Definition: app-layer-ssl.h:57
SSLStateConnp_::cert0_not_after
time_t cert0_not_after
Definition: app-layer-ssl.h:216
TLS_VERSION_UNKNOWN
@ TLS_VERSION_UNKNOWN
Definition: app-layer-ssl.h:154
TLS_VERSION_13_DRAFT28
@ TLS_VERSION_13_DRAFT28
Definition: app-layer-ssl.h:161
TLS_VERSION_10
@ TLS_VERSION_10
Definition: app-layer-ssl.h:157
TLS_DECODER_EVENT_CERTIFICATE_INVALID_VALIDITY
@ TLS_DECODER_EVENT_CERTIFICATE_INVALID_VALIDITY
Definition: app-layer-ssl.h:73
TLS_DECODER_EVENT_CERTIFICATE_INVALID_EXTENSIONS
@ TLS_DECODER_EVENT_CERTIFICATE_INVALID_EXTENSIONS
Definition: app-layer-ssl.h:69
SSLEnableJA3
void SSLEnableJA3(void)
if not explicitly disabled in config, enable ja3 support
Definition: app-layer-ssl.c:3101
SSLStateConnp_::handshake_type
uint8_t handshake_type
Definition: app-layer-ssl.h:202
SSLStateConnp_::hs_bytes_processed
uint16_t hs_bytes_processed
Definition: app-layer-ssl.h:208
TLS_VERSION_13_DRAFT20
@ TLS_VERSION_13_DRAFT20
Definition: app-layer-ssl.h:169
SSLCertsChain_
Definition: app-layer-ssl.h:182
TlsFrameTypes
TlsFrameTypes
Definition: app-layer-ssl.h:35
SSLSetEvent
void SSLSetEvent(SSLState *ssl_state, uint8_t event)
Definition: app-layer-ssl.c:268
SSLStateConnp_::trec_len
uint32_t trec_len
Definition: app-layer-ssl.h:234
TLS_VERSION_13_DRAFT22
@ TLS_VERSION_13_DRAFT22
Definition: app-layer-ssl.h:167
TLS_DECODER_EVENT_INVALID_SSLV2_HEADER
@ TLS_DECODER_EVENT_INVALID_SSLV2_HEADER
Definition: app-layer-ssl.h:47
TLS_VERSION_13_DRAFT23
@ TLS_VERSION_13_DRAFT23
Definition: app-layer-ssl.h:166
app-layer-parser.h
SSLState_::events
uint16_t events
Definition: app-layer-ssl.h:254
TLS_FRAME_SSLV2_PDU
@ TLS_FRAME_SSLV2_PDU
Definition: app-layer-ssl.h:42
RegisterSSLParsers
void RegisterSSLParsers(void)
Function to register the SSL protocol parser and other functions.
Definition: app-layer-ssl.c:2963
TLS_DECODER_EVENT_CERTIFICATE_INVALID_X509NAME
@ TLS_DECODER_EVENT_CERTIFICATE_INVALID_X509NAME
Definition: app-layer-ssl.h:67
TLS_VERSION_13_DRAFT27
@ TLS_VERSION_13_DRAFT27
Definition: app-layer-ssl.h:162
TLS_VERSION_13
@ TLS_VERSION_13
Definition: app-layer-ssl.h:160
TLS_VERSION_13_DRAFT23_FB
@ TLS_VERSION_13_DRAFT23_FB
Definition: app-layer-ssl.h:178
TLS_DECODER_EVENT_ERROR_MSG_ENCOUNTERED
@ TLS_DECODER_EVENT_ERROR_MSG_ENCOUNTERED
Definition: app-layer-ssl.h:74
TLS_VERSION_13_DRAFT25
@ TLS_VERSION_13_DRAFT25
Definition: app-layer-ssl.h:164
SSLStateConnp_::record_length
uint32_t record_length
Definition: app-layer-ssl.h:191
TLS_VERSION_13_DRAFT17
@ TLS_VERSION_13_DRAFT17
Definition: app-layer-ssl.h:172
queue.h
SSLCertsChain_::cert_data
uint8_t * cert_data
Definition: app-layer-ssl.h:183
SSLStateConnp_::handshake_length
uint32_t handshake_length
Definition: app-layer-ssl.h:203
decode-events.h
TLS_DECODER_EVENT_CERTIFICATE_INVALID_DATE
@ TLS_DECODER_EVENT_CERTIFICATE_INVALID_DATE
Definition: app-layer-ssl.h:68
TLS_FRAME_PDU
@ TLS_FRAME_PDU
Definition: app-layer-ssl.h:36
TLS_DECODER_EVENT_INVALID_RECORD_TYPE
@ TLS_DECODER_EVENT_INVALID_RECORD_TYPE
Definition: app-layer-ssl.h:50
TLS_DECODER_EVENT_CERTIFICATE_INVALID_LENGTH
@ TLS_DECODER_EVENT_CERTIFICATE_INVALID_LENGTH
Definition: app-layer-ssl.h:63
TLS_VERSION_13_DRAFT16
@ TLS_VERSION_13_DRAFT16
Definition: app-layer-ssl.h:173
SSLStateConnp_::content_type
uint8_t content_type
Definition: app-layer-ssl.h:200
TLS_DECODER_EVENT_HANDSHAKE_INVALID_LENGTH
@ TLS_DECODER_EVENT_HANDSHAKE_INVALID_LENGTH
Definition: app-layer-ssl.h:56
TLS_VERSION_13_DRAFT19
@ TLS_VERSION_13_DRAFT19
Definition: app-layer-ssl.h:170
TLS_DECODER_EVENT_OVERFLOW_HEARTBEAT
@ TLS_DECODER_EVENT_OVERFLOW_HEARTBEAT
Definition: app-layer-ssl.h:54
SSL_VERSION_2
@ SSL_VERSION_2
Definition: app-layer-ssl.h:155
TLS_DECODER_EVENT_CERTIFICATE_INVALID_ISSUER
@ TLS_DECODER_EVENT_CERTIFICATE_INVALID_ISSUER
Definition: app-layer-ssl.h:72
TLS_DECODER_EVENT_TOO_MANY_RECORDS_IN_PACKET
@ TLS_DECODER_EVENT_TOO_MANY_RECORDS_IN_PACKET
Definition: app-layer-ssl.h:60
TLS_DECODER_EVENT_CERTIFICATE_INVALID_SUBJECT
@ TLS_DECODER_EVENT_CERTIFICATE_INVALID_SUBJECT
Definition: app-layer-ssl.h:71
SSLJA3IsEnabled
bool SSLJA3IsEnabled(void)
Definition: app-layer-ssl.c:3112
SSLStateConnp_::TAILQ_HEAD
TAILQ_HEAD(, SSLCertsChain_) certs
TLS_DECODER_EVENT_CERTIFICATE_INVALID_VERSION
@ TLS_DECODER_EVENT_CERTIFICATE_INVALID_VERSION
Definition: app-layer-ssl.h:64
SSLStateConnp_::cert_log_flag
uint32_t cert_log_flag
Definition: app-layer-ssl.h:226
app-layer-protos.h
TLS_DECODER_EVENT_INVALID_HEARTBEAT
@ TLS_DECODER_EVENT_INVALID_HEARTBEAT
Definition: app-layer-ssl.h:53
TLS_DECODER_EVENT_INVALID_RECORD_VERSION
@ TLS_DECODER_EVENT_INVALID_RECORD_VERSION
Definition: app-layer-ssl.h:49
TLS_VERSION_13_DRAFT22_FB
@ TLS_VERSION_13_DRAFT22_FB
Definition: app-layer-ssl.h:177
TLS_STATE_IN_PROGRESS
@ TLS_STATE_IN_PROGRESS
Definition: app-layer-ssl.h:79
TLS_FRAME_ALERT_DATA
@ TLS_FRAME_ALERT_DATA
Definition: app-layer-ssl.h:39
TLS_VERSION_13_DRAFT20_FB
@ TLS_VERSION_13_DRAFT20_FB
Definition: app-layer-ssl.h:175
SSLCertsChain_::TAILQ_ENTRY
TAILQ_ENTRY(SSLCertsChain_) next
SSLStateConnp_::session_id
char * session_id
Definition: app-layer-ssl.h:222
TLS_FRAME_HDR
@ TLS_FRAME_HDR
Definition: app-layer-ssl.h:37
SSLStateConnp_::cert0_fingerprint
char * cert0_fingerprint
Definition: app-layer-ssl.h:217
TLS_VERSION_13_DRAFT24
@ TLS_VERSION_13_DRAFT24
Definition: app-layer-ssl.h:165
SSLStateConnp_::ja3_str
JA3Buffer * ja3_str
Definition: app-layer-ssl.h:228
SSLState
struct SSLState_ SSLState
SSLv[2.0|3.[0|1|2|3]] state structure.
SSLCertsChain
struct SSLCertsChain_ SSLCertsChain
TLS_DECODER_EVENT_CERTIFICATE_INVALID_ALGORITHMIDENTIFIER
@ TLS_DECODER_EVENT_CERTIFICATE_INVALID_ALGORITHMIDENTIFIER
Definition: app-layer-ssl.h:66
SSLStateConnp_::trec_pos
uint32_t trec_pos
Definition: app-layer-ssl.h:235
TLS_HANDSHAKE_DONE
@ TLS_HANDSHAKE_DONE
Definition: app-layer-ssl.h:81
SSL_VERSION_3
@ SSL_VERSION_3
Definition: app-layer-ssl.h:156
SSLStateConnp_::cert0_serial
char * cert0_serial
Definition: app-layer-ssl.h:214
SSLStateConnp_::trec
uint8_t * trec
Definition: app-layer-ssl.h:233
TLS_DECODER_EVENT_INVALID_TLS_HEADER
@ TLS_DECODER_EVENT_INVALID_TLS_HEADER
Definition: app-layer-ssl.h:48
TLS_VERSION_13_PRE_DRAFT16
@ TLS_VERSION_13_PRE_DRAFT16
Definition: app-layer-ssl.h:174
TLS_DECODER_EVENT_INVALID_HANDSHAKE_MESSAGE
@ TLS_DECODER_EVENT_INVALID_HANDSHAKE_MESSAGE
Definition: app-layer-ssl.h:51
TLS_DECODER_EVENT_CERTIFICATE_INVALID_SERIAL
@ TLS_DECODER_EVENT_CERTIFICATE_INVALID_SERIAL
Definition: app-layer-ssl.h:65
SSLState_::flags
uint32_t flags
Definition: app-layer-ssl.h:249
SSLStateConnp_::version
uint16_t version
Definition: app-layer-ssl.h:199