From: Victor Julien Date: Tue, 29 May 2018 19:37:21 +0000 (+0200) Subject: tls: document encrypt-handling option X-Git-Tag: suricata-4.1.0-rc1~47 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=693a3df031f985203528ca473aec32fc4cbdfaeb;p=thirdparty%2Fsuricata.git 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 3e4f659274..4f3b9ae15a 100644 --- 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 5f01b8131c..c31937b6df 100644 --- 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 01bef3197d..cef42e02d1 100644 --- 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 60ce166e31..d902a7c6e7 100644 --- 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: