Functions
Certificate_Status_Code	build_all_certificate_paths (std::vector< std::vector< X509_Certificate > > &cert_paths, const std::vector< Certificate_Store * > &trusted_certstores, const std::optional< X509_Certificate > &end_entity, const std::vector< X509_Certificate > &end_entity_extra)
Certificate_Status_Code	build_certificate_path (std::vector< X509_Certificate > &cert_path_out, const std::vector< Certificate_Store * > &trusted_certstores, const X509_Certificate &end_entity, const std::vector< X509_Certificate > &end_entity_extra)
CertificatePathStatusCodes	check_chain (const std::vector< X509_Certificate > &cert_path, std::chrono::system_clock::time_point ref_time, std::string_view hostname, Usage_Type usage, const Path_Validation_Restrictions &restrictions)
CertificatePathStatusCodes	check_crl (const std::vector< X509_Certificate > &cert_path, const std::vector< Certificate_Store * > &certstores, std::chrono::system_clock::time_point ref_time)
CertificatePathStatusCodes	check_crl (const std::vector< X509_Certificate > &cert_path, const std::vector< std::optional< X509_CRL > > &crls, std::chrono::system_clock::time_point ref_time)
CertificatePathStatusCodes	check_ocsp (const std::vector< X509_Certificate > &cert_path, const std::vector< std::optional< OCSP::Response > > &ocsp_responses, const std::vector< Certificate_Store * > &certstores, std::chrono::system_clock::time_point ref_time, const Path_Validation_Restrictions &restrictions)
void	merge_revocation_status (CertificatePathStatusCodes &chain_status, const CertificatePathStatusCodes &crl_status, const CertificatePathStatusCodes &ocsp_status, const Path_Validation_Restrictions &restrictions)
Certificate_Status_Code	overall_status (const CertificatePathStatusCodes &cert_status)

Detailed Description

namespace PKIX holds the building blocks that are called by x509_path_validate. This allows custom validation logic to be written by applications and makes for easier testing, but unless you're positive you know what you're doing you probably want to just call x509_path_validate instead.

Function Documentation

◆ build_all_certificate_paths()

Certificate_Status_Code Botan::PKIX::build_all_certificate_paths	(	std::vector< std::vector< X509_Certificate > > &	cert_paths_out,
		const std::vector< Certificate_Store * > &	trusted_certstores,
		const std::optional< X509_Certificate > &	end_entity,
		const std::vector< X509_Certificate > &	end_entity_extra )

Build all possible certificate paths from the end certificate to self-signed trusted roots.

All potentially valid paths are put into the cert_paths vector. If no potentially valid paths are found, one of the encountered errors is returned arbitrarily.

todo add a path building function that returns detailed information on errors encountered while building the potentially numerous path candidates.

Basically, a DFS is performed starting from the end certificate. A stack (vector) serves to control the DFS. At the beginning of each iteration, a pair is popped from the stack that contains (1) the next certificate to add to the path (2) a bool that indicates if the certificate is part of a trusted certstore. Ideally, we follow the unique issuer of the current certificate until a trusted root is reached. However, the issuer DN + authority key id need not be unique among the certificates used for building the path. In such a case, we consider all the matching issuers by pushing <IssuerCert, trusted?> on the stack for each of them.

Definition at line 692 of file x509path.cpp.

                                                                                                               {
   if(!cert_paths_out.empty()) {
      throw Invalid_Argument("PKIX::build_all_certificate_paths: cert_paths_out must be empty");
   }
 
   if(end_entity->is_self_signed()) {
      return Certificate_Status_Code::CANNOT_ESTABLISH_TRUST;
   }
 
   /*
    * Pile up error messages
    */
   std::vector<Certificate_Status_Code> stats;
 
   Certificate_Store_In_Memory ee_extras;
   for(const auto& cert : end_entity_extra) {
      ee_extras.add_certificate(cert);
   }
 
   /*
   * This is an inelegant but functional way of preventing path loops
   * (where C1 -> C2 -> C3 -> C1). We store a set of all the certificate
   * fingerprints in the path. If there is a duplicate, we error out.
   * TODO: save fingerprints in result struct? Maybe useful for blacklists, etc.
   */
   std::set<std::string> certs_seen;
 
   // new certs are added and removed from the path during the DFS
   // it is copied into cert_paths_out when we encounter a trusted root
   std::vector<X509_Certificate> path_so_far;
 
   // todo can we assume that the end certificate is not trusted?
   std::vector<cert_maybe_trusted> stack = {{end_entity, false}};
 
   while(!stack.empty()) {
      std::optional<X509_Certificate> last = stack.back().first;
      // found a deletion marker that guides the DFS, backtracking
      if(last == std::nullopt) {
         stack.pop_back();
         std::string fprint = path_so_far.back().fingerprint("SHA-256");
         certs_seen.erase(fprint);
         path_so_far.pop_back();
      }
      // process next cert on the path
      else {
         const bool trusted = stack.back().second;
         stack.pop_back();
 
         // certificate already seen?
         const std::string fprint = last->fingerprint("SHA-256");
         if(certs_seen.count(fprint) == 1) {
            stats.push_back(Certificate_Status_Code::CERT_CHAIN_LOOP);
            // the current path ended in a loop
            continue;
         }
 
         // the current path ends here
         if(last->is_self_signed()) {
            // found a trust anchor
            if(trusted) {
               cert_paths_out.push_back(path_so_far);
               cert_paths_out.back().push_back(*last);
 
               continue;
            }
            // found an untrustworthy root
            else {
               stats.push_back(Certificate_Status_Code::CANNOT_ESTABLISH_TRUST);
               continue;
            }
         }
 
         const X509_DN issuer_dn = last->issuer_dn();
         const std::vector<uint8_t> auth_key_id = last->authority_key_id();
 
         // search for trusted issuers
         std::vector<X509_Certificate> trusted_issuers;
         for(Certificate_Store* store : trusted_certstores) {
            auto new_issuers = store->find_all_certs(issuer_dn, auth_key_id);
            trusted_issuers.insert(trusted_issuers.end(), new_issuers.begin(), new_issuers.end());
         }
 
         // search the supplemental certs
         std::vector<X509_Certificate> misc_issuers = ee_extras.find_all_certs(issuer_dn, auth_key_id);
 
         // if we could not find any issuers, the current path ends here
         if(trusted_issuers.empty() && misc_issuers.empty()) {
            stats.push_back(Certificate_Status_Code::CERT_ISSUER_NOT_FOUND);
            continue;
         }
 
         // push the latest certificate onto the path_so_far
         path_so_far.push_back(*last);
         certs_seen.emplace(fprint);
 
         // push a deletion marker on the stack for backtracking later
         stack.push_back({std::optional<X509_Certificate>(), false});
 
         for(const auto& trusted_cert : trusted_issuers) {
            stack.push_back({trusted_cert, true});
         }
 
         for(const auto& misc : misc_issuers) {
            stack.push_back({misc, false});
         }
      }
   }
 
   // could not construct any potentially valid path
   if(cert_paths_out.empty()) {
      if(stats.empty()) {
         throw Internal_Error("X509 path building failed for unknown reasons");
      } else {
         // arbitrarily return the first error
         return stats[0];
      }
   } else {
      return Certificate_Status_Code::OK;
   }
}

References Botan::Certificate_Store_In_Memory::add_certificate(), Botan::CANNOT_ESTABLISH_TRUST, Botan::CERT_CHAIN_LOOP, Botan::CERT_ISSUER_NOT_FOUND, Botan::Certificate_Store_In_Memory::find_all_certs(), and Botan::OK.

Referenced by Botan::x509_path_validate().

◆ build_certificate_path()

Certificate_Status_Code Botan::PKIX::build_certificate_path	(	std::vector< X509_Certificate > &	cert_path_out,
		const std::vector< Certificate_Store * > &	trusted_certstores,
		const X509_Certificate &	end_entity,
		const std::vector< X509_Certificate > &	end_entity_extra )

Build certificate path

Parameters

cert_path_out	output parameter, cert_path will be appended to this vector
trusted_certstores	list of certificate stores that contain trusted certificates
end_entity	the cert to be validated
end_entity_extra	optional list of additional untrusted certs for path building

Returns: result of the path building operation (OK or error)

Definition at line 597 of file x509path.cpp.

                                                                                                          {
   if(end_entity.is_self_signed()) {
      return Certificate_Status_Code::CANNOT_ESTABLISH_TRUST;
   }
 
   /*
   * This is an inelegant but functional way of preventing path loops
   * (where C1 -> C2 -> C3 -> C1). We store a set of all the certificate
   * fingerprints in the path. If there is a duplicate, we error out.
   * TODO: save fingerprints in result struct? Maybe useful for blacklists, etc.
   */
   std::set<std::string> certs_seen;
 
   cert_path.push_back(end_entity);
   certs_seen.insert(end_entity.fingerprint("SHA-256"));
 
   Certificate_Store_In_Memory ee_extras;
   for(const auto& cert : end_entity_extra) {
      ee_extras.add_certificate(cert);
   }
 
   // iterate until we reach a root or cannot find the issuer
   for(;;) {
      const X509_Certificate& last = cert_path.back();
      const X509_DN issuer_dn = last.issuer_dn();
      const std::vector<uint8_t> auth_key_id = last.authority_key_id();
 
      std::optional<X509_Certificate> issuer;
      bool trusted_issuer = false;
 
      for(Certificate_Store* store : trusted_certstores) {
         issuer = store->find_cert(issuer_dn, auth_key_id);
         if(issuer) {
            trusted_issuer = true;
            break;
         }
      }
 
      if(!issuer) {
         // fall back to searching supplemental certs
         issuer = ee_extras.find_cert(issuer_dn, auth_key_id);
      }
 
      if(!issuer) {
         return Certificate_Status_Code::CERT_ISSUER_NOT_FOUND;
      }
 
      const std::string fprint = issuer->fingerprint("SHA-256");
 
      if(certs_seen.contains(fprint)) {
         // we already saw this certificate -> loop
         return Certificate_Status_Code::CERT_CHAIN_LOOP;
      }
 
      certs_seen.insert(fprint);
      cert_path.push_back(*issuer);
 
      if(issuer->is_self_signed()) {
         if(trusted_issuer) {
            return Certificate_Status_Code::OK;
         } else {
            return Certificate_Status_Code::CANNOT_ESTABLISH_TRUST;
         }
      }
   }
}

References Botan::Certificate_Store_In_Memory::add_certificate(), Botan::X509_Certificate::authority_key_id(), Botan::CANNOT_ESTABLISH_TRUST, Botan::CERT_CHAIN_LOOP, Botan::CERT_ISSUER_NOT_FOUND, Botan::Certificate_Store_In_Memory::find_cert(), Botan::X509_Certificate::fingerprint(), Botan::X509_Certificate::is_self_signed(), Botan::X509_Certificate::issuer_dn(), and Botan::OK.

◆ check_chain()

CertificatePathStatusCodes Botan::PKIX::check_chain	(	const std::vector< X509_Certificate > &	cert_path,
		std::chrono::system_clock::time_point	ref_time,
		std::string_view	hostname,
		Usage_Type	usage,
		const Path_Validation_Restrictions &	restrictions )

Check the certificate chain, but not any revocation data

Parameters

cert_path	path built by build_certificate_path with OK result. The first element is the end entity certificate, the last element is the trusted root certificate.
ref_time	whatever time you want to perform the validation against (normally current system clock)
hostname	the hostname
usage	end entity usage checks
restrictions	the relevant path validation restrictions object

Returns: vector of results on per certificate in the path, each containing a set of results. If all codes in the set are < Certificate_Status_Code::FIRST_ERROR_STATUS, then the result for that certificate is successful. If all results are

Definition at line 32 of file x509path.cpp.

                                                                                               {
   if(cert_path.empty()) {
      throw Invalid_Argument("PKIX::check_chain cert_path empty");
   }
 
   const bool self_signed_ee_cert = (cert_path.size() == 1);
 
   X509_Time validation_time(ref_time);
 
   CertificatePathStatusCodes cert_status(cert_path.size());
 
   // Before anything else verify the entire chain of signatures
   for(size_t i = 0; i != cert_path.size(); ++i) {
      std::set<Certificate_Status_Code>& status = cert_status.at(i);
 
      const bool at_self_signed_root = (i == cert_path.size() - 1);
 
      const X509_Certificate& subject = cert_path[i];
      const X509_Certificate& issuer = cert_path[at_self_signed_root ? (i) : (i + 1)];
 
      // Check the signature algorithm is known
      if(!subject.signature_algorithm().oid().registered_oid()) {
         status.insert(Certificate_Status_Code::SIGNATURE_ALGO_UNKNOWN);
      } else {
         std::unique_ptr<Public_Key> issuer_key;
         try {
            issuer_key = issuer.subject_public_key();
         } catch(...) {
            status.insert(Certificate_Status_Code::CERT_PUBKEY_INVALID);
         }
 
         if(issuer_key) {
            if(issuer_key->estimated_strength() < restrictions.minimum_key_strength()) {
               status.insert(Certificate_Status_Code::SIGNATURE_METHOD_TOO_WEAK);
            }
 
            const auto sig_status = subject.verify_signature(*issuer_key);
 
            if(sig_status.first != Certificate_Status_Code::VERIFIED) {
               status.insert(sig_status.first);
            } else {
               // Signature is valid, check if hash used was acceptable
               const std::string hash_used_for_signature = sig_status.second;
               BOTAN_ASSERT_NOMSG(!hash_used_for_signature.empty());
               const auto& trusted_hashes = restrictions.trusted_hashes();
 
               // Ignore untrusted hashes on self-signed roots
               if(!trusted_hashes.empty() && !at_self_signed_root) {
                  if(!trusted_hashes.contains(hash_used_for_signature)) {
                     status.insert(Certificate_Status_Code::UNTRUSTED_HASH);
                  }
               }
            }
         }
      }
   }
 
   // If any of the signatures were invalid, return immediately; we know the
   // chain is invalid and signature failure is always considered the most
   // critical result. This does mean other problems in the certificate (eg
   // expired) will not be reported, but we'd have to assume any such data is
   // anyway arbitrary considering we couldn't verify the signature chain
 
   for(size_t i = 0; i != cert_path.size(); ++i) {
      for(auto status : cert_status.at(i)) {
         // This ignores errors relating to the key or hash being weak since
         // these are somewhat advisory
         if(static_cast<uint32_t>(status) >= 5000) {
            return cert_status;
         }
      }
   }
 
   if(!hostname.empty() && !cert_path[0].matches_dns_name(hostname)) {
      cert_status[0].insert(Certificate_Status_Code::CERT_NAME_NOMATCH);
   }
 
   if(!cert_path[0].allowed_usage(usage)) {
      if(usage == Usage_Type::OCSP_RESPONDER) {
         cert_status[0].insert(Certificate_Status_Code::OCSP_RESPONSE_MISSING_KEYUSAGE);
      }
      cert_status[0].insert(Certificate_Status_Code::INVALID_USAGE);
   }
 
   if(cert_path[0].has_constraints(Key_Constraints::KeyCertSign) && cert_path[0].is_CA_cert() == false) {
      /*
      "If the keyCertSign bit is asserted, then the cA bit in the
      basic constraints extension (Section 4.2.1.9) MUST also be
      asserted." - RFC 5280
 
      We don't bother doing this check on the rest of the path since they
      must have the cA bit asserted or the validation will fail anyway.
      */
      cert_status[0].insert(Certificate_Status_Code::INVALID_USAGE);
   }
 
   for(size_t i = 0; i != cert_path.size(); ++i) {
      std::set<Certificate_Status_Code>& status = cert_status.at(i);
 
      const bool at_self_signed_root = (i == cert_path.size() - 1);
 
      const X509_Certificate& subject = cert_path[i];
      const X509_Certificate& issuer = cert_path[at_self_signed_root ? (i) : (i + 1)];
 
      if(at_self_signed_root && (issuer.is_self_signed() == false)) {
         status.insert(Certificate_Status_Code::CHAIN_LACKS_TRUST_ROOT);
      }
 
      // This should never happen; it indicates a bug in path building
      if(subject.issuer_dn() != issuer.subject_dn()) {
         status.insert(Certificate_Status_Code::CHAIN_NAME_MISMATCH);
      }
 
      // Check the serial number
      if(subject.is_serial_negative()) {
         status.insert(Certificate_Status_Code::CERT_SERIAL_NEGATIVE);
      }
 
      // Check the subject's DN components' length
 
      for(const auto& dn_pair : subject.subject_dn().dn_info()) {
         const size_t dn_ub = X509_DN::lookup_ub(dn_pair.first);
         // dn_pair = <OID,str>
         if(dn_ub > 0 && dn_pair.second.size() > dn_ub) {
            status.insert(Certificate_Status_Code::DN_TOO_LONG);
         }
      }
 
      // Only warn, if trusted root is not in time range if configured this way
      const bool is_trusted_root_and_time_ignored =
         restrictions.ignore_trusted_root_time_range() && at_self_signed_root;
      // Check all certs for valid time range
      if(validation_time < subject.not_before()) {
         if(is_trusted_root_and_time_ignored) {
            status.insert(Certificate_Status_Code::TRUSTED_CERT_NOT_YET_VALID);  // only warn
         } else {
            status.insert(Certificate_Status_Code::CERT_NOT_YET_VALID);
         }
      }
 
      if(validation_time > subject.not_after()) {
         if(is_trusted_root_and_time_ignored) {
            status.insert(Certificate_Status_Code::TRUSTED_CERT_HAS_EXPIRED);  // only warn
         } else {
            status.insert(Certificate_Status_Code::CERT_HAS_EXPIRED);
         }
      }
 
      // Check issuer constraints
      if(!issuer.is_CA_cert() && !self_signed_ee_cert) {
         status.insert(Certificate_Status_Code::CA_CERT_NOT_FOR_CERT_ISSUER);
      }
 
      // Check cert extensions
 
      if(subject.x509_version() == 1) {
         if(subject.v2_issuer_key_id().empty() == false || subject.v2_subject_key_id().empty() == false) {
            status.insert(Certificate_Status_Code::V2_IDENTIFIERS_IN_V1_CERT);
         }
      }
 
      const Extensions& extensions = subject.v3_extensions();
      const auto& extensions_vec = extensions.extensions();
      if(subject.x509_version() < 3 && !extensions_vec.empty()) {
         status.insert(Certificate_Status_Code::EXT_IN_V1_V2_CERT);
      }
      for(const auto& extension : extensions_vec) {
         extension.first->validate(subject, issuer, cert_path, cert_status, i);
      }
      if(extensions_vec.size() != extensions.get_extension_oids().size()) {
         status.insert(Certificate_Status_Code::DUPLICATE_CERT_EXTENSION);
      }
   }
 
   // path len check
   size_t max_path_length = cert_path.size();
   for(size_t i = cert_path.size() - 1; i > 0; --i) {
      std::set<Certificate_Status_Code>& status = cert_status.at(i);
      const X509_Certificate& subject = cert_path[i];
 
      /*
      * If the certificate was not self-issued, verify that max_path_length is
      * greater than zero and decrement max_path_length by 1.
      */
      if(subject.subject_dn() != subject.issuer_dn()) {
         if(max_path_length > 0) {
            max_path_length -= 1;
         } else {
            status.insert(Certificate_Status_Code::CERT_CHAIN_TOO_LONG);
         }
      }
 
      /*
      * If pathLenConstraint is present in the certificate and is less than max_path_length,
      * set max_path_length to the value of pathLenConstraint.
      */
      if(auto path_len_constraint = subject.path_length_constraint()) {
         max_path_length = std::min(max_path_length, *path_len_constraint);
      }
   }
 
   return cert_status;
}

Referenced by Botan::x509_path_validate().

◆ check_crl() [1/2]

CertificatePathStatusCodes Botan::PKIX::check_crl	(	const std::vector< X509_Certificate > &	cert_path,
		const std::vector< Certificate_Store * > &	certstores,
		std::chrono::system_clock::time_point	ref_time )

Check CRLs for revocation information

Parameters

cert_path	path already validated by check_chain
certstores	a list of certificate stores to query for the CRL
ref_time	whatever time you want to perform the validation against (normally current system clock)

Returns: revocation status

Definition at line 429 of file x509path.cpp.

                                                                                     {
   if(cert_path.empty()) {
      throw Invalid_Argument("PKIX::check_crl cert_path empty");
   }
 
   if(certstores.empty()) {
      throw Invalid_Argument("PKIX::check_crl certstores empty");
   }
 
   std::vector<std::optional<X509_CRL>> crls(cert_path.size());
 
   for(size_t i = 0; i != cert_path.size(); ++i) {
      for(auto* certstore : certstores) {
         crls[i] = certstore->find_crl_for(cert_path[i]);
         if(crls[i]) {
            break;
         }
      }
   }
 
   return PKIX::check_crl(cert_path, crls, ref_time);
}

References check_crl().

◆ check_crl() [2/2]

CertificatePathStatusCodes Botan::PKIX::check_crl	(	const std::vector< X509_Certificate > &	cert_path,
		const std::vector< std::optional< X509_CRL > > &	crls,
		std::chrono::system_clock::time_point	ref_time )

Check CRLs for revocation information

Parameters

cert_path	path already validated by check_chain
crls	the list of CRLs to check, it is assumed that crls[i] (if not null) is the associated CRL for the subject in cert_path[i].
ref_time	whatever time you want to perform the validation against (normally current system clock)

Returns: revocation status

Definition at line 358 of file x509path.cpp.

                                                                                     {
   if(cert_path.empty()) {
      throw Invalid_Argument("PKIX::check_crl cert_path empty");
   }
 
   CertificatePathStatusCodes cert_status(cert_path.size());
   const X509_Time validation_time(ref_time);
 
   for(size_t i = 0; i != cert_path.size() - 1; ++i) {
      std::set<Certificate_Status_Code>& status = cert_status.at(i);
 
      if(i < crls.size() && crls[i].has_value()) {
         const X509_Certificate& subject = cert_path.at(i);
         const X509_Certificate& ca = cert_path.at(i + 1);
 
         if(!ca.allowed_usage(Key_Constraints::CrlSign)) {
            status.insert(Certificate_Status_Code::CA_CERT_NOT_FOR_CRL_ISSUER);
         }
 
         if(validation_time < crls[i]->this_update()) {
            status.insert(Certificate_Status_Code::CRL_NOT_YET_VALID);
         }
 
         if(crls[i]->next_update().time_is_set() && validation_time > crls[i]->next_update()) {
            status.insert(Certificate_Status_Code::CRL_HAS_EXPIRED);
         }
 
         auto ca_key = ca.subject_public_key();
         if(crls[i]->check_signature(*ca_key) == false) {
            status.insert(Certificate_Status_Code::CRL_BAD_SIGNATURE);
         }
 
         status.insert(Certificate_Status_Code::VALID_CRL_CHECKED);
 
         if(crls[i]->is_revoked(subject)) {
            status.insert(Certificate_Status_Code::CERT_IS_REVOKED);
         }
 
         const auto dp = subject.crl_distribution_points();
         if(!dp.empty()) {
            const auto crl_idp = crls[i]->crl_issuing_distribution_point();
 
            if(std::find(dp.begin(), dp.end(), crl_idp) == dp.end()) {
               status.insert(Certificate_Status_Code::NO_MATCHING_CRLDP);
            }
         }
 
         for(const auto& extension : crls[i]->extensions().extensions()) {
            // XXX this is wrong - the OID might be defined but the extension not full parsed
            // for example see #1652
 
            // is the extension critical and unknown?
            if(extension.second && !extension.first->oid_of().registered_oid()) {
               /* NIST Certificate Path Valiadation Testing document: "When an implementation does not recognize a critical extension in the
                * crlExtensions field, it shall assume that identified certificates have been revoked and are no longer valid"
                */
               status.insert(Certificate_Status_Code::CERT_IS_REVOKED);
            }
         }
      }
   }
 
   while(!cert_status.empty() && cert_status.back().empty()) {
      cert_status.pop_back();
   }
 
   return cert_status;
}

References Botan::X509_Certificate::allowed_usage(), Botan::CA_CERT_NOT_FOR_CRL_ISSUER, Botan::CERT_IS_REVOKED, Botan::CRL_BAD_SIGNATURE, Botan::X509_Certificate::crl_distribution_points(), Botan::CRL_HAS_EXPIRED, Botan::CRL_NOT_YET_VALID, Botan::Key_Constraints::CrlSign, Botan::NO_MATCHING_CRLDP, Botan::X509_Certificate::subject_public_key(), and Botan::VALID_CRL_CHECKED.

Referenced by check_crl(), and Botan::x509_path_validate().

◆ check_ocsp()

CertificatePathStatusCodes Botan::PKIX::check_ocsp	(	const std::vector< X509_Certificate > &	cert_path,
		const std::vector< std::optional< OCSP::Response > > &	ocsp_responses,
		const std::vector< Certificate_Store * > &	certstores,
		std::chrono::system_clock::time_point	ref_time,
		const Path_Validation_Restrictions &	restrictions )

Check OCSP responses for revocation information

Parameters

cert_path	path already validated by check_chain
ocsp_responses	the OCSP responses to consider
certstores	trusted roots
ref_time	whatever time you want to perform the validation against (normally current system clock)
restrictions	the relevant path validation restrictions object

Returns: revocation status

Definition at line 303 of file x509path.cpp.

                                                                                              {
   if(cert_path.empty()) {
      throw Invalid_Argument("PKIX::check_ocsp cert_path empty");
   }
 
   CertificatePathStatusCodes cert_status(cert_path.size() - 1);
 
   for(size_t i = 0; i != cert_path.size() - 1; ++i) {
      std::set<Certificate_Status_Code>& status = cert_status.at(i);
 
      const X509_Certificate& subject = cert_path.at(i);
      const X509_Certificate& ca = cert_path.at(i + 1);
 
      if(i < ocsp_responses.size() && (ocsp_responses.at(i) != std::nullopt) &&
         (ocsp_responses.at(i)->status() == OCSP::Response_Status_Code::Successful)) {
         try {
            const auto& ocsp_response = ocsp_responses.at(i);
 
            if(auto dummy_status = ocsp_response->dummy_status()) {
               // handle softfail conditions
               status.insert(dummy_status.value());
            } else if(auto signing_cert =
                         ocsp_response->find_signing_certificate(ca, restrictions.trusted_ocsp_responders());
                      !signing_cert) {
               status.insert(Certificate_Status_Code::OCSP_ISSUER_NOT_FOUND);
            } else if(auto ocsp_signing_cert_status =
                         verify_ocsp_signing_cert(signing_cert.value(),
                                                  ca,
                                                  concat(ocsp_response->certificates(), cert_path),
                                                  certstores,
                                                  ref_time,
                                                  restrictions);
                      ocsp_signing_cert_status > Certificate_Status_Code::FIRST_ERROR_STATUS) {
               status.insert(ocsp_signing_cert_status);
               status.insert(Certificate_Status_Code::OCSP_ISSUER_NOT_TRUSTED);
            } else {
               status.insert(ocsp_response->status_for(ca, subject, ref_time, restrictions.max_ocsp_age()));
            }
         } catch(Exception&) {
            status.insert(Certificate_Status_Code::OCSP_RESPONSE_INVALID);
         }
      }
   }
 
   while(!cert_status.empty() && cert_status.back().empty()) {
      cert_status.pop_back();
   }
 
   return cert_status;
}

References Botan::concat(), Botan::FIRST_ERROR_STATUS, Botan::Path_Validation_Restrictions::max_ocsp_age(), Botan::OCSP_ISSUER_NOT_FOUND, Botan::OCSP_ISSUER_NOT_TRUSTED, Botan::OCSP_RESPONSE_INVALID, Botan::OCSP::Successful, and Botan::Path_Validation_Restrictions::trusted_ocsp_responders().

Referenced by Botan::x509_path_validate().

◆ merge_revocation_status()

void Botan::PKIX::merge_revocation_status	(	CertificatePathStatusCodes &	chain_status,
		const CertificatePathStatusCodes &	crl_status,
		const CertificatePathStatusCodes &	ocsp_status,
		const Path_Validation_Restrictions &	restrictions )

Merge the results from CRL and/or OCSP checks into chain_status

Parameters

chain_status	the certificate status
crl_status	results from check_crl
ocsp_status	results from check_ocsp
restrictions	the relevant path validation restrictions object

Definition at line 816 of file x509path.cpp.

                                                                                     {
   if(chain_status.empty()) {
      throw Invalid_Argument("PKIX::merge_revocation_status chain_status was empty");
   }
 
   for(size_t i = 0; i != chain_status.size() - 1; ++i) {
      bool had_crl = false;
      bool had_ocsp = false;
 
      if(i < crl_status.size() && !crl_status[i].empty()) {
         for(auto&& code : crl_status[i]) {
            if(code == Certificate_Status_Code::VALID_CRL_CHECKED) {
               had_crl = true;
            }
            chain_status[i].insert(code);
         }
      }
 
      if(i < ocsp_status.size() && !ocsp_status[i].empty()) {
         for(auto&& code : ocsp_status[i]) {
            // NO_REVOCATION_URL and OCSP_SERVER_NOT_AVAILABLE are softfail
            if(code == Certificate_Status_Code::OCSP_RESPONSE_GOOD ||
               code == Certificate_Status_Code::OCSP_NO_REVOCATION_URL ||
               code == Certificate_Status_Code::OCSP_SERVER_NOT_AVAILABLE) {
               had_ocsp = true;
            }
 
            chain_status[i].insert(code);
         }
      }
 
      if(had_crl == false && had_ocsp == false) {
         if((restrictions.require_revocation_information() && i == 0) ||
            (restrictions.ocsp_all_intermediates() && i > 0)) {
            chain_status[i].insert(Certificate_Status_Code::NO_REVOCATION_DATA);
         }
      }
   }
}

References Botan::NO_REVOCATION_DATA, Botan::Path_Validation_Restrictions::ocsp_all_intermediates(), Botan::OCSP_NO_REVOCATION_URL, Botan::OCSP_RESPONSE_GOOD, Botan::OCSP_SERVER_NOT_AVAILABLE, Botan::Path_Validation_Restrictions::require_revocation_information(), and Botan::VALID_CRL_CHECKED.

Referenced by Botan::x509_path_validate().

◆ overall_status()

Certificate_Status_Code Botan::PKIX::overall_status ( const CertificatePathStatusCodes & cert_status )

Find overall status (OK, error) of a validation

Parameters

cert_status result of merge_revocation_status or check_chain

Definition at line 859 of file x509path.cpp.

                                                                                          {
   if(cert_status.empty()) {
      throw Invalid_Argument("PKIX::overall_status empty cert status");
   }
 
   Certificate_Status_Code overall_status = Certificate_Status_Code::OK;
 
   // take the "worst" error as overall
   for(const std::set<Certificate_Status_Code>& s : cert_status) {
      if(!s.empty()) {
         auto worst = *s.rbegin();
         // Leave informative OCSP/CRL confirmations on cert-level status only
         if(worst >= Certificate_Status_Code::FIRST_ERROR_STATUS && worst > overall_status) {
            overall_status = worst;
         }
      }
   }
   return overall_status;
}

References Botan::FIRST_ERROR_STATUS, Botan::OK, and overall_status().

Referenced by overall_status().

Functions

Detailed Description

Function Documentation

◆ build_all_certificate_paths()

◆ build_certificate_path()

◆ check_chain()

◆ check_crl() [1/2]

◆ check_crl() [2/2]

◆ check_ocsp()

◆ merge_revocation_status()

◆ overall_status()