:tocdepth: 3

policy/protocols/ssl/known-certs.bro
====================================
.. bro:namespace:: Known

Log information about certificates while attempting to avoid duplicate
logging.

:Namespace: Known
:Imports: :doc:`base/files/x509 </scripts/base/files/x509/index>`, :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`, :doc:`base/utils/directions-and-hosts.bro </scripts/base/utils/directions-and-hosts.bro>`
:Source File: :download:`/scripts/policy/protocols/ssl/known-certs.bro`

Summary
~~~~~~~
Options
#######
=================================================================== ==============================================================
:bro:id:`Known::cert_tracking`: :bro:type:`Host` :bro:attr:`&redef` The certificates whose existence should be logged and tracked.
=================================================================== ==============================================================

State Variables
###############
============================================================================================================================= ====================================================================
:bro:id:`Known::certs`: :bro:type:`set` :bro:attr:`&create_expire` = ``1.0 day`` :bro:attr:`&synchronized` :bro:attr:`&redef` The set of all known certificates to store for preventing duplicate 
                                                                                                                              logging.
============================================================================================================================= ====================================================================

Types
#####
================================================ =
:bro:type:`Known::CertsInfo`: :bro:type:`record` 
================================================ =

Redefinitions
#############
===================================== =
:bro:type:`Log::ID`: :bro:type:`enum` 
===================================== =

Events
######
=================================================== =====================================================================
:bro:id:`Known::log_known_certs`: :bro:type:`event` Event that can be handled to access the loggable record as it is sent
                                                    on to the logging framework.
=================================================== =====================================================================


Detailed Interface
~~~~~~~~~~~~~~~~~~
Options
#######
.. bro:id:: Known::cert_tracking

   :Type: :bro:type:`Host`
   :Attributes: :bro:attr:`&redef`
   :Default: ``ALL_HOSTS``

   The certificates whose existence should be logged and tracked.
   Choices are: LOCAL_HOSTS, REMOTE_HOSTS, ALL_HOSTS, NO_HOSTS.

State Variables
###############
.. bro:id:: Known::certs

   :Type: :bro:type:`set` [:bro:type:`addr`, :bro:type:`string`]
   :Attributes: :bro:attr:`&create_expire` = ``1.0 day`` :bro:attr:`&synchronized` :bro:attr:`&redef`
   :Default: ``{}``

   The set of all known certificates to store for preventing duplicate 
   logging. It can also be used from other scripts to 
   inspect if a certificate has been seen in use. The string value 
   in the set is for storing the DER formatted certificate' SHA1 hash.

Types
#####
.. bro:type:: Known::CertsInfo

   :Type: :bro:type:`record`

      ts: :bro:type:`time` :bro:attr:`&log`
         The timestamp when the certificate was detected.

      host: :bro:type:`addr` :bro:attr:`&log`
         The address that offered the certificate.

      port_num: :bro:type:`port` :bro:attr:`&log` :bro:attr:`&optional`
         If the certificate was handed out by a server, this is the 
         port that the server was listening on.

      subject: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
         Certificate subject.

      issuer_subject: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
         Certificate issuer subject.

      serial: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
         Serial number for the certificate.


Events
######
.. bro:id:: Known::log_known_certs

   :Type: :bro:type:`event` (rec: :bro:type:`Known::CertsInfo`)

   Event that can be handled to access the loggable record as it is sent
   on to the logging framework.


