1 // Copyright 2012 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_CERT_VERIFIER_H_ 6 #define NET_CERT_CERT_VERIFIER_H_ 7 8 #include <memory> 9 #include <string> 10 #include <string_view> 11 #include <vector> 12 13 #include "base/memory/scoped_refptr.h" 14 #include "base/observer_list_types.h" 15 #include "net/base/completion_once_callback.h" 16 #include "net/base/hash_value.h" 17 #include "net/base/net_export.h" 18 #include "net/cert/cert_net_fetcher.h" 19 #include "net/cert/cert_verify_proc.h" 20 #include "net/cert/x509_certificate.h" 21 22 namespace net { 23 24 class CertVerifyResult; 25 class CertVerifierWithUpdatableProc; 26 class NetLogWithSource; 27 28 // CertVerifier represents a service for verifying certificates. 29 // 30 // CertVerifiers can handle multiple requests at a time. 31 class NET_EXPORT CertVerifier { 32 public: 33 class NET_EXPORT Observer : public base::CheckedObserver { 34 public: 35 // Called when the certificate verifier changes internal configuration. 36 // Observers can use this method to invalidate caches that incorporate 37 // previous trust decisions. 38 // 39 // This method will not be called on `CertVerifier::SetConfig`. It is 40 // assumed that callers will know to clear their caches when calling the 41 // function. https://crbug.com/1427326 tracks migrating `SetConfig` to this 42 // mechanism. 43 virtual void OnCertVerifierChanged() = 0; 44 }; 45 46 struct NET_EXPORT Config { 47 Config(); 48 Config(const Config&); 49 Config(Config&&); 50 ~Config(); 51 Config& operator=(const Config&); 52 Config& operator=(Config&&); 53 54 // Enable online revocation checking via CRLs and OCSP for the certificate 55 // chain. Note that revocation checking is soft-fail. 56 bool enable_rev_checking = false; 57 58 // Enable online revocation checking via CRLs and OCSP for the certificate 59 // chain if the constructed chain terminates in a locally-installed, 60 // non-public trust anchor. A revocation error, such as a failure to 61 // obtain fresh revocation information, is treated as a hard failure. 62 bool require_rev_checking_local_anchors = false; 63 64 // Enable support for SHA-1 signatures if the constructed chain terminates 65 // in a locally-installed, non-public trust anchor. 66 bool enable_sha1_local_anchors = false; 67 68 // Disable enforcement of the policies described at 69 // https://security.googleblog.com/2017/09/chromes-plan-to-distrust-symantec.html 70 bool disable_symantec_enforcement = false; 71 }; 72 73 class Request { 74 public: 75 Request() = default; 76 77 Request(const Request&) = delete; 78 Request& operator=(const Request&) = delete; 79 80 // Destruction of the Request cancels it. 81 virtual ~Request() = default; 82 }; 83 84 enum VerifyFlags { 85 // If set, actively overrides the current CertVerifier::Config to disable 86 // dependent network fetches. This can be used to avoid triggering 87 // re-entrancy in the network stack. For example, fetching a PAC script 88 // over HTTPS may cause AIA, OCSP, or CRL fetches to block on retrieving 89 // the PAC script, while the PAC script fetch is waiting for those 90 // dependent fetches, creating a deadlock. When set, this flag prevents 91 // those fetches from being started (best effort). 92 // Note that cached information may still be used, if it can be accessed 93 // without accessing the network. 94 VERIFY_DISABLE_NETWORK_FETCHES = 1 << 0, 95 96 VERIFY_FLAGS_LAST = VERIFY_DISABLE_NETWORK_FETCHES 97 }; 98 99 // Parameters to verify |certificate| against the supplied 100 // |hostname| as an SSL server. 101 // 102 // |hostname| should be a canonicalized hostname (in A-Label form) or IP 103 // address in string form, following the rules of a URL host portion. In 104 // the case of |hostname| being a domain name, it may contain a trailing 105 // dot (e.g. "example.com."), as used to signal to DNS not to perform 106 // suffix search, and it will safely be ignored. If |hostname| is an IPv6 107 // address, it MUST be in URL form - that is, surrounded in square 108 // brackets, such as "[::1]". 109 // 110 // |flags| is a bitwise OR of VerifyFlags. 111 // 112 // |ocsp_response| is optional, but if non-empty, should contain an OCSP 113 // response obtained via OCSP stapling. It may be ignored by the 114 // CertVerifier. 115 // 116 // |sct_list| is optional, but if non-empty, should contain a 117 // SignedCertificateTimestampList from the TLS extension as described in 118 // RFC6962 section 3.3.1. It may be ignored by the CertVerifier. 119 class NET_EXPORT RequestParams { 120 public: 121 RequestParams(); 122 RequestParams(scoped_refptr<X509Certificate> certificate, 123 std::string_view hostname, 124 int flags, 125 std::string_view ocsp_response, 126 std::string_view sct_list); 127 RequestParams(const RequestParams& other); 128 ~RequestParams(); 129 certificate()130 const scoped_refptr<X509Certificate>& certificate() const { 131 return certificate_; 132 } hostname()133 const std::string& hostname() const { return hostname_; } flags()134 int flags() const { return flags_; } ocsp_response()135 const std::string& ocsp_response() const { return ocsp_response_; } sct_list()136 const std::string& sct_list() const { return sct_list_; } 137 138 bool operator==(const RequestParams& other) const; 139 bool operator<(const RequestParams& other) const; 140 141 private: 142 scoped_refptr<X509Certificate> certificate_; 143 std::string hostname_; 144 int flags_; 145 std::string ocsp_response_; 146 std::string sct_list_; 147 148 // Used to optimize sorting/indexing comparisons. 149 std::string key_; 150 }; 151 152 // When the verifier is destroyed, all certificate verification requests are 153 // canceled, and their completion callbacks will not be called. 154 virtual ~CertVerifier() = default; 155 156 // Verifies the given certificate against the given hostname as an SSL server. 157 // Returns OK if successful or an error code upon failure. 158 // 159 // The |*verify_result| structure, including the |verify_result->cert_status| 160 // bitmask and |verify_result->verified_cert|, is always filled out regardless 161 // of the return value. If the certificate has multiple errors, the 162 // corresponding status flags are set in |verify_result->cert_status|, and the 163 // error code for the most serious error is returned. 164 // 165 // |callback| must not be null. ERR_IO_PENDING is returned if the operation 166 // could not be completed synchronously, in which case the result code will 167 // be passed to the callback when available. 168 // 169 // |*out_req| is used to store a request handle in the event of asynchronous 170 // completion (when Verify returns ERR_IO_PENDING). Provided that neither 171 // the CertVerifier nor the Request have been deleted, |callback| will be 172 // invoked once the underlying verification finishes. If either the 173 // CertVerifier or the Request are deleted, then |callback| will be Reset() 174 // and will not be invoked. It is fine for |out_req| to outlive the 175 // CertVerifier, and it is fine to reset |out_req| or delete the 176 // CertVerifier during the processing of |callback|. 177 // 178 // If Verify() completes synchronously then |out_req| *may* be reset to 179 // nullptr. However it is not guaranteed that all implementations will reset 180 // it in this case. 181 virtual int Verify(const RequestParams& params, 182 CertVerifyResult* verify_result, 183 CompletionOnceCallback callback, 184 std::unique_ptr<Request>* out_req, 185 const NetLogWithSource& net_log) = 0; 186 187 // Sets the configuration for new certificate verifications to be |config|. 188 // Any in-progress verifications (i.e. those with outstanding Request 189 // handles) will continue using the old configuration. This may be called 190 // throughout the CertVerifier's lifetime in response to configuration 191 // changes from embedders. 192 // Note: As configuration changes will replace any existing configuration, 193 // this should only be called by the logical 'owner' of this CertVerifier. 194 // Callers should NOT attempt to change configuration for single calls, and 195 // should NOT attempt to change configuration for CertVerifiers they do not 196 // explicitly manage. 197 virtual void SetConfig(const Config& config) = 0; 198 199 // Add an observer to be notified when the CertVerifier has changed. 200 // RemoveObserver() must be called before |observer| is destroyed. 201 virtual void AddObserver(Observer* observer) = 0; 202 203 // Remove an observer added with AddObserver(). 204 virtual void RemoveObserver(Observer* observer) = 0; 205 206 // Creates a CertVerifier implementation that verifies certificates using 207 // the preferred underlying cryptographic libraries. |cert_net_fetcher| may 208 // not be used, depending on the platform. 209 static std::unique_ptr<CertVerifierWithUpdatableProc> 210 CreateDefaultWithoutCaching(scoped_refptr<CertNetFetcher> cert_net_fetcher); 211 212 // Wraps the result of |CreateDefaultWithoutCaching| in a CachingCertVerifier 213 // and a CoalescingCertVerifier. 214 static std::unique_ptr<CertVerifier> CreateDefault( 215 scoped_refptr<CertNetFetcher> cert_net_fetcher); 216 }; 217 218 // Overloads for comparing two configurations. Note, comparison is shallow - 219 // that is, two scoped_refptr<CRLSet>s are equal iff they point to the same 220 // object. 221 NET_EXPORT bool operator==(const CertVerifier::Config& lhs, 222 const CertVerifier::Config& rhs); 223 NET_EXPORT bool operator!=(const CertVerifier::Config& lhs, 224 const CertVerifier::Config& rhs); 225 226 // A CertVerifier that can update its CertVerifyProc while it is running. 227 class NET_EXPORT CertVerifierWithUpdatableProc : public CertVerifier { 228 public: 229 // Update the CertVerifyProc with a new set of parameters. 230 virtual void UpdateVerifyProcData( 231 scoped_refptr<CertNetFetcher> cert_net_fetcher, 232 const net::CertVerifyProc::ImplParams& impl_params, 233 const net::CertVerifyProc::InstanceParams& instance_params) = 0; 234 }; 235 236 } // namespace net 237 238 #endif // NET_CERT_CERT_VERIFIER_H_ 239