net/socket/ssl_client_socket.h

   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_SOCKET_SSL_CLIENT_SOCKET_H_
   6 #define NET_SOCKET_SSL_CLIENT_SOCKET_H_
   7
   8 #include <string>
   9
  10 #include "base/gtest_prod_util.h"
  11 #include "net/base/completion_callback.h"
  12 #include "net/base/load_flags.h"
  13 #include "net/base/net_errors.h"
  14 #include "net/socket/ssl_socket.h"
  15 #include "net/socket/stream_socket.h"
  16
  17 namespace net {
  18
  19 class CertPolicyEnforcer;
  20 class CertVerifier;
  21 class ChannelIDService;
  22 class CTVerifier;
  23 class HostPortPair;
  24 class ServerBoundCertService;
  25 class SSLCertRequestInfo;
  26 struct SSLConfig;
  27 class SSLInfo;
  28 class TransportSecurityState;
  29 class X509Certificate;
  30
  31 // This struct groups together several fields which are used by various
  32 // classes related to SSLClientSocket.
  33 struct SSLClientSocketContext {
  34   SSLClientSocketContext()
  35       : cert_verifier(NULL),
  36         channel_id_service(NULL),
  37         transport_security_state(NULL),
  38         cert_transparency_verifier(NULL),
  39         cert_policy_enforcer(NULL) {}
  40
  41   SSLClientSocketContext(CertVerifier* cert_verifier_arg,
  42                          ChannelIDService* channel_id_service_arg,
  43                          TransportSecurityState* transport_security_state_arg,
  44                          CTVerifier* cert_transparency_verifier_arg,
  45                          CertPolicyEnforcer* cert_policy_enforcer_arg,
  46                          const std::string& ssl_session_cache_shard_arg)
  47       : cert_verifier(cert_verifier_arg),
  48         channel_id_service(channel_id_service_arg),
  49         transport_security_state(transport_security_state_arg),
  50         cert_transparency_verifier(cert_transparency_verifier_arg),
  51         cert_policy_enforcer(cert_policy_enforcer_arg),
  52         ssl_session_cache_shard(ssl_session_cache_shard_arg) {}
  53
  54   CertVerifier* cert_verifier;
  55   ChannelIDService* channel_id_service;
  56   TransportSecurityState* transport_security_state;
  57   CTVerifier* cert_transparency_verifier;
  58   CertPolicyEnforcer* cert_policy_enforcer;
  59   // ssl_session_cache_shard is an opaque string that identifies a shard of the
  60   // SSL session cache. SSL sockets with the same ssl_session_cache_shard may
  61   // resume each other's SSL sessions but we'll never sessions between shards.
  62   const std::string ssl_session_cache_shard;
  63 };
  64
  65 // A client socket that uses SSL as the transport layer.
  66 //
  67 // NOTE: The SSL handshake occurs within the Connect method after a TCP
  68 // connection is established.  If a SSL error occurs during the handshake,
  69 // Connect will fail.
  70 //
  71 class NET_EXPORT SSLClientSocket : public SSLSocket {
  72  public:
  73   SSLClientSocket();
  74
  75   // Next Protocol Negotiation (NPN) allows a TLS client and server to come to
  76   // an agreement about the application level protocol to speak over a
  77   // connection.
  78   enum NextProtoStatus {
  79     // WARNING: These values are serialized to disk. Don't change them.
  80
  81     kNextProtoUnsupported = 0,  // The server doesn't support NPN.
  82     kNextProtoNegotiated = 1,   // We agreed on a protocol.
  83     kNextProtoNoOverlap = 2,    // No protocols in common. We requested
  84                                 // the first protocol in our list.
  85   };
  86
  87   // TLS extension used to negotiate protocol.
  88   enum SSLNegotiationExtension {
  89     kExtensionUnknown,
  90     kExtensionALPN,
  91     kExtensionNPN,
  92   };
  93
  94   // StreamSocket:
  95   bool WasNpnNegotiated() const override;
  96   NextProto GetNegotiatedProtocol() const override;
  97
  98   // Computes a unique key string for the SSL session cache.
  99   virtual std::string GetSessionCacheKey() const = 0;
 100
 101   // Returns true if there is a cache entry in the SSL session cache
 102   // for the cache key of the SSL socket.
 103   //
 104   // The cache key consists of a host and port concatenated with a session
 105   // cache shard. These two strings are passed to the constructor of most
 106   // subclasses of SSLClientSocket.
 107   virtual bool InSessionCache() const = 0;
 108
 109   // Sets |callback| to be run when the handshake has fully completed.
 110   // For example, in the case of False Start, Connect() will return
 111   // early, before the peer's TLS Finished message has been verified,
 112   // in order to allow the caller to call Write() and send application
 113   // data with the client's Finished message.
 114   // In such situations, |callback| will be invoked sometime after
 115   // Connect() - either during a Write() or Read() call, and before
 116   // invoking the Read() or Write() callback.
 117   // Otherwise, during a traditional TLS connection (i.e. no False
 118   // Start), this will be called right before the Connect() callback
 119   // is called.
 120   //
 121   // Note that it's not valid to mutate this socket during such
 122   // callbacks, including deleting the socket.
 123   //
 124   // TODO(mshelley): Provide additional details about whether or not
 125   // the handshake actually succeeded or not. This can be inferred
 126   // from the result to Connect()/Read()/Write(), but may be useful
 127   // to inform here as well.
 128   virtual void SetHandshakeCompletionCallback(
 129       const base::Closure& callback) = 0;
 130
 131   // Gets the SSL CertificateRequest info of the socket after Connect failed
 132   // with ERR_SSL_CLIENT_AUTH_CERT_NEEDED.
 133   virtual void GetSSLCertRequestInfo(
 134       SSLCertRequestInfo* cert_request_info) = 0;
 135
 136   // Get the application level protocol that we negotiated with the server.
 137   // *proto is set to the resulting protocol (n.b. that the string may have
 138   // embedded NULs).
 139   //   kNextProtoUnsupported: *proto is cleared.
 140   //   kNextProtoNegotiated:  *proto is set to the negotiated protocol.
 141   //   kNextProtoNoOverlap:   *proto is set to the first protocol in the
 142   //                          supported list.
 143   virtual NextProtoStatus GetNextProto(std::string* proto) = 0;
 144
 145   static NextProto NextProtoFromString(const std::string& proto_string);
 146
 147   static const char* NextProtoToString(NextProto next_proto);
 148
 149   static const char* NextProtoStatusToString(const NextProtoStatus status);
 150
 151   // Returns true if |error| is OK or |load_flags| ignores certificate errors
 152   // and |error| is a certificate error.
 153   static bool IgnoreCertError(int error, int load_flags);
 154
 155   // ClearSessionCache clears the SSL session cache, used to resume SSL
 156   // sessions.
 157   static void ClearSessionCache();
 158
 159   // Get the maximum SSL version supported by the underlying library and
 160   // cryptographic implementation.
 161   static uint16 GetMaxSupportedSSLVersion();
 162
 163   virtual bool set_was_npn_negotiated(bool negotiated);
 164
 165   virtual bool was_spdy_negotiated() const;
 166
 167   virtual bool set_was_spdy_negotiated(bool negotiated);
 168
 169   virtual void set_protocol_negotiated(NextProto protocol_negotiated);
 170
 171   void set_negotiation_extension(SSLNegotiationExtension negotiation_extension);
 172
 173   // Returns the ChannelIDService used by this socket, or NULL if
 174   // channel ids are not supported.
 175   virtual ChannelIDService* GetChannelIDService() const = 0;
 176
 177   // Returns true if a channel ID was sent on this connection.
 178   // This may be useful for protocols, like SPDY, which allow the same
 179   // connection to be shared between multiple domains, each of which need
 180   // a channel ID.
 181   //
 182   // Public for ssl_client_socket_openssl_unittest.cc.
 183   virtual bool WasChannelIDSent() const;
 184
 185   // Record which TLS extension was used to negotiate protocol and protocol
 186   // chosen in a UMA histogram.
 187   void RecordNegotiationExtension();
 188
 189  protected:
 190   virtual void set_channel_id_sent(bool channel_id_sent);
 191
 192   virtual void set_signed_cert_timestamps_received(
 193       bool signed_cert_timestamps_received);
 194
 195   virtual void set_stapled_ocsp_response_received(
 196       bool stapled_ocsp_response_received);
 197
 198   // Records histograms for channel id support during full handshakes - resumed
 199   // handshakes are ignored.
 200   static void RecordChannelIDSupport(
 201       ChannelIDService* channel_id_service,
 202       bool negotiated_channel_id,
 203       bool channel_id_enabled,
 204       bool supports_ecc);
 205
 206   // Returns whether TLS channel ID is enabled.
 207   static bool IsChannelIDEnabled(
 208       const SSLConfig& ssl_config,
 209       ChannelIDService* channel_id_service);
 210
 211   // Determine if there is at least one enabled cipher suite that satisfies
 212   // Section 9.2 of the HTTP/2 specification.  Note that the server might still
 213   // pick an inadequate cipher suite.
 214   static bool HasCipherAdequateForHTTP2(
 215       const std::vector<uint16>& cipher_suites);
 216
 217   // Determine if the TLS version required by Section 9.2 of the HTTP/2
 218   // specification is enabled.  Note that the server might still pick an
 219   // inadequate TLS version.
 220   static bool IsTLSVersionAdequateForHTTP2(const SSLConfig& ssl_config);
 221
 222   // Serializes |next_protos| in the wire format for ALPN: protocols are listed
 223   // in order, each prefixed by a one-byte length.  Any HTTP/2 protocols in
 224   // |next_protos| are ignored if |can_advertise_http2| is false.
 225   static std::vector<uint8_t> SerializeNextProtos(
 226       const NextProtoVector& next_protos,
 227       bool can_advertise_http2);
 228
 229   // For unit testing only.
 230   // Returns the unverified certificate chain as presented by server.
 231   // Note that chain may be different than the verified chain returned by
 232   // StreamSocket::GetSSLInfo().
 233   virtual scoped_refptr<X509Certificate> GetUnverifiedServerCertificateChain()
 234       const = 0;
 235
 236  private:
 237   FRIEND_TEST_ALL_PREFIXES(SSLClientSocket, SerializeNextProtos);
 238   // For signed_cert_timestamps_received_ and stapled_ocsp_response_received_.
 239   FRIEND_TEST_ALL_PREFIXES(SSLClientSocketTest,
 240                            ConnectSignedCertTimestampsEnabledTLSExtension);
 241   FRIEND_TEST_ALL_PREFIXES(SSLClientSocketTest,
 242                            ConnectSignedCertTimestampsEnabledOCSP);
 243   FRIEND_TEST_ALL_PREFIXES(SSLClientSocketTest,
 244                            ConnectSignedCertTimestampsDisabled);
 245   FRIEND_TEST_ALL_PREFIXES(SSLClientSocketTest,
 246                            VerifyServerChainProperlyOrdered);
 247
 248   // True if NPN was responded to, independent of selecting SPDY or HTTP.
 249   bool was_npn_negotiated_;
 250   // True if NPN successfully negotiated SPDY.
 251   bool was_spdy_negotiated_;
 252   // Protocol that we negotiated with the server.
 253   NextProto protocol_negotiated_;
 254   // True if a channel ID was sent.
 255   bool channel_id_sent_;
 256   // True if SCTs were received via a TLS extension.
 257   bool signed_cert_timestamps_received_;
 258   // True if a stapled OCSP response was received.
 259   bool stapled_ocsp_response_received_;
 260   // Protocol negotiation extension used.
 261   SSLNegotiationExtension negotiation_extension_;
 262 };
 263
 264 }  // namespace net
 265
 266 #endif  // NET_SOCKET_SSL_CLIENT_SOCKET_H_