1 // Copyright 2017 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef NET_CERT_INTERNAL_REVOCATION_CHECKER_H_ 6 #define NET_CERT_INTERNAL_REVOCATION_CHECKER_H_ 7 8 #include <string_view> 9 10 #include "base/time/time.h" 11 #include "net/base/net_export.h" 12 #include "net/cert/crl_set.h" 13 #include "third_party/boringssl/src/pki/cert_errors.h" 14 #include "third_party/boringssl/src/pki/ocsp.h" 15 #include "third_party/boringssl/src/pki/parsed_certificate.h" 16 17 namespace net { 18 19 class CertNetFetcher; 20 21 // Baseline Requirements 1.6.5, section 4.9.7: 22 // For the status of Subscriber Certificates: If the CA publishes a CRL, 23 // then the CA SHALL update and reissue CRLs at least once every seven 24 // days, and the value of the nextUpdate field MUST NOT be more than ten 25 // days beyond the value of the thisUpdate field. 26 // 27 // Baseline Requirements 1.6.5, section 4.9.10: 28 // For the status of Subscriber Certificates: The CA SHALL update 29 // information provided via an Online Certificate Status Protocol at least 30 // every four days. OCSP responses from this service MUST have a maximum 31 // expiration time of ten days. 32 // 33 // Use 7 days as the max allowable leaf revocation status age, which is 34 // sufficient for both CRL and OCSP, and which aligns with Microsoft policies. 35 constexpr base::TimeDelta kMaxRevocationLeafUpdateAge = base::Days(7); 36 37 // Baseline Requirements 1.6.5, section 4.9.7: 38 // For the status of Subordinate CA Certificates: The CA SHALL update and 39 // reissue CRLs at least (i) once every twelve months and (ii) within 24 40 // hours after revoking a Subordinate CA Certificate, and the value of the 41 // nextUpdate field MUST NOT be more than twelve months beyond the value of 42 // the thisUpdate field. 43 // 44 // Baseline Requirements 1.6.5, section 4.9.10: 45 // For the status of Subordinate CA Certificates: The CA SHALL update 46 // information provided via an Online Certificate Status Protocol at least 47 // (i) every twelve months and (ii) within 24 hours after revoking a 48 // Subordinate CA Certificate. 49 // 50 // Use 366 days to allow for leap years, though it is overly permissive in 51 // other years. 52 constexpr base::TimeDelta kMaxRevocationIntermediateUpdateAge = base::Days(366); 53 54 // RevocationPolicy describes how revocation should be carried out for a 55 // particular chain. 56 // Callers should not rely on the default-initialized value, but should fully 57 // specify all the parameters. The default values specify a strict revocation 58 // checking mode, in case users fail to fully set the parameters. 59 struct NET_EXPORT_PRIVATE RevocationPolicy { 60 // If |check_revocation| is true, then revocation checking is mandatory. This 61 // means that every certificate in the chain (excluding trust anchors) must 62 // have valid (unexpired) revocation information proving it to be unrevoked. 63 // 64 // The mechanisms used for checking revocation may include stapled OCSP, 65 // cached OCSP, online OCSP, cached CRL, online CRL. 66 // 67 // The other properties of RevocationPolicy place further constraints on how 68 // revocation checking may proceed. 69 bool check_revocation = true; 70 71 // If |networking_allowed| is true then revocation checking is allowed to 72 // issue network requests in order to fetch fresh OCSP/CRL. Otherwise 73 // networking is not permitted in the course of revocation checking. 74 bool networking_allowed = false; 75 76 // If |crl_allowed| is true then CRLs will be checked as a fallback when an 77 // OCSP URL is not present or OCSP results are indeterminate. 78 bool crl_allowed = true; 79 80 // If set to true, considers certificates lacking URLs for OCSP/CRL to be 81 // unrevoked. Otherwise will fail for certificates lacking revocation 82 // mechanisms. 83 bool allow_missing_info = false; 84 85 // If set to true, other failure to perform revocation checks (e.g. due to a 86 // network level failure, OCSP response error status, failure parsing or 87 // evaluating the OCSP/CRL response, etc) is considered equivalent to a 88 // successful revocation check. 89 bool allow_unable_to_check = false; 90 91 // If set to true, enforce requirements specified in the Baseline 92 // Requirements such as maximum age of revocation responses. 93 bool enforce_baseline_requirements = true; 94 }; 95 96 // Checks the revocation status of |certs| according to |policy|, and adds 97 // any failures to |errors|. On failure errors are added to |errors|. On success 98 // no errors are added. 99 // 100 // |deadline|, if not null, will limit the overall amount of time spent doing 101 // online revocation checks. If |base::TimeTicks::Now()| exceeds |deadline|, no 102 // more revocation checks will be attempted. Note that this is not a hard 103 // limit, the deadline may be exceeded by the individual request timetout of a 104 // single CertNetFetcher. 105 // 106 // |certs| must be a successfully validated chain according to RFC 5280 section 107 // 6.1, in order from leaf to trust anchor. 108 // 109 // |net_fetcher| may be null, however this may lead to failed revocation checks 110 // depending on |policy|. 111 // 112 // |stapled_ocsp_verify_result|, if non-null, will be filled with the result of 113 // checking the leaf certificate against |stapled_leaf_ocsp_response|. 114 NET_EXPORT_PRIVATE void CheckValidatedChainRevocation( 115 const bssl::ParsedCertificateList& certs, 116 const RevocationPolicy& policy, 117 base::TimeTicks deadline, 118 std::string_view stapled_leaf_ocsp_response, 119 CertNetFetcher* net_fetcher, 120 bssl::CertPathErrors* errors, 121 bssl::OCSPVerifyResult* stapled_ocsp_verify_result); 122 123 // Checks the revocation status of a certificate chain using the CRLSet and adds 124 // revocation errors to |errors|. 125 // 126 // Returns the revocation status of the leaf certificate: 127 // 128 // * CRLSet::REVOKED if any certificate in the chain is revoked. Also adds a 129 // corresponding error for the certificate in |errors|. 130 // 131 // * CRLSet::GOOD if the leaf certificate is covered as GOOD by the CRLSet, and 132 // none of the intermediates were revoked according to the CRLSet. 133 // 134 // * CRLSet::UNKNOWN if none of the certificates are known to be revoked, and 135 // the revocation status of leaf certificate was UNKNOWN by the CRLSet. 136 NET_EXPORT_PRIVATE CRLSet::Result CheckChainRevocationUsingCRLSet( 137 const CRLSet* crl_set, 138 const bssl::ParsedCertificateList& certs, 139 bssl::CertPathErrors* errors); 140 141 } // namespace net 142 143 #endif // NET_CERT_INTERNAL_REVOCATION_CHECKER_H_ 144