1// Copyright (c) 2012 The Chromium Authors. All rights reserved.
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/macros.h"
13#include "base/memory/ref_counted.h"
14#include "net/base/completion_once_callback.h"
15#include "net/base/hash_value.h"
16#include "net/base/net_export.h"
17#include "net/cert/x509_certificate.h"
18
19namespace net {
20
21class CertVerifyResult;
22class CRLSet;
23class NetLogWithSource;
24
25// CertVerifier represents a service for verifying certificates.
26//
27// CertVerifiers can handle multiple requests at a time.
28class NET_EXPORT CertVerifier {
29 public:
30 struct NET_EXPORT Config {
31 Config();
32 Config(const Config&);
33 Config(Config&&);
34 ~Config();
35 Config& operator=(const Config&);
36 Config& operator=(Config&&);
37
38 // Enable online revocation checking via CRLs and OCSP for the certificate
39 // chain. Note that revocation checking is soft-fail.
40 bool enable_rev_checking = false;
41
42 // Enable online revocation checking via CRLs and OCSP for the certificate
43 // chain if the constructed chain terminates in a locally-installed,
44 // non-public trust anchor. A revocation error, such as a failure to
45 // obtain fresh revocation information, is treated as a hard failure.
46 bool require_rev_checking_local_anchors = false;
47
48 // Enable support for SHA-1 signatures if the constructed chain terminates
49 // in a locally-installed, non-public trust anchor.
50 bool enable_sha1_local_anchors = false;
51
52 // Disable enforcement of the policies described at
53 // https://security.googleblog.com/2017/09/chromes-plan-to-distrust-symantec.html
54 bool disable_symantec_enforcement = false;
55
56 // Provides an optional CRLSet structure that can be used to avoid
57 // revocation checks over the network. CRLSets can be used to add
58 // additional certificates to be blacklisted beyond the internal blacklist,
59 // whether leaves or intermediates.
60 scoped_refptr<CRLSet> crl_set;
61
62 // Additional trust anchors to consider during path validation. Ordinarily,
63 // implementations of CertVerifier use trust anchors from the configured
64 // system store. This is implementation-specific plumbing for passing
65 // additional anchors through.
66 CertificateList additional_trust_anchors;
67 };
68
69 class Request {
70 public:
71 Request() {}
72
73 // Destruction of the Request cancels it.
74 virtual ~Request() {}
75
76 private:
77 DISALLOW_COPY_AND_ASSIGN(Request);
78 };
79
80 enum VerifyFlags {
81 // If set, actively overrides the current CertVerifier::Config to disable
82 // dependent network fetches. This can be used to avoid triggering
83 // re-entrancy in the network stack. For example, fetching a PAC script
84 // over HTTPS may cause AIA, OCSP, or CRL fetches to block on retrieving
85 // the PAC script, while the PAC script fetch is waiting for those
86 // dependent fetches, creating a deadlock. When set, this flag prevents
87 // those fetches from being started (best effort).
88 // Note that cached information may still be used, if it can be accessed
89 // without accessing the network.
90 VERIFY_DISABLE_NETWORK_FETCHES = 1 << 0,
91 };
92
93 // Parameters to verify |certificate| against the supplied
94 // |hostname| as an SSL server.
95 //
96 // |hostname| should be a canonicalized hostname (in A-Label form) or IP
97 // address in string form, following the rules of a URL host portion. In
98 // the case of |hostname| being a domain name, it may contain a trailing
99 // dot (e.g. "example.com."), as used to signal to DNS not to perform
100 // suffix search, and it will safely be ignored. If |hostname| is an IPv6
101 // address, it MUST be in URL form - that is, surrounded in square
102 // brackets, such as "[::1]".
103 //
104 // |flags| is a bitwise OR of VerifyFlags.
105 //
106 // |ocsp_response| is optional, but if non-empty, should contain an OCSP
107 // response obtained via OCSP stapling. It may be ignored by the
108 // CertVerifier.
109 class NET_EXPORT RequestParams {
110 public:
111 RequestParams(scoped_refptr<X509Certificate> certificate,
112 const std::string& hostname,
113 int flags,
114 const std::string& ocsp_response);
115 RequestParams(const RequestParams& other);
116 ~RequestParams();
117
118 const scoped_refptr<X509Certificate>& certificate() const {
119 return certificate_;
120 }
121 const std::string& hostname() const { return hostname_; }
122 int flags() const { return flags_; }
123 const std::string& ocsp_response() const { return ocsp_response_; }
124
125 bool operator==(const RequestParams& other) const;
126 bool operator<(const RequestParams& other) const;
127
128 private:
129 scoped_refptr<X509Certificate> certificate_;
130 std::string hostname_;
131 int flags_;
132 std::string ocsp_response_;
133
134 // Used to optimize sorting/indexing comparisons.
135 std::string key_;
136 };
137
138 // When the verifier is destroyed, all certificate verification requests are
139 // canceled, and their completion callbacks will not be called.
140 virtual ~CertVerifier() {}
141
142 // Verifies the given certificate against the given hostname as an SSL server.
143 // Returns OK if successful or an error code upon failure.
144 //
145 // The |*verify_result| structure, including the |verify_result->cert_status|
146 // bitmask, is always filled out regardless of the return value. If the
147 // certificate has multiple errors, the corresponding status flags are set in
148 // |verify_result->cert_status|, and the error code for the most serious
149 // error is returned.
150 //
151 // |callback| must not be null. ERR_IO_PENDING is returned if the operation
152 // could not be completed synchronously, in which case the result code will
153 // be passed to the callback when available.
154 //
155 // On asynchronous completion (when Verify returns ERR_IO_PENDING) |out_req|
156 // will be reset with a pointer to the request. Freeing this pointer before
157 // the request has completed will cancel it.
158 //
159 // If Verify() completes synchronously then |out_req| *may* be reset to
160 // nullptr. However it is not guaranteed that all implementations will reset
161 // it in this case.
162 virtual int Verify(const RequestParams& params,
163 CertVerifyResult* verify_result,
164 CompletionOnceCallback callback,
165 std::unique_ptr<Request>* out_req,
166 const NetLogWithSource& net_log) = 0;
167
168 // Sets the configuration for new certificate verifications to be |config|.
169 // Any in-progress verifications (i.e. those with outstanding Request
170 // handles) will continue using the old configuration. This may be called
171 // throughout the CertVerifier's lifetime in response to configuration
172 // changes from embedders.
173 // Note: As configuration changes will replace any existing configuration,
174 // this should only be called by the logical 'owner' of this CertVerifier.
175 // Callers should NOT attempt to change configuration for single calls, and
176 // should NOT attempt to change configuration for CertVerifiers they do not
177 // explicitly manage.
178 virtual void SetConfig(const Config& config) = 0;
179
180 // Creates a CertVerifier implementation that verifies certificates using
181 // the preferred underlying cryptographic libraries, using the specified
182 // configuration.
183 static std::unique_ptr<CertVerifier> CreateDefault();
184};
185
186// Overloads for comparing two configurations. Note, comparison is shallow -
187// that is, two scoped_refptr<CRLSet>s are equal iff they point to the same
188// object.
189NET_EXPORT bool operator==(const CertVerifier::Config& lhs,
190 const CertVerifier::Config& rhs);
191NET_EXPORT bool operator!=(const CertVerifier::Config& lhs,
192 const CertVerifier::Config& rhs);
193
194} // namespace net
195
196#endif // NET_CERT_CERT_VERIFIER_H_
197