128 lines
6.6 KiB
ReStructuredText
128 lines
6.6 KiB
ReStructuredText
:tocdepth: 3
|
|
|
|
policy/protocols/ssl/validate-certs.zeek
|
|
========================================
|
|
.. zeek:namespace:: SSL
|
|
|
|
Perform full certificate chain validation for SSL certificates.
|
|
|
|
:Namespace: SSL
|
|
:Imports: :doc:`base/frameworks/cluster </scripts/base/frameworks/cluster/index>`, :doc:`base/frameworks/notice </scripts/base/frameworks/notice/index>`, :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`
|
|
|
|
Summary
|
|
~~~~~~~
|
|
State Variables
|
|
###############
|
|
========================================================================================================================= ==================================================================
|
|
:zeek:id:`SSL::recently_validated_certs`: :zeek:type:`table` :zeek:attr:`&read_expire` = ``5.0 mins`` :zeek:attr:`&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.
|
|
:zeek:id:`SSL::ssl_cache_intermediate_ca`: :zeek:type:`bool` :zeek:attr:`&redef` Use intermediate CA certificate caching when trying to validate
|
|
certificates.
|
|
:zeek:id:`SSL::ssl_store_valid_chain`: :zeek:type:`bool` :zeek:attr:`&redef` Store the valid chain in c$ssl$valid_chain if validation succeeds.
|
|
========================================================================================================================= ==================================================================
|
|
|
|
Redefinitions
|
|
#############
|
|
============================================ ========================================================================================
|
|
:zeek:type:`Notice::Type`: :zeek:type:`enum`
|
|
|
|
* :zeek:enum:`SSL::Invalid_Server_Cert`:
|
|
This notice indicates that the result of validating the
|
|
certificate along with its full certificate chain was
|
|
invalid.
|
|
:zeek:type:`SSL::Info`: :zeek:type:`record`
|
|
|
|
:New Fields: :zeek:type:`SSL::Info`
|
|
|
|
validation_status: :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
|
|
Result of certificate validation for this connection.
|
|
|
|
validation_code: :zeek:type:`int` :zeek:attr:`&optional`
|
|
Result of certificate validation for this connection, given
|
|
as OpenSSL validation code.
|
|
|
|
valid_chain: :zeek:type:`vector` of :zeek:type:`opaque` of x509 :zeek:attr:`&optional`
|
|
Ordered chain of validated certificate, if validation succeeded.
|
|
============================================ ========================================================================================
|
|
|
|
Events
|
|
######
|
|
==================================================== ===============================================================
|
|
:zeek:id:`SSL::intermediate_add`: :zeek:type:`event` Event from a manager to workers when encountering a new, valid
|
|
intermediate.
|
|
:zeek:id:`SSL::new_intermediate`: :zeek:type:`event` Event from workers to the manager when a new intermediate chain
|
|
is to be added.
|
|
==================================================== ===============================================================
|
|
|
|
|
|
Detailed Interface
|
|
~~~~~~~~~~~~~~~~~~
|
|
State Variables
|
|
###############
|
|
.. zeek:id:: SSL::recently_validated_certs
|
|
:source-code: policy/protocols/ssl/validate-certs.zeek 33 33
|
|
|
|
:Type: :zeek:type:`table` [:zeek:type:`string`] of :zeek:type:`X509::Result`
|
|
:Attributes: :zeek:attr:`&read_expire` = ``5.0 mins`` :zeek:attr:`&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.
|
|
|
|
.. zeek:id:: SSL::ssl_cache_intermediate_ca
|
|
:source-code: policy/protocols/ssl/validate-certs.zeek 46 46
|
|
|
|
:Type: :zeek:type:`bool`
|
|
:Attributes: :zeek:attr:`&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.
|
|
|
|
.. zeek:id:: SSL::ssl_store_valid_chain
|
|
:source-code: policy/protocols/ssl/validate-certs.zeek 51 51
|
|
|
|
:Type: :zeek:type:`bool`
|
|
:Attributes: :zeek:attr:`&redef`
|
|
:Default: ``F``
|
|
:Redefinition: from :doc:`/scripts/policy/protocols/ssl/validate-sct.zeek`
|
|
|
|
``=``::
|
|
|
|
T
|
|
|
|
|
|
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
|
|
######
|
|
.. zeek:id:: SSL::intermediate_add
|
|
:source-code: policy/protocols/ssl/validate-certs.zeek 72 75
|
|
|
|
:Type: :zeek:type:`event` (key: :zeek:type:`string`, value: :zeek:type:`vector` of :zeek:type:`opaque` of x509)
|
|
|
|
Event from a manager to workers when encountering a new, valid
|
|
intermediate.
|
|
|
|
.. zeek:id:: SSL::new_intermediate
|
|
:source-code: policy/protocols/ssl/validate-certs.zeek 77 84
|
|
|
|
:Type: :zeek:type:`event` (key: :zeek:type:`string`, value: :zeek:type:`vector` of :zeek:type:`opaque` of x509)
|
|
|
|
Event from workers to the manager when a new intermediate chain
|
|
is to be added.
|
|
|
|
|