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
17namespace net {
18
19class CertVerifier;
20class ChannelIDService;
21class CTVerifier;
22class HostPortPair;
23class ServerBoundCertService;
24class SSLCertRequestInfo;
25struct SSLConfig;
26class SSLInfo;
27class TransportSecurityState;
28class X509Certificate;
29
30// This struct groups together several fields which are used by various
31// classes related to SSLClientSocket.
32struct 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//
66class 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