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 */
59 };
60 
61 enum {
66 };
67 
68 /* Flag to indicate that server will now on send encrypted msgs */
69 #define SSL_AL_FLAG_SERVER_CHANGE_CIPHER_SPEC BIT_U32(0)
70 /* Flag to indicate that client will now on send encrypted msgs */
71 #define SSL_AL_FLAG_CLIENT_CHANGE_CIPHER_SPEC BIT_U32(1)
72 #define SSL_AL_FLAG_CHANGE_CIPHER_SPEC BIT_U32(2)
73 
74 /* SSL related flags */
75 #define SSL_AL_FLAG_SSL_CLIENT_HS BIT_U32(3)
76 #define SSL_AL_FLAG_SSL_SERVER_HS BIT_U32(4)
77 #define SSL_AL_FLAG_SSL_CLIENT_MASTER_KEY BIT_U32(5)
78 #define SSL_AL_FLAG_SSL_CLIENT_SSN_ENCRYPTED BIT_U32(6)
79 #define SSL_AL_FLAG_SSL_SERVER_SSN_ENCRYPTED BIT_U32(7)
80 #define SSL_AL_FLAG_SSL_NO_SESSION_ID BIT_U32(8)
81 
82 /* flags specific to detect-ssl-state keyword */
83 #define SSL_AL_FLAG_STATE_CLIENT_HELLO BIT_U32(9)
84 #define SSL_AL_FLAG_STATE_SERVER_HELLO BIT_U32(10)
85 #define SSL_AL_FLAG_STATE_CLIENT_KEYX BIT_U32(11)
86 #define SSL_AL_FLAG_STATE_SERVER_KEYX BIT_U32(12)
87 #define SSL_AL_FLAG_STATE_UNKNOWN BIT_U32(13)
88 
89 /* flag to indicate that session is finished */
90 #define SSL_AL_FLAG_STATE_FINISHED BIT_U32(14)
91 
92 /* flags specific to HeartBeat state */
93 #define SSL_AL_FLAG_HB_INFLIGHT BIT_U32(15)
94 #define SSL_AL_FLAG_HB_CLIENT_INIT BIT_U32(16)
95 #define SSL_AL_FLAG_HB_SERVER_INIT BIT_U32(17)
96 
97 /* flag to indicate that handshake is done */
98 #define SSL_AL_FLAG_HANDSHAKE_DONE BIT_U32(18)
99 
100 /* A session ID in the Client Hello message, indicating the client
101  wants to resume a session */
102 #define SSL_AL_FLAG_SSL_CLIENT_SESSION_ID BIT_U32(19)
103 /* Session resumed without a full handshake */
104 #define SSL_AL_FLAG_SESSION_RESUMED BIT_U32(20)
105 
106 /* Encountered a supported_versions extension in client hello */
107 #define SSL_AL_FLAG_CH_VERSION_EXTENSION BIT_U32(21)
108 
109 /* Log the session even without ever seeing a certificate. This is used
110  to log TLSv1.3 sessions. */
111 #define SSL_AL_FLAG_LOG_WITHOUT_CERT BIT_U32(22)
112 
113 /* Encountered a early data extension in client hello. This extension is
114  used by 0-RTT. */
115 #define SSL_AL_FLAG_EARLY_DATA BIT_U32(23)
116 
117 /* config flags */
118 #define SSL_TLS_LOG_PEM (1 << 0)
119 
120 /* extensions */
121 #define SSL_EXTENSION_SNI 0x0000
122 #define SSL_EXTENSION_ELLIPTIC_CURVES 0x000a
123 #define SSL_EXTENSION_EC_POINT_FORMATS 0x000b
124 #define SSL_EXTENSION_SESSION_TICKET 0x0023
125 #define SSL_EXTENSION_EARLY_DATA 0x002a
126 #define SSL_EXTENSION_SUPPORTED_VERSIONS 0x002b
127 
128 /* SNI types */
129 #define SSL_SNI_TYPE_HOST_NAME 0
130 
131 /* Max string length of the TLS version string */
132 #define SSL_VERSION_MAX_STRLEN 20
133 
134 /* SSL versions. We'll use a unified format for all, with the top byte
135  * holding the major version and the lower byte the minor version */
136 enum {
138  SSL_VERSION_2 = 0x0200,
139  SSL_VERSION_3 = 0x0300,
140  TLS_VERSION_10 = 0x0301,
141  TLS_VERSION_11 = 0x0302,
142  TLS_VERSION_12 = 0x0303,
143  TLS_VERSION_13 = 0x0304,
163 };
164 
165 typedef struct SSLCertsChain_ {
166  uint8_t *cert_data;
167  uint32_t cert_len;
169 } SSLCertsChain;
170 
171 
172 typedef struct SSLStateConnp_ {
173  /* record length */
174  uint32_t record_length;
175  /* record length's length for SSLv2 */
177 
178  /* offset of the beginning of the current message (including header) */
179  uint32_t message_start;
180  uint32_t message_length;
181 
182  uint16_t version;
183  uint8_t content_type;
184 
185  uint8_t handshake_type;
187 
188  /* the no of bytes processed in the currently parsed record */
189  uint16_t bytes_processed;
190  /* the no of bytes processed in the currently parsed handshake */
192 
194 
201 
202  /* ssl server name indication extension */
203  char *sni;
204 
205  char *session_id;
206 
207  TAILQ_HEAD(, SSLCertsChain_) certs;
208 
209  uint32_t cert_log_flag;
210 
211  /* buffer for the tls record.
212  * We use a malloced buffer, if the record is fragmented */
213  uint8_t *trec;
214  uint32_t trec_len;
215  uint32_t trec_pos;
216 } SSLStateConnp;
217 
218 /**
219  * \brief SSLv[2.0|3.[0|1|2|3]] state structure.
220  *
221  * Structure to store the SSL state values.
222  */
223 typedef struct SSLState_ {
224  Flow *f;
225 
226  /* holds some state flags we need */
227  uint32_t flags;
228 
229  /* specifies which loggers are done logging */
230  uint32_t logged;
231 
232  /* detect flags */
233  uint64_t detect_flags_ts;
234  uint64_t detect_flags_tc;
235 
236  /* there might be a better place to store this*/
237  uint16_t hb_record_len;
238 
239  uint16_t events;
240 
241  uint32_t current_flags;
242 
244  char *ja3_hash;
245 
247 
250 
253 } SSLState;
254 
255 void RegisterSSLParsers(void);
256 void SSLParserRegisterTests(void);
257 void SSLSetEvent(SSLState *ssl_state, uint8_t event);
258 void SSLVersionToString(uint16_t, char *);
259 
260 #endif /* __APP_LAYER_SSL_H__ */
uint16_t hb_record_len
uint64_t detect_flags_ts
TAILQ_ENTRY(SSLCertsChain_) next
char * cert0_subject
time_t cert0_not_before
uint32_t flags
uint16_t hs_bytes_processed
void SSLParserRegisterTests(void)
struct HtpBodyChunk_ * next
uint16_t version
uint32_t message_length
SSLStateConnp * curr_connp
char * cert0_fingerprint
SSLStateConnp server_connp
time_t cert0_not_after
#define TAILQ_HEAD(name, type)
Definition: queue.h:321
uint16_t bytes_processed
uint32_t record_lengths_length
void SSLVersionToString(uint16_t, char *)
SSLv[2.0|3.[0|1|2|3]] state structure.
uint32_t message_start
void SSLSetEvent(SSLState *ssl_state, uint8_t event)
uint64_t detect_flags_tc
Data structure to store app layer decoder events.
uint16_t session_id_length
uint16_t events
uint32_t logged
AppLayerDecoderEvents * decoder_events
uint32_t current_flags
uint32_t handshake_length
uint8_t handshake_type
JA3Buffer * ja3_str
void RegisterSSLParsers(void)
Function to register the SSL protocol parser and other functions.
struct SSLState_ SSLState
SSLv[2.0|3.[0|1|2|3]] state structure.
uint32_t record_length
char * ja3_hash
uint32_t cert_len
uint8_t * cert_data
DetectEngineState * de_state
uint8_t content_type
Flow data structure.
Definition: flow.h:324
SSLStateConnp client_connp
char * cert0_issuerdn