base/bif/plugins/Zeek_X509.functions.bif.zeek

GLOBAL
Namespace

GLOBAL

Summary

Functions

sct_verify: function

Verifies a Signed Certificate Timestamp as used for Certificate Transparency.

x509_from_der: function

Constructs an opaque of X509 from a der-formatted string.

x509_get_certificate_string: function

Returns the string form of a certificate.

x509_issuer_name_hash: function

Get the hash of the issuer’s distinguished name.

x509_ocsp_verify: function

Verifies an OCSP reply.

x509_parse: function

Parses a certificate into an X509::Certificate structure.

x509_set_certificate_cache: function

This function can be used to set up certificate caching.

x509_set_certificate_cache_hit_callback: function

This function sets up the callback that is called when an entry is matched against the table set by x509_set_certificate_cache.

x509_spki_hash: function

Get the hash of the Subject Public Key Information of the certificate.

x509_subject_name_hash: function

Get the hash of the subject’s distinguished name.

x509_verify: function

Verifies a certificate.

Detailed Interface

Functions

sct_verify
Type

function (cert: opaque of x509, logid: string, log_key: string, signature: string, timestamp: count, hash_algorithm: count, issuer_key_hash: string &default = "" &optional) : bool

Verifies a Signed Certificate Timestamp as used for Certificate Transparency. See RFC6962 for more details.

Cert

Certificate against which the SCT should be validated.

Logid

Log id of the SCT.

Log_key

Public key of the Log that issued the SCT proof.

Timestamp

Timestamp at which the proof was generated.

Hash_algorithm

Hash algorithm that was used for the SCT proof.

Issuer_key_hash

The SHA-256 hash of the certificate issuer’s public key. This only has to be provided if the SCT was encountered in an X.509 certificate extension; in that case, it is necessary for validation.

Returns

T if the validation could be performed succesfully, F otherwhise.

See also: ssl_extension_signed_certificate_timestamp, x509_ocsp_ext_signed_certificate_timestamp, x509_verify

x509_from_der
Type

function (der: string) : opaque of x509

Constructs an opaque of X509 from a der-formatted string.

Note

this function is mostly meant for testing purposes

See also: x509_certificate, x509_extension, x509_ext_basic_constraints, x509_ext_subject_alternative_name, x509_verify, x509_get_certificate_string, x509_parse

x509_get_certificate_string
Type

function (cert: opaque of x509, pem: bool &default = F &optional) : string

Returns the string form of a certificate.

Cert

The X509 certificate opaque handle.

Pem

A boolean that specifies if the certificate is returned in pem-form (true), or as the raw ASN1 encoded binary (false).

Returns

X509 certificate as a string.

See also: x509_certificate, x509_extension, x509_ext_basic_constraints, x509_ext_subject_alternative_name, x509_parse, x509_verify

x509_issuer_name_hash
Type

function (cert: opaque of x509, hash_alg: count) : string

Get the hash of the issuer’s distinguished name.

Cert

The X509 certificate opaque handle.

Hash_alg

the hash algorithm to use, according to the IANA mapping at

:https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-18

Returns

The hash as a string.

See also: x509_subject_name_hash, x509_spki_hash, x509_verify, sct_verify

x509_ocsp_verify
Type

function (certs: x509_opaque_vector, ocsp_reply: string, root_certs: table_string_of_string, verify_time: time &default = 0.0 &optional) : X509::Result

Verifies an OCSP reply.

Certs

Specifies the certificate chain to use. Server certificate first.

Ocsp_reply

the ocsp reply to validate.

Root_certs

A list of root certificates to validate the certificate chain.

Verify_time

Time for the validity check of the certificates.

Returns

A record of type X509::Result containing the result code of the verify operation.

See also: x509_certificate, x509_extension, x509_ext_basic_constraints, x509_ext_subject_alternative_name, x509_parse, x509_get_certificate_string, x509_verify

x509_parse
Type

function (cert: opaque of x509) : X509::Certificate

Parses a certificate into an X509::Certificate structure.

Cert

The X509 certificate opaque handle.

Returns

A X509::Certificate structure.

See also: x509_certificate, x509_extension, x509_ext_basic_constraints, x509_ext_subject_alternative_name, x509_verify, x509_get_certificate_string

x509_set_certificate_cache
Type

function (tbl: string_any_table) : bool

This function can be used to set up certificate caching. It has to be passed a table[string] which can contain any type.

After this is set up, for each certificate encountered, the X509 analyzer will check if the entry tbl[sha256 of certificate] is set. If this is the case, the X509 analyzer will skip all further processing, and instead just call the callback that is set with

x509_set_certificate_cache_hit_callback.

Tbl

Table to use as the certificate cache.

Returns

Always returns true.

Note

The base scripts use this function to set up certificate caching. You should only change the cache table if you are sure you will not conflict with the base scripts.

See also: x509_set_certificate_cache_hit_callback

x509_set_certificate_cache_hit_callback
Type

function (f: string_any_file_hook) : bool

This function sets up the callback that is called when an entry is matched against the table set by x509_set_certificate_cache.

F

The callback that will be called when encountering a certificate in the cache table.

Returns

Always returns true.

Note

The base scripts use this function to set up certificate caching. You should only change the callback function if you are sure you will not conflict with the base scripts.

See also: x509_set_certificate_cache

x509_spki_hash
Type

function (cert: opaque of x509, hash_alg: count) : string

Get the hash of the Subject Public Key Information of the certificate.

Cert

The X509 certificate opaque handle.

Hash_alg

the hash algorithm to use, according to the IANA mapping at

:https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-18

Returns

The hash as a string.

See also: x509_subject_name_hash, x509_issuer_name_hash, x509_verify, sct_verify

x509_subject_name_hash
Type

function (cert: opaque of x509, hash_alg: count) : string

Get the hash of the subject’s distinguished name.

Cert

The X509 certificate opaque handle.

Hash_alg

the hash algorithm to use, according to the IANA mapping at

:https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-18

Returns

The hash as a string.

See also: x509_issuer_name_hash, x509_spki_hash, x509_verify, sct_verify

x509_verify
Type

function (certs: x509_opaque_vector, root_certs: table_string_of_string, verify_time: time &default = 0.0 &optional) : X509::Result

Verifies a certificate.

Certs

Specifies a certificate chain that is being used to validate the given certificate against the root store given in root_certs. The host certificate has to be at index 0.

Root_certs

A list of root certificates to validate the certificate chain.

Verify_time

Time for the validity check of the certificates.

Returns

A record of type X509::Result containing the result code of the verify operation. In case of success also returns the full certificate chain.

See also: x509_certificate, x509_extension, x509_ext_basic_constraints, x509_ext_subject_alternative_name, x509_parse, x509_get_certificate_string, x509_ocsp_verify, sct_verify