SSL: Update OCSP/SCT scripts and documentation.

doc/script-reference/log-files.rst

@@ -76,6 +76,10 @@ Files
 +============================+=======================================+=================================+
 | files.log                  | File analysis results                 | :bro:type:`Files::Info`         |
 +----------------------------+---------------------------------------+---------------------------------+
+| ocsp.log                   | Online Certificate Status Protocol    | :bro:type:`OCSP::Info`          |
+|                            | (OCSP). Only created if policy script |                                 |
+|                            | is loaded.                            |                                 |
++----------------------------+---------------------------------------+---------------------------------+
 | pe.log                     | Portable Executable (PE)              | :bro:type:`PE::Info`            |
 +----------------------------+---------------------------------------+---------------------------------+
 | x509.log                   | X.509 certificate info                | :bro:type:`X509::Info`          |

scripts/base/files/x509/README

@@ -1,2 +1,2 @@
 Support for X509 certificates with the file analysis framework.
-Also supposrts OCSP requests and responses.
+Also supports parsing OCSP requests and responses.

scripts/base/files/x509/__load__.bro

@@ -1,2 +1 @@
 @load ./main
-#@load ./ocsp

scripts/base/files/x509/main.bro

@@ -10,23 +10,17 @@ export {
 	type Info: record {
 		## Current timestamp.
 		ts: time &log;
-
 		## File id of this certificate.
 		id: string &log;
-
 		## Basic information about the certificate.
 		certificate: X509::Certificate &log;
-
 		## The opaque wrapping the certificate. Mainly used
 		## for the verify operations.
 		handle: opaque of x509;
-
 		## All extensions that were encountered in the certificate.
 		extensions: vector of X509::Extension &default=vector();
-
 		## Subject alternative name extension of the certificate.
 		san: X509::SubjectAlternativeName &optional &log;
-
 		## Basic constraints extension of the certificate.
 		basic_constraints: X509::BasicConstraints &optional &log;
 	};
@@ -39,6 +33,11 @@ event bro_init() &priority=5
 	{
 	Log::create_stream(X509::LOG, [$columns=Info, $ev=log_x509, $path="x509"]);
 
+	# We use mime types internally to distinguish between user and ca certificates.
+	# The first certificate in a connection always gets tagged as user-cert, all
+	# following certificates get tagged as CA certificates. Certificates gotten via
+	# other means (e.g. identified from HTTP traffic when they are transfered in plain
+	# text) get tagged as application/pkix-cert.
 	Files::register_for_mime_type(Files::ANALYZER_X509, "application/x-x509-user-cert");
 	Files::register_for_mime_type(Files::ANALYZER_X509, "application/x-x509-ca-cert");
 	Files::register_for_mime_type(Files::ANALYZER_X509, "application/pkix-cert");

scripts/base/protocols/ssl/README

@@ -1 +1 @@
-Support for Secure Sockets Layer (SSL) protocol analysis.
+Support for Secure Sockets Layer (SSL)/Transport Layer Security(TLS) protocol analysis.

scripts/base/protocols/ssl/main.bro

@@ -64,7 +64,6 @@ export {
 		## Flag to indicate if this ssl session has been established
 		## successfully, or if it was aborted during the handshake.
 		established:      bool             &log &default=F;
-
 		## Flag to indicate if this record already has been logged, to
 		## prevent duplicates.
 		logged:           bool             &default=F;
@@ -74,11 +73,18 @@ export {
 	## script sets this to Mozilla's root CA list.
 	const root_certs: table[string] of string = {} &redef;
 
+	## The record type which contains the field for the Certificate
+	## Transparency log bundle.
 	type CTInfo: record {
+		## Description of the Log
 	  description:           string;
+		## Operator of the Log
 	  operator:              string;
+		## Public key of the Log.
 		key:                   string;
+		## Maximum merge delay of the Log
 		maximum_merge_delay:   count;
+		## URL of the Log
 		url:                   string;
 	};
 
@@ -104,7 +110,8 @@ export {
 	## record as it is sent on to the logging framework.
 	global log_ssl: event(rec: Info);
 
-	# do everything you want to do right before logging here
+	# Hook that can be used to perform actions right before the log record
+	# is written.
 	global ssl_finishing: hook(c: connection);
 }
 

scripts/policy/files/x509/log-ocsp.bro

@@ -1,31 +1,41 @@
-##! Enable basic OCSP logging.
+##! Enable logging of OCSP responses.
-
+#
-# This is in policy because probably just about no one is interested
+# This script is in policy and not loaded by default because OCSP logging
-# in logging OCSP responses.
+# does not provide a lot of interesting information in most environments.
 
 module OCSP;
 
 export {
 	redef enum Log::ID += { LOG };
 
+	## The record type which contains the fields of the OCSP log.
 	type Info: record {
-	## Current timestamp.
+		## Time when the OCSP reply was encountered.
 		ts: time &log;
-
 		## File id of the ocsp reply.
 		id: string &log;
-
+		## Hash algorithm used to generate issuerNameHash and issuerKeyHash.
 		hashAlgorithm: string &log;
+		## Hash of the issuer's distingueshed name.
 		issuerNameHash: string &log;
+		## Hash of the issuer's public key.
 		issuerKeyHash: string &log;
+		## Serial number of the affected certificate.
 		serialNumber: string &log;
+		## Status of the affected certificate.
 		certStatus: string &log;
+		## Time at which the certificate was revoked.
 		revoketime: time &log &optional;
+		## Reason for which the certificate was revoked.
 		revokereason: string &log &optional;
+		## The time at which the status being shows is known to have been correct.
 		thisUpdate: time &log;
+		## The latest time at which new information about the status of the certificate will be available.
 		nextUpdate: time &log &optional;
 	};
 
+	## Event that can be handled to access the OCSP record
+	## as it is sent to the logging framework.
 	global log_ocsp: event(rec: Info);
 }
 
@@ -43,10 +53,8 @@ event ocsp_response_certificate(f: fa_file, hashAlgorithm: string, issuerNameHas
 
 	if ( revokereason != "" )
 		wr$revokereason = revokereason;
-
 	if ( time_to_double(revoketime) != 0 )
 		wr$revoketime = revoketime;
-
 	if ( time_to_double(nextUpdate) != 0 )
 		wr$nextUpdate = nextUpdate;
 

scripts/policy/protocols/ssl/validate-ocsp.bro

@@ -1,4 +1,9 @@
 ##! Perform validation of stapled OCSP responses.
+#!
+#! Note: this _only_ performs validation of stapled OCSP responsed. It does
+#! not validate OCSP responses that are retrieved via HTTP, because we do not
+#! have a mapping to certificates.
+
 
 @load base/frameworks/notice
 @load base/protocols/ssl
@@ -15,7 +20,6 @@ export {
 	redef record Info += {
 		## Result of ocsp validation for this connection.
 		ocsp_status: string &log &optional;
-
 		## ocsp response as string.
 		ocsp_response: string &optional;
 	};

scripts/policy/protocols/ssl/validate-sct.bro

@@ -1,6 +1,5 @@
 ##! Perform validation of Signed Certificate Timestamps, as used
-##! for Certificate Transparency. See https://tools.ietf.org/html/rfc6962
+##! for Certificate Transparency. See RFC6962 for more details.
-##! for more details.
 
 @load base/protocols/ssl
 @load protocols/ssl/validate-certs
@@ -13,39 +12,62 @@ module SSL;
 
 export {
 
+	## List of the different sources for Signed Certificate Timestamp
 	type SctSource: enum {
+		## Signed Certificate Timestamp was encountered in the extension of
+		## an X.509 certificate.
 		SCT_X509_EXT,
+		## Signed Certificate Timestamp was encountered in an TLS session
+		## extension.
 		SCT_TLS_EXT,
+		## Signed Certificate Timestamp was encountered in the extension of
+		## an stapled OCSP reply.
 		SCT_OCSP_EXT
 	};
 
+	## This record is used to store information about the SCTs that are
+	## encountered in a SSL connection.
 	type SctInfo: record {
+		## The version of the encountered SCT (should always be 0 for v1).
 		version: count;
+		## The ID of the log issuing this SCT.
 		logid: string;
+		## The timestamp at which this SCT was issued measured since the 
+		## epoch (January 1, 1970, 00:00), ignoring leap seconds, in
+		## milliseconds. Not converted to a Bro timestamp because we need
+		## the exact value for validation.
 		timestamp: count;
+		## The signature algorithm used for this sct.
 		sig_alg: count;
+		## The hash algorithm used for this sct.
 		hash_alg: count;
+		## The signature of this SCT.
 		signature: string;
+		## Source of this SCT.
 		source: SctSource;
+		## Validation result of this SCT.
 		valid: bool &optional;
 	};
 
 	redef record Info += {
+		## Number of valid SCTs that were encountered in the connection.
 		valid_scts: count &optional;
+		## Number of SCTs that could not be validated that were encountered in the connection.
 		invalid_scts: count &optional;
+		## Number of different Logs for which valid SCTs were encountered in the connection.
 		valid_ct_logs: count &log &optional;
+		## Number of different Log operators of which valid SCTs were encountered in the connection.
 		valid_ct_operators: count &log &optional;
+		## List of operators for which valid SCTs were encountered in the connection.
 		valid_ct_operators_list: set[string] &optional;
-	};
+		## Information about all SCTs that were encountered in the connection.
-
-}
-
-global recently_validated_scts: table[string] of bool = table()
-	&read_expire=5mins &redef;
-
-redef record SSL::Info += {
 		ct_proofs: vector of SctInfo &default=vector();
 	};
+}
+
+# Used to cache validations for 5 minutes to lessen computational load.
+global recently_validated_scts: table[string] of bool = table()
+	&read_expire=5mins &redef;
 
 event bro_init()
 	{
@@ -134,7 +156,6 @@ hook ssl_finishing(c: connection) &priority=19
 			# the right issuer cert.
 			#
 			# First - Let's try if a previous round already established the correct issuer key hash.
-
 			if ( issuer_key_hash != "" )
 				{
 				valid = sct_verify(cert, proof$logid, log$key, proof$signature, proof$timestamp, proof$hash_alg, issuer_key_hash);
@@ -151,9 +172,9 @@ hook ssl_finishing(c: connection) &priority=19
 				issuer_key_hash = x509_spki_hash(c$ssl$valid_chain[1], 4);
 				valid = sct_verify(cert, proof$logid, log$key, proof$signature, proof$timestamp, proof$hash_alg, issuer_key_hash);
 				}
+
 			# ok, if it still did not work - let's just try with all the certs that were sent
 			# in the connection. Perhaps it will work with one of them.
-
 			if ( !valid )
 				for ( i in c$ssl$cert_chain )
 					{

src/analyzer/protocol/ssl/events.bif

@@ -211,6 +211,7 @@ event ssl_dh_server_params%(c: connection, p: string, q: string, Ys: string%);
 ##    ssl_extension_elliptic_curves ssl_extension_ec_point_formats
 ##    ssl_extension_server_name ssl_extension_key_share
 ##    ssl_extension_psk_key_exchange_modes ssl_extension_supported_versions
+##    ssl_extension_signed_certificate_timestamp
 event ssl_extension_application_layer_protocol_negotiation%(c: connection, is_orig: bool, protocols: string_vec%);
 
 ## Generated for an SSL/TLS Server Name extension. This SSL/TLS extension is
@@ -231,6 +232,7 @@ event ssl_extension_application_layer_protocol_negotiation%(c: connection, is_or
 ##    ssl_extension_application_layer_protocol_negotiation
 ##    ssl_extension_key_share
 ##    ssl_extension_psk_key_exchange_modes ssl_extension_supported_versions
+##    ssl_extension_signed_certificate_timestamp
 event ssl_extension_server_name%(c: connection, is_orig: bool, names: string_vec%);
 
 ## Generated for the signed_certificate_timestamp TLS extension as defined in
@@ -253,6 +255,14 @@ event ssl_extension_server_name%(c: connection, is_orig: bool, names: string_vec
 ##                              digitally_signed struct
 ##
 ## signature: signature part of the digitally_signed struct
+##
+## .. bro:see:: ssl_alert ssl_client_hello ssl_established ssl_server_hello
+##    ssl_session_ticket_handshake ssl_extension
+##    ssl_extension_elliptic_curves ssl_extension_ec_point_formats
+##    ssl_extension_server_name ssl_extension_key_share
+##    ssl_extension_psk_key_exchange_modes ssl_extension_supported_versions
+##    ssl_extension_application_layer_protocol_negotiation
+##    x509_ocsp_ext_signed_certificate_timestamp sct_verify
 event ssl_extension_signed_certificate_timestamp%(c: connection, is_orig: bool, version: count, logid: string, timestamp: count, signature_and_hashalgorithm: SSL::SignatureAndHashAlgorithm, signature: string%);
 
 ## Generated for an TLS Supported Versions extension. This TLS extension
@@ -271,7 +281,7 @@ event ssl_extension_signed_certificate_timestamp%(c: connection, is_orig: bool,
 ##    ssl_extension_elliptic_curves ssl_extension_ec_point_formats
 ##    ssl_extension_application_layer_protocol_negotiation
 ##    ssl_extension_key_share ssl_extension_server_name
-##    ssl_extension_psk_key_exchange_modes
+##    ssl_extension_psk_key_exchange_modes ssl_extension_signed_certificate_timestamp
 event ssl_extension_supported_versions%(c: connection, is_orig: bool, versions: index_vec%);
 
 ## Generated for an TLS Pre-Shared Key Exchange Modes extension. This TLS extension is defined
@@ -288,7 +298,7 @@ event ssl_extension_supported_versions%(c: connection, is_orig: bool, versions:
 ##    ssl_extension_elliptic_curves ssl_extension_ec_point_formats
 ##    ssl_extension_application_layer_protocol_negotiation
 ##    ssl_extension_key_share ssl_extension_server_name
-##    ssl_extension_supported_versions
+##    ssl_extension_supported_versions ssl_extension_signed_certificate_timestamp
 event ssl_extension_psk_key_exchange_modes%(c: connection, is_orig: bool, modes: index_vec%);
 
 ## Generated at the end of an SSL/TLS handshake. SSL/TLS sessions start with

src/file_analysis/analyzer/x509/events.bif

@@ -13,7 +13,7 @@
 ##
 ## .. bro:see:: x509_extension x509_ext_basic_constraints
 ##              x509_ext_subject_alternative_name x509_parse x509_verify
-##              x509_get_certificate_string
+##              x509_get_certificate_string x509_ocsp_ext_signed_certificate_timestamp
 event x509_certificate%(f: fa_file, cert_ref: opaque of x509, cert: X509::Certificate%);
 
 ## Generated for X509 extensions seen in a certificate.
@@ -27,7 +27,7 @@ event x509_certificate%(f: fa_file, cert_ref: opaque of x509, cert: X509::Certif
 ##
 ## .. bro:see:: x509_certificate x509_ext_basic_constraints
 ##              x509_ext_subject_alternative_name x509_parse x509_verify
-##              x509_get_certificate_string
+##              x509_get_certificate_string x509_ocsp_ext_signed_certificate_timestamp
 event x509_extension%(f: fa_file, ext: X509::Extension%);
 
 ## Generated for the X509 basic constraints extension seen in a certificate.
@@ -39,7 +39,7 @@ event x509_extension%(f: fa_file, ext: X509::Extension%);
 ##
 ## .. bro:see:: x509_certificate x509_extension
 ##              x509_ext_subject_alternative_name x509_parse x509_verify
-##              x509_get_certificate_string
+##              x509_get_certificate_string x509_ocsp_ext_signed_certificate_timestamp
 event x509_ext_basic_constraints%(f: fa_file, ext: X509::BasicConstraints%);
 
 ## Generated for the X509 subject alternative name extension seen in a certificate.
@@ -52,13 +52,14 @@ event x509_ext_basic_constraints%(f: fa_file, ext: X509::BasicConstraints%);
 ## ext: The parsed subject alternative name extension.
 ##
 ## .. bro:see:: x509_certificate x509_extension x509_ext_basic_constraints
-##              x509_parse x509_verify
+##              x509_parse x509_verify x509_ocsp_ext_signed_certificate_timestamp
 ##              x509_get_certificate_string
 event x509_ext_subject_alternative_name%(f: fa_file, ext: X509::SubjectAlternativeName%);
 
 ## Generated for the signed_certificate_timestamp X509 extension as defined in
 ## :rfc:`6962`. The extension is used to transmit signed proofs that are
-## used for Certificate Transparency.
+## used for Certificate Transparency. Raised when the extension is encountered
+## in an X.509 certificate or in an OCSP reply.
 ##
 ## f: The file.
 ##
@@ -74,4 +75,11 @@ event x509_ext_subject_alternative_name%(f: fa_file, ext: X509::SubjectAlternati
 ##                              digitally_signed struct
 ##
 ## signature: signature part of the digitally_signed struct
+##
+## .. bro:see:: ssl_extension_signed_certificate_timestamp x509_extension x509_ext_basic_constraints
+##              x509_parse x509_verify x509_ext_subject_alternative_name
+##              x509_get_certificate_string ssl_extension_signed_certificate_timestamp
+##              sct_verify ocsp_request ocsp_request_certificate ocsp_response_status
+##              ocsp_response_bytes ocsp_response_certificate
+##              x509_ocsp_ext_signed_certificate_timestamp
 event x509_ocsp_ext_signed_certificate_timestamp%(f: fa_file, version: count, logid: string, timestamp: count, hash_algorithm: count, signature_algorithm: count, signature: string%);

src/file_analysis/analyzer/x509/functions.bif

@@ -140,6 +140,8 @@ X509* x509_get_ocsp_signer(STACK_OF(X509) *certs, OCSP_RESPID *rid)
 	return 0;
 	}
 
+// Convert hash algorithm registry numbers to the OpenSSL EVP_MD.
+// Mapping at https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-18
 const EVP_MD* hash_to_evp(int hash)
 	{
 	switch ( hash )
@@ -483,7 +485,7 @@ x509_ocsp_cleanup:
 ##
 ## .. bro:see:: x509_certificate x509_extension x509_ext_basic_constraints
 ##              x509_ext_subject_alternative_name x509_parse
-##              x509_get_certificate_string x509_ocsp_verify
+##              x509_get_certificate_string x509_ocsp_verify sct_verify
 function x509_verify%(certs: x509_opaque_vector, root_certs: table_string_of_string, verify_time: time &default=network_time()%): X509::Result
 	%{
 	X509_STORE* ctx = x509_get_root_store(root_certs->AsTableVal());
@@ -571,6 +573,28 @@ x509_verify_chainerror:
 	return rrecord;
 	%}
 
+## 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.
+##
+## .. bro:see:: ssl_extension_signed_certificate_timestamp
+##              x509_ocsp_ext_signed_certificate_timestamp
+##              x509_verify
 function sct_verify%(cert: opaque of x509, logid: string, log_key: string, signature: string, timestamp: count, hash_algorithm: count, issuer_key_hash: string &default=""%): bool
 	%{
 	assert(cert);
@@ -789,6 +813,17 @@ StringVal* x509_entity_hash(file_analysis::X509Val *cert_handle, unsigned int ha
 	}
 %%}
 
+## 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.
+##
+## .. bro:see:: x509_issuer_name_hash x509_spki_hash
+##              x509_verify sct_verify
 function x509_subject_name_hash%(cert: opaque of x509, hash_alg: count%): string
 	%{
 	file_analysis::X509Val *cert_handle = (file_analysis::X509Val *) cert;
@@ -796,17 +831,17 @@ function x509_subject_name_hash%(cert: opaque of x509, hash_alg: count%): string
 	return x509_entity_hash(cert_handle, hash_alg, 0);
 	%}
 
-## Get the hash of issuer name of a certificate
+## Get the hash of the issuer's distinguished name.
 ##
 ## cert: The X509 certificate opaque handle.
 ##
-## hash_alg: the hash algorithm to use
+## 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: A string of hash of issuer name.
+## Returns: The hash as a string.
 ##
-## .. bro:see:: x509_certificate x509_extension x509_ext_basic_constraints
+## .. bro:see:: x509_subject_name_hash x509_spki_hash
-##              x509_ext_subject_alternative_name x509_parse
+##              x509_verify sct_verify
-##              x509_get_certificate_string x509_verify
 function x509_issuer_name_hash%(cert: opaque of x509, hash_alg: count%): string
 	%{
 	file_analysis::X509Val *cert_handle = (file_analysis::X509Val *) cert;
@@ -814,6 +849,17 @@ function x509_issuer_name_hash%(cert: opaque of x509, hash_alg: count%): string
 	return x509_entity_hash(cert_handle, hash_alg, 1);
 	%}
 
+## 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.
+##
+## .. bro:see:: x509_subject_name_hash x509_issuer_name_hash
+##              x509_verify sct_verify
 function x509_spki_hash%(cert: opaque of x509, hash_alg: count%): string
 	%{
 	file_analysis::X509Val *cert_handle = (file_analysis::X509Val *) cert;

src/file_analysis/analyzer/x509/ocsp_events.bif

@@ -1,6 +1,8 @@
 ## Event that is raised when encountering an OCSP request, e.g. in an HTTP
 ## connection. See :rfc:`6960` for more details.
 ##
+## This event is raised exactly once for each OCSP Request.
+##
 ## f: The file.
 ##
 ## req: version: the version of the OCSP request. Typically 0 (Version 1).
@@ -8,23 +10,111 @@
 ## requestorName: name of the OCSP requestor. This attribute is optional; if
 ##                it is not set, an empty string is returned here.
 ##
+## .. bro:see:: ocsp_request_certificate ocsp_response_status
+##              ocsp_response_bytes ocsp_response_certificate ocsp_extension
+##              x509_ocsp_ext_signed_certificate_timestamp
 event ocsp_request%(f: fa_file, version: count, requestorName: string%);
 
+## Event that is raised when encountering an OCSP request for a certificate, 
+## e.g. in an HTTP connection. See :rfc:`6960` for more details.
+##
+## Note that a single OCSP request can contain requests for several certificates.
+## Thus this event can fire several times for one OCSP request, each time
+## requesting information for a different (or in theory even the same) certificate.
+##
+## f: The file.
+##
+## hashAlgorithm: The hash algorithm used for the issuerKeyHash.
+##
+## issuerKeyHash: Hash of the issuers public key.
+##
+## serialNumber: Serial number of the certificate for which the status is requested.
+##
+## .. bro:see:: ocsp_request ocsp_response_status
+##              ocsp_response_bytes ocsp_response_certificate ocsp_extension
+##              x509_ocsp_ext_signed_certificate_timestamp
 event ocsp_request_certificate%(f: fa_file, hashAlgorithm: string, issuerNameHash: string, issuerKeyHash: string, serialNumber: string%);
 
-## Generated for encountered OCSP response
+## This event is raised when encountering an OCSP reply, e.g. in an HTTP
+## connection or a TLS extension. See :rfc:`6960` for more details.
+##
+## This event is raised exactly once for each OCSP reply.
+##
+## f: The file.
+##
+## status: The status of the OCSP response (e.g. succesful, malformedRequest, tryLater).
+##
+## .. bro:see:: ocsp_request ocsp_request_certificate
+##              ocsp_response_bytes ocsp_response_certificate ocsp_extension
+##              x509_ocsp_ext_signed_certificate_timestamp
+event ocsp_response_status%(f: fa_file, status: string%);
+
+## This event is raised when encountering an OCSP response that contains response information.
+## An OCSP reply can be encountered, for example, in an HTTP connection or
+## a TLS extension. See :rfc:`6960` for more details on OCSP.
 ##
 ## f: The file.
 ##
 ## req_ref: An opaque pointer to the underlying OpenSSL data structure of the
-##          OCSP response
+##          OCSP response.
 ##
-## req: The parsed OCSP response information.
+## status: The status of the OCSP response (e.g. succesful, malformedRequest, tryLater).
 ##
-event ocsp_response_status%(f: fa_file, status: string%);
+## version: Version of the OCSP response (typically - for version 1). 
-
+##
+## responderId: The id of the OCSP responder; either a public key hash or a distinguished name.
+##
+## producedAt: Time at which the reply was produced.
+##
+## signatureAlgorithm: Algorithm used for the OCSP signature.
+##
+## certs: Optional list of certificates that are sent with the OCSP response; these typically
+##        are needed to perform validation of the reply.
+##
+## .. bro:see:: ocsp_request ocsp_request_certificate ocsp_response_status
+##              ocsp_response_certificate ocsp_extension
+##              x509_ocsp_ext_signed_certificate_timestamp
 event ocsp_response_bytes%(f: fa_file, resp_ref: opaque of ocsp_resp, status: string, version: count, responderId: string, producedAt: time, signatureAlgorithm: string, certs: x509_opaque_vector%);
 
-event ocsp_response_certificate%(f: fa_file, hashAlgorithm: string, issuerNameHash: string, issuerKeyHash: string, serialNumber: string, certStatus: string, revoketime: time, revokereason: string, thisUpdate: time, nextUpdate: time%);
+## This event is raised for each SingleResponse contained in an OCSP response.
+## See :rfc:`6960` for more details on OCSP.
+##
+## f: The file.
+##
+## hashAlgorithm: The hash algorithm used for issuerNameHash and issuerKeyHash.
+##
+## issuerNameHash: Hash of the issuer's distinguished name.
+##
+## issuerKeyHash: Hash of the issuer's public key.
+##
+## serialNumber: Serial number of the affected certificate.
+##
+## certStatus: Status of the certificate.
+##
+## revokeTime: Time the certificate was revoked, 0 if not revoked.
+##
+## revokeTeason: Reason certificate was revoked; empty string if not revoked or not specified.
+##
+## thisUpdate: Time this response was generated.
+##
+## nextUpdate: Time next response will be ready; 0 if not supploed.
+##
+## .. bro:see:: ocsp_request ocsp_request_certificate ocsp_response_status
+##              ocsp_response_bytes ocsp_extension
+##              x509_ocsp_ext_signed_certificate_timestamp
+event ocsp_response_certificate%(f: fa_file, hashAlgorithm: string, issuerNameHash: string, issuerKeyHash: string, serialNumber: string, certStatus: string, revokeTime: time, revokeReason: string, thisUpdate: time, nextUpdate: time%);
 
+## This event is raised when an OCSP extension is encountered in an OCSP response.
+## See :rfc:`6960` for more details on OCSP.
+##
+## f: The file.
+##
+## ext: The parsed extension (same format as X.509 extensions).
+##
+## global_resp: T if extension encountered in the global response (in ResponseData),
+##              F when encountered in a SingleResponse.
+##
+## .. bro:see:: ocsp_request ocsp_request_certificate ocsp_response_status
+##              ocsp_response_bytes ocsp_response_certificate
+##              x509_ocsp_ext_signed_certificate_timestamp
 event ocsp_extension%(f: fa_file, ext: X509::Extension, global_resp: bool%);

testing/btest/Baseline/coverage.find-bro-logs/out

@@ -30,6 +30,7 @@ netcontrol_shunt
 notice
 notice_alarm
 ntlm
+ocsp
 open_flow
 packet_filter
 pe