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