tls: add tls.random* keywords

Add tls.random keyword that matches on the 32 bytes of the TLS
random field for client as well as server.
Add tls.random_time keyword that matches on the first 4 bytes of the TLS
random field for client as well as server.
Add tls.random_bytes keyword that matches on the last 28 bytes of the TLS
random field for client as well as server.

All these are sticky buffers.

Feature 5190

src/Makefile.am

@@ -334,6 +334,7 @@ noinst_HEADERS = \
 	detect-tls-ja3-string.h \
 	detect-tls-sni.h \
 	detect-tls-version.h \
+	detect-tls-random.h \
 	detect-tos.h \
 	detect-transform-compress-whitespace.h \
 	detect-transform-dotprefix.h \
@@ -931,6 +932,7 @@ libsuricata_c_a_SOURCES = \
 	detect-tls-ja3-string.c \
 	detect-tls-sni.c \
 	detect-tls-version.c \
+	detect-tls-random.c \
 	detect-tos.c \
 	detect-transform-compress-whitespace.c \
 	detect-transform-dotprefix.c \

src/app-layer-ssl.c

@@ -1,4 +1,4 @@
-/* Copyright (C) 2007-2020 Open Information Security Foundation
+/* Copyright (C) 2007-2022 Open Information Security Foundation
  *
  * You can copy, redistribute or modify this Program under the terms of
  * the GNU General Public License version 2 as published by the Free
@@ -705,6 +705,14 @@ static inline int TLSDecodeHSHelloRandom(SSLState *ssl_state,
         return -1;
     }
 
+    if (ssl_state->current_flags & SSL_AL_FLAG_STATE_SERVER_HELLO) {
+        memcpy(ssl_state->server_connp.random, input, TLS_RANDOM_LEN);
+        ssl_state->flags |= TLS_TS_RANDOM_SET;
+    } else if (ssl_state->current_flags & SSL_AL_FLAG_STATE_CLIENT_HELLO) {
+        memcpy(ssl_state->client_connp.random, input, TLS_RANDOM_LEN);
+        ssl_state->flags |= TLS_TC_RANDOM_SET;
+    }
+
     /* Skip random */
     input += SSLV3_CLIENT_HELLO_RANDOM_LEN;
 
@@ -2682,6 +2690,8 @@ static void *SSLStateAlloc(void *orig_state, AppProto proto_orig)
     memset(ssl_state, 0, sizeof(SSLState));
     ssl_state->client_connp.cert_log_flag = 0;
     ssl_state->server_connp.cert_log_flag = 0;
+    memset(ssl_state->client_connp.random, 0, TLS_RANDOM_LEN);
+    memset(ssl_state->server_connp.random, 0, TLS_RANDOM_LEN);
     TAILQ_INIT(&ssl_state->server_connp.certs);
 
     return (void *)ssl_state;

src/app-layer-ssl.h

@@ -1,4 +1,4 @@
-/* Copyright (C) 2007-2012 Open Information Security Foundation
+/* Copyright (C) 2007-2022 Open Information Security Foundation
  *
  * You can copy, redistribute or modify this Program under the terms of
  * the GNU General Public License version 2 as published by the Free
@@ -128,6 +128,12 @@ enum {
    used by 0-RTT. */
 #define SSL_AL_FLAG_EARLY_DATA                  BIT_U32(23)
 
+/* flag to indicate that server random was filled */
+#define TLS_TS_RANDOM_SET BIT_U32(24)
+
+/* flag to indicate that client random was filled */
+#define TLS_TC_RANDOM_SET BIT_U32(25)
+
 /* config flags */
 #define SSL_TLS_LOG_PEM                         (1 << 0)
 
@@ -145,6 +151,9 @@ enum {
 /* Max string length of the TLS version string */
 #define SSL_VERSION_MAX_STRLEN 20
 
+/* TLS random bytes for the sticky buffer */
+#define TLS_RANDOM_LEN 32
+
 /* SSL versions.  We'll use a unified format for all, with the top byte
  * holding the major version and the lower byte the minor version */
 enum {
@@ -206,6 +215,7 @@ typedef struct SSLStateConnp_ {
 
     uint16_t session_id_length;
 
+    uint8_t random[TLS_RANDOM_LEN];
     char *cert0_subject;
     char *cert0_issuerdn;
     char *cert0_serial;

src/detect-engine-register.c

@@ -53,6 +53,7 @@
 #include "detect-tls-cert-issuer.h"
 #include "detect-tls-cert-subject.h"
 #include "detect-tls-cert-serial.h"
+#include "detect-tls-random.h"
 #include "detect-tls-ja3-hash.h"
 #include "detect-tls-ja3-string.h"
 #include "detect-tls-ja3s-hash.h"
@@ -520,6 +521,7 @@ void SigTableSetup(void)
     DetectTlsSerialRegister();
     DetectTlsFingerprintRegister();
     DetectTlsCertsRegister();
+    DetectTlsRandomRegister();
 
     DetectTlsJa3HashRegister();
     DetectTlsJa3StringRegister();

src/detect-engine-register.h

@@ -221,6 +221,9 @@ enum DetectKeywordId {
     DETECT_AL_TLS_CERT_SUBJECT,
     DETECT_AL_TLS_CERT_SERIAL,
     DETECT_AL_TLS_CERT_FINGERPRINT,
+    DETECT_AL_TLS_RANDOM_TIME,
+    DETECT_AL_TLS_RANDOM_BYTES,
+    DETECT_AL_TLS_RANDOM,
 
     DETECT_AL_TLS_JA3_HASH,
     DETECT_AL_TLS_JA3_STRING,

src/detect-tls-random.c

@@ -0,0 +1,284 @@
+/* Copyright (C) 2022 Open Information Security Foundation
+ *
+ * You can copy, redistribute or modify this Program under the terms of
+ * the GNU General Public License version 2 as published by the Free
+ * Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * version 2 along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ * 02110-1301, USA.
+ */
+
+#include "suricata-common.h"
+#include "threads.h"
+#include "debug.h"
+#include "detect.h"
+
+#include "detect-parse.h"
+#include "detect-engine.h"
+#include "detect-engine-mpm.h"
+#include "detect-content.h"
+
+#include "flow.h"
+#include "stream-tcp.h"
+
+#include "app-layer.h"
+#include "app-layer-ssl.h"
+#include "detect-engine-prefilter.h"
+#include "detect-tls-random.h"
+
+#define DETECT_TLS_RANDOM_TIME_LEN  4
+#define DETECT_TLS_RANDOM_BYTES_LEN 28
+
+static int DetectTlsRandomTimeSetup(DetectEngineCtx *, Signature *, const char *);
+static int DetectTlsRandomBytesSetup(DetectEngineCtx *, Signature *, const char *);
+static int DetectTlsRandomSetup(DetectEngineCtx *, Signature *, const char *);
+static InspectionBuffer *GetRandomTimeData(DetectEngineThreadCtx *det_ctx,
+        const DetectEngineTransforms *transforms, Flow *f, const uint8_t flow_flags, void *txv,
+        const int list_id);
+static InspectionBuffer *GetRandomBytesData(DetectEngineThreadCtx *det_ctx,
+        const DetectEngineTransforms *transforms, Flow *f, const uint8_t flow_flags, void *txv,
+        const int list_id);
+static InspectionBuffer *GetRandomData(DetectEngineThreadCtx *det_ctx,
+        const DetectEngineTransforms *transforms, Flow *f, const uint8_t flow_flags, void *txv,
+        const int list_id);
+
+static int g_tls_random_time_buffer_id = 0;
+static int g_tls_random_bytes_buffer_id = 0;
+static int g_tls_random_buffer_id = 0;
+
+void DetectTlsRandomTimeRegister(void)
+{
+    sigmatch_table[DETECT_AL_TLS_RANDOM_TIME].name = "tls.random_time";
+    sigmatch_table[DETECT_AL_TLS_RANDOM_TIME].desc = "sticky buffer to match specifically and only "
+                                                     "on the first 4 bytes of a TLS random buffer";
+    sigmatch_table[DETECT_AL_TLS_RANDOM_TIME].url = "/rules/tls-keywords.html#tls-random-time";
+    sigmatch_table[DETECT_AL_TLS_RANDOM_TIME].Setup = DetectTlsRandomTimeSetup;
+    sigmatch_table[DETECT_AL_TLS_RANDOM_TIME].flags |= SIGMATCH_NOOPT | SIGMATCH_INFO_STICKY_BUFFER;
+
+    /* Register engine for Server random */
+    DetectAppLayerInspectEngineRegister2("tls.random_time", ALPROTO_TLS, SIG_FLAG_TOSERVER, 0,
+            DetectEngineInspectBufferGeneric, GetRandomTimeData);
+    DetectAppLayerMpmRegister2("tls.random_time", SIG_FLAG_TOSERVER, 2, PrefilterGenericMpmRegister,
+            GetRandomTimeData, ALPROTO_TLS, 0);
+
+    /* Register engine for Client random */
+    DetectAppLayerInspectEngineRegister2("tls.random_time", ALPROTO_TLS, SIG_FLAG_TOCLIENT, 0,
+            DetectEngineInspectBufferGeneric, GetRandomTimeData);
+    DetectAppLayerMpmRegister2("tls.random_time", SIG_FLAG_TOCLIENT, 2, PrefilterGenericMpmRegister,
+            GetRandomTimeData, ALPROTO_TLS, 0);
+
+    DetectBufferTypeSetDescriptionByName("tls.random_time", "TLS Random Time");
+
+    g_tls_random_time_buffer_id = DetectBufferTypeGetByName("tls.random_time");
+}
+
+void DetectTlsRandomBytesRegister(void)
+{
+    sigmatch_table[DETECT_AL_TLS_RANDOM_BYTES].name = "tls.random_bytes";
+    sigmatch_table[DETECT_AL_TLS_RANDOM_BYTES].desc =
+            "sticky buffer to match specifically and only on the last 28 bytes of a TLS random "
+            "buffer";
+    sigmatch_table[DETECT_AL_TLS_RANDOM_BYTES].url = "/rules/tls-keywords.html#tls-random-bytes";
+    sigmatch_table[DETECT_AL_TLS_RANDOM_BYTES].Setup = DetectTlsRandomBytesSetup;
+    sigmatch_table[DETECT_AL_TLS_RANDOM_BYTES].flags |=
+            SIGMATCH_NOOPT | SIGMATCH_INFO_STICKY_BUFFER;
+
+    /* Register engine for Server random */
+    DetectAppLayerInspectEngineRegister2("tls.random_bytes", ALPROTO_TLS, SIG_FLAG_TOSERVER, 0,
+            DetectEngineInspectBufferGeneric, GetRandomBytesData);
+    DetectAppLayerMpmRegister2("tls.random_bytes", SIG_FLAG_TOSERVER, 2,
+            PrefilterGenericMpmRegister, GetRandomBytesData, ALPROTO_TLS, 0);
+
+    /* Register engine for Client random */
+    DetectAppLayerInspectEngineRegister2("tls.random_bytes", ALPROTO_TLS, SIG_FLAG_TOCLIENT, 0,
+            DetectEngineInspectBufferGeneric, GetRandomBytesData);
+    DetectAppLayerMpmRegister2("tls.random_bytes", SIG_FLAG_TOCLIENT, 2,
+            PrefilterGenericMpmRegister, GetRandomBytesData, ALPROTO_TLS, 0);
+
+    DetectBufferTypeSetDescriptionByName("tls.random_bytes", "TLS Random Bytes");
+
+    g_tls_random_bytes_buffer_id = DetectBufferTypeGetByName("tls.random_bytes");
+}
+
+/**
+ * \brief Registration function for keyword: tls.random
+ */
+void DetectTlsRandomRegister(void)
+{
+    DetectTlsRandomTimeRegister();
+    DetectTlsRandomBytesRegister();
+
+    sigmatch_table[DETECT_AL_TLS_RANDOM].name = "tls.random";
+    sigmatch_table[DETECT_AL_TLS_RANDOM].desc =
+            "sticky buffer to match specifically and only on a TLS random buffer";
+    sigmatch_table[DETECT_AL_TLS_RANDOM].url = "/rules/tls-keywords.html#tls-random";
+    sigmatch_table[DETECT_AL_TLS_RANDOM].Setup = DetectTlsRandomSetup;
+    sigmatch_table[DETECT_AL_TLS_RANDOM].flags |= SIGMATCH_NOOPT | SIGMATCH_INFO_STICKY_BUFFER;
+
+    /* Register engine for Server random */
+    DetectAppLayerInspectEngineRegister2("tls.random", ALPROTO_TLS, SIG_FLAG_TOSERVER, 0,
+            DetectEngineInspectBufferGeneric, GetRandomData);
+    DetectAppLayerMpmRegister2("tls.random", SIG_FLAG_TOSERVER, 2, PrefilterGenericMpmRegister,
+            GetRandomData, ALPROTO_TLS, 0);
+
+    /* Register engine for Client random */
+    DetectAppLayerInspectEngineRegister2("tls.random", ALPROTO_TLS, SIG_FLAG_TOCLIENT, 0,
+            DetectEngineInspectBufferGeneric, GetRandomData);
+    DetectAppLayerMpmRegister2("tls.random", SIG_FLAG_TOCLIENT, 2, PrefilterGenericMpmRegister,
+            GetRandomData, ALPROTO_TLS, 0);
+
+    DetectBufferTypeSetDescriptionByName("tls.random", "TLS Random");
+
+    g_tls_random_buffer_id = DetectBufferTypeGetByName("tls.random");
+}
+
+/**
+ * \brief this function setup the tls.random_time sticky buffer keyword used in the rule
+ *
+ * \param de_ctx   Pointer to the Detection Engine Context
+ * \param s        Pointer to the Signature to which the current keyword belongs
+ * \param str      Should hold an empty string always
+ *
+ * \retval 0  On success
+ * \retval -1 On failure
+ */
+static int DetectTlsRandomTimeSetup(DetectEngineCtx *de_ctx, Signature *s, const char *str)
+{
+    if (DetectBufferSetActiveList(s, g_tls_random_time_buffer_id) < 0)
+        return -1;
+
+    if (DetectSignatureSetAppProto(s, ALPROTO_TLS) < 0)
+        return -1;
+
+    return 0;
+}
+
+/**
+ * \brief this function setup the tls.random_bytes sticky buffer keyword used in the rule
+ *
+ * \param de_ctx   Pointer to the Detection Engine Context
+ * \param s        Pointer to the Signature to which the current keyword belongs
+ * \param str      Should hold an empty string always
+ *
+ * \retval 0  On success
+ * \retval -1 On failure
+ */
+static int DetectTlsRandomBytesSetup(DetectEngineCtx *de_ctx, Signature *s, const char *str)
+{
+    if (DetectBufferSetActiveList(s, g_tls_random_bytes_buffer_id) < 0)
+        return -1;
+
+    if (DetectSignatureSetAppProto(s, ALPROTO_TLS) < 0)
+        return -1;
+
+    return 0;
+}
+
+/**
+ * \brief this function setup the tls.random sticky buffer keyword used in the rule
+ *
+ * \param de_ctx   Pointer to the Detection Engine Context
+ * \param s        Pointer to the Signature to which the current keyword belongs
+ * \param str      Should hold an empty string always
+ *
+ * \retval 0  On success
+ * \retval -1 On failure
+ */
+static int DetectTlsRandomSetup(DetectEngineCtx *de_ctx, Signature *s, const char *str)
+{
+    if (DetectBufferSetActiveList(s, g_tls_random_buffer_id) < 0)
+        return -1;
+
+    if (DetectSignatureSetAppProto(s, ALPROTO_TLS) < 0)
+        return -1;
+
+    return 0;
+}
+
+static InspectionBuffer *GetRandomTimeData(DetectEngineThreadCtx *det_ctx,
+        const DetectEngineTransforms *transforms, Flow *f, const uint8_t flow_flags, void *txv,
+        const int list_id)
+{
+    InspectionBuffer *buffer = InspectionBufferGet(det_ctx, list_id);
+    if (buffer->inspect == NULL) {
+        const SSLState *ssl_state = (SSLState *)f->alstate;
+        if (flow_flags & STREAM_TOSERVER) {
+            if (!(ssl_state->flags & TLS_TS_RANDOM_SET))
+                return NULL;
+        } else {
+            if (!(ssl_state->flags & TLS_TC_RANDOM_SET))
+                return NULL;
+        }
+        const uint32_t data_len = DETECT_TLS_RANDOM_TIME_LEN;
+        const uint8_t *data;
+        if (flow_flags & STREAM_TOSERVER) {
+            data = ssl_state->server_connp.random;
+        } else {
+            data = ssl_state->client_connp.random;
+        }
+        InspectionBufferSetup(det_ctx, list_id, buffer, data, data_len);
+        InspectionBufferApplyTransforms(buffer, transforms);
+    }
+    return buffer;
+}
+
+static InspectionBuffer *GetRandomBytesData(DetectEngineThreadCtx *det_ctx,
+        const DetectEngineTransforms *transforms, Flow *f, const uint8_t flow_flags, void *txv,
+        const int list_id)
+{
+    InspectionBuffer *buffer = InspectionBufferGet(det_ctx, list_id);
+    if (buffer->inspect == NULL) {
+        const SSLState *ssl_state = (SSLState *)f->alstate;
+        if (flow_flags & STREAM_TOSERVER) {
+            if (!(ssl_state->flags & TLS_TS_RANDOM_SET))
+                return NULL;
+        } else {
+            if (!(ssl_state->flags & TLS_TC_RANDOM_SET))
+                return NULL;
+        }
+        const uint32_t data_len = DETECT_TLS_RANDOM_BYTES_LEN;
+        const uint8_t *data;
+        if (flow_flags & STREAM_TOSERVER) {
+            data = ssl_state->server_connp.random + DETECT_TLS_RANDOM_TIME_LEN;
+        } else {
+            data = ssl_state->client_connp.random + DETECT_TLS_RANDOM_TIME_LEN;
+        }
+        InspectionBufferSetup(det_ctx, list_id, buffer, data, data_len);
+        InspectionBufferApplyTransforms(buffer, transforms);
+    }
+    return buffer;
+}
+
+static InspectionBuffer *GetRandomData(DetectEngineThreadCtx *det_ctx,
+        const DetectEngineTransforms *transforms, Flow *f, const uint8_t flow_flags, void *txv,
+        const int list_id)
+{
+    InspectionBuffer *buffer = InspectionBufferGet(det_ctx, list_id);
+    if (buffer->inspect == NULL) {
+        const SSLState *ssl_state = (SSLState *)f->alstate;
+        if (flow_flags & STREAM_TOSERVER) {
+            if (!(ssl_state->flags & TLS_TS_RANDOM_SET))
+                return NULL;
+        } else {
+            if (!(ssl_state->flags & TLS_TC_RANDOM_SET))
+                return NULL;
+        }
+        const uint32_t data_len = TLS_RANDOM_LEN;
+        const uint8_t *data;
+        if (flow_flags & STREAM_TOSERVER) {
+            data = ssl_state->server_connp.random;
+        } else {
+            data = ssl_state->client_connp.random;
+        }
+        InspectionBufferSetup(det_ctx, list_id, buffer, data, data_len);
+        InspectionBufferApplyTransforms(buffer, transforms);
+    }
+    return buffer;
+}

src/detect-tls-random.h

@@ -0,0 +1,25 @@
+/* Copyright (C) 2022 Open Information Security Foundation
+ *
+ * You can copy, redistribute or modify this Program under the terms of
+ * the GNU General Public License version 2 as published by the Free
+ * Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * version 2 along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ * 02110-1301, USA.
+ */
+
+#ifndef __DETECT_TLS_RANDOM_H__
+#define __DETECT_TLS_RANDOM_H__
+
+void DetectTlsRandomTimeRegister(void);
+void DetectTlsRandomBytesRegister(void);
+void DetectTlsRandomRegister(void);
+
+#endif /* __DETECT_TLS_RANDOM_H__ */