main.zeek¶

X509¶

Namespace: X509
Imports: base/files/hash, base/frameworks/files

Summary¶

Runtime Options¶

`X509::caching_required_encounters`: `count` `&redef`	How often do you have to encounter a certificate before caching it.
`X509::caching_required_encounters_interval`: `interval` `&redef`	The timespan over which caching_required_encounters has to be reached
`X509::certificate_cache_max_entries`: `count` `&redef`	Maximum size of the certificate cache
`X509::certificate_cache_minimum_eviction_interval`: `interval` `&redef`	After a certificate has not been encountered for this time, it may be evicted from the certificate cache.

Types¶

`X509::Info`: `record`	The record type which contains the fields of the X.509 log.
`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`	`X509::LOG`

Events¶

X509::log_x509: event

Event for accessing logged records.

Hooks¶

`X509::log_policy`: `Log::PolicyHook`
`X509::x509_certificate_cache_replay`: `hook`	This hook performs event-replays in case a certificate that already is in the cache is encountered.

Detailed Interface¶

Runtime Options¶

X509::caching_required_encounters¶

Type: count
Attributes: &redef
Default: 10

How often do you have to encounter a certificate before caching it. Set to 0 to disable caching of certificates.

X509::caching_required_encounters_interval¶

Type: interval
Attributes: &redef
Default: 1.0 min 2.0 secs

The timespan over which caching_required_encounters has to be reached

X509::certificate_cache_max_entries¶

Type: count
Attributes: &redef
Default: 10000

Maximum size of the certificate cache

X509::certificate_cache_minimum_eviction_interval¶

Type: interval
Attributes: &redef
Default: 1.0 min 2.0 secs

After a certificate has not been encountered for this time, it may be evicted from the certificate cache.

Types¶

X509::Info¶

Type

record

ts: time &log

Current timestamp.

id: string &log

File id of this certificate.

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.

logcert: bool &default = T &optional

(present if policy/protocols/ssl/log-hostcerts-only.zeek is loaded)

Logging of certificate is suppressed if set to F

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

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::log_policy¶

Type: Log::PolicyHook

X509::x509_certificate_cache_replay¶

Type: hook (f: fa_file, e: X509::Info, sha256: string) : bool

This hook performs event-replays in case a certificate that already is in the cache is encountered.

It is possible to change this behavior/skip sending the events by installing a higher priority hook instead.