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 inline 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 inline constexpr base::TimeDelta kMaxRevocationIntermediateUpdateAge = 53 base::Days(366); 54 55 // RevocationPolicy describes how revocation should be carried out for a 56 // particular chain. 57 // Callers should not rely on the default-initialized value, but should fully 58 // specify all the parameters. The default values specify a strict revocation 59 // checking mode, in case users fail to fully set the parameters. 60 struct NET_EXPORT_PRIVATE RevocationPolicy { 61 // If |check_revocation| is true, then revocation checking is mandatory. This 62 // means that every certificate in the chain (excluding trust anchors) must 63 // have valid (unexpired) revocation information proving it to be unrevoked. 64 // 65 // The mechanisms used for checking revocation may include stapled OCSP, 66 // cached OCSP, online OCSP, cached CRL, online CRL. 67 // 68 // The other properties of RevocationPolicy place further constraints on how 69 // revocation checking may proceed. 70 bool check_revocation = true; 71 72 // If |networking_allowed| is true then revocation checking is allowed to 73 // issue network requests in order to fetch fresh OCSP/CRL. Otherwise 74 // networking is not permitted in the course of revocation checking. 75 bool networking_allowed = false; 76 77 // If |crl_allowed| is true then CRLs will be checked as a fallback when an 78 // OCSP URL is not present or OCSP results are indeterminate. 79 bool crl_allowed = true; 80 81 // If set to true, considers certificates lacking URLs for OCSP/CRL to be 82 // unrevoked. Otherwise will fail for certificates lacking revocation 83 // mechanisms. 84 bool allow_missing_info = false; 85 86 // If set to true, other failure to perform revocation checks (e.g. due to a 87 // network level failure, OCSP response error status, failure parsing or 88 // evaluating the OCSP/CRL response, etc) is considered equivalent to a 89 // successful revocation check. 90 bool allow_unable_to_check = false; 91 92 // If set to true, enforce requirements specified in the Baseline 93 // Requirements such as maximum age of revocation responses. 94 bool enforce_baseline_requirements = true; 95 }; 96 97 // Checks the revocation status of |certs| according to |policy|, and adds 98 // any failures to |errors|. On failure errors are added to |errors|. On success 99 // no errors are added. 100 // 101 // |deadline|, if not null, will limit the overall amount of time spent doing 102 // online revocation checks. If |base::TimeTicks::Now()| exceeds |deadline|, no 103 // more revocation checks will be attempted. Note that this is not a hard 104 // limit, the deadline may be exceeded by the individual request timetout of a 105 // single CertNetFetcher. 106 // 107 // |certs| must be a successfully validated chain according to RFC 5280 section 108 // 6.1, in order from leaf to trust anchor. 109 // 110 // |net_fetcher| may be null, however this may lead to failed revocation checks 111 // depending on |policy|. 112 // 113 // |stapled_ocsp_verify_result|, if non-null, will be filled with the result of 114 // checking the leaf certificate against |stapled_leaf_ocsp_response|. 115 NET_EXPORT_PRIVATE void CheckValidatedChainRevocation( 116 const bssl::ParsedCertificateList& certs, 117 const RevocationPolicy& policy, 118 base::TimeTicks deadline, 119 std::string_view stapled_leaf_ocsp_response, 120 base::Time current_time, 121 CertNetFetcher* net_fetcher, 122 bssl::CertPathErrors* errors, 123 bssl::OCSPVerifyResult* stapled_ocsp_verify_result); 124 125 // Checks the revocation status of a certificate chain using the CRLSet and adds 126 // revocation errors to |errors|. 127 // 128 // Returns the revocation status of the leaf certificate: 129 // 130 // * CRLSet::REVOKED if any certificate in the chain is revoked. Also adds a 131 // corresponding error for the certificate in |errors|. 132 // 133 // * CRLSet::GOOD if the leaf certificate is covered as GOOD by the CRLSet, and 134 // none of the intermediates were revoked according to the CRLSet. 135 // 136 // * CRLSet::UNKNOWN if none of the certificates are known to be revoked, and 137 // the revocation status of leaf certificate was UNKNOWN by the CRLSet. 138 NET_EXPORT_PRIVATE CRLSet::Result CheckChainRevocationUsingCRLSet( 139 const CRLSet* crl_set, 140 const bssl::ParsedCertificateList& certs, 141 bssl::CertPathErrors* errors); 142 143 } // namespace net 144 145 #endif // NET_CERT_INTERNAL_REVOCATION_CHECKER_H_ 146