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