src/app-layer-ssl.h

   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 */
  37     TLS_DECODER_EVENT_INVALID_SSLV2_HEADER,
  38     TLS_DECODER_EVENT_INVALID_TLS_HEADER,
  39     TLS_DECODER_EVENT_INVALID_RECORD_VERSION,
  40     TLS_DECODER_EVENT_INVALID_RECORD_TYPE,
  41     TLS_DECODER_EVENT_INVALID_HANDSHAKE_MESSAGE,
  42     TLS_DECODER_EVENT_HEARTBEAT,
  43     TLS_DECODER_EVENT_INVALID_HEARTBEAT,
  44     TLS_DECODER_EVENT_OVERFLOW_HEARTBEAT,
  45     TLS_DECODER_EVENT_DATALEAK_HEARTBEAT_MISMATCH,
  46     TLS_DECODER_EVENT_HANDSHAKE_INVALID_LENGTH,
  47     TLS_DECODER_EVENT_MULTIPLE_SNI_EXTENSIONS,
  48     TLS_DECODER_EVENT_INVALID_SNI_TYPE,
  49     TLS_DECODER_EVENT_INVALID_SNI_LENGTH,
  50     TLS_DECODER_EVENT_TOO_MANY_RECORDS_IN_PACKET,
  51     /* Certificates decoding messages */
  52     TLS_DECODER_EVENT_INVALID_CERTIFICATE,
  53     TLS_DECODER_EVENT_CERTIFICATE_INVALID_LENGTH,
  54     TLS_DECODER_EVENT_CERTIFICATE_INVALID_VERSION,
  55     TLS_DECODER_EVENT_CERTIFICATE_INVALID_SERIAL,
  56     TLS_DECODER_EVENT_CERTIFICATE_INVALID_ALGORITHMIDENTIFIER,
  57     TLS_DECODER_EVENT_CERTIFICATE_INVALID_X509NAME,
  58     TLS_DECODER_EVENT_CERTIFICATE_INVALID_DATE,
  59     TLS_DECODER_EVENT_CERTIFICATE_INVALID_EXTENSIONS,
  60     TLS_DECODER_EVENT_CERTIFICATE_INVALID_DER,
  61     TLS_DECODER_EVENT_CERTIFICATE_INVALID_SUBJECT,
  62     TLS_DECODER_EVENT_CERTIFICATE_INVALID_ISSUER,
  63     TLS_DECODER_EVENT_CERTIFICATE_INVALID_VALIDITY,
  64     TLS_DECODER_EVENT_ERROR_MSG_ENCOUNTERED,
  65     TLS_DECODER_EVENT_INVALID_SSL_RECORD,
  66 };
  67
  68 enum {
  69     TLS_STATE_IN_PROGRESS = 0,
  70     TLS_STATE_CERT_READY = 1,
  71     TLS_HANDSHAKE_DONE = 2,
  72     TLS_STATE_FINISHED = 3
  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 {
 144     TLS_VERSION_UNKNOWN = 0x0000,
 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,
 151     TLS_VERSION_13_DRAFT28 = 0x7f1c,
 152     TLS_VERSION_13_DRAFT27 = 0x7f1b,
 153     TLS_VERSION_13_DRAFT26 = 0x7f1a,
 154     TLS_VERSION_13_DRAFT25 = 0x7f19,
 155     TLS_VERSION_13_DRAFT24 = 0x7f18,
 156     TLS_VERSION_13_DRAFT23 = 0x7f17,
 157     TLS_VERSION_13_DRAFT22 = 0x7f16,
 158     TLS_VERSION_13_DRAFT21 = 0x7f15,
 159     TLS_VERSION_13_DRAFT20 = 0x7f14,
 160     TLS_VERSION_13_DRAFT19 = 0x7f13,
 161     TLS_VERSION_13_DRAFT18 = 0x7f12,
 162     TLS_VERSION_13_DRAFT17 = 0x7f11,
 163     TLS_VERSION_13_DRAFT16 = 0x7f10,
 164     TLS_VERSION_13_PRE_DRAFT16 = 0x7f01,
 165     TLS_VERSION_13_DRAFT20_FB = 0xfb14,
 166     TLS_VERSION_13_DRAFT21_FB = 0xfb15,
 167     TLS_VERSION_13_DRAFT22_FB = 0xfb16,
 168     TLS_VERSION_13_DRAFT23_FB = 0xfb17,
 169     TLS_VERSION_13_DRAFT26_FB = 0xfb1a,
 170 };
 171
 172 typedef struct SSLCertsChain_ {
 173     uint8_t *cert_data;
 174     uint32_t cert_len;
 175     TAILQ_ENTRY(SSLCertsChain_) next;
 176 } SSLCertsChain;
 177
 178
 179 typedef struct SSLStateConnp_ {
 180     /* record length */
 181     uint32_t record_length;
 182     /* record length's length for SSLv2 */
 183     uint32_t record_lengths_length;
 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;
 193     uint32_t handshake_length;
 194
 195     /* the no of bytes processed in the currently parsed record */
 196     uint32_t bytes_processed;
 197     /* the no of bytes processed in the currently parsed handshake */
 198     uint16_t hs_bytes_processed;
 199
 200     uint16_t session_id_length;
 201
 202     char *cert0_subject;
 203     char *cert0_issuerdn;
 204     char *cert0_serial;
 205     time_t cert0_not_before;
 206     time_t cert0_not_after;
 207     char *cert0_fingerprint;
 208
 209     /* ssl server name indication extension */
 210     char *sni;
 211
 212     char *session_id;
 213
 214     TAILQ_HEAD(, SSLCertsChain_) certs;
 215
 216     uint32_t cert_log_flag;
 217
 218     JA3Buffer *ja3_str;
 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;
 226 } SSLStateConnp;
 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
 248     SSLStateConnp *curr_connp;
 249
 250     SSLStateConnp client_connp;
 251     SSLStateConnp server_connp;
 252
 253     DetectEngineState *de_state;
 254     AppLayerDecoderEvents *decoder_events;
 255 } SSLState;
 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__ */