Botan 3.14.1
Crypto and TLS for C&
Botan::OCSP::Response Class Referencefinal

#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
statusthe status code the check functions will return

TODO(Botan4) make this constructor private

Definition at line 371 of file ocsp.cpp.

371 :
372 m_status(Response_Status_Code::Successful), m_dummy_response_status(status) {}
Response_Status_Code status() const
Definition ocsp.h:240

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_bitsresponse bits received

Definition at line 186 of file ocsp.h.

186 :
187 Response(response_bits.data(), response_bits.size()) {}
BOTAN_FUTURE_EXPLICIT Response(Certificate_Status_Code status)
Definition ocsp.cpp:371

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_bitsresponse bits received
response_bits_lenlength of response in bytes

Definition at line 374 of file ocsp.cpp.

374 :
375 m_response_bits(response_bits, response_bits + response_bits_len) {
376 /*
377 * RFC 6960 Section 4.2.1
378 *
379 * OCSPResponse ::= SEQUENCE {
380 * responseStatus OCSPResponseStatus,
381 * responseBytes [0] EXPLICIT ResponseBytes OPTIONAL }
382 *
383 * OCSPResponseStatus ::= ENUMERATED { ... }
384 *
385 * ResponseBytes ::= SEQUENCE {
386 * responseType OBJECT IDENTIFIER,
387 * response OCTET STRING }
388 */
389 BER_Decoder outer_decoder(m_response_bits, BER_Decoder::Limits::DER());
390 BER_Decoder response_outer = outer_decoder.start_sequence();
391
392 size_t resp_status = 0;
393
394 response_outer.decode(resp_status, ASN1_Type::Enumerated, ASN1_Class::Universal);
395
396 /*
397 RFC 6960 4.2.1
398
399 OCSPResponseStatus ::= ENUMERATED {
400 successful (0), -- Response has valid confirmations
401 malformedRequest (1), -- Illegal confirmation request
402 internalError (2), -- Internal error in issuer
403 tryLater (3), -- Try again later
404 -- (4) is not used
405 sigRequired (5), -- Must sign the request
406 unauthorized (6) -- Request unauthorized
407 }
408 */
409 if(resp_status == 4 || resp_status >= 7) {
410 throw Decoding_Error("Unknown OCSPResponseStatus code");
411 }
412
413 m_status = static_cast<Response_Status_Code>(resp_status);
414
415 /*
416 * RFC 6960 4.2.1: "If the value of responseStatus is one of the error
417 * conditions, the responseBytes field is not set."
418 */
419 const bool successful = (m_status == Response_Status_Code::Successful);
420 const bool has_response_bytes = response_outer.more_items();
421
422 if(successful && !has_response_bytes) {
423 throw Decoding_Error("OCSP response with successful status is missing responseBytes");
424 }
425 if(!successful && has_response_bytes) {
426 throw Decoding_Error("OCSP response with non-successful status includes responseBytes");
427 }
428
429 if(successful) {
430 BER_Decoder response_bytes_ctx = response_outer.start_context_specific(0);
431 BER_Decoder response_bytes = response_bytes_ctx.start_sequence();
432
433 response_bytes.decode_and_check(OID::from_string("PKIX.OCSP.BasicResponse"),
434 "Unknown response type in OCSP response");
435
436 /*
437 * RFC 6960 Section 4.2.1
438 *
439 * BasicOCSPResponse ::= SEQUENCE {
440 * tbsResponseData ResponseData,
441 * signatureAlgorithm AlgorithmIdentifier,
442 * signature BIT STRING,
443 * certs [0] EXPLICIT SEQUENCE OF Certificate OPTIONAL }
444 */
445 BER_Decoder basic_response_decoder(response_bytes.get_next_octet_string(), BER_Decoder::Limits::DER());
446 BER_Decoder basicresponse = basic_response_decoder.start_sequence();
447
448 basicresponse.start_sequence()
449 .raw_bytes(m_tbs_bits)
450 .end_cons()
451 .decode(m_sig_algo)
452 .decode_octet_aligned_bitstring(m_signature);
453 decode_optional_list(basicresponse, ASN1_Type(0), m_certs);
454
455 basicresponse.verify_end();
456 basic_response_decoder.verify_end();
457
458 /*
459 * RFC 6960 Section 4.2.1
460 *
461 * ResponseData ::= SEQUENCE {
462 * version [0] EXPLICIT Version DEFAULT v1,
463 * responderID ResponderID,
464 * producedAt GeneralizedTime,
465 * responses SEQUENCE OF SingleResponse,
466 * responseExtensions [1] EXPLICIT Extensions OPTIONAL }
467 *
468 * ResponderID ::= CHOICE {
469 * byName [1] Name,
470 * byKey [2] KeyHash }
471 */
472 size_t responsedata_version = 0;
473 Extensions extensions;
474
475 BER_Decoder tbs_decoder(m_tbs_bits, BER_Decoder::Limits::DER());
476 tbs_decoder
477 .decode_optional(responsedata_version, ASN1_Type(0), ASN1_Class::ContextSpecific | ASN1_Class::Constructed)
478
479 .decode_optional(m_signer_name, ASN1_Type(1), ASN1_Class::ContextSpecific | ASN1_Class::Constructed)
480
481 .decode_optional_string(
483
484 .decode(m_produced_at)
485
486 .decode_list(m_responses);
487
488 check_generalized_time(m_produced_at, "producedAt");
489
490 if(tbs_decoder.more_items()) {
491 const BER_Object next = tbs_decoder.get_next_object();
493 BER_Decoder ext_decoder(next, BER_Decoder::Limits::DER());
494 extensions.decode_from(ext_decoder, Extension_Context::OCSP_Response);
495 ext_decoder.verify_end();
496 } else {
497 throw Decoding_Error("Unexpected tag in OCSP ResponseData");
498 }
499 }
500 tbs_decoder.verify_end();
501
502 const bool has_signer = !m_signer_name.empty();
503 const bool has_key_hash = !m_key_hash.empty();
504
505 if(has_signer && has_key_hash) {
506 throw Decoding_Error("OCSP response includes both byName and byKey in responderID field");
507 }
508 if(!has_signer && !has_key_hash) {
509 throw Decoding_Error("OCSP response contains neither byName nor byKey in responderID field");
510 }
511 if(has_key_hash && m_key_hash.size() != 20) {
512 // KeyHash ::= OCTET STRING -- SHA-1 hash of responder's public key
513 throw Decoding_Error("OCSP response contains a byKey with invalid length");
514 }
515
516 response_bytes.verify_end();
517 response_bytes_ctx.verify_end();
518
519 // We don't currently recognize any extensions here so if any are critical we should reject
520 m_has_unknown_critical_ext = !extensions.critical_extensions().empty();
521 }
522
523 response_outer.verify_end();
524 outer_decoder.verify_end();
525
526 if(m_has_unknown_critical_ext == false) {
527 // Check all of the SingleResponse extensions
528 for(const auto& sr : m_responses) {
529 if(sr.has_unknown_critical_extension()) {
530 m_has_unknown_critical_ext = true;
531 break;
532 }
533 }
534 }
535}
static Limits DER()
Definition ber_dec.h:44
static OID from_string(std::string_view str)
Definition asn1_oid.cpp:80
Response_Status_Code
Definition ocsp.h:158
ASN1_Type
Definition asn1_obj.h:47

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.

284{ 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.

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.

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.

312{ 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_certificateis the issuer of the certificate in question
trusted_ocsp_respondersoptionally, a certificate store containing additionally trusted responder certificates
Returns
the certificate that signed this response or std::nullopt if not found

Definition at line 600 of file ocsp.cpp.

601 {
602 using namespace std::placeholders;
603
604 // Check whether the CA issuing the certificate in question also signed this
605 if(is_issued_by(issuer_certificate)) {
606 return issuer_certificate;
607 }
608
609 // Then try to find a delegated responder certificate in the stapled certs
610 for(const auto& cert : m_certs) {
611 if(this->is_issued_by(cert)) {
612 return cert;
613 }
614 }
615
616 // Last resort: check the additionally provides trusted OCSP responders
617 if(trusted_ocsp_responders != nullptr) {
618 if(!m_key_hash.empty()) {
619 auto signing_cert = trusted_ocsp_responders->find_cert_by_pubkey_sha1(m_key_hash);
620 if(signing_cert) {
621 return signing_cert;
622 }
623 }
624
625 if(!m_signer_name.empty()) {
626 auto signing_cert = trusted_ocsp_responders->find_cert(m_signer_name, {});
627 if(signing_cert) {
628 return signing_cert;
629 }
630 }
631 }
632
633 return std::nullopt;
634}

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.

245{ 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.

257{ 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.

290{ 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.

255{ 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.

250{ 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.

240{ 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
issuerissuer certificate
subjectsubject certificate
ref_timethe reference time
max_agethe 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 636 of file ocsp.cpp.

639 {
640 if(m_dummy_response_status) {
641 return m_dummy_response_status.value();
642 }
643
644 for(const auto& response : m_responses) {
645 if(response.certid().is_id_for(issuer, subject)) {
646 const X509_Time x509_ref_time(ref_time);
647
648 /*
649 * We check certificate status prior to checking expiration, since otherwise it's
650 * possible to take an OCSP response indicating revocation, wait for it to expire,
651 * and then staple it. If such a response was reported as "expired" rather than
652 * "revoked" it's easy to dismiss as a clock issue or other misconfiguration.
653 */
654
655 if(response.cert_status() == 1) {
657 }
658
659 try {
660 if(response.this_update() > x509_ref_time) {
662 }
663
664 if(response.next_update().time_is_set()) {
665 if(x509_ref_time > response.next_update()) {
667 }
668 } else if(max_age > std::chrono::seconds::zero() &&
669 ref_time - response.this_update().to_std_timepoint() > max_age) {
671 }
672 } catch(Exception&) {
673 // This can occur if eg the OCSP time is not representable by the system clock
675 }
676
677 if(response.cert_status() == 0) {
679 } else {
681 }
682 }
683 }
684
686}
ASN1_Time X509_Time
Definition asn1_obj.h:27

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_certificatethe certificate that signed this response (
See also
Response::find_signing_certificate).
Returns
status code indicating the validity of the signature

Definition at line 549 of file ocsp.cpp.

549 {
550 const Path_Validation_Restrictions restrictions;
551
552 return this->verify_signature(issuer, restrictions);
553}
Certificate_Status_Code verify_signature(const X509_Certificate &signing_certificate) const
Definition ocsp.cpp:549

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_certificatethe certificate that signed this response (
See also
Response::find_signing_certificate)
Parameters
restrictionson the signature validation
Returns
status code indicating the validity of the signature

Definition at line 555 of file ocsp.cpp.

556 {
557 if(m_dummy_response_status) {
558 return m_dummy_response_status.value();
559 }
560
561 if(m_signer_name.empty() && m_key_hash.empty()) {
563 }
564
565 if(!is_issued_by(issuer)) {
567 }
568
569 try {
570 auto pub_key = issuer.subject_public_key();
571
572 PK_Verifier verifier(*pub_key, m_sig_algo);
573 verifier.update(ASN1::der_sequence_header(m_tbs_bits.size()));
574 verifier.update(m_tbs_bits);
575 const bool valid_signature = verifier.check_signature(m_signature);
576
577 if(valid_signature == false) {
579 }
580
581 if(m_has_unknown_critical_ext) {
583 }
584
585 const auto& trusted_hashes = restrictions.trusted_hashes();
586 if(!trusted_hashes.empty() && !trusted_hashes.contains(verifier.hash_function())) {
588 }
589
590 if(pub_key->estimated_strength() < restrictions.minimum_key_strength()) {
592 }
593
595 } catch(Exception&) {
597 }
598}
std::vector< uint8_t > der_sequence_header(size_t contents_len)
Definition der_enc.cpp:71

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: