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 <vector> 11 12 #include "base/memory/scoped_refptr.h" 13 #include "base/observer_list_types.h" 14 #include "base/strings/string_piece.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 // Additional trust anchors to consider during path validation. Ordinarily, 73 // implementations of CertVerifier use trust anchors from the configured 74 // system store. This is implementation-specific plumbing for passing 75 // additional anchors through. 76 CertificateList additional_trust_anchors; 77 78 // Additional temporary certs to consider as intermediates during path 79 // validation. Ordinarily, implementations of CertVerifier use intermediate 80 // certs from the configured system store. This is implementation-specific 81 // plumbing for passing additional intermediates through. 82 CertificateList additional_untrusted_authorities; 83 }; 84 85 class Request { 86 public: 87 Request() = default; 88 89 Request(const Request&) = delete; 90 Request& operator=(const Request&) = delete; 91 92 // Destruction of the Request cancels it. 93 virtual ~Request() = default; 94 }; 95 96 enum VerifyFlags { 97 // If set, actively overrides the current CertVerifier::Config to disable 98 // dependent network fetches. This can be used to avoid triggering 99 // re-entrancy in the network stack. For example, fetching a PAC script 100 // over HTTPS may cause AIA, OCSP, or CRL fetches to block on retrieving 101 // the PAC script, while the PAC script fetch is waiting for those 102 // dependent fetches, creating a deadlock. When set, this flag prevents 103 // those fetches from being started (best effort). 104 // Note that cached information may still be used, if it can be accessed 105 // without accessing the network. 106 VERIFY_DISABLE_NETWORK_FETCHES = 1 << 0, 107 108 VERIFY_FLAGS_LAST = VERIFY_DISABLE_NETWORK_FETCHES 109 }; 110 111 // Parameters to verify |certificate| against the supplied 112 // |hostname| as an SSL server. 113 // 114 // |hostname| should be a canonicalized hostname (in A-Label form) or IP 115 // address in string form, following the rules of a URL host portion. In 116 // the case of |hostname| being a domain name, it may contain a trailing 117 // dot (e.g. "example.com."), as used to signal to DNS not to perform 118 // suffix search, and it will safely be ignored. If |hostname| is an IPv6 119 // address, it MUST be in URL form - that is, surrounded in square 120 // brackets, such as "[::1]". 121 // 122 // |flags| is a bitwise OR of VerifyFlags. 123 // 124 // |ocsp_response| is optional, but if non-empty, should contain an OCSP 125 // response obtained via OCSP stapling. It may be ignored by the 126 // CertVerifier. 127 // 128 // |sct_list| is optional, but if non-empty, should contain a 129 // SignedCertificateTimestampList from the TLS extension as described in 130 // RFC6962 section 3.3.1. It may be ignored by the CertVerifier. 131 class NET_EXPORT RequestParams { 132 public: 133 RequestParams(); 134 RequestParams(scoped_refptr<X509Certificate> certificate, 135 base::StringPiece hostname, 136 int flags, 137 base::StringPiece ocsp_response, 138 base::StringPiece sct_list); 139 RequestParams(const RequestParams& other); 140 ~RequestParams(); 141 certificate()142 const scoped_refptr<X509Certificate>& certificate() const { 143 return certificate_; 144 } hostname()145 const std::string& hostname() const { return hostname_; } flags()146 int flags() const { return flags_; } ocsp_response()147 const std::string& ocsp_response() const { return ocsp_response_; } sct_list()148 const std::string& sct_list() const { return sct_list_; } 149 150 bool operator==(const RequestParams& other) const; 151 bool operator<(const RequestParams& other) const; 152 153 private: 154 scoped_refptr<X509Certificate> certificate_; 155 std::string hostname_; 156 int flags_; 157 std::string ocsp_response_; 158 std::string sct_list_; 159 160 // Used to optimize sorting/indexing comparisons. 161 std::string key_; 162 }; 163 164 // When the verifier is destroyed, all certificate verification requests are 165 // canceled, and their completion callbacks will not be called. 166 virtual ~CertVerifier() = default; 167 168 // Verifies the given certificate against the given hostname as an SSL server. 169 // Returns OK if successful or an error code upon failure. 170 // 171 // The |*verify_result| structure, including the |verify_result->cert_status| 172 // bitmask and |verify_result->verified_cert|, is always filled out regardless 173 // of the return value. If the certificate has multiple errors, the 174 // corresponding status flags are set in |verify_result->cert_status|, and the 175 // error code for the most serious error is returned. 176 // 177 // |callback| must not be null. ERR_IO_PENDING is returned if the operation 178 // could not be completed synchronously, in which case the result code will 179 // be passed to the callback when available. 180 // 181 // |*out_req| is used to store a request handle in the event of asynchronous 182 // completion (when Verify returns ERR_IO_PENDING). Provided that neither 183 // the CertVerifier nor the Request have been deleted, |callback| will be 184 // invoked once the underlying verification finishes. If either the 185 // CertVerifier or the Request are deleted, then |callback| will be Reset() 186 // and will not be invoked. It is fine for |out_req| to outlive the 187 // CertVerifier, and it is fine to reset |out_req| or delete the 188 // CertVerifier during the processing of |callback|. 189 // 190 // If Verify() completes synchronously then |out_req| *may* be reset to 191 // nullptr. However it is not guaranteed that all implementations will reset 192 // it in this case. 193 virtual int Verify(const RequestParams& params, 194 CertVerifyResult* verify_result, 195 CompletionOnceCallback callback, 196 std::unique_ptr<Request>* out_req, 197 const NetLogWithSource& net_log) = 0; 198 199 // Sets the configuration for new certificate verifications to be |config|. 200 // Any in-progress verifications (i.e. those with outstanding Request 201 // handles) will continue using the old configuration. This may be called 202 // throughout the CertVerifier's lifetime in response to configuration 203 // changes from embedders. 204 // Note: As configuration changes will replace any existing configuration, 205 // this should only be called by the logical 'owner' of this CertVerifier. 206 // Callers should NOT attempt to change configuration for single calls, and 207 // should NOT attempt to change configuration for CertVerifiers they do not 208 // explicitly manage. 209 virtual void SetConfig(const Config& config) = 0; 210 211 // Add an observer to be notified when the CertVerifier has changed. 212 // RemoveObserver() must be called before |observer| is destroyed. 213 virtual void AddObserver(Observer* observer) = 0; 214 215 // Remove an observer added with AddObserver(). 216 virtual void RemoveObserver(Observer* observer) = 0; 217 218 // Creates a CertVerifier implementation that verifies certificates using 219 // the preferred underlying cryptographic libraries. |cert_net_fetcher| may 220 // not be used, depending on the platform. 221 static std::unique_ptr<CertVerifierWithUpdatableProc> 222 CreateDefaultWithoutCaching(scoped_refptr<CertNetFetcher> cert_net_fetcher); 223 224 // Wraps the result of |CreateDefaultWithoutCaching| in a CachingCertVerifier 225 // and a CoalescingCertVerifier. 226 static std::unique_ptr<CertVerifier> CreateDefault( 227 scoped_refptr<CertNetFetcher> cert_net_fetcher); 228 }; 229 230 // Overloads for comparing two configurations. Note, comparison is shallow - 231 // that is, two scoped_refptr<CRLSet>s are equal iff they point to the same 232 // object. 233 NET_EXPORT bool operator==(const CertVerifier::Config& lhs, 234 const CertVerifier::Config& rhs); 235 NET_EXPORT bool operator!=(const CertVerifier::Config& lhs, 236 const CertVerifier::Config& rhs); 237 238 // A CertVerifier that can update its CertVerifyProc while it is running. 239 class NET_EXPORT CertVerifierWithUpdatableProc : public CertVerifier { 240 public: 241 // Update the CertVerifyProc with a new set of parameters. 242 virtual void UpdateVerifyProcData( 243 scoped_refptr<CertNetFetcher> cert_net_fetcher, 244 const net::CertVerifyProcFactory::ImplParams& impl_params) = 0; 245 }; 246 247 } // namespace net 248 249 #endif // NET_CERT_CERT_VERIFIER_H_ 250