From: Lukas Sismis <lsismis@oisf.net>
Date: Thu, 27 Mar 2025 16:10:12 +0000 (+0100)
Subject: tls: deprecate "default" as a encryption-handling option
X-Git-Tag: suricata-8.0.0-beta1~51
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=185123a1304434d13a8eca4bd027e97641f1c4f6;p=thirdparty%2Fsuricata.git

tls: deprecate "default" as a encryption-handling option

The default value for TLS encryption is generic and not precise.
The new keyword, "track-only" substitues the old keyword, being
more on point what action is actually taken when the TLS flow
reaches an encrypted state.
---

diff --git a/doc/userguide/configuration/suricata-yaml.rst b/doc/userguide/configuration/suricata-yaml.rst
index e79db42627..071b5a9d94 100644
--- a/doc/userguide/configuration/suricata-yaml.rst
+++ b/doc/userguide/configuration/suricata-yaml.rst
@@ -1842,7 +1842,7 @@ port independent.
         dp: 443
 
       # What to do when the encrypted communications start:
-      # - default: keep tracking TLS session, check for protocol anomalies,
+      # - track-only: keep tracking TLS session, check for protocol anomalies,
       #            inspect tls_* keywords. Disables inspection of unmodified
       #            'content' signatures.
       # - bypass:  stop processing this flow as much as possible. No further
@@ -1853,7 +1853,7 @@ port independent.
       #
       # For best performance, select 'bypass'.
       #
-      #encryption-handling: default
+      #encryption-handling: track-only
 
 
 Encrypted traffic
@@ -1879,7 +1879,7 @@ flow as normal, without inspection limitations or bypass.
 
 The option has replaced the ``no-reassemble`` option. If ``no-reassemble`` is
 present, and ``encryption-handling`` is not, ``false`` is interpreted as
-``encryption-handling: default`` and ``true`` is interpreted as
+``encryption-handling: track-only`` and ``true`` is interpreted as
 ``encryption-handling: bypass``.
 
 
diff --git a/doc/userguide/upgrade.rst b/doc/userguide/upgrade.rst
index 33443886af..a6ca06283e 100644
--- a/doc/userguide/upgrade.rst
+++ b/doc/userguide/upgrade.rst
@@ -153,6 +153,9 @@ Deprecations
 - The ``syslog`` output is now deprecated and will be removed in
   Suricata 9.0. Note that this is the standalone ``syslog`` output and
   does affect the ``eve`` outputs ability to send to syslog.
+- The ``default`` option in ``app-layer.protocols.tls.encryption-handling`` is
+  now deprecated and will be removed in Suricata 9.0. The ``track-only`` option
+  should be used instead.
 
 Keyword changes
 ~~~~~~~~~~~~~~~
diff --git a/src/app-layer-ssl.c b/src/app-layer-ssl.c
index c77654b31e..331c56895a 100644
--- a/src/app-layer-ssl.c
+++ b/src/app-layer-ssl.c
@@ -137,9 +137,9 @@ enum {
 #define SSL_CONFIG_DEFAULT_JA4 0
 
 enum SslConfigEncryptHandling {
-    SSL_CNF_ENC_HANDLE_DEFAULT = 0, /**< disable raw content, continue tracking */
-    SSL_CNF_ENC_HANDLE_BYPASS = 1,  /**< skip processing of flow, bypass if possible */
-    SSL_CNF_ENC_HANDLE_FULL = 2,    /**< handle fully like any other proto */
+    SSL_CNF_ENC_HANDLE_TRACK_ONLY = 0, /**< disable raw content, continue tracking */
+    SSL_CNF_ENC_HANDLE_BYPASS = 1,     /**< skip processing of flow, bypass if possible */
+    SSL_CNF_ENC_HANDLE_FULL = 2,       /**< handle fully like any other proto */
 };
 
 typedef struct SslConfig_ {
@@ -3316,10 +3316,15 @@ void RegisterSSLParsers(void)
                 ssl_config.encrypt_mode = SSL_CNF_ENC_HANDLE_FULL;
             } else if (strcmp(enc_handle->val, "bypass") == 0) {
                 ssl_config.encrypt_mode = SSL_CNF_ENC_HANDLE_BYPASS;
+            } else if (strcmp(enc_handle->val, "track-only") == 0) {
+                ssl_config.encrypt_mode = SSL_CNF_ENC_HANDLE_TRACK_ONLY;
             } else if (strcmp(enc_handle->val, "default") == 0) {
-                ssl_config.encrypt_mode = SSL_CNF_ENC_HANDLE_DEFAULT;
+                SCLogWarning("app-layer.protocols.tls.encryption-handling = default is deprecated "
+                             "and will be removed in Suricata 9, use \"track-only\" instead, "
+                             "(see ticket #7642)");
+                ssl_config.encrypt_mode = SSL_CNF_ENC_HANDLE_TRACK_ONLY;
             } else {
-                ssl_config.encrypt_mode = SSL_CNF_ENC_HANDLE_DEFAULT;
+                ssl_config.encrypt_mode = SSL_CNF_ENC_HANDLE_TRACK_ONLY;
             }
         } else {
             /* Get the value of no reassembly option from the config file */
diff --git a/suricata.yaml.in b/suricata.yaml.in
index 2a16a563c4..8623c80bf3 100644
--- a/suricata.yaml.in
+++ b/suricata.yaml.in
@@ -933,9 +933,9 @@ app-layer:
       #ja4-fingerprints: auto
 
       # What to do when the encrypted communications start:
-      # - default: keep tracking TLS session, check for protocol anomalies,
+      # - track-only: keep tracking TLS session, check for protocol anomalies,
       #            inspect tls_* keywords. Disables inspection of unmodified
-      #            'content' signatures.
+      #            'content' signatures. (default)
       # - bypass:  stop processing this flow as much as possible. No further
       #            TLS parsing and inspection. Offload flow bypass to kernel
       #            or hardware if possible.
@@ -944,7 +944,7 @@ app-layer:
       #
       # For best performance, select 'bypass'.
       #
-      #encryption-handling: default
+      #encryption-handling: track-only
 
     pgsql:
       enabled: no