suricata
app-layer-ssl.h
Go to the documentation of this file.
1 /* Copyright (C) 2007-2022 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 SURICATA_APP_LAYER_SSL_H
27 #define SURICATA_APP_LAYER_SSL_H
28 
29 #include "util-ja3.h"
30 #include "rust.h"
31 
33  TLS_FRAME_PDU = 0, /**< whole PDU, so header + data */
34  TLS_FRAME_HDR, /**< only header portion */
35  TLS_FRAME_DATA, /**< only data portion */
40 };
41 
42 enum {
43  /* TLS protocol messages */
60  /* Certificates decoding messages */
75 };
76 
83 };
84 
92 };
93 
94 /* Flag to indicate that server will now on send encrypted msgs */
95 #define SSL_AL_FLAG_SERVER_CHANGE_CIPHER_SPEC BIT_U32(0)
96 /* Flag to indicate that client will now on send encrypted msgs */
97 #define SSL_AL_FLAG_CLIENT_CHANGE_CIPHER_SPEC BIT_U32(1)
98 #define SSL_AL_FLAG_CHANGE_CIPHER_SPEC BIT_U32(2)
99 
100 /* SSL related flags */
101 #define SSL_AL_FLAG_SSL_CLIENT_HS BIT_U32(3)
102 #define SSL_AL_FLAG_SSL_SERVER_HS BIT_U32(4)
103 #define SSL_AL_FLAG_SSL_CLIENT_MASTER_KEY BIT_U32(5)
104 #define SSL_AL_FLAG_SSL_CLIENT_SSN_ENCRYPTED BIT_U32(6)
105 #define SSL_AL_FLAG_SSL_SERVER_SSN_ENCRYPTED BIT_U32(7)
106 #define SSL_AL_FLAG_SSL_NO_SESSION_ID BIT_U32(8)
107 
108 /* flags specific to detect-ssl-state keyword */
109 #define SSL_AL_FLAG_STATE_CLIENT_HELLO BIT_U32(9)
110 #define SSL_AL_FLAG_STATE_SERVER_HELLO BIT_U32(10)
111 #define SSL_AL_FLAG_STATE_CLIENT_KEYX BIT_U32(11)
112 #define SSL_AL_FLAG_STATE_SERVER_KEYX BIT_U32(12)
113 #define SSL_AL_FLAG_STATE_UNKNOWN BIT_U32(13)
114 
115 /* flags specific to HeartBeat state */
116 #define SSL_AL_FLAG_HB_INFLIGHT BIT_U32(15)
117 #define SSL_AL_FLAG_HB_CLIENT_INIT BIT_U32(16)
118 #define SSL_AL_FLAG_HB_SERVER_INIT BIT_U32(17)
119 
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 /* flag to indicate that server random was filled */
135 #define TLS_TS_RANDOM_SET BIT_U32(24)
136 
137 /* flag to indicate that client random was filled */
138 #define TLS_TC_RANDOM_SET BIT_U32(25)
139 
140 #define SSL_AL_FLAG_NEED_CLIENT_CERT BIT_U32(26)
141 
142 /* config flags */
143 #define SSL_TLS_LOG_PEM (1 << 0)
144 
145 /* extensions */
146 #define SSL_EXTENSION_SNI 0x0000
147 #define SSL_EXTENSION_ELLIPTIC_CURVES 0x000a
148 #define SSL_EXTENSION_EC_POINT_FORMATS 0x000b
149 #define SSL_EXTENSION_SIGNATURE_ALGORITHMS 0x000d
150 #define SSL_EXTENSION_ALPN 0x0010
151 #define SSL_EXTENSION_SESSION_TICKET 0x0023
152 #define SSL_EXTENSION_EARLY_DATA 0x002a
153 #define SSL_EXTENSION_SUPPORTED_VERSIONS 0x002b
154 
155 /* SNI types */
156 #define SSL_SNI_TYPE_HOST_NAME 0
157 
158 /* TLS random bytes for the sticky buffer */
159 #define TLS_RANDOM_LEN 32
160 
161 typedef struct SSLCertsChain_ {
162  uint8_t *cert_data;
163  uint32_t cert_len;
166 
167 typedef struct SSLStateConnp_ {
168  /* record length */
169  uint32_t record_length;
170  /* record length's length for SSLv2 */
172 
173  /* offset of the beginning of the current message (including header) */
174  uint32_t message_length;
175 
176  uint16_t version;
177  uint8_t content_type;
178 
179  uint8_t handshake_type;
180 
181  /* the no of bytes processed in the currently parsed record */
182  uint32_t bytes_processed;
183 
185 
193 
194  char **cert0_sans;
195  uint16_t cert0_sans_len;
196  /* ssl server name indication extension */
197  char *sni;
198 
199  char *session_id;
200 
202 
203  uint8_t *certs_buffer;
205 
206  uint32_t cert_log_flag;
207 
209  char *ja3_hash;
210 
211  HandshakeParams *hs;
212 
213  /* handshake tls fragmentation buffer. Handshake messages can be fragmented over multiple
214  * TLS records. */
215  uint8_t *hs_buffer;
218  uint32_t hs_buffer_size; /**< allocation size */
219  uint32_t hs_buffer_offset; /**< write offset */
221 
222 /**
223  * \brief SSLv[2.0|3.[0|1|2|3]] state structure.
224  *
225  * Structure to store the SSL state values.
226  */
227 typedef struct SSLState_ {
228  Flow *f;
229 
230  AppLayerStateData state_data;
232 
233  /* holds some state flags we need */
234  uint32_t flags;
235 
236  /* there might be a better place to store this*/
237  uint32_t hb_record_len;
238 
239  uint16_t events;
240 
241  uint32_t current_flags;
242 
244 
247 
251 
252 void RegisterSSLParsers(void);
253 void SSLEnableJA3(void);
254 bool SSLJA3IsEnabled(void);
255 void SSLEnableJA4(void);
256 bool SSLJA4IsEnabled(void);
257 
258 #endif /* SURICATA_APP_LAYER_SSL_H */
TLS_DECODER_EVENT_CERTIFICATE_INVALID_ISSUER
@ TLS_DECODER_EVENT_CERTIFICATE_INVALID_ISSUER
Definition: app-layer-ssl.h:71
SSLStateConnp_::cert0_subject
char * cert0_subject
Definition: app-layer-ssl.h:187
SSLState_
SSLv[2.0|3.[0|1|2|3]] state structure.
Definition: app-layer-ssl.h:227
JA3Buffer_
Definition: util-ja3.h:31
TLS_DECODER_EVENT_DATALEAK_HEARTBEAT_MISMATCH
@ TLS_DECODER_EVENT_DATALEAK_HEARTBEAT_MISMATCH
Definition: app-layer-ssl.h:53
SSLCertsChain_::cert_len
uint32_t cert_len
Definition: app-layer-ssl.h:163
TLS_DECODER_EVENT_HEARTBEAT
@ TLS_DECODER_EVENT_HEARTBEAT
Definition: app-layer-ssl.h:50
TLS_DECODER_EVENT_OVERFLOW_HEARTBEAT
@ TLS_DECODER_EVENT_OVERFLOW_HEARTBEAT
Definition: app-layer-ssl.h:52
TLS_DECODER_EVENT_ERROR_MSG_ENCOUNTERED
@ TLS_DECODER_EVENT_ERROR_MSG_ENCOUNTERED
Definition: app-layer-ssl.h:73
SSLState_::hb_record_len
uint32_t hb_record_len
Definition: app-layer-ssl.h:237
SSLStateConnp_::message_length
uint32_t message_length
Definition: app-layer-ssl.h:174
SSLState_::client_connp
SSLStateConnp client_connp
Definition: app-layer-ssl.h:248
TLS_DECODER_EVENT_INVALID_HANDSHAKE_MESSAGE
@ TLS_DECODER_EVENT_INVALID_HANDSHAKE_MESSAGE
Definition: app-layer-ssl.h:49
TLS_FRAME_DATA
@ TLS_FRAME_DATA
Definition: app-layer-ssl.h:35
SSLStateConnp_::bytes_processed
uint32_t bytes_processed
Definition: app-layer-ssl.h:182
next
struct HtpBodyChunk_ * next
Definition: app-layer-htp.h:0
SSLState_::server_connp
SSLStateConnp server_connp
Definition: app-layer-ssl.h:249
SSLStateConnp_::cert0_not_before
int64_t cert0_not_before
Definition: app-layer-ssl.h:190
SSLStateConnp_
Definition: app-layer-ssl.h:167
SSLStateConnp_::ja3_hash
char * ja3_hash
Definition: app-layer-ssl.h:209
SSLStateConnp_::session_id_length
uint16_t session_id_length
Definition: app-layer-ssl.h:184
Flow_
Flow data structure.
Definition: flow.h:356
SSLState_::f
Flow * f
Definition: app-layer-ssl.h:228
SSLState_::tx_data
AppLayerTxData tx_data
Definition: app-layer-ssl.h:231
SSLState_::curr_connp
SSLStateConnp * curr_connp
Definition: app-layer-ssl.h:243
TLS_STATE_SERVER_HELLO_DONE
@ TLS_STATE_SERVER_HELLO_DONE
Definition: app-layer-ssl.h:89
rust.h
util-ja3.h
SSLState_::state_data
AppLayerStateData state_data
Definition: app-layer-ssl.h:230
SSLStateConnp_::sni
char * sni
Definition: app-layer-ssl.h:197
TLS_DECODER_EVENT_INVALID_TLS_HEADER
@ TLS_DECODER_EVENT_INVALID_TLS_HEADER
Definition: app-layer-ssl.h:45
SSLStateConnp_::hs_buffer_message_type
uint8_t hs_buffer_message_type
Definition: app-layer-ssl.h:216
TLS_DECODER_EVENT_INVALID_SSL_RECORD
@ TLS_DECODER_EVENT_INVALID_SSL_RECORD
Definition: app-layer-ssl.h:74
TLS_DECODER_EVENT_TOO_MANY_RECORDS_IN_PACKET
@ TLS_DECODER_EVENT_TOO_MANY_RECORDS_IN_PACKET
Definition: app-layer-ssl.h:58
TLS_DECODER_EVENT_MULTIPLE_SNI_EXTENSIONS
@ TLS_DECODER_EVENT_MULTIPLE_SNI_EXTENSIONS
Definition: app-layer-ssl.h:55
SSLStateConnp_::record_lengths_length
uint32_t record_lengths_length
Definition: app-layer-ssl.h:171
TLS_FRAME_SSLV2_HDR
@ TLS_FRAME_SSLV2_HDR
Definition: app-layer-ssl.h:38
SSLStateConnp_::cert0_issuerdn
char * cert0_issuerdn
Definition: app-layer-ssl.h:188
SSLStateConnp_::hs_buffer_size
uint32_t hs_buffer_size
Definition: app-layer-ssl.h:218
TLS_DECODER_EVENT_CERTIFICATE_INVALID_DER
@ TLS_DECODER_EVENT_CERTIFICATE_INVALID_DER
Definition: app-layer-ssl.h:69
TLS_DECODER_EVENT_CERTIFICATE_INVALID_LENGTH
@ TLS_DECODER_EVENT_CERTIFICATE_INVALID_LENGTH
Definition: app-layer-ssl.h:62
TLS_FRAME_HB_DATA
@ TLS_FRAME_HB_DATA
Definition: app-layer-ssl.h:37
SSLStateConnp_::cert0_not_after
int64_t cert0_not_after
Definition: app-layer-ssl.h:191
SSLStateConnp
struct SSLStateConnp_ SSLStateConnp
SSLState_::current_flags
uint32_t current_flags
Definition: app-layer-ssl.h:241
TLS_DECODER_EVENT_CERTIFICATE_INVALID_VALIDITY
@ TLS_DECODER_EVENT_CERTIFICATE_INVALID_VALIDITY
Definition: app-layer-ssl.h:72
TLS_STATE_CLIENT_HANDSHAKE_DONE
@ TLS_STATE_CLIENT_HANDSHAKE_DONE
Definition: app-layer-ssl.h:81
TLS_DECODER_EVENT_INVALID_RECORD_TYPE
@ TLS_DECODER_EVENT_INVALID_RECORD_TYPE
Definition: app-layer-ssl.h:47
SSLState_::client_state
enum TlsStateClient client_state
Definition: app-layer-ssl.h:245
SSLEnableJA3
void SSLEnableJA3(void)
if not explicitly disabled in config, enable ja3 support
Definition: app-layer-ssl.c:3352
SSLStateConnp_::handshake_type
uint8_t handshake_type
Definition: app-layer-ssl.h:179
SSLStateConnp_::hs_buffer_offset
uint32_t hs_buffer_offset
Definition: app-layer-ssl.h:219
SSLStateConnp_::certs_buffer
uint8_t * certs_buffer
Definition: app-layer-ssl.h:203
TLS_STATE_CLIENT_HELLO_DONE
@ TLS_STATE_CLIENT_HELLO_DONE
Definition: app-layer-ssl.h:79
TLS_DECODER_EVENT_INVALID_RECORD_VERSION
@ TLS_DECODER_EVENT_INVALID_RECORD_VERSION
Definition: app-layer-ssl.h:46
TlsStateServer
TlsStateServer
Definition: app-layer-ssl.h:85
TLS_DECODER_EVENT_CERTIFICATE_INVALID_DATE
@ TLS_DECODER_EVENT_CERTIFICATE_INVALID_DATE
Definition: app-layer-ssl.h:67
SSLCertsChain_
Definition: app-layer-ssl.h:161
TlsFrameTypes
TlsFrameTypes
Definition: app-layer-ssl.h:32
TLS_DECODER_EVENT_CERTIFICATE_INVALID_SERIAL
@ TLS_DECODER_EVENT_CERTIFICATE_INVALID_SERIAL
Definition: app-layer-ssl.h:64
TlsStateClient
TlsStateClient
Definition: app-layer-ssl.h:77
TLS_DECODER_EVENT_CERTIFICATE_INVALID_SUBJECT
@ TLS_DECODER_EVENT_CERTIFICATE_INVALID_SUBJECT
Definition: app-layer-ssl.h:70
TLS_STATE_SERVER_FINISHED
@ TLS_STATE_SERVER_FINISHED
Definition: app-layer-ssl.h:91
TLS_RANDOM_LEN
#define TLS_RANDOM_LEN
Definition: app-layer-ssl.h:159
TLS_STATE_CLIENT_IN_PROGRESS
@ TLS_STATE_CLIENT_IN_PROGRESS
Definition: app-layer-ssl.h:78
SSLState_::events
uint16_t events
Definition: app-layer-ssl.h:239
TLS_FRAME_SSLV2_PDU
@ TLS_FRAME_SSLV2_PDU
Definition: app-layer-ssl.h:39
RegisterSSLParsers
void RegisterSSLParsers(void)
Function to register the SSL protocol parser and other functions.
Definition: app-layer-ssl.c:3212
TLS_DECODER_EVENT_INVALID_SSLV2_HEADER
@ TLS_DECODER_EVENT_INVALID_SSLV2_HEADER
Definition: app-layer-ssl.h:44
TLS_DECODER_EVENT_INVALID_RECORD_LENGTH
@ TLS_DECODER_EVENT_INVALID_RECORD_LENGTH
Definition: app-layer-ssl.h:48
SSLState_::server_state
enum TlsStateServer server_state
Definition: app-layer-ssl.h:246
SSLStateConnp_::record_length
uint32_t record_length
Definition: app-layer-ssl.h:169
TLS_STATE_SERVER_CERT_DONE
@ TLS_STATE_SERVER_CERT_DONE
Definition: app-layer-ssl.h:88
SSLCertsChain_::cert_data
uint8_t * cert_data
Definition: app-layer-ssl.h:162
SSLStateConnp_::certs_buffer_size
uint32_t certs_buffer_size
Definition: app-layer-ssl.h:204
TLS_DECODER_EVENT_INVALID_HEARTBEAT
@ TLS_DECODER_EVENT_INVALID_HEARTBEAT
Definition: app-layer-ssl.h:51
TLS_DECODER_EVENT_HANDSHAKE_INVALID_LENGTH
@ TLS_DECODER_EVENT_HANDSHAKE_INVALID_LENGTH
Definition: app-layer-ssl.h:54
AppLayerTxData
struct AppLayerTxData AppLayerTxData
Definition: detect.h:1485
TLS_DECODER_EVENT_CERTIFICATE_INVALID_VERSION
@ TLS_DECODER_EVENT_CERTIFICATE_INVALID_VERSION
Definition: app-layer-ssl.h:63
SSLStateConnp_::random
uint8_t random[TLS_RANDOM_LEN]
Definition: app-layer-ssl.h:186
TLS_DECODER_EVENT_INVALID_CERTIFICATE
@ TLS_DECODER_EVENT_INVALID_CERTIFICATE
Definition: app-layer-ssl.h:61
TLS_FRAME_PDU
@ TLS_FRAME_PDU
Definition: app-layer-ssl.h:33
SSLStateConnp_::content_type
uint8_t content_type
Definition: app-layer-ssl.h:177
SSLStateConnp_::hs_buffer_message_size
uint32_t hs_buffer_message_size
Definition: app-layer-ssl.h:217
TLS_DECODER_EVENT_CERTIFICATE_INVALID_ALGORITHMIDENTIFIER
@ TLS_DECODER_EVENT_CERTIFICATE_INVALID_ALGORITHMIDENTIFIER
Definition: app-layer-ssl.h:65
SSLEnableJA4
void SSLEnableJA4(void)
if not explicitly disabled in config, enable ja4 support
Definition: app-layer-ssl.c:3369
TLS_DECODER_EVENT_INVALID_SNI_TYPE
@ TLS_DECODER_EVENT_INVALID_SNI_TYPE
Definition: app-layer-ssl.h:56
TLS_STATE_CLIENT_CERT_DONE
@ TLS_STATE_CLIENT_CERT_DONE
Definition: app-layer-ssl.h:80
TLS_STATE_SERVER_IN_PROGRESS
@ TLS_STATE_SERVER_IN_PROGRESS
Definition: app-layer-ssl.h:86
TLS_DECODER_EVENT_CERTIFICATE_INVALID_X509NAME
@ TLS_DECODER_EVENT_CERTIFICATE_INVALID_X509NAME
Definition: app-layer-ssl.h:66
SSLJA3IsEnabled
bool SSLJA3IsEnabled(void)
return whether ja3 is effectively enabled
Definition: app-layer-ssl.c:3389
SSLStateConnp_::TAILQ_HEAD
TAILQ_HEAD(, SSLCertsChain_) certs
SSLStateConnp_::cert0_sans_len
uint16_t cert0_sans_len
Definition: app-layer-ssl.h:195
SSLStateConnp_::cert_log_flag
uint32_t cert_log_flag
Definition: app-layer-ssl.h:206
TLS_DECODER_EVENT_CERTIFICATE_INVALID_EXTENSIONS
@ TLS_DECODER_EVENT_CERTIFICATE_INVALID_EXTENSIONS
Definition: app-layer-ssl.h:68
TLS_DECODER_EVENT_INVALID_SNI_LENGTH
@ TLS_DECODER_EVENT_INVALID_SNI_LENGTH
Definition: app-layer-ssl.h:57
SSLStateConnp_::hs
HandshakeParams * hs
Definition: app-layer-ssl.h:211
TLS_FRAME_ALERT_DATA
@ TLS_FRAME_ALERT_DATA
Definition: app-layer-ssl.h:36
TLS_STATE_SERVER_HELLO
@ TLS_STATE_SERVER_HELLO
Definition: app-layer-ssl.h:87
SSLCertsChain_::TAILQ_ENTRY
TAILQ_ENTRY(SSLCertsChain_) next
SSLStateConnp_::session_id
char * session_id
Definition: app-layer-ssl.h:199
TLS_FRAME_HDR
@ TLS_FRAME_HDR
Definition: app-layer-ssl.h:34
TLS_DECODER_EVENT_INVALID_ALERT
@ TLS_DECODER_EVENT_INVALID_ALERT
Definition: app-layer-ssl.h:59
SSLStateConnp_::cert0_fingerprint
char * cert0_fingerprint
Definition: app-layer-ssl.h:192
SSLStateConnp_::ja3_str
JA3Buffer * ja3_str
Definition: app-layer-ssl.h:208
TLS_STATE_SERVER_HANDSHAKE_DONE
@ TLS_STATE_SERVER_HANDSHAKE_DONE
Definition: app-layer-ssl.h:90
SSLState
struct SSLState_ SSLState
SSLv[2.0|3.[0|1|2|3]] state structure.
SSLCertsChain
struct SSLCertsChain_ SSLCertsChain
SSLStateConnp_::hs_buffer
uint8_t * hs_buffer
Definition: app-layer-ssl.h:215
SSLStateConnp_::cert0_serial
char * cert0_serial
Definition: app-layer-ssl.h:189
TLS_STATE_CLIENT_FINISHED
@ TLS_STATE_CLIENT_FINISHED
Definition: app-layer-ssl.h:82
SSLJA4IsEnabled
bool SSLJA4IsEnabled(void)
return whether ja4 is effectively enabled
Definition: app-layer-ssl.c:3402
SSLStateConnp_::cert0_sans
char ** cert0_sans
Definition: app-layer-ssl.h:194
SSLState_::flags
uint32_t flags
Definition: app-layer-ssl.h:234
SSLStateConnp_::version
uint16_t version
Definition: app-layer-ssl.h:176