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