| // 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); |
| |
| // For unit tests only; causes ShouldRequireCT() to return |*required| |
| // by default (that is, unless a RequireCTDelegate overrides). Set to |
| // nullptr to reset. |
| static void SetShouldRequireCTForTesting(bool* required); |
| |
| 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_ |