Home | History | Annotate | Download | only in socket 
      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_
    227