// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef NET_HTTP_TRANSPORT_SECURITY_STATE_H_
#define NET_HTTP_TRANSPORT_SECURITY_STATE_H_
#include <map>
#include <string>
#include <utility>
#include <vector>
#include "base/basictypes.h"
#include "base/gtest_prod_util.h"
#include "base/threading/non_thread_safe.h"
#include "base/time/time.h"
#include "net/base/net_export.h"
#include "net/cert/x509_cert_types.h"
#include "net/cert/x509_certificate.h"
namespace net {
class SSLInfo;
// Tracks which hosts have enabled strict transport security and/or public
// key pins.
//
// This object manages the in-memory store. Register a Delegate with
// |SetDelegate| to persist the state to disk.
//
// HTTP strict transport security (HSTS) is defined in
// http://tools.ietf.org/html/ietf-websec-strict-transport-sec, and
// HTTP-based dynamic public key pinning (HPKP) is defined in
// http://tools.ietf.org/html/ietf-websec-key-pinning.
class NET_EXPORT TransportSecurityState
: NON_EXPORTED_BASE(public base::NonThreadSafe) {
public:
class NET_EXPORT Delegate {
public:
// This function may not block and may be called with internal locks held.
// Thus it must not reenter the TransportSecurityState object.
virtual void StateIsDirty(TransportSecurityState* state) = 0;
protected:
virtual ~Delegate() {}
};
TransportSecurityState();
~TransportSecurityState();
// A DomainState describes the transport security state (required upgrade
// to HTTPS, and/or any public key pins).
class NET_EXPORT DomainState {
public:
enum UpgradeMode {
// These numbers must match those in hsts_view.js, function modeToString.
MODE_FORCE_HTTPS = 0,
MODE_DEFAULT = 1,
};
DomainState();
~DomainState();
// Takes a set of SubjectPublicKeyInfo |hashes| and returns true if:
// 1) |bad_static_spki_hashes| does not intersect |hashes|; AND
// 2) Both |static_spki_hashes| and |dynamic_spki_hashes| are empty
// or at least one of them intersects |hashes|.
//
// |{dynamic,static}_spki_hashes| contain trustworthy public key hashes,
// any one of which is sufficient to validate the certificate chain in
// question. The public keys could be of a root CA, intermediate CA, or
// leaf certificate, depending on the security vs. disaster recovery
// tradeoff selected. (Pinning only to leaf certifiates increases
// security because you no longer trust any CAs, but it hampers disaster
// recovery because you can't just get a new certificate signed by the
// CA.)
//
// |bad_static_spki_hashes| contains public keys that we don't want to
// trust.
bool CheckPublicKeyPins(const HashValueVector& hashes) const;
// Returns true if any of the HashValueVectors |static_spki_hashes|,
// |bad_static_spki_hashes|, or |dynamic_spki_hashes| contains any
// items.
bool HasPublicKeyPins() const;
// ShouldUpgradeToSSL returns true iff, given the |mode| of this
// DomainState, HTTP requests should be internally redirected to HTTPS
// (also if the "ws" WebSocket request should be upgraded to "wss")
bool ShouldUpgradeToSSL() const;
// ShouldSSLErrorsBeFatal returns true iff HTTPS errors should cause
// hard-fail behavior (e.g. if HSTS is set for the domain)
bool ShouldSSLErrorsBeFatal() const;
UpgradeMode upgrade_mode;
// The absolute time (UTC) when the |upgrade_mode| was observed.
//
// TODO(palmer): Perhaps static entries should have an "observed" time.
base::Time sts_observed;
// The absolute time (UTC) when the |dynamic_spki_hashes| (and other
// |dynamic_*| state) were observed.
//
// TODO(palmer): Perhaps static entries should have an "observed" time.
base::Time pkp_observed;
// The absolute time (UTC) when the |upgrade_mode|, if set to
// UPGRADE_ALWAYS, downgrades to UPGRADE_NEVER.
base::Time upgrade_expiry;
// Are subdomains subject to this DomainState, for the purposes of
// upgrading to HTTPS?
bool sts_include_subdomains;
// Are subdomains subject to this DomainState, for the purposes of
// Pin Validation?
bool pkp_include_subdomains;
// Optional; hashes of static pinned SubjectPublicKeyInfos. Unless both
// are empty, at least one of |static_spki_hashes| and
// |dynamic_spki_hashes| MUST intersect with the set of SPKIs in the TLS
// server's certificate chain.
//
// |dynamic_spki_hashes| take precedence over |static_spki_hashes|.
// That is, |IsChainOfPublicKeysPermitted| first checks dynamic pins and
// then checks static pins.
HashValueVector static_spki_hashes;
// Optional; hashes of dynamically pinned SubjectPublicKeyInfos.
HashValueVector dynamic_spki_hashes;
// The absolute time (UTC) when the |dynamic_spki_hashes| expire.
base::Time dynamic_spki_hashes_expiry;
// Optional; hashes of static known-bad SubjectPublicKeyInfos which
// MUST NOT intersect with the set of SPKIs in the TLS server's
// certificate chain.
HashValueVector bad_static_spki_hashes;
// The following members are not valid when stored in |enabled_hosts_|:
// The domain which matched during a search for this DomainState entry.
// Updated by |GetDomainState|, |GetDynamicDomainState|, and
// |GetStaticDomainState|.
std::string domain;
};
class NET_EXPORT Iterator {
public:
explicit Iterator(const TransportSecurityState& state);
~Iterator();
bool HasNext() const { return iterator_ != end_; }
void Advance() { ++iterator_; }
const std::string& hostname() const { return iterator_->first; }
const DomainState& domain_state() const { return iterator_->second; }
private:
std::map<std::string, DomainState>::const_iterator iterator_;
std::map<std::string, DomainState>::const_iterator end_;
};
// Assign a |Delegate| for persisting the transport security state. If
// |NULL|, state will not be persisted. The caller retains
// ownership of |delegate|.
// Note: This is only used for serializing/deserializing the
// TransportSecurityState.
void SetDelegate(Delegate* delegate);
// Clears all dynamic data (e.g. HSTS and HPKP data).
//
// Does NOT persist changes using the Delegate, as this function is only
// used to clear any dynamic data prior to re-loading it from a file.
// Note: This is only used for serializing/deserializing the
// TransportSecurityState.
void ClearDynamicData();
// Inserts |state| into |enabled_hosts_| under the key |hashed_host|.
// |hashed_host| is already in the internal representation
// HashHost(CanonicalizeHost(host)).
// Note: This is only used for serializing/deserializing the
// TransportSecurityState.
void AddOrUpdateEnabledHosts(const std::string& hashed_host,
const DomainState& state);
// Deletes all dynamic data (e.g. HSTS or HPKP data) created since a given
// time.
//
// If any entries are deleted, the new state will be persisted through
// the Delegate (if any).
void DeleteAllDynamicDataSince(const base::Time& time);
// Deletes any dynamic data stored for |host| (e.g. HSTS or HPKP data).
// If |host| doesn't have an exact entry then no action is taken. Does
// not delete static (i.e. preloaded) data. Returns true iff an entry
// was deleted.
//
// If an entry is deleted, the new state will be persisted through
// the Delegate (if any).
bool DeleteDynamicDataForHost(const std::string& host);
// Returns true and updates |*result| iff there is a DomainState for
// |host|.
//
// If |sni_enabled| is true, searches the static pins defined for
// SNI-using hosts as well as the rest of the pins.
//
// If |host| matches both an exact entry and is a subdomain of another
// entry, the exact match determines the return value.
//
// Note that this method is not const because it opportunistically removes
// entries that have expired.
bool GetDomainState(const std::string& host,
bool sni_enabled,
DomainState* result);
// Processes an HSTS header value from the host, adding entries to
// dynamic state if necessary.
bool AddHSTSHeader(const std::string& host, const std::string& value);
// Processes an HPKP header value from the host, adding entries to
// dynamic state if necessary. ssl_info is used to check that
// the specified pins overlap with the certificate chain.
bool AddHPKPHeader(const std::string& host, const std::string& value,
const SSLInfo& ssl_info);
// Adds explicitly-specified data as if it was processed from an
// HSTS header (used for net-internals and unit tests).
bool AddHSTS(const std::string& host, const base::Time& expiry,
bool include_subdomains);
// Adds explicitly-specified data as if it was processed from an
// HPKP header (used for net-internals and unit tests).
bool AddHPKP(const std::string& host, const base::Time& expiry,
bool include_subdomains, const HashValueVector& hashes);
// Returns true iff we have any static public key pins for the |host| and
// iff its set of required pins is the set we expect for Google
// properties.
//
// If |sni_enabled| is true, searches the static pins defined for
// SNI-using hosts as well as the rest of the pins.
//
// If |host| matches both an exact entry and is a subdomain of another
// entry, the exact match determines the return value.
static bool IsGooglePinnedProperty(const std::string& host,
bool sni_enabled);
// GetPinsForDebugging finds the preloaded entry for the given host. If none
// exists, it returns false. Otherwise it returns true and sets |out_pins|
// and |out_bad_pins| to point to arrays of SHA-1 hashes, each 20 bytes long
// with a NULL pointer signalling the end of the array, for the required and
// excluded pins, respectively.
// This is a temporary debugging measure to check for binary alteration /
// corruption.
static bool GetPinsForDebugging(
const std::string& host,
const char* const** out_pins,
const char* const** out_bad_pins);
// The maximum number of seconds for which we'll cache an HSTS request.
static const long int kMaxHSTSAgeSecs;
// Send an UMA report on pin validation failure, if the host is in a
// statically-defined list of domains.
//
// TODO(palmer): This doesn't really belong here, and should be moved into
// the exactly one call site. This requires unifying |struct HSTSPreload|
// (an implementation detail of this class) with a more generic
// representation of first-class DomainStates, and exposing the preloads
// to the caller with |GetStaticDomainState|.
static void ReportUMAOnPinFailure(const std::string& host);
// IsBuildTimely returns true if the current build is new enough ensure that
// built in security information (i.e. HSTS preloading and pinning
// information) is timely.
static bool IsBuildTimely();
private:
friend class TransportSecurityStateTest;
FRIEND_TEST_ALL_PREFIXES(HttpSecurityHeadersTest,
UpdateDynamicPKPOnly);
typedef std::map<std::string, DomainState> DomainStateMap;
// If a Delegate is present, notify it that the internal state has
// changed.
void DirtyNotify();
// Enable TransportSecurity for |host|. |state| supercedes any previous
// state for the |host|, including static entries.
//
// The new state for |host| is persisted using the Delegate (if any).
void EnableHost(const std::string& host, const DomainState& state);
// Converts |hostname| from dotted form ("www.google.com") to the form
// used in DNS: "\x03www\x06google\x03com", lowercases that, and returns
// the result.
static std::string CanonicalizeHost(const std::string& hostname);
// Returns true and updates |*result| iff there is a static DomainState for
// |host|.
//
// |GetStaticDomainState| is identical to |GetDomainState| except that it
// searches only the statically-defined transport security state, ignoring
// all dynamically-added DomainStates.
//
// If |sni_enabled| is true, searches the static pins defined for
// SNI-using hosts as well as the rest of the pins.
//
// If |host| matches both an exact entry and is a subdomain of another
// entry, the exact match determines the return value.
//
// Note that this method is not const because it opportunistically removes
// entries that have expired.
bool GetStaticDomainState(const std::string& host,
bool sni_enabled,
DomainState* result);
// Returns true and updates |*result| iff there is a dynamic DomainState for
// |host|.
//
// |GetDynamicDomainState| is identical to |GetDomainState| except that it
// searches only the dynamically-added transport security state, ignoring
// all statically-defined DomainStates.
//
// If |host| matches both an exact entry and is a subdomain of another
// entry, the exact match determines the return value.
//
// Note that this method is not const because it opportunistically removes
// entries that have expired.
bool GetDynamicDomainState(const std::string& host, DomainState* result);
// The set of hosts that have enabled TransportSecurity.
DomainStateMap enabled_hosts_;
Delegate* delegate_;
DISALLOW_COPY_AND_ASSIGN(TransportSecurityState);
};
} // namespace net
#endif // NET_HTTP_TRANSPORT_SECURITY_STATE_H_