text: // 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);
  
    // 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_
  