Home | History | Annotate | Download | only in http
      1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
      2 // Use of this source code is governed by a BSD-style license that can be
      3 // found in the LICENSE file.
      4 
      5 #ifndef NET_HTTP_TRANSPORT_SECURITY_STATE_H_
      6 #define NET_HTTP_TRANSPORT_SECURITY_STATE_H_
      7 
      8 #include <map>
      9 #include <string>
     10 #include <utility>
     11 #include <vector>
     12 
     13 #include "base/basictypes.h"
     14 #include "base/gtest_prod_util.h"
     15 #include "base/threading/non_thread_safe.h"
     16 #include "base/time/time.h"
     17 #include "net/base/net_export.h"
     18 #include "net/cert/x509_cert_types.h"
     19 #include "net/cert/x509_certificate.h"
     20 
     21 namespace net {
     22 
     23 class SSLInfo;
     24 
     25 // Tracks which hosts have enabled strict transport security and/or public
     26 // key pins.
     27 //
     28 // This object manages the in-memory store. Register a Delegate with
     29 // |SetDelegate| to persist the state to disk.
     30 //
     31 // HTTP strict transport security (HSTS) is defined in
     32 // http://tools.ietf.org/html/ietf-websec-strict-transport-sec, and
     33 // HTTP-based dynamic public key pinning (HPKP) is defined in
     34 // http://tools.ietf.org/html/ietf-websec-key-pinning.
     35 class NET_EXPORT TransportSecurityState
     36     : NON_EXPORTED_BASE(public base::NonThreadSafe) {
     37  public:
     38   class NET_EXPORT Delegate {
     39    public:
     40     // This function may not block and may be called with internal locks held.
     41     // Thus it must not reenter the TransportSecurityState object.
     42     virtual void StateIsDirty(TransportSecurityState* state) = 0;
     43 
     44    protected:
     45     virtual ~Delegate() {}
     46   };
     47 
     48   TransportSecurityState();
     49   ~TransportSecurityState();
     50 
     51   // A DomainState describes the transport security state (required upgrade
     52   // to HTTPS, and/or any public key pins).
     53   class NET_EXPORT DomainState {
     54    public:
     55     enum UpgradeMode {
     56       // These numbers must match those in hsts_view.js, function modeToString.
     57       MODE_FORCE_HTTPS = 0,
     58       MODE_DEFAULT = 1,
     59     };
     60 
     61     DomainState();
     62     ~DomainState();
     63 
     64     // Takes a set of SubjectPublicKeyInfo |hashes| and returns true if:
     65     //   1) |bad_static_spki_hashes| does not intersect |hashes|; AND
     66     //   2) Both |static_spki_hashes| and |dynamic_spki_hashes| are empty
     67     //      or at least one of them intersects |hashes|.
     68     //
     69     // |{dynamic,static}_spki_hashes| contain trustworthy public key hashes,
     70     // any one of which is sufficient to validate the certificate chain in
     71     // question. The public keys could be of a root CA, intermediate CA, or
     72     // leaf certificate, depending on the security vs. disaster recovery
     73     // tradeoff selected. (Pinning only to leaf certifiates increases
     74     // security because you no longer trust any CAs, but it hampers disaster
     75     // recovery because you can't just get a new certificate signed by the
     76     // CA.)
     77     //
     78     // |bad_static_spki_hashes| contains public keys that we don't want to
     79     // trust.
     80     bool CheckPublicKeyPins(const HashValueVector& hashes) const;
     81 
     82     // Returns true if any of the HashValueVectors |static_spki_hashes|,
     83     // |bad_static_spki_hashes|, or |dynamic_spki_hashes| contains any
     84     // items.
     85     bool HasPublicKeyPins() const;
     86 
     87     // ShouldUpgradeToSSL returns true iff, given the |mode| of this
     88     // DomainState, HTTP requests should be internally redirected to HTTPS
     89     // (also if the "ws" WebSocket request should be upgraded to "wss")
     90     bool ShouldUpgradeToSSL() const;
     91 
     92     // ShouldSSLErrorsBeFatal returns true iff HTTPS errors should cause
     93     // hard-fail behavior (e.g. if HSTS is set for the domain)
     94     bool ShouldSSLErrorsBeFatal() const;
     95 
     96     UpgradeMode upgrade_mode;
     97 
     98     // The absolute time (UTC) when this DomainState was first created.
     99     //
    100     // Static entries do not have a created time.
    101     base::Time created;
    102 
    103     // The absolute time (UTC) when the |upgrade_mode|, if set to
    104     // UPGRADE_ALWAYS, downgrades to UPGRADE_NEVER.
    105     base::Time upgrade_expiry;
    106 
    107     // Are subdomains subject to this DomainState, for the purposes of
    108     // upgrading to HTTPS?
    109     bool sts_include_subdomains;
    110 
    111     // Are subdomains subject to this DomainState, for the purposes of
    112     // Pin Validation?
    113     bool pkp_include_subdomains;
    114 
    115     // Optional; hashes of static pinned SubjectPublicKeyInfos. Unless both
    116     // are empty, at least one of |static_spki_hashes| and
    117     // |dynamic_spki_hashes| MUST intersect with the set of SPKIs in the TLS
    118     // server's certificate chain.
    119     //
    120     // |dynamic_spki_hashes| take precedence over |static_spki_hashes|.
    121     // That is, |IsChainOfPublicKeysPermitted| first checks dynamic pins and
    122     // then checks static pins.
    123     HashValueVector static_spki_hashes;
    124 
    125     // Optional; hashes of dynamically pinned SubjectPublicKeyInfos.
    126     HashValueVector dynamic_spki_hashes;
    127 
    128     // The absolute time (UTC) when the |dynamic_spki_hashes| expire.
    129     base::Time dynamic_spki_hashes_expiry;
    130 
    131     // Optional; hashes of static known-bad SubjectPublicKeyInfos which
    132     // MUST NOT intersect with the set of SPKIs in the TLS server's
    133     // certificate chain.
    134     HashValueVector bad_static_spki_hashes;
    135 
    136     // The following members are not valid when stored in |enabled_hosts_|:
    137 
    138     // The domain which matched during a search for this DomainState entry.
    139     // Updated by |GetDomainState|, |GetDynamicDomainState|, and
    140     // |GetStaticDomainState|.
    141     std::string domain;
    142   };
    143 
    144   class NET_EXPORT Iterator {
    145    public:
    146     explicit Iterator(const TransportSecurityState& state);
    147     ~Iterator();
    148 
    149     bool HasNext() const { return iterator_ != end_; }
    150     void Advance() { ++iterator_; }
    151     const std::string& hostname() const { return iterator_->first; }
    152     const DomainState& domain_state() const { return iterator_->second; }
    153 
    154    private:
    155     std::map<std::string, DomainState>::const_iterator iterator_;
    156     std::map<std::string, DomainState>::const_iterator end_;
    157   };
    158 
    159   // Assign a |Delegate| for persisting the transport security state. If
    160   // |NULL|, state will not be persisted. The caller retains
    161   // ownership of |delegate|.
    162   // Note: This is only used for serializing/deserializing the
    163   // TransportSecurityState.
    164   void SetDelegate(Delegate* delegate);
    165 
    166   // Clears all dynamic data (e.g. HSTS and HPKP data).
    167   //
    168   // Does NOT persist changes using the Delegate, as this function is only
    169   // used to clear any dynamic data prior to re-loading it from a file.
    170   // Note: This is only used for serializing/deserializing the
    171   // TransportSecurityState.
    172   void ClearDynamicData();
    173 
    174   // Inserts |state| into |enabled_hosts_| under the key |hashed_host|.
    175   // |hashed_host| is already in the internal representation
    176   // HashHost(CanonicalizeHost(host)).
    177   // Note: This is only used for serializing/deserializing the
    178   // TransportSecurityState.
    179   void AddOrUpdateEnabledHosts(const std::string& hashed_host,
    180                                const DomainState& state);
    181 
    182   // Deletes all dynamic data (e.g. HSTS or HPKP data) created since a given
    183   // time.
    184   //
    185   // If any entries are deleted, the new state will be persisted through
    186   // the Delegate (if any).
    187   void DeleteAllDynamicDataSince(const base::Time& time);
    188 
    189   // Deletes any dynamic data stored for |host| (e.g. HSTS or HPKP data).
    190   // If |host| doesn't have an exact entry then no action is taken. Does
    191   // not delete static (i.e. preloaded) data.  Returns true iff an entry
    192   // was deleted.
    193   //
    194   // If an entry is deleted, the new state will be persisted through
    195   // the Delegate (if any).
    196   bool DeleteDynamicDataForHost(const std::string& host);
    197 
    198   // Returns true and updates |*result| iff there is a DomainState for
    199   // |host|.
    200   //
    201   // If |sni_enabled| is true, searches the static pins defined for
    202   // SNI-using hosts as well as the rest of the pins.
    203   //
    204   // If |host| matches both an exact entry and is a subdomain of another
    205   // entry, the exact match determines the return value.
    206   //
    207   // Note that this method is not const because it opportunistically removes
    208   // entries that have expired.
    209   bool GetDomainState(const std::string& host,
    210                       bool sni_enabled,
    211                       DomainState* result);
    212 
    213   // Processes an HSTS header value from the host, adding entries to
    214   // dynamic state if necessary.
    215   bool AddHSTSHeader(const std::string& host, const std::string& value);
    216 
    217   // Processes an HPKP header value from the host, adding entries to
    218   // dynamic state if necessary.  ssl_info is used to check that
    219   // the specified pins overlap with the certificate chain.
    220   bool AddHPKPHeader(const std::string& host, const std::string& value,
    221                      const SSLInfo& ssl_info);
    222 
    223   // Adds explicitly-specified data as if it was processed from an
    224   // HSTS header (used for net-internals and unit tests).
    225   bool AddHSTS(const std::string& host, const base::Time& expiry,
    226                bool include_subdomains);
    227 
    228   // Adds explicitly-specified data as if it was processed from an
    229   // HPKP header (used for net-internals and unit tests).
    230   bool AddHPKP(const std::string& host, const base::Time& expiry,
    231                bool include_subdomains, const HashValueVector& hashes);
    232 
    233   // Returns true iff we have any static public key pins for the |host| and
    234   // iff its set of required pins is the set we expect for Google
    235   // properties.
    236   //
    237   // If |sni_enabled| is true, searches the static pins defined for
    238   // SNI-using hosts as well as the rest of the pins.
    239   //
    240   // If |host| matches both an exact entry and is a subdomain of another
    241   // entry, the exact match determines the return value.
    242   static bool IsGooglePinnedProperty(const std::string& host,
    243                                      bool sni_enabled);
    244 
    245   // The maximum number of seconds for which we'll cache an HSTS request.
    246   static const long int kMaxHSTSAgeSecs;
    247 
    248   // Send an UMA report on pin validation failure, if the host is in a
    249   // statically-defined list of domains.
    250   //
    251   // TODO(palmer): This doesn't really belong here, and should be moved into
    252   // the exactly one call site. This requires unifying |struct HSTSPreload|
    253   // (an implementation detail of this class) with a more generic
    254   // representation of first-class DomainStates, and exposing the preloads
    255   // to the caller with |GetStaticDomainState|.
    256   static void ReportUMAOnPinFailure(const std::string& host);
    257 
    258   // IsBuildTimely returns true if the current build is new enough ensure that
    259   // built in security information (i.e. HSTS preloading and pinning
    260   // information) is timely.
    261   static bool IsBuildTimely();
    262 
    263  private:
    264   friend class TransportSecurityStateTest;
    265   FRIEND_TEST_ALL_PREFIXES(HttpSecurityHeadersTest,
    266                            UpdateDynamicPKPOnly);
    267 
    268   typedef std::map<std::string, DomainState> DomainStateMap;
    269 
    270   // If a Delegate is present, notify it that the internal state has
    271   // changed.
    272   void DirtyNotify();
    273 
    274   // Enable TransportSecurity for |host|. |state| supercedes any previous
    275   // state for the |host|, including static entries.
    276   //
    277   // The new state for |host| is persisted using the Delegate (if any).
    278   void EnableHost(const std::string& host, const DomainState& state);
    279 
    280   // Converts |hostname| from dotted form ("www.google.com") to the form
    281   // used in DNS: "\x03www\x06google\x03com", lowercases that, and returns
    282   // the result.
    283   static std::string CanonicalizeHost(const std::string& hostname);
    284 
    285   // Returns true and updates |*result| iff there is a static DomainState for
    286   // |host|.
    287   //
    288   // |GetStaticDomainState| is identical to |GetDomainState| except that it
    289   // searches only the statically-defined transport security state, ignoring
    290   // all dynamically-added DomainStates.
    291   //
    292   // If |sni_enabled| is true, searches the static pins defined for
    293   // SNI-using hosts as well as the rest of the pins.
    294   //
    295   // If |host| matches both an exact entry and is a subdomain of another
    296   // entry, the exact match determines the return value.
    297   //
    298   // Note that this method is not const because it opportunistically removes
    299   // entries that have expired.
    300   bool GetStaticDomainState(const std::string& host,
    301                             bool sni_enabled,
    302                             DomainState* result);
    303 
    304   // Returns true and updates |*result| iff there is a dynamic DomainState for
    305   // |host|.
    306   //
    307   // |GetDynamicDomainState| is identical to |GetDomainState| except that it
    308   // searches only the dynamically-added transport security state, ignoring
    309   // all statically-defined DomainStates.
    310   //
    311   // If |host| matches both an exact entry and is a subdomain of another
    312   // entry, the exact match determines the return value.
    313   //
    314   // Note that this method is not const because it opportunistically removes
    315   // entries that have expired.
    316   bool GetDynamicDomainState(const std::string& host, DomainState* result);
    317 
    318   // The set of hosts that have enabled TransportSecurity.
    319   DomainStateMap enabled_hosts_;
    320 
    321   Delegate* delegate_;
    322 
    323   DISALLOW_COPY_AND_ASSIGN(TransportSecurityState);
    324 };
    325 
    326 }  // namespace net
    327 
    328 #endif  // NET_HTTP_TRANSPORT_SECURITY_STATE_H_
    329