Functions
Certificate_Status_Code	build_all_certificate_paths (std::vector< std::vector< X509_Certificate > > &cert_paths, const std::vector< Certificate_Store * > &trusted_certstores, const 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 X509_Certificate &	end_entity,
		const std::vector< X509_Certificate > &	end_entity_extra )

Create all certificate paths by identifying all possible routes from the end-entity certificate to any certificate in the certificate store list. Paths may also end in intermediate or leaf certificates found in the certificate stores.

WARNING: The validity (e.g. signatures or constraints) of the output path IS NOT checked.

Parameters

cert_paths	output parameter to be filled with all discovered certificate paths
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)

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 680 of file x509path.cpp.

                                                                                                               {
   if(!cert_paths_out.empty()) {
      throw Invalid_Argument("PKIX::build_all_certificate_paths: cert_paths_out must be empty");
   }
   if(std::ranges::any_of(trusted_certstores, [](auto* ptr) { return ptr == nullptr; })) {
      throw Invalid_Argument("certificate store list must not contain nullptr");
   }
 
   auto cert_in_any_trusted_store = [&](const X509_Certificate& cert) {
      return std::ranges::any_of(trusted_certstores,
                                 [&](const Certificate_Store* store) { return store->certificate_known(cert); });
   };
 
   /*
    * Pile up error messages
    */
   std::vector<Certificate_Status_Code> stats;
 
   Certificate_Store_In_Memory ee_extras;
   for(const auto& cert : end_entity_extra) {
      if(!cert_in_any_trusted_store(cert)) {
         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;
 
   std::vector<cert_maybe_trusted> stack = {{end_entity, cert_in_any_trusted_store(end_entity)}};
 
   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();
         const 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;
         }
 
         // A valid path has been discovered. It includes endpoints that may end
         // with either a self-signed or a non-self-signed certificate. For
         // certificates that are not self-signed, additional paths could
         // potentially extend from the current one.
         if(trusted) {
            cert_paths_out.push_back(path_so_far);
            cert_paths_out.back().push_back(*last);
         } else if(last->is_self_signed()) {
            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(const 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
         const 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::certificate_known(), Botan::Certificate_Store_In_Memory::find_all_certs(), and Botan::OK.

Referenced by build_certificate_path(), and 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 )

Same as build_all_certificate_paths but only outputs a single path. If there are paths ending in self-signed certificates, these are prioritized over paths ending in intermediate or leaf certificates of the certificate store.

WARNING: The validity (e.g. signatures or constraints) of the output path IS NOT checked.

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 629 of file x509path.cpp.

                                                                                                          {
   std::vector<std::vector<X509_Certificate>> all_cert_paths;
   const auto build_all_paths_res =
      build_all_certificate_paths(all_cert_paths, trusted_certstores, end_entity, end_entity_extra);
 
   if(build_all_paths_res != Certificate_Status_Code::OK) {
      return build_all_paths_res;
   }
   BOTAN_ASSERT_NOMSG(!all_cert_paths.empty());
 
   // Paths ending in self-signed certificates are preferred.
   const auto first_with_self_signed_anchor = std::ranges::find_if(all_cert_paths, [&](const auto& left_path) {
      BOTAN_ASSERT_NOMSG(!left_path.empty());
      return left_path.back().is_self_signed();
   });
   if(first_with_self_signed_anchor != all_cert_paths.end()) {
      cert_path.insert(cert_path.end(), first_with_self_signed_anchor->begin(), first_with_self_signed_anchor->end());
   } else {
      cert_path.insert(cert_path.end(), all_cert_paths.front().begin(), all_cert_paths.front().end());
   }
   return Certificate_Status_Code::OK;
}

References BOTAN_ASSERT_NOMSG, build_all_certificate_paths(), 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 33 of file x509path.cpp.

                                                                                               {
   if(cert_path.empty()) {
      throw Invalid_Argument("PKIX::check_chain cert_path empty");
   }
 
   const bool is_end_entity_trust_anchor = (cert_path.size() == 1);
 
   const 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_trust_anchor = (i == cert_path.size() - 1);
 
      const X509_Certificate& subject = cert_path[i];
 
      // If using intermediate CAs as trust anchors, the signature of the trust
      // anchor cannot be verified since the issuer is not part of the
      // certificate chain
      if(!restrictions.require_self_signed_trust_anchors() && at_trust_anchor && !subject.is_self_signed()) {
         continue;
      }
 
      const X509_Certificate& issuer = cert_path[at_trust_anchor ? (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_trust_anchor) {
                  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_trust_anchor = (i == cert_path.size() - 1);
 
      const X509_Certificate& subject = cert_path[i];
      const auto issuer = [&]() -> std::optional<X509_Certificate> {
         if(!at_trust_anchor) {
            return cert_path[i + 1];
         } else if(subject.is_self_signed()) {
            return cert_path[i];
         } else {
            return {};  // Non self-signed trust anchors have no checkable issuers.
         }
      }();
 
      if(restrictions.require_self_signed_trust_anchors() && !issuer.has_value()) {
         status.insert(Certificate_Status_Code::CHAIN_LACKS_TRUST_ROOT);
      }
 
      // This should never happen; it indicates a bug in path building
      if(issuer.has_value() && 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);
         }
      }
 
      // If so configured, allow trust anchors outside the validity period with
      // a warning rather than a hard error
      const bool enforce_validity_period = !at_trust_anchor || !restrictions.ignore_trusted_root_time_range();
      // Check all certs for valid time range
      if(validation_time < subject.not_before()) {
         if(enforce_validity_period) {
            status.insert(Certificate_Status_Code::CERT_NOT_YET_VALID);
         } else {
            status.insert(Certificate_Status_Code::TRUSTED_CERT_NOT_YET_VALID);  // only warn
         }
      }
 
      if(validation_time > subject.not_after()) {
         if(enforce_validity_period) {
            status.insert(Certificate_Status_Code::CERT_HAS_EXPIRED);
         } else {
            status.insert(Certificate_Status_Code::TRUSTED_CERT_HAS_EXPIRED);  // only warn
         }
      }
 
      // Check issuer constraints
      if(issuer.has_value() && !issuer->is_CA_cert() && !is_end_entity_trust_anchor) {
         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 461 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 390 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 357 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) {
      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).has_value() &&
         ocsp_responses.at(i)->status() == OCSP::Response_Status_Code::Successful) {
         try {
            cert_status.at(i) = evaluate_ocsp_response(
               ocsp_responses.at(i).value(), subject, ca, cert_path, certstores, ref_time, restrictions);
         } catch(Exception&) {
            cert_status.at(i).insert(Certificate_Status_Code::OCSP_RESPONSE_INVALID);
         }
      }
   }
 
   while(!cert_status.empty() && cert_status.back().empty()) {
      cert_status.pop_back();
   }
 
   return cert_status;
}

References Botan::OCSP_RESPONSE_INVALID, and Botan::OCSP::Successful.

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 805 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 848 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()