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