blob: a76f235e43be6e8c5a08b821752cfa06b42cf04c [file] [log] [blame]
// 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 <stdint.h>
#include <map>
#include <string>
#include "base/callback.h"
#include "base/gtest_prod_util.h"
#include "base/macros.h"
#include "base/threading/non_thread_safe.h"
#include "base/time/time.h"
#include "net/base/expiring_cache.h"
#include "net/base/hash_value.h"
#include "net/base/net_export.h"
#include "url/gurl.h"
namespace net {
class HostPortPair;
class SSLInfo;
class X509Certificate;
// 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() {}
};
class NET_EXPORT RequireCTDelegate {
public:
// Provides a capability for altering the default handling of Certificate
// Transparency information, allowing it to be always required for some
// hosts, for some hosts to be opted out of the default policy, or
// allowing the TransportSecurityState to apply the default security
// policies.
enum class CTRequirementLevel {
// The host is required to always supply Certificate Transparency
// information that complies with the CT policy.
REQUIRED,
// The host is explicitly not required to supply Certificate
// Transparency information that complies with the CT policy.
NOT_REQUIRED,
// The delegate makes no statements, positive or negative, about
// requiring the host to supply Certificate Transparency information,
// allowing the default behaviour to happen.
DEFAULT,
};
// Called by the TransportSecurityState, allows the Delegate to override
// the default handling of Certificate Transparency requirements, if
// desired.
virtual CTRequirementLevel IsCTRequiredForHost(
const std::string& hostname) = 0;
protected:
virtual ~RequireCTDelegate() = default;
};
// A STSState describes the strict transport security state (required
// upgrade to HTTPS).
class NET_EXPORT STSState {
public:
enum UpgradeMode {
// These numbers must match those in hsts_view.js, function modeToString.
MODE_FORCE_HTTPS = 0,
MODE_DEFAULT = 1,
};
STSState();
~STSState();
// The absolute time (UTC) when the |upgrade_mode| (and other state) was
// observed.
base::Time last_observed;
// The absolute time (UTC) when |upgrade_mode| (and other state)
// expires.
base::Time expiry;
UpgradeMode upgrade_mode;
// Are subdomains subject to this policy state?
bool include_subdomains;
// The domain which matched during a search for this STSState entry.
// Updated by |GetDynamicSTSState| and |GetStaticDomainState|.
std::string domain;
// ShouldUpgradeToSSL returns true iff HTTP requests should be internally
// redirected to HTTPS (also if WS should be upgraded to WSS).
bool ShouldUpgradeToSSL() const;
};
class NET_EXPORT STSStateIterator {
public:
explicit STSStateIterator(const TransportSecurityState& state);
~STSStateIterator();
bool HasNext() const { return iterator_ != end_; }
void Advance() { ++iterator_; }
const std::string& hostname() const { return iterator_->first; }
const STSState& domain_state() const { return iterator_->second; }
private:
std::map<std::string, STSState>::const_iterator iterator_;
std::map<std::string, STSState>::const_iterator end_;
};
// PKPStatus describes the result of a pinning check.
enum class PKPStatus {
// Pinning was enabled and the necessary pins were not present.
VIOLATED,
// Pinning was not enabled, or pinning was enabled and the certificate
// satisfied the pins.
OK,
// Pinning was enabled and the certificate did not satisfy the pins, but the
// violation was ignored due to local policy, such as a local trust anchor.
BYPASSED,
};
// A PKPState describes the public key pinning state.
class NET_EXPORT PKPState {
public:
PKPState();
PKPState(const PKPState& other);
~PKPState();
// The absolute time (UTC) when the |spki_hashes| (and other state) were
// observed.
base::Time last_observed;
// The absolute time (UTC) when the |spki_hashes| expire.
base::Time expiry;
// Optional; hashes of pinned SubjectPublicKeyInfos.
HashValueVector spki_hashes;
// 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_spki_hashes;
// Are subdomains subject to this policy state?
bool include_subdomains;
// The domain which matched during a search for this DomainState entry.
// Updated by |GetDynamicPKPState| and |GetStaticDomainState|.
std::string domain;
// An optional URI indicating where reports should be sent when this
// pin is violated, or empty when omitted.
GURL report_uri;
// 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,
std::string* failure_log) 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;
};
class NET_EXPORT PKPStateIterator {
public:
explicit PKPStateIterator(const TransportSecurityState& state);
~PKPStateIterator();
bool HasNext() const { return iterator_ != end_; }
void Advance() { ++iterator_; }
const std::string& hostname() const { return iterator_->first; }
const PKPState& domain_state() const { return iterator_->second; }
private:
std::map<std::string, PKPState>::const_iterator iterator_;
std::map<std::string, PKPState>::const_iterator end_;
};
// An ExpectCTState describes a site that expects valid Certificate
// Transparency information to be supplied on every connection to it.
class NET_EXPORT ExpectCTState {
public:
ExpectCTState();
~ExpectCTState();
// The domain which matched during a search for this DomainState entry.
std::string domain;
// The URI to which reports should be sent if valid CT info is not
// provided.
GURL report_uri;
};
// An ExpectStapleState describes a site that expects valid OCSP information
// to be stapled to its certificate on every connection.
class NET_EXPORT ExpectStapleState {
public:
ExpectStapleState();
~ExpectStapleState();
// The domain which matched during a search for this Expect-Staple entry
std::string domain;
// The URI reports are sent to if a valid OCSP response is not stapled
GURL report_uri;
// True if subdomains are subject to this policy
bool include_subdomains;
};
// An interface for asynchronously sending HPKP violation reports.
class NET_EXPORT ReportSenderInterface {
public:
// Sends the given serialized |report| to |report_uri|.
virtual void Send(const GURL& report_uri, const std::string& report) = 0;
// Sets a callback to be called when report sending fails.
virtual void SetErrorCallback(
const base::Callback<void(const GURL&, int)>& error_callback) = 0;
protected:
virtual ~ReportSenderInterface() {}
};
// An interface for building and asynchronously sending reports when a
// site expects valid Certificate Transparency information but it
// wasn't supplied.
class NET_EXPORT ExpectCTReporter {
public:
// Called when the host in |host_port_pair| has opted in to have
// reports about Expect CT policy violations sent to |report_uri|,
// and such a violation has occurred.
virtual void OnExpectCTFailed(const net::HostPortPair& host_port_pair,
const GURL& report_uri,
const net::SSLInfo& ssl_info) = 0;
protected:
virtual ~ExpectCTReporter() {}
};
// Indicates whether or not a public key pin check should send a
// report if a violation is detected.
enum PublicKeyPinReportStatus { ENABLE_PIN_REPORTS, DISABLE_PIN_REPORTS };
TransportSecurityState();
~TransportSecurityState();
// These functions search for static and dynamic STS and PKP states, and
// invoke the functions of the same name on them. These functions are the
// primary public interface; direct access to STS and PKP states is best
// left to tests. The caller needs to handle the optional pinning override
// when is_issued_by_known_root is false.
bool ShouldSSLErrorsBeFatal(const std::string& host);
bool ShouldUpgradeToSSL(const std::string& host);
PKPStatus CheckPublicKeyPins(
const HostPortPair& host_port_pair,
bool is_issued_by_known_root,
const HashValueVector& hashes,
const X509Certificate* served_certificate_chain,
const X509Certificate* validated_certificate_chain,
const PublicKeyPinReportStatus report_status,
std::string* failure_log);
bool HasPublicKeyPins(const std::string& host);
// Returns true if connections to |host|, using the validated certificate
// |validated_certificate_chain|, are expected to be accompanied with
// valid Certificate Transparency information that complies with the
// connection's CTPolicyEnforcer.
//
// The behavior may be further be altered by setting a RequireCTDelegate
// via |SetRequireCTDelegate()|.
bool ShouldRequireCT(const std::string& host,
const X509Certificate* validated_certificate_chain,
const HashValueVector& hashes);
// 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);
void SetReportSender(ReportSenderInterface* report_sender);
void SetExpectCTReporter(ExpectCTReporter* expect_ct_reporter);
// Assigns a delegate responsible for determining whether or not a
// connection to a given host should require Certificate Transparency
// information that complies with the CT policy provided by a
// CTPolicyEnforcer.
// If nullptr, no delegate will be consulted.
// The caller retains ownership of the |delegate|, and must persist for
// the lifetime of this object or until called with nullptr, whichever
// occurs first.
void SetRequireCTDelegate(RequireCTDelegate* 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_sts_hosts_| under the key |hashed_host|.
// |hashed_host| is already in the internal representation.
// Note: This is only used for serializing/deserializing the
// TransportSecurityState.
void AddOrUpdateEnabledSTSHosts(const std::string& hashed_host,
const STSState& state);
// Inserts |state| into |enabled_pkp_hosts_| under the key |hashed_host|.
// |hashed_host| is already in the internal representation.
// Note: This is only used for serializing/deserializing the
// TransportSecurityState.
void AddOrUpdateEnabledPKPHosts(const std::string& hashed_host,
const PKPState& 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 |*sts_result| and |*pkp_result| iff there is a
// static (built-in) state for |host|. If multiple entries match |host|,
// the most specific match determines the return value.
bool GetStaticDomainState(const std::string& host,
STSState* sts_result,
PKPState* pkp_result) const;
// Returns true iff there is static (built-in) state for |host| that
// references the Google pins.
// TODO(rch): Remove this temporary gross layering violation once QUIC 32 is
// deployed.
bool IsGooglePinnedHost(const std::string& host) const;
// Returns true and updates |*result| iff |host| has HSTS (respectively, HPKP)
// state. If multiple HSTS (respectively, HPKP) entries match |host|, the
// most specific match determines the HSTS (respectively, HPKP) return value.
//
// Note that these methods are not const because they opportunistically remove
// entries that have expired.
bool GetDynamicSTSState(const std::string& host, STSState* result);
bool GetDynamicPKPState(const std::string& host, PKPState* 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).
void 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.
// Note: This method will persist the HPKP if a Delegate is present. Make sure
// that the delegate is nullptr if the persistence is not desired.
// See |SetDelegate| method for more details.
void AddHPKP(const std::string& host,
const base::Time& expiry,
bool include_subdomains,
const HashValueVector& hashes,
const GURL& report_uri);
// Parses |value| as a Public-Key-Pins-Report-Only header value and
// sends a HPKP report for |host_port_pair| if |ssl_info| violates the
// pin. Returns true if |value| parses and includes a valid
// report-uri, and false otherwise.
bool ProcessHPKPReportOnlyHeader(const std::string& value,
const HostPortPair& host_port_pair,
const SSLInfo& ssl_info);
// Parses |value| as a Expect CT header value and sends an Expect CT
// report for |host_port_pair| if the following conditions are true:
// 1. The header value is "preload", indicating that the site wants to
// be opted in to Expect CT.
// 2. The given host is present on the Expect CT preload list with a
// valid report-uri, and the build is timely (i.e. preload list is fresh).
// 3. |ssl_info| indicates that the connection violated the Expect CT policy.
// 4. An Expect CT reporter has been provided with SetExpectCTReporter().
void ProcessExpectCTHeader(const std::string& value,
const HostPortPair& host_port_pair,
const SSLInfo& ssl_info);
private:
friend class TransportSecurityStateTest;
FRIEND_TEST_ALL_PREFIXES(HttpSecurityHeadersTest, UpdateDynamicPKPOnly);
FRIEND_TEST_ALL_PREFIXES(HttpSecurityHeadersTest, UpdateDynamicPKPMaxAge0);
FRIEND_TEST_ALL_PREFIXES(HttpSecurityHeadersTest, NoClobberPins);
FRIEND_TEST_ALL_PREFIXES(URLRequestTestHTTP, ExpectCTHeader);
typedef std::map<std::string, STSState> STSStateMap;
typedef std::map<std::string, PKPState> PKPStateMap;
// 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();
// Helper method for actually checking pins.
PKPStatus CheckPublicKeyPinsImpl(
const HostPortPair& host_port_pair,
bool is_issued_by_known_root,
const HashValueVector& hashes,
const X509Certificate* served_certificate_chain,
const X509Certificate* validated_certificate_chain,
const PublicKeyPinReportStatus report_status,
std::string* failure_log);
// If a Delegate is present, notify it that the internal state has
// changed.
void DirtyNotify();
// Adds HSTS state to |host|.
void AddHSTSInternal(const std::string& host,
STSState::UpgradeMode upgrade_mode,
const base::Time& expiry,
bool include_subdomains);
// Adds HPKP state to |host|.
void AddHPKPInternal(const std::string& host,
const base::Time& last_observed,
const base::Time& expiry,
bool include_subdomains,
const HashValueVector& hashes,
const GURL& report_uri);
// 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 EnableSTSHost(const std::string& host, const STSState& state);
void EnablePKPHost(const std::string& host, const PKPState& state);
// Returns true if a request to |host_port_pair| with the given
// SubjectPublicKeyInfo |hashes| satisfies the pins in |pkp_state|,
// and false otherwise. If a violation is found and reporting is
// configured (i.e. there is a report URI in |pkp_state| and
// |report_status| says to), this method sends an HPKP violation
// report containing |served_certificate_chain| and
// |validated_certificate_chain|.
PKPStatus CheckPinsAndMaybeSendReport(
const HostPortPair& host_port_pair,
bool is_issued_by_known_root,
const TransportSecurityState::PKPState& pkp_state,
const HashValueVector& hashes,
const X509Certificate* served_certificate_chain,
const X509Certificate* validated_certificate_chain,
const TransportSecurityState::PublicKeyPinReportStatus report_status,
std::string* failure_log);
// Returns true and updates |*expect_ct_result| iff there is a static
// (built-in) state for |host| with expect_ct=true.
bool GetStaticExpectCTState(const std::string& host,
ExpectCTState* expect_ct_result) const;
// Returns true and updates |*expect_staple_result| iff there is a static
// (built-in) state for |host| with expect_staple=true, or if |host| is a
// subdomain of another domain with expect_staple=true and
// include_subdomains_for_expect_staple=true.
bool GetStaticExpectStapleState(
const std::string& host,
ExpectStapleState* expect_staple_result) const;
// The sets of hosts that have enabled TransportSecurity. |domain| will always
// be empty for a STSState or PKPState in these maps; the domain
// comes from the map keys instead. In addition, |upgrade_mode| in the
// STSState is never MODE_DEFAULT and |HasPublicKeyPins| in the PKPState
// always returns true.
STSStateMap enabled_sts_hosts_;
PKPStateMap enabled_pkp_hosts_;
Delegate* delegate_ = nullptr;
ReportSenderInterface* report_sender_ = nullptr;
// True if static pins should be used.
bool enable_static_pins_;
// True if static expect-CT state should be used.
bool enable_static_expect_ct_;
// True if static expect-staple state should be used.
bool enable_static_expect_staple_;
ExpectCTReporter* expect_ct_reporter_ = nullptr;
RequireCTDelegate* require_ct_delegate_ = nullptr;
// Keeps track of reports that have been sent recently for
// rate-limiting.
ExpiringCache<std::string, bool, base::TimeTicks, std::less<base::TimeTicks>>
sent_reports_cache_;
DISALLOW_COPY_AND_ASSIGN(TransportSecurityState);
};
} // namespace net
#endif // NET_HTTP_TRANSPORT_SECURITY_STATE_H_