Improve TransportSecurityState data storage.

net/base/transport_security_state.h

 // 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_BASE_TRANSPORT_SECURITY_STATE_H_
 #define NET_BASE_TRANSPORT_SECURITY_STATE_H_
 
 #include <map>
 #include <string>
 #include <utility>
@@ skipping 10 matching lines @@
 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 strict transport security (HSTS) is defined in RFC 6797, and

[palmer, 2013/03/25 23:54:34]

Oh good, thank you.

 // 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 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).
+  // A DomainState describes the entire set of applicable transport security
+  // state for a domain at a particular point in time (required upgrade to
+  // HTTPS, public key pins, etc).  DomainStates are not stored directly
+  // but are calculated by searching through the dynamic and preload entries
+  // and merging all relevant and nonexpired data into the DomainState.
   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();
 
+    // ShouldUpgradeToSSL returns true iff HTTP requests should be internally

[palmer, 2013/03/25 23:54:34]

Just say, "Returns true iff...". No need to restate the function name in the
comment.

[unsafe, 2013/03/26 01:42:22]

Done.

+    // 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

[palmer, 2013/03/25 23:54:34]

Same here; also end the sentence with a ".".

[unsafe, 2013/03/26 01:42:22]

Done.

+    // hard-fail behavior (e.g. if HSTS is set for the domain)
+    bool ShouldSSLErrorsBeFatal() const;
+
+    // Returns true if CheckPublicKeyPins() should be called to verify
+    // SSL/TLS connections.
+    bool HasPublicKeyPins() const;
+
     // 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|.
+    //   1) |public_key_pins_bad_hashes_| does not intersect |hashes|; AND
+    //   2) |public_key_pins_good_hashes_| is either empty or intersects
+    //      |hashes|.
     //
-    // |{dynamic,static}_spki_hashes| contain trustworthy public key hashes,
+    // |public_key_pins_good_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.
+    // |public_key_pins_bad_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;
+    // Returns true iff we have any preloaded public key pins for the domain
+    // and iff its set of required pins is the set we expect for Google
+    // properties.
+    bool IsGooglePinnedProperty() 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;
+    // Send an UMA report on pin validation failure, if the host is in a
+    // statically-defined list of domains.
+    void ReportUMAOnPinFailure() const;
 
-    // ShouldSSLErrorsBeFatal returns true iff HTTPS errors should cause
-    // hard-fail behavior (e.g. if HSTS is set for the domain)
-    bool ShouldSSLErrorsBeFatal() const;
+    // Provide direct read-only access for net-internals

[palmer, 2013/03/25 23:54:34]

Punctuation. Also maybe be more obvious: say chrome://net-internals.

[unsafe, 2013/03/26 01:42:22]

Done.

+    const HashValueVector& GetPublicKeyPinsGoodHashes() const;
+    const HashValueVector& GetPublicKeyPinsBadHashes() const;
 
-    bool Equals(const DomainState& other) const;
+   private:
+    friend TransportSecurityState;
 
-    UpgradeMode upgrade_mode;
+    bool should_upgrade_;
+    bool has_public_key_pins_;
+    bool is_google_pinned_property_;
+    bool report_uma_on_pin_failure_;
 
-    // The absolute time (UTC) when this DomainState was first created.
-    //
-    // Static entries do not have a created time.
-    base::Time created;
+    HashValueVector public_key_pins_good_hashes_;  // if has_public_key_pins_
+    HashValueVector public_key_pins_bad_hashes_;   // if has_public_key_pins_
 
-    // 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?
-    //
-    // TODO(palmer): Decide if we should have separate |pin_subdomains| and
-    // |upgrade_subdomains|. Alternately, and perhaps better, is to separate
-    // DomainState into UpgradeState and PinState (requiring also changing the
-    // serialization format?).
-    bool 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| and |GetStaticDomainState|.
-    std::string domain;
+    size_t second_level_domain_name_;  // if report_uma_on_pin_failure_

[palmer, 2013/03/25 23:54:34]

The meaning of these comments (lines 100 – 103) is not immediately clear to me.

[unsafe, 2013/03/26 01:42:22]

Added comment:
    // The following values are only relevant if one of the above
    // booleans is true:

   };
 
-  class NET_EXPORT Iterator {
+  // DynamicEntry stores the HSTS data for a single domain.
+  struct DynamicEntry {
+    DynamicEntry();
+    ~DynamicEntry();
+    DynamicEntry(bool include_subdomains, const base::Time& created,
+                 const base::Time& expiry);
+
+    bool include_subdomains_;
+    base::Time created_;
+    base::Time expiry_;
+  };
+
+  // HPKPEntry stores the HPKP data for a single domain.
+  struct HPKPEntry : public DynamicEntry {
+    HPKPEntry();
+    ~HPKPEntry();
+    HPKPEntry(bool include_subdomains, const base::Time& created,
+              const base::Time& expiry,
+              const HashValueVector& good_hashes);
+    HashValueVector good_hashes_;
+  };
+
+  class Delegate {
    public:
-    explicit Iterator(const TransportSecurityState& state);
-    ~Iterator();
+    // 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;
 
-    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; }
+   protected:
+    virtual ~Delegate() {}
+  };
 
-   private:
-    std::map<std::string, DomainState>::const_iterator iterator_;
-    std::map<std::string, DomainState>::const_iterator end_;
-  };
+  TransportSecurityState();
+  ~TransportSecurityState();
 
   // 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);
+  // Returns true and updates |*result| iff there is DomainState for |host|.
+  //
+  // If |sni_enabled| is true, searches the preload data defined for
+  // SNI-only hosts as well as the other preload data.
+  bool GetDomainState(const std::string& host,
+                      bool sni_enabled,
+                      DomainState* result) const;
 
-  // Inserts |state| into |forced_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 AddOrUpdateForcedHosts(const std::string& hashed_host,
-                              const DomainState& state);
+  // Processes an HSTS header value from the host, adds/deletes entries
+  // in dynamic state if necessary.
+  void AddHSTSHeader(const std::string& host, const std::string& value);
+
+  // Processes an HPKP header value from the host, adds/deletes entries
+  // in dynamic state if necessary.  ssl_info is used to check that

[palmer, 2013/03/25 23:54:34]

Denote identifiers with pipes: |ssl_info|

[unsafe, 2013/03/26 01:42:22]

Done.

+  // the specified pins overlap with the certificate chain.
+  void 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/HPKP header (used for net-internals and unit tests).
+  // Returns true iff an entry was succesfully added, false if
+  // expiry < now or created > now.
+  bool AddHSTS(const std::string& host, const base::Time& created,
+               const base::Time& expiry, bool include_subdomains);
+  bool AddHPKP(const std::string& host, const base::Time& created,
+               const base::Time& expiry, bool include_subdomains,
+               const HashValueVector& hashes);
+
+  // As AddHSTS()/AddHPKP() but uses the internal "hashed" representation of
+  // a hostname.  This is used internally by AddHSTS()/AddHPKP() and is also
+  // used for deserializing the TransportSecurityState (since the JSON stores
+  // entries in hashed form).
+  bool AddHSTSHashedHost(const std::string& hashed_host,
+                         const base::Time& created, const base::Time& expiry,
+                         bool include_subdomains);
+  bool AddHPKPHashedHost(const std::string& hashed_host,
+                         const base::Time& created, const base::Time& expiry,
+                         bool include_subdomains,
+                         const HashValueVector& hashes);
+
+  // Deletes HSTS/HPKP data for the specified |host|.
+  // Returns true iff an entry was succesfully deleted.
+  bool DeleteHSTS(const std::string& host);
+  bool DeleteHPKP(const std::string& host);
+
+  // 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 preload 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);
 
   // 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);
+  // Direct (read-only) access to HSTS and HPKP entries.  Used for
+  // serializing.
+  const std::map<std::string, DynamicEntry>& GetHSTSEntries() const;
+  const std::map<std::string, HPKPEntry>& GetHPKPEntries() const;
 
-  // 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);
+  // Only used by template functions within the .cc to signal that
+  // the dynamic entry maps were changed
+  void StateIsDirty();
 
   // 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();
 
+  // The maximum number of seconds for which we'll cache an HSTS request.
+  static const long int kMaxHSTSAgeSecs;
+
  private:
   friend class TransportSecurityStateTest;
 
-  typedef std::map<std::string, DomainState> DomainStateMap;
+  // Returns true iff there is any DomainState data in preload entries
+  bool GetPreloadDomainState(bool sni_enabled, const base::Time& now,
+                             const std::string& host, DomainState* result)
+                             const;
 
-  // If a Delegate is present, notify it that the internal state has
-  // changed.
-  void DirtyNotify();
+  // Returns true iff there is any DomainState data in dynamic entries
+  bool GetDynamicDomainState(const base::Time& now, const std::string& host,
+                             DomainState* result) const;
 
-  // 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);
-
-  // The set of hosts that have enabled TransportSecurity.
-  DomainStateMap enabled_hosts_;
-
-  // Extra entries, provided by the user at run-time, to treat as if they
-  // were static.
-  DomainStateMap forced_hosts_;
+  std::map<std::string, DynamicEntry> hsts_entries_;
+  std::map<std::string, HPKPEntry> hpkp_entries_;
 
   Delegate* delegate_;
 
   DISALLOW_COPY_AND_ASSIGN(TransportSecurityState);
 };
 
 }  // namespace net
 
 #endif  // NET_BASE_TRANSPORT_SECURITY_STATE_H_