tls: document encrypt-handling option

Document in sample yaml and user guide.

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
+        encrypt-handling: bypass
-        # 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
-
 
 Setup eBPF filter
 -----------------

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
+      # What to do when the encrypted communications start:
-      # completed. If bypass is enabled this will also trigger flow
+      # - default: keep tracking TLS session, check for protocol anomalies,
-      # bypass. If disabled (the default), TLS/SSL session is still
+      #            inspect tls_* keywords. Disables inspection of unmodified
-      # tracked for Heartbleed and other anomalies.
+      #            'content' signatures.
-      #no-reassemble: yes
+      # - 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
+If ``encrypt-handling`` is set to ``default`` (or if the option is not set),
-stopped. No further parsing and inspection happens. If ``bypass`` is enabled
+Suricata will continue to track the SSL/TLS session. Inspection will be limited,
-this will lead to the flow being bypassed, either inside Suricata or by the
+as raw ``content`` inspection will still be disabled. There is no point in doing
-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
 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
 ~~~~~~
 

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.

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
+      # What to do when the encrypted communications start:
-      # completed. If bypass is enabled this will also trigger flow
+      # - default: keep tracking TLS session, check for protocol anomalies,
-      # bypass. If disabled (the default), TLS/SSL session is still
+      #            inspect tls_* keywords. Disables inspection of unmodified
-      # tracked for Heartbleed and other anomalies.
+      #            'content' signatures.
-      #no-reassemble: yes
+      # - 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: