Botan::OCSP::Response Class Reference

#include <ocsp.h>

Public Member Functions
const std::vector< X509_Certificate > &	certificates () const
std::optional< Certificate_Status_Code >	dummy_status () const
std::optional< X509_Certificate >	find_signing_certificate (const X509_Certificate &issuer_certificate, const Certificate_Store *trusted_ocsp_responders=nullptr) const
const X509_Time &	produced_at () const
const std::vector< uint8_t > &	raw_bits () const
BOTAN_FUTURE_EXPLICIT	Response (Certificate_Status_Code status)
BOTAN_FUTURE_EXPLICIT	Response (const std::vector< uint8_t > &response_bits)
	Response (const uint8_t response_bits[], size_t response_bits_len)
const std::vector< SingleResponse > &	responses () const
const std::vector< uint8_t > &	signer_key_hash () const
const X509_DN &	signer_name () const
Response_Status_Code	status () const
Certificate_Status_Code	status_for (const X509_Certificate &issuer, const X509_Certificate &subject, std::chrono::system_clock::time_point ref_time=std::chrono::system_clock::now(), std::chrono::seconds max_age=std::chrono::seconds::zero()) const
Certificate_Status_Code	verify_signature (const X509_Certificate &signing_certificate) const
Certificate_Status_Code	verify_signature (const X509_Certificate &signing_certificate, const Path_Validation_Restrictions &restrictions) const

Static Public Member Functions
static Response	dummy_no_revocation_url_response ()
static Response	dummy_server_not_available_response ()

Detailed Description

OCSP response.

Note this class is only usable as an OCSP client

Definition at line 172 of file ocsp.h.

Constructor & Destructor Documentation

Response() [1/3]

Botan::OCSP::Response::Response

(

Certificate_Status_Code

status

)

Create a fake OCSP response from a given status code.

Parameters

status

the status code the check functions will return

TODO(Botan4) make this constructor private

Definition at line 372 of file ocsp.cpp.

                                                 :
      m_status(Response_Status_Code::Successful), m_dummy_response_status(status) {}

References status().

Referenced by dummy_no_revocation_url_response(), dummy_server_not_available_response(), and Response().

Response() [2/3]

BOTAN_FUTURE_EXPLICIT Botan::OCSP::Response::Response ( const std::vector< uint8_t > & response_bits )

inline

Parses an OCSP response.

Parameters

response_bits

response bits received

Definition at line 186 of file ocsp.h.

                                                                              :
            Response(response_bits.data(), response_bits.size()) {}

References BOTAN_FUTURE_EXPLICIT, and Response().

Response() [3/3]

Botan::OCSP::Response::Response	(	const uint8_t	response_bits[],
		size_t	response_bits_len )

Parses an OCSP response.

Parameters

response_bits	response bits received
response_bits_len	length of response in bytes

Definition at line 375 of file ocsp.cpp.

                                                                          :
      m_response_bits(response_bits, response_bits + response_bits_len) {
   /*
   * RFC 6960 Section 4.2.1
   *
   * OCSPResponse ::= SEQUENCE {
   *    responseStatus         OCSPResponseStatus,
   *    responseBytes      [0] EXPLICIT ResponseBytes OPTIONAL }
   *
   * OCSPResponseStatus ::= ENUMERATED { ... }
   *
   * ResponseBytes ::= SEQUENCE {
   *    responseType   OBJECT IDENTIFIER,
   *    response       OCTET STRING }
   */
   BER_Decoder outer_decoder(m_response_bits, BER_Decoder::Limits::DER());
   BER_Decoder response_outer = outer_decoder.start_sequence();
 
   size_t resp_status = 0;
 
   response_outer.decode(resp_status, ASN1_Type::Enumerated, ASN1_Class::Universal);
 
   /*
   RFC 6960 4.2.1
 
   OCSPResponseStatus ::= ENUMERATED {
       successful            (0),  -- Response has valid confirmations
       malformedRequest      (1),  -- Illegal confirmation request
       internalError         (2),  -- Internal error in issuer
       tryLater              (3),  -- Try again later
                                   -- (4) is not used
       sigRequired           (5),  -- Must sign the request
       unauthorized          (6)   -- Request unauthorized
   }
   */
   if(resp_status == 4 || resp_status >= 7) {
      throw Decoding_Error("Unknown OCSPResponseStatus code");
   }
 
   m_status = static_cast<Response_Status_Code>(resp_status);
 
   /*
   * RFC 6960 4.2.1: "If the value of responseStatus is one of the error
   * conditions, the responseBytes field is not set."
   */
   const bool successful = (m_status == Response_Status_Code::Successful);
   const bool has_response_bytes = response_outer.more_items();
 
   if(successful && !has_response_bytes) {
      throw Decoding_Error("OCSP response with successful status is missing responseBytes");
   }
   if(!successful && has_response_bytes) {
      throw Decoding_Error("OCSP response with non-successful status includes responseBytes");
   }
 
   if(successful) {
      BER_Decoder response_bytes_ctx = response_outer.start_context_specific(0);
      BER_Decoder response_bytes = response_bytes_ctx.start_sequence();
 
      response_bytes.decode_and_check(OID::from_string("PKIX.OCSP.BasicResponse"),
                                      "Unknown response type in OCSP response");
 
      /*
      * RFC 6960 Section 4.2.1
      *
      * BasicOCSPResponse ::= SEQUENCE {
      *    tbsResponseData      ResponseData,
      *    signatureAlgorithm   AlgorithmIdentifier,
      *    signature            BIT STRING,
      *    certs            [0] EXPLICIT SEQUENCE OF Certificate OPTIONAL }
      */
      BER_Decoder basic_response_decoder(response_bytes.get_next_octet_string(), BER_Decoder::Limits::DER());
      BER_Decoder basicresponse = basic_response_decoder.start_sequence();
 
      basicresponse.start_sequence()
         .raw_bytes(m_tbs_bits)
         .end_cons()
         .decode(m_sig_algo)
         .decode_octet_aligned_bitstring(m_signature);
      decode_optional_list(basicresponse, ASN1_Type(0), m_certs);
 
      basicresponse.verify_end();
      basic_response_decoder.verify_end();
 
      /*
      * RFC 6960 Section 4.2.1
      *
      * ResponseData ::= SEQUENCE {
      *    version              [0] EXPLICIT Version DEFAULT v1,
      *    responderID              ResponderID,
      *    producedAt               GeneralizedTime,
      *    responses                SEQUENCE OF SingleResponse,
      *    responseExtensions   [1] EXPLICIT Extensions OPTIONAL }
      *
      * ResponderID ::= CHOICE {
      *    byName   [1] Name,
      *    byKey    [2] KeyHash }
      */
      size_t responsedata_version = 0;
      Extensions extensions;
 
      BER_Decoder tbs_decoder(m_tbs_bits, BER_Decoder::Limits::DER());
      tbs_decoder
         .decode_optional(responsedata_version, ASN1_Type(0), ASN1_Class::ContextSpecific | ASN1_Class::Constructed)
 
         .decode_optional(m_signer_name, ASN1_Type(1), ASN1_Class::ContextSpecific | ASN1_Class::Constructed)
 
         .decode_optional_string(
            m_key_hash, ASN1_Type::OctetString, 2, ASN1_Class::ContextSpecific | ASN1_Class::Constructed)
 
         .decode(m_produced_at)
 
         .decode_list(m_responses);
 
      check_generalized_time(m_produced_at, "producedAt");
 
      if(tbs_decoder.more_items()) {
         const BER_Object next = tbs_decoder.get_next_object();
         if(next.is_a(1, ASN1_Class::ContextSpecific | ASN1_Class::Constructed)) {
            BER_Decoder ext_decoder(next, BER_Decoder::Limits::DER());
            extensions.decode_from(ext_decoder, Extension_Context::OCSP_Response);
            ext_decoder.verify_end();
         } else {
            throw Decoding_Error("Unexpected tag in OCSP ResponseData");
         }
      }
      tbs_decoder.verify_end();
 
      const bool has_signer = !m_signer_name.empty();
      const bool has_key_hash = !m_key_hash.empty();
 
      if(has_signer && has_key_hash) {
         throw Decoding_Error("OCSP response includes both byName and byKey in responderID field");
      }
      if(!has_signer && !has_key_hash) {
         throw Decoding_Error("OCSP response contains neither byName nor byKey in responderID field");
      }
      if(has_key_hash && m_key_hash.size() != 20) {
         // KeyHash ::= OCTET STRING -- SHA-1 hash of responder's public key
         throw Decoding_Error("OCSP response contains a byKey with invalid length");
      }
 
      response_bytes.verify_end();
      response_bytes_ctx.verify_end();
 
      // We don't currently recognize any extensions here so if any are critical we should reject
      m_has_unknown_critical_ext = !extensions.critical_extensions().empty();
   }
 
   response_outer.verify_end();
   outer_decoder.verify_end();
 
   if(m_has_unknown_critical_ext == false) {
      // Check all of the SingleResponse extensions
      for(const auto& sr : m_responses) {
         if(sr.has_unknown_critical_extension()) {
            m_has_unknown_critical_ext = true;
            break;
         }
      }
   }
}

References Botan::Constructed, Botan::ContextSpecific, Botan::Extensions::critical_extensions(), Botan::BER_Decoder::decode(), Botan::BER_Decoder::decode_and_check(), Botan::Extensions::decode_from(), Botan::BER_Decoder::decode_list(), Botan::BER_Decoder::decode_octet_aligned_bitstring(), Botan::BER_Decoder::decode_optional(), Botan::BER_Decoder::decode_optional_string(), Botan::BER_Decoder::Limits::DER(), Botan::BER_Decoder::end_cons(), Botan::Enumerated, Botan::OID::from_string(), Botan::BER_Decoder::get_next_object(), Botan::BER_Decoder::get_next_octet_string(), Botan::BER_Object::is_a(), Botan::BER_Decoder::more_items(), Botan::OCSP_Response, Botan::OctetString, Botan::BER_Decoder::raw_bytes(), Botan::BER_Decoder::start_context_specific(), Botan::BER_Decoder::start_sequence(), Botan::OCSP::Successful, Botan::Universal, and Botan::BER_Decoder::verify_end().

Member Function Documentation

certificates()

const std::vector< X509_Certificate > & Botan::OCSP::Response::certificates ( ) const

inline

Returns

the certificate chain, if provided in response

Definition at line 284 of file ocsp.h.

{ return m_certs; }

dummy_no_revocation_url_response()

Response Botan::OCSP::Response::dummy_no_revocation_url_response ( )

inlinestatic

Return a fake OCSP response indicating there was no usable OCSP URL This is not normally useful for applications

Definition at line 304 of file ocsp.h.

                                                         {
         return Response(Certificate_Status_Code::OCSP_NO_REVOCATION_URL);
      }

References Botan::OCSP_NO_REVOCATION_URL, and Response().

dummy_server_not_available_response()

Response Botan::OCSP::Response::dummy_server_not_available_response ( )

inlinestatic

Return a fake OCSP response indicating the server was not available This is not normally useful for applications

Definition at line 296 of file ocsp.h.

                                                            {
         return Response(Certificate_Status_Code::OCSP_SERVER_NOT_AVAILABLE);
      }

References Botan::OCSP_SERVER_NOT_AVAILABLE, and Response().

dummy_status()

std::optional< Certificate_Status_Code > Botan::OCSP::Response::dummy_status ( ) const

inline

Return the dummy response if this is a 'fake' OCSP response otherwise std::nullopt This is not normally useful for applications

Definition at line 312 of file ocsp.h.

{ return m_dummy_response_status; }

find_signing_certificate()

std::optional< X509_Certificate > Botan::OCSP::Response::find_signing_certificate	(	const X509_Certificate &	issuer_certificate,
		const Certificate_Store *	trusted_ocsp_responders = nullptr ) const

Find the certificate that signed this OCSP response from all possible candidates and taking the attached certificates into account.

Parameters

issuer_certificate	is the issuer of the certificate in question
trusted_ocsp_responders	optionally, a certificate store containing additionally trusted responder certificates

Returns

the certificate that signed this response or std::nullopt if not found

Definition at line 601 of file ocsp.cpp.

                                                                                                       {
   using namespace std::placeholders;
 
   // Check whether the CA issuing the certificate in question also signed this
   if(is_issued_by(issuer_certificate)) {
      return issuer_certificate;
   }
 
   // Then try to find a delegated responder certificate in the stapled certs
   for(const auto& cert : m_certs) {
      if(this->is_issued_by(cert)) {
         return cert;
      }
   }
 
   // Last resort: check the additionally provides trusted OCSP responders
   if(trusted_ocsp_responders != nullptr) {
      if(!m_key_hash.empty()) {
         auto signing_cert = trusted_ocsp_responders->find_cert_by_pubkey_sha1(m_key_hash);
         if(signing_cert) {
            return signing_cert;
         }
      }
 
      if(!m_signer_name.empty()) {
         auto signing_cert = trusted_ocsp_responders->find_cert(m_signer_name, {});
         if(signing_cert) {
            return signing_cert;
         }
      }
   }
 
   return std::nullopt;
}

References Botan::Certificate_Store::find_cert(), and Botan::Certificate_Store::find_cert_by_pubkey_sha1().

produced_at()

const X509_Time & Botan::OCSP::Response::produced_at ( ) const

inline

Returns

the time this OCSP response was supposedly produced at

Definition at line 245 of file ocsp.h.

{ return m_produced_at; }

raw_bits()

const std::vector< uint8_t > & Botan::OCSP::Response::raw_bits ( ) const

inline

Definition at line 257 of file ocsp.h.

{ return m_response_bits; }

responses()

const std::vector< SingleResponse > & Botan::OCSP::Response::responses ( ) const

inline

Returns

the SingleResponses included in this response (empty for a 'fake' or non-successful response)

Definition at line 290 of file ocsp.h.

{ return m_responses; }

signer_key_hash()

const std::vector< uint8_t > & Botan::OCSP::Response::signer_key_hash ( ) const

inline

Returns

key hash, if provided in response (may be empty)

Definition at line 255 of file ocsp.h.

{ return m_key_hash; }

signer_name()

const X509_DN & Botan::OCSP::Response::signer_name ( ) const

inline

Returns

DN of signer, if provided in response (may be empty)

Definition at line 250 of file ocsp.h.

{ return m_signer_name; }

status()

Response_Status_Code Botan::OCSP::Response::status ( ) const

inline

Returns

the status of the response

Definition at line 240 of file ocsp.h.

{ return m_status; }

Referenced by Response().

status_for()

Certificate_Status_Code Botan::OCSP::Response::status_for	(	const X509_Certificate &	issuer,
		const X509_Certificate &	subject,
		std::chrono::system_clock::time_point	ref_time = std::chrono::system_clock::now(),
		std::chrono::seconds	max_age = std::chrono::seconds::zero() ) const

Searches the OCSP response for issuer and subject certificate.

Parameters

issuer	issuer certificate
subject	subject certificate
ref_time	the reference time
max_age	the maximum age the response should be considered valid if next_update is not set

Returns

OCSP status code, possible values: CERT_IS_REVOKED, OCSP_NOT_YET_VALID, OCSP_HAS_EXPIRED, OCSP_IS_TOO_OLD, OCSP_RESPONSE_GOOD, OCSP_BAD_STATUS, OCSP_CERT_NOT_LISTED

Definition at line 637 of file ocsp.cpp.

                                                                             {
   if(m_dummy_response_status) {
      return m_dummy_response_status.value();
   }
 
   for(const auto& response : m_responses) {
      if(response.certid().is_id_for(issuer, subject)) {
         const X509_Time x509_ref_time(ref_time);
 
         /*
         * We check certificate status prior to checking expiration, since otherwise it's
         * possible to take an OCSP response indicating revocation, wait for it to expire,
         * and then staple it. If such a response was reported as "expired" rather than
         * "revoked" it's easy to dismiss as a clock issue or other misconfiguration.
         */
 
         if(response.cert_status() == 1) {
            return Certificate_Status_Code::CERT_IS_REVOKED;
         }
 
         try {
            if(response.this_update() > x509_ref_time) {
               return Certificate_Status_Code::OCSP_NOT_YET_VALID;
            }
 
            if(response.next_update().time_is_set()) {
               if(x509_ref_time > response.next_update()) {
                  return Certificate_Status_Code::OCSP_HAS_EXPIRED;
               }
            } else if(max_age > std::chrono::seconds::zero() &&
                      ref_time - response.this_update().to_std_timepoint() > max_age) {
               return Certificate_Status_Code::OCSP_IS_TOO_OLD;
            }
         } catch(Exception&) {
            // This can occur if eg the OCSP time is not representable by the system clock
            return Certificate_Status_Code::OCSP_RESPONSE_INVALID;
         }
 
         if(response.cert_status() == 0) {
            return Certificate_Status_Code::OCSP_RESPONSE_GOOD;
         } else {
            return Certificate_Status_Code::OCSP_BAD_STATUS;
         }
      }
   }
 
   return Certificate_Status_Code::OCSP_CERT_NOT_LISTED;
}

References Botan::CERT_IS_REVOKED, Botan::OCSP_BAD_STATUS, Botan::OCSP_CERT_NOT_LISTED, Botan::OCSP_HAS_EXPIRED, Botan::OCSP_IS_TOO_OLD, Botan::OCSP_NOT_YET_VALID, Botan::OCSP_RESPONSE_GOOD, and Botan::OCSP_RESPONSE_INVALID.

verify_signature() [1/2]

Certificate_Status_Code Botan::OCSP::Response::verify_signature

(

const X509_Certificate &

signing_certificate

)

const

Check signature of the OCSP response.

Note: It is the responsibility of the caller to verify that signing certificate is trustworthy and authorized to do so.

Parameters

signing_certificate

the certificate that signed this response (

See also

Response::find_signing_certificate).

Returns

status code indicating the validity of the signature

Definition at line 550 of file ocsp.cpp.

                                                                                       {
   const Path_Validation_Restrictions restrictions;
 
   return this->verify_signature(issuer, restrictions);
}

References verify_signature().

Referenced by verify_signature().

verify_signature() [2/2]

Certificate_Status_Code Botan::OCSP::Response::verify_signature	(	const X509_Certificate &	signing_certificate,
		const Path_Validation_Restrictions &	restrictions ) const

Check signature of the OCSP response.

Note: It is the responsibility of the caller to verify that signing certificate is trustworthy and authorized to do so.

Parameters

signing_certificate

the certificate that signed this response (

See also

Response::find_signing_certificate)

Parameters

restrictions

on the signature validation

Returns

status code indicating the validity of the signature

Definition at line 556 of file ocsp.cpp.

                                                                                                           {
   if(m_dummy_response_status) {
      return m_dummy_response_status.value();
   }
 
   if(m_signer_name.empty() && m_key_hash.empty()) {
      return Certificate_Status_Code::OCSP_RESPONSE_INVALID;
   }
 
   if(!is_issued_by(issuer)) {
      return Certificate_Status_Code::OCSP_ISSUER_NOT_FOUND;
   }
 
   try {
      auto pub_key = issuer.subject_public_key();
 
      PK_Verifier verifier(*pub_key, m_sig_algo);
      verifier.update(ASN1::der_sequence_header(m_tbs_bits.size()));
      verifier.update(m_tbs_bits);
      const bool valid_signature = verifier.check_signature(m_signature);
 
      if(valid_signature == false) {
         return Certificate_Status_Code::OCSP_SIGNATURE_ERROR;
      }
 
      if(m_has_unknown_critical_ext) {
         return Certificate_Status_Code::UNKNOWN_CRITICAL_EXTENSION;
      }
 
      const auto& trusted_hashes = restrictions.trusted_hashes();
      if(!trusted_hashes.empty() && !trusted_hashes.contains(verifier.hash_function())) {
         return Certificate_Status_Code::UNTRUSTED_HASH;
      }
 
      if(pub_key->estimated_strength() < restrictions.minimum_key_strength()) {
         return Certificate_Status_Code::SIGNATURE_METHOD_TOO_WEAK;
      }
 
      return Certificate_Status_Code::OCSP_SIGNATURE_OK;
   } catch(Exception&) {
      return Certificate_Status_Code::OCSP_SIGNATURE_ERROR;
   }
}

References Botan::PK_Verifier::check_signature(), Botan::ASN1::der_sequence_header(), Botan::PK_Verifier::hash_function(), Botan::Path_Validation_Restrictions::minimum_key_strength(), Botan::OCSP_ISSUER_NOT_FOUND, Botan::OCSP_RESPONSE_INVALID, Botan::OCSP_SIGNATURE_ERROR, Botan::OCSP_SIGNATURE_OK, Botan::SIGNATURE_METHOD_TOO_WEAK, Botan::X509_Certificate::subject_public_key(), Botan::Path_Validation_Restrictions::trusted_hashes(), Botan::UNKNOWN_CRITICAL_EXTENSION, Botan::UNTRUSTED_HASH, and Botan::PK_Verifier::update().

---

The documentation for this class was generated from the following files:

• src/lib/x509/ocsp.h
• src/lib/x509/ocsp.cpp