validate-certs.zeek

SSL

Perform full certificate chain validation for SSL certificates.

Namespace: SSL
Imports: base/frameworks/cluster, base/frameworks/notice, base/protocols/ssl

Summary

State Variables

`SSL::recently_validated_certs`: `table` `&read_expire` = `5.0 mins` `&redef`	Result values for recently validated chains along with the validation status are kept in this table to avoid constant validation every time the same certificate chain is seen.
`SSL::ssl_cache_intermediate_ca`: `bool` `&redef`	Use intermediate CA certificate caching when trying to validate certificates.
`SSL::ssl_store_valid_chain`: `bool` `&redef`	Store the valid chain in c$ssl$valid_chain if validation succeeds.

Redefinitions

`Notice::Type`: `enum`	`SSL::Invalid_Server_Cert`: This notice indicates that the result of validating the certificate along with its full certificate chain was invalid.
`SSL::Info`: `record`	New Fields `SSL::Info` validation_status: `string` `&log` `&optional` Result of certificate validation for this connection. validation_code: `int` `&optional` Result of certificate validation for this connection, given as OpenSSL validation code. valid_chain: `vector` of `opaque` of x509 `&optional` Ordered chain of validated certificate, if validation succeeded.

Events

`SSL::intermediate_add`: `event`	Event from a manager to workers when encountering a new, valid intermediate.
`SSL::new_intermediate`: `event`	Event from workers to the manager when a new intermediate chain is to be added.

Detailed Interface

State Variables

SSL::recently_validated_certs 

Type: table [string] of X509::Result
Attributes: &read_expire = 5.0 mins &redef
Default: {}

Result values for recently validated chains along with the validation status are kept in this table to avoid constant validation every time the same certificate chain is seen.

SSL::ssl_cache_intermediate_ca 

Type: bool
Attributes: &redef
Default: T

Use intermediate CA certificate caching when trying to validate certificates. When this is enabled, Zeek keeps track of all valid intermediate CA certificates that it has seen in the past. When encountering a host certificate that cannot be validated because of missing intermediate CA certificate, the cached list is used to try to validate the cert. This is similar to how Firefox is doing certificate validation.

Disabling this will usually greatly increase the number of validation warnings that you encounter. Only disable if you want to find misconfigured servers.

SSL::ssl_store_valid_chain 

Type

bool

Attributes

&redef

Default

F

Redefinition

from policy/protocols/ssl/validate-sct.zeek

=:

Store the valid chain in c$ssl$valid_chain if validation succeeds. This has a potentially high memory impact, depending on the local environment and is thus disabled by default.

Events

SSL::intermediate_add 

Type: event (key: string, value: vector of opaque of x509)

Event from a manager to workers when encountering a new, valid intermediate.

SSL::new_intermediate 

Type: event (key: string, value: vector of opaque of x509)

Event from workers to the manager when a new intermediate chain is to be added.