tls: document encrypt-handling option

Document in sample yaml and user guide.

diff --git a/doc/userguide/capture-hardware/ebpf-xdp.rst b/doc/userguide/capture-hardware/ebpf-xdp.rst
index 3e4f65927432d9e10bfdf351f38658ea1ce243e8..4f3b9ae15a06eb4ff69cf6454c2cd188d40b1bc0 100644 (file)
--- a/doc/userguide/capture-hardware/ebpf-xdp.rst
+++ b/doc/userguide/capture-hardware/ebpf-xdp.rst
@@ -121,7 +121,7 @@ First, enable `bypass` in the `stream` section ::
  stream:
    bypass: true
 
-If you want, you can also bypass encrypted flows by setting `no-reassemble` to `yes`
+If you want, you can also bypass encrypted flows by setting `encrypt-handling` to `bypass`
 in the app-layer tls section ::
 
   app-layer:
@@ -131,12 +131,7 @@ in the app-layer tls section ::
         detection-ports:
           dp: 443
   
-        # Completely stop processing TLS/SSL session after the handshake
-        # completed. If bypass is enabled this will also trigger flow
-        # bypass. If disabled (the default), TLS/SSL session is still
-        # tracked for Heartbleed and other anomalies.
-        no-reassemble: yes
-
+        encrypt-handling: bypass
 
 Setup eBPF filter
 -----------------

diff --git a/doc/userguide/configuration/suricata-yaml.rst b/doc/userguide/configuration/suricata-yaml.rst
index 5f01b8131c9f972fb1db4bfb1e0ad9d288e64a60..c31937b6dfa1fdf9ae5db0c65417231103da7cf3 100644 (file)
--- a/doc/userguide/configuration/suricata-yaml.rst
+++ b/doc/userguide/configuration/suricata-yaml.rst
@@ -2115,30 +2115,48 @@ port independent.
       detection-ports:
         dp: 443
 
-      # Completely stop processing TLS/SSL session after the handshake
-      # completed. If bypass is enabled this will also trigger flow
-      # bypass. If disabled (the default), TLS/SSL session is still
-      # tracked for Heartbleed and other anomalies.
-      #no-reassemble: yes
+      # What to do when the encrypted communications start:
+      # - default: 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
+      #            TLS parsing and inspection. Offload flow bypass to kernel
+      #            or hardware if possible.
+      # - full:    keep tracking and inspection as normal. Unmodified content
+      #            keyword signatures are inspected as well.
+      #
+      # For best performance, select 'bypass'.
+      #
+      #encrypt-handling: default
+
 
 Encrypted traffic
 ^^^^^^^^^^^^^^^^^
 
 There is no decryption of encrypted traffic, so once the handshake is complete
-continued tracking of the session is of limited use. The ``no-reassemble``
+continued tracking of the session is of limited use. The ``encrypt-handling``
 option controls the behavior after the handshake.
 
-If ``no-reassemble`` is set to ``true``, all processing of this session is
-stopped. No further parsing and inspection happens. If ``bypass`` is enabled
-this will lead to the flow being bypassed, either inside Suricata or by the
-capture method if it supports it.
-
-If ``no-reassemble`` is set to ``false``, which is the default, Suricata will
-continue to track the SSL/TLS session. Inspection will be limited, as
-``content`` inspection will still be disabled. There is no point in doing
+If ``encrypt-handling`` is set to ``default`` (or if the option is not set),
+Suricata will continue to track the SSL/TLS session. Inspection will be limited,
+as raw ``content`` inspection will still be disabled. There is no point in doing
 pattern matching on traffic known to be encrypted. Inspection for (encrypted)
 Heartbleed and other protocol anomalies still happens.
 
+When ``encrypt-handling`` is set to ``bypass``, all processing of this session is
+stopped. No further parsing and inspection happens. If ``stream.bypass`` is enabled
+this will lead to the flow being bypassed, either inside Suricata or by the
+capture method if it supports it and is configured for it.
+
+Finally, if ``encrypt-handling`` is set to ``full``, Suricata will process the
+flow as normal, without inspection limitations or bypass.
+
+The option has replaced the ``no-reassemble`` option. If ``no-reassemble`` is
+present, and ``encrypt-handling`` is not, ``false`` is intepreted as
+``encrypt-handling: default`` and ``true`` is interpreted as
+``encrypt-handling: bypass``.
+
+
 Modbus
 ~~~~~~
 

diff --git a/doc/userguide/performance/ignoring-traffic.rst b/doc/userguide/performance/ignoring-traffic.rst
index 01bef3197dd9e078710ebdd60a464cd186dee1d1..cef42e02d177bcd1fd0fcd1b2cc0c2e6e42ed347 100644 (file)
--- a/doc/userguide/performance/ignoring-traffic.rst
+++ b/doc/userguide/performance/ignoring-traffic.rst
@@ -64,3 +64,12 @@ Example:
 ::
 
   suppress gen_id 0, sig_id 0, track by_src, ip 1.2.3.4
+
+
+Encrypted traffic
+-----------------
+
+The TLS app layer parser has the ability to stop processing encrypted traffic
+after the initial handshake. By setting the `app-layer.protocols.tls.encryption-handling`
+option to `bypass` the rest of this flow is ignored. If flow bypass is enabled,
+the bypass is done in the kernel or in hardware.

diff --git a/suricata.yaml.in b/suricata.yaml.in
index 60ce166e3108b7de3c31ddf21a9a543f139e9683..d902a7c6e7620d17c903795342f0873ea6dd2848 100644 (file)
--- a/suricata.yaml.in
+++ b/suricata.yaml.in
@@ -830,11 +830,20 @@ app-layer:
       # Generate JA3 fingerprint from client hello
       ja3-fingerprints: no
 
-      # Completely stop processing TLS/SSL session after the handshake
-      # completed. If bypass is enabled this will also trigger flow
-      # bypass. If disabled (the default), TLS/SSL session is still
-      # tracked for Heartbleed and other anomalies.
-      #no-reassemble: yes
+      # What to do when the encrypted communications start:
+      # - default: 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
+      #            TLS parsing and inspection. Offload flow bypass to kernel
+      #            or hardware if possible.
+      # - full:    keep tracking and inspection as normal. Unmodified content
+      #            keyword signatures are inspected as well.
+      #
+      # For best performance, select 'bypass'.
+      #
+      #encrypt-handling: default
+
     dcerpc:
       enabled: yes
     ftp: