base/bif/plugins/Zeek_X509.functions.bif.zeek
- GLOBAL
- Namespace
GLOBAL
Summary
Functions
Verifies a Signed Certificate Timestamp as used for Certificate Transparency. |
|
This function checks if a hostname matches one of the hostnames given in the certificate. |
|
This function checks a hostname against the name given in a certificate subject/SAN, including our interpretation of RFC6128 wildcard expansions. |
|
Constructs an opaque of X509 from a der-formatted string. |
|
Returns the string form of a certificate. |
|
Get the hash of the issuer’s distinguished name. |
|
Verifies an OCSP reply. |
|
Parses a certificate into an X509::Certificate structure. |
|
This function can be used to set up certificate caching. |
|
This function sets up the callback that is called when an entry is matched against the table set
by |
|
Get the hash of the Subject Public Key Information of the certificate. |
|
Get the hash of the subject’s distinguished name. |
|
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_check_cert_hostname
-
This function checks if a hostname matches one of the hostnames given in the certificate.
For our matching we adhere to RFC6128 for the labels (see
x509_check_hostname
). Furthermore we adhere to RFC2818 and check only the names given in the SAN, if a SAN is present, ignoring CNs in the Subject. If no SAN is present, we will use the last CN in the subject for our tests.- Cert
The X509 certificate opaque handle.
- Hostname
Hostname to check
- Returns
empty string if the hostname does not match; matched name (which can contain wildcards) if it did.
See also:
x509_check_hostname
- x509_check_hostname
-
This function checks a hostname against the name given in a certificate subject/SAN, including our interpretation of RFC6128 wildcard expansions. This specifically means that wildcards are only allowed in the leftmost label, wildcards only span one label, the wildcard has to be the last character before the label-separator, but additional characters are allowed before it, and the wildcard has to be at least at the third level (so *.a.b).
- Hostname
Hostname to test
- Certname
Name given in the CN/SAN of a certificate; wildcards will be expanded
- Returns
True if the hostname matches.
See also:
x509_check_cert_hostname
- x509_from_der
-
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
-
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
-
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
-
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
-
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