policy/protocols/ssl/decryption.zeek

SSL

This script allows for the decryption of certain TLS 1.2 connections, if the user is in possession of the private key material for the session. Key material can either be provided via a file (useful for processing trace files) or via sending events via Broker (for live decoding).

Please note that this feature is experimental and can change without guarantees to our typical deprecation timeline. Please also note that currently only TLS 1.2 connections that use the TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 cipher suite are supported.

Namespace

SSL

Imports

base/frameworks/input, base/frameworks/notice, base/protocols/conn, base/protocols/ssl

Summary

Redefinable Options

SSL::keylog_file: string &redef

This can be set to a file that contains the session secrets for decryption, when parsing a pcap file.

SSL::secret_expiration: interval &redef

Secrets expire after this time of not being used.

Redefinitions

SSL::Info: record
New Fields

SSL::Info

client_random: string &optional

SSL::disable_analyzer_after_detection: bool &redef

Events

SSL::add_keys: event

This event can be triggered, e.g., via Broker to add known keys to the TLS key database.

SSL::add_secret: event

This event can be triggered, e.g., via Broker to add known secrets to the TLS secret database.

Detailed Interface

Redefinable Options

SSL::keylog_file
Type

string

Attributes

&redef

Default

""

This can be set to a file that contains the session secrets for decryption, when parsing a pcap file. Please note that, when using this feature, you probably want to pause processing of data till this file has been read.

SSL::secret_expiration
Type

interval

Attributes

&redef

Default

5.0 mins

Secrets expire after this time of not being used.

Events

SSL::add_keys
Type

event (client_random: string, keys: string)

This event can be triggered, e.g., via Broker to add known keys to the TLS key database.

Parameters

  • client_random – client random for which the key is set

  • keys – key material

SSL::add_secret
Type

event (client_random: string, secrets: string)

This event can be triggered, e.g., via Broker to add known secrets to the TLS secret database.

Parameters

  • client_random – client random for which the secret is set

  • secrets – derived TLS secrets material