base/files/x509/main.zeek

X509
Namespace

X509

Imports

base/files/hash, base/frameworks/cluster, base/frameworks/files

Summary

Runtime Options

X509::known_log_certs_maximum_size: count &redef

Maximum size of the known_log_certs table

X509::log_x509_in_files_log: bool &redef

This option specifies if X.509 certificates are logged in file.log.

X509::relog_known_certificates_after: interval &redef

By default, x509 certificates are deduplicated.

State Variables

X509::known_log_certs: set &create_expire = X509::relog_known_certificates_after

The set that stores information about certificates that already have been logged and should not be logged again.

X509::known_log_certs_use_broker: bool

Use broker stores to deduplicate certificates across the whole cluster.

Types

X509::Info: record

The record type which contains the fields of the X.509 log.

X509::LogCertHash: record

Type that is used to decide which certificates are duplicates for logging purposes.

X509::SctInfo: record

This record is used to store information about the SCTs that are encountered in Certificates.

Redefinitions

Files::Info: record &redef

New Fields

Files::Info

x509: X509::Info &optional

Information about X509 certificates.

Log::ID: enum

Events

X509::log_x509: event

Event for accessing logged records.

Hooks

X509::create_deduplication_index: hook

Hook that is used to create the index value used for log deduplication.

X509::log_policy: Log::PolicyHook

Functions

X509::hash_function: function &redef

The hash function used for certificate hashes.

Detailed Interface

Runtime Options

X509::known_log_certs_maximum_size
Type

count

Attributes

&redef

Default

1000000

Maximum size of the known_log_certs table

X509::log_x509_in_files_log
Type

bool

Attributes

&redef

Default

F

This option specifies if X.509 certificates are logged in file.log. Typically, there is not much value to having the entry in files.log - especially since, by default, the file ID is not present in the X509 log.

X509::relog_known_certificates_after
Type

interval

Attributes

&redef

Default

1.0 day

By default, x509 certificates are deduplicated. This configuration option configures the maximum time after which certificates are re-logged. Note - depending on other configuration options, this setting might only apply on a per-worker basis and you still might see certificates logged several times.

To disable deduplication completely, set this to 0secs.

State Variables

X509::known_log_certs
Type

set [X509::LogCertHash]

Attributes

&create_expire = X509::relog_known_certificates_after

Default

{}

The set that stores information about certificates that already have been logged and should not be logged again.

X509::known_log_certs_use_broker
Type

bool

Default

T

Use broker stores to deduplicate certificates across the whole cluster. This will cause log-deduplication to work cluster wide, but come at a slightly higher cost of memory and inter-node-communication.

This setting is ignored if Zeek is run in standalone mode.

Types

X509::Info
Type

record

ts: time &log

Current timestamp.

fingerprint: string &log

Fingerprint of the certificate - uses chosen algorithm.

certificate: X509::Certificate &log

Basic information about the certificate.

handle: opaque of x509

The opaque wrapping the certificate. Mainly used for the verify operations.

extensions: vector of X509::Extension &default = [] &optional

All extensions that were encountered in the certificate.

san: X509::SubjectAlternativeName &optional &log

Subject alternative name extension of the certificate.

basic_constraints: X509::BasicConstraints &optional &log

Basic constraints extension of the certificate.

extensions_cache: vector of any &default = [] &optional

All extensions in the order they were raised. This is used for caching certificates that are commonly encountered and should not be relied on in user scripts.

host_cert: bool &log &default = F &optional

Indicates if this certificate was a end-host certificate, or sent as part of a chain

client_cert: bool &log &default = F &optional

Indicates if this certificate was sent from the client

deduplication_index: X509::LogCertHash &optional

Record that is used to deduplicate log entries.

always_raise_x509_events: bool &default = F &optional

(present if policy/files/x509/disable-certificate-events-known-certs.zeek is loaded)

Set to true to force certificate events to always be raised for this certificate.

cert: string &log &optional

(present if policy/protocols/ssl/log-certs-base64.zeek is loaded)

Base64 encoded X.509 certificate.

The record type which contains the fields of the X.509 log.

X509::LogCertHash
Type

record

fingerprint: string

Certificate fingerprint

host_cert: bool

Indicates if this certificate was a end-host certificate, or sent as part of a chain

client_cert: bool

Indicates if this certificate was sent from the client

Type that is used to decide which certificates are duplicates for logging purposes. When adding entries to this, also change the create_deduplication_index to update them.

X509::SctInfo
Type

record

version: count

The version of the encountered SCT (should always be 0 for v1).

logid: string

The ID of the log issuing this SCT.

timestamp: count

The timestamp at which this SCT was issued measured since the epoch (January 1, 1970, 00:00), ignoring leap seconds, in milliseconds. Not converted to a Zeek timestamp because we need the exact value for validation.

hash_alg: count

The hash algorithm used for this sct.

sig_alg: count

The signature algorithm used for this sct.

signature: string

The signature of this SCT.

This record is used to store information about the SCTs that are encountered in Certificates.

Events

X509::log_x509
Type

event (rec: X509::Info)

Event for accessing logged records.

Hooks

X509::create_deduplication_index
Type

hook (c: X509::Info) : bool

Hook that is used to create the index value used for log deduplication.

X509::log_policy
Type

Log::PolicyHook

Functions

X509::hash_function
Type

function (cert: string) : string

Attributes

&redef

The hash function used for certificate hashes. By default this is sha256; you can use any other hash function and the hashes will change in ssl.log and in x509.log.