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.
5 #ifndef NET_HTTP_TRANSPORT_SECURITY_STATE_H_
6 #define NET_HTTP_TRANSPORT_SECURITY_STATE_H_
13 #include "base/basictypes.h"
14 #include "base/gtest_prod_util.h"
15 #include "base/threading/non_thread_safe.h"
16 #include "base/time/time.h"
17 #include "net/base/net_export.h"
18 #include "net/cert/x509_cert_types.h"
19 #include "net/cert/x509_certificate.h"
25 // Tracks which hosts have enabled strict transport security and/or public
28 // This object manages the in-memory store. Register a Delegate with
29 // |SetDelegate| to persist the state to disk.
31 // HTTP strict transport security (HSTS) is defined in
32 // http://tools.ietf.org/html/ietf-websec-strict-transport-sec, and
33 // HTTP-based dynamic public key pinning (HPKP) is defined in
34 // http://tools.ietf.org/html/ietf-websec-key-pinning.
35 class NET_EXPORT TransportSecurityState
36 : NON_EXPORTED_BASE(public base::NonThreadSafe) {
40 // This function may not block and may be called with internal locks held.
41 // Thus it must not reenter the TransportSecurityState object.
42 virtual void StateIsDirty(TransportSecurityState* state) = 0;
45 virtual ~Delegate() {}
48 TransportSecurityState();
49 ~TransportSecurityState();
51 // A DomainState describes the transport security state (required upgrade
52 // to HTTPS, and/or any public key pins).
53 class NET_EXPORT DomainState {
56 // These numbers must match those in hsts_view.js, function modeToString.
64 // Takes a set of SubjectPublicKeyInfo |hashes| and returns true if:
65 // 1) |bad_static_spki_hashes| does not intersect |hashes|; AND
66 // 2) Both |static_spki_hashes| and |dynamic_spki_hashes| are empty
67 // or at least one of them intersects |hashes|.
69 // |{dynamic,static}_spki_hashes| contain trustworthy public key hashes,
70 // any one of which is sufficient to validate the certificate chain in
71 // question. The public keys could be of a root CA, intermediate CA, or
72 // leaf certificate, depending on the security vs. disaster recovery
73 // tradeoff selected. (Pinning only to leaf certifiates increases
74 // security because you no longer trust any CAs, but it hampers disaster
75 // recovery because you can't just get a new certificate signed by the
78 // |bad_static_spki_hashes| contains public keys that we don't want to
80 bool CheckPublicKeyPins(const HashValueVector& hashes) const;
82 // Returns true if any of the HashValueVectors |static_spki_hashes|,
83 // |bad_static_spki_hashes|, or |dynamic_spki_hashes| contains any
85 bool HasPublicKeyPins() const;
87 // ShouldUpgradeToSSL returns true iff, given the |mode| of this
88 // DomainState, HTTP requests should be internally redirected to HTTPS
89 // (also if the "ws" WebSocket request should be upgraded to "wss")
90 bool ShouldUpgradeToSSL() const;
92 // ShouldSSLErrorsBeFatal returns true iff HTTPS errors should cause
93 // hard-fail behavior (e.g. if HSTS is set for the domain)
94 bool ShouldSSLErrorsBeFatal() const;
96 UpgradeMode upgrade_mode;
98 // The absolute time (UTC) when this DomainState was first created.
100 // Static entries do not have a created time.
103 // The absolute time (UTC) when the |upgrade_mode|, if set to
104 // UPGRADE_ALWAYS, downgrades to UPGRADE_NEVER.
105 base::Time upgrade_expiry;
107 // Are subdomains subject to this DomainState, for the purposes of
108 // upgrading to HTTPS?
109 bool sts_include_subdomains;
111 // Are subdomains subject to this DomainState, for the purposes of
113 bool pkp_include_subdomains;
115 // Optional; hashes of static pinned SubjectPublicKeyInfos. Unless both
116 // are empty, at least one of |static_spki_hashes| and
117 // |dynamic_spki_hashes| MUST intersect with the set of SPKIs in the TLS
118 // server's certificate chain.
120 // |dynamic_spki_hashes| take precedence over |static_spki_hashes|.
121 // That is, |IsChainOfPublicKeysPermitted| first checks dynamic pins and
122 // then checks static pins.
123 HashValueVector static_spki_hashes;
125 // Optional; hashes of dynamically pinned SubjectPublicKeyInfos.
126 HashValueVector dynamic_spki_hashes;
128 // The absolute time (UTC) when the |dynamic_spki_hashes| expire.
129 base::Time dynamic_spki_hashes_expiry;
131 // Optional; hashes of static known-bad SubjectPublicKeyInfos which
132 // MUST NOT intersect with the set of SPKIs in the TLS server's
133 // certificate chain.
134 HashValueVector bad_static_spki_hashes;
136 // The following members are not valid when stored in |enabled_hosts_|:
138 // The domain which matched during a search for this DomainState entry.
139 // Updated by |GetDomainState|, |GetDynamicDomainState|, and
140 // |GetStaticDomainState|.
144 class NET_EXPORT Iterator {
146 explicit Iterator(const TransportSecurityState& state);
149 bool HasNext() const { return iterator_ != end_; }
150 void Advance() { ++iterator_; }
151 const std::string& hostname() const { return iterator_->first; }
152 const DomainState& domain_state() const { return iterator_->second; }
155 std::map<std::string, DomainState>::const_iterator iterator_;
156 std::map<std::string, DomainState>::const_iterator end_;
159 // Assign a |Delegate| for persisting the transport security state. If
160 // |NULL|, state will not be persisted. The caller retains
161 // ownership of |delegate|.
162 // Note: This is only used for serializing/deserializing the
163 // TransportSecurityState.
164 void SetDelegate(Delegate* delegate);
166 // Clears all dynamic data (e.g. HSTS and HPKP data).
168 // Does NOT persist changes using the Delegate, as this function is only
169 // used to clear any dynamic data prior to re-loading it from a file.
170 // Note: This is only used for serializing/deserializing the
171 // TransportSecurityState.
172 void ClearDynamicData();
174 // Inserts |state| into |enabled_hosts_| under the key |hashed_host|.
175 // |hashed_host| is already in the internal representation
176 // HashHost(CanonicalizeHost(host)).
177 // Note: This is only used for serializing/deserializing the
178 // TransportSecurityState.
179 void AddOrUpdateEnabledHosts(const std::string& hashed_host,
180 const DomainState& state);
182 // Deletes all dynamic data (e.g. HSTS or HPKP data) created since a given
185 // If any entries are deleted, the new state will be persisted through
186 // the Delegate (if any).
187 void DeleteAllDynamicDataSince(const base::Time& time);
189 // Deletes any dynamic data stored for |host| (e.g. HSTS or HPKP data).
190 // If |host| doesn't have an exact entry then no action is taken. Does
191 // not delete static (i.e. preloaded) data. Returns true iff an entry
194 // If an entry is deleted, the new state will be persisted through
195 // the Delegate (if any).
196 bool DeleteDynamicDataForHost(const std::string& host);
198 // Returns true and updates |*result| iff there is a DomainState for
201 // If |sni_enabled| is true, searches the static pins defined for
202 // SNI-using hosts as well as the rest of the pins.
204 // If |host| matches both an exact entry and is a subdomain of another
205 // entry, the exact match determines the return value.
207 // Note that this method is not const because it opportunistically removes
208 // entries that have expired.
209 bool GetDomainState(const std::string& host,
211 DomainState* result);
213 // Processes an HSTS header value from the host, adding entries to
214 // dynamic state if necessary.
215 bool AddHSTSHeader(const std::string& host, const std::string& value);
217 // Processes an HPKP header value from the host, adding entries to
218 // dynamic state if necessary. ssl_info is used to check that
219 // the specified pins overlap with the certificate chain.
220 bool AddHPKPHeader(const std::string& host, const std::string& value,
221 const SSLInfo& ssl_info);
223 // Adds explicitly-specified data as if it was processed from an
224 // HSTS header (used for net-internals and unit tests).
225 bool AddHSTS(const std::string& host, const base::Time& expiry,
226 bool include_subdomains);
228 // Adds explicitly-specified data as if it was processed from an
229 // HPKP header (used for net-internals and unit tests).
230 bool AddHPKP(const std::string& host, const base::Time& expiry,
231 bool include_subdomains, const HashValueVector& hashes);
233 // Returns true iff we have any static public key pins for the |host| and
234 // iff its set of required pins is the set we expect for Google
237 // If |sni_enabled| is true, searches the static pins defined for
238 // SNI-using hosts as well as the rest of the pins.
240 // If |host| matches both an exact entry and is a subdomain of another
241 // entry, the exact match determines the return value.
242 static bool IsGooglePinnedProperty(const std::string& host,
245 // The maximum number of seconds for which we'll cache an HSTS request.
246 static const long int kMaxHSTSAgeSecs;
248 // Send an UMA report on pin validation failure, if the host is in a
249 // statically-defined list of domains.
251 // TODO(palmer): This doesn't really belong here, and should be moved into
252 // the exactly one call site. This requires unifying |struct HSTSPreload|
253 // (an implementation detail of this class) with a more generic
254 // representation of first-class DomainStates, and exposing the preloads
255 // to the caller with |GetStaticDomainState|.
256 static void ReportUMAOnPinFailure(const std::string& host);
258 // IsBuildTimely returns true if the current build is new enough ensure that
259 // built in security information (i.e. HSTS preloading and pinning
260 // information) is timely.
261 static bool IsBuildTimely();
264 friend class TransportSecurityStateTest;
265 FRIEND_TEST_ALL_PREFIXES(HttpSecurityHeadersTest,
266 UpdateDynamicPKPOnly);
268 typedef std::map<std::string, DomainState> DomainStateMap;
270 // If a Delegate is present, notify it that the internal state has
274 // Enable TransportSecurity for |host|. |state| supercedes any previous
275 // state for the |host|, including static entries.
277 // The new state for |host| is persisted using the Delegate (if any).
278 void EnableHost(const std::string& host, const DomainState& state);
280 // Converts |hostname| from dotted form ("www.google.com") to the form
281 // used in DNS: "\x03www\x06google\x03com", lowercases that, and returns
283 static std::string CanonicalizeHost(const std::string& hostname);
285 // Returns true and updates |*result| iff there is a static DomainState for
288 // |GetStaticDomainState| is identical to |GetDomainState| except that it
289 // searches only the statically-defined transport security state, ignoring
290 // all dynamically-added DomainStates.
292 // If |sni_enabled| is true, searches the static pins defined for
293 // SNI-using hosts as well as the rest of the pins.
295 // If |host| matches both an exact entry and is a subdomain of another
296 // entry, the exact match determines the return value.
298 // Note that this method is not const because it opportunistically removes
299 // entries that have expired.
300 bool GetStaticDomainState(const std::string& host,
302 DomainState* result);
304 // Returns true and updates |*result| iff there is a dynamic DomainState for
307 // |GetDynamicDomainState| is identical to |GetDomainState| except that it
308 // searches only the dynamically-added transport security state, ignoring
309 // all statically-defined DomainStates.
311 // If |host| matches both an exact entry and is a subdomain of another
312 // entry, the exact match determines the return value.
314 // Note that this method is not const because it opportunistically removes
315 // entries that have expired.
316 bool GetDynamicDomainState(const std::string& host, DomainState* result);
318 // The set of hosts that have enabled TransportSecurity.
319 DomainStateMap enabled_hosts_;
323 DISALLOW_COPY_AND_ASSIGN(TransportSecurityState);
328 #endif // NET_HTTP_TRANSPORT_SECURITY_STATE_H_