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 SSLCertRequestInfo;
  24 struct SSLConfig;
  25 class SSLInfo;
  26 class TransportSecurityState;
  27 class X509Certificate;
  28
  29 // This struct groups together several fields which are used by various
  30 // classes related to SSLClientSocket.
  31 struct SSLClientSocketContext {
  32   SSLClientSocketContext()
  33       : cert_verifier(NULL),
  34         channel_id_service(NULL),
  35         transport_security_state(NULL),
  36         cert_transparency_verifier(NULL),
  37         cert_policy_enforcer(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                          CertPolicyEnforcer* cert_policy_enforcer_arg,
  44                          const std::string& ssl_session_cache_shard_arg)
  45       : cert_verifier(cert_verifier_arg),
  46         channel_id_service(channel_id_service_arg),
  47         transport_security_state(transport_security_state_arg),
  48         cert_transparency_verifier(cert_transparency_verifier_arg),
  49         cert_policy_enforcer(cert_policy_enforcer_arg),
  50         ssl_session_cache_shard(ssl_session_cache_shard_arg) {}
  51
  52   CertVerifier* cert_verifier;
  53   ChannelIDService* channel_id_service;
  54   TransportSecurityState* transport_security_state;
  55   CTVerifier* cert_transparency_verifier;
  56   CertPolicyEnforcer* cert_policy_enforcer;
  57   // ssl_session_cache_shard is an opaque string that identifies a shard of the
  58   // SSL session cache. SSL sockets with the same ssl_session_cache_shard may
  59   // resume each other's SSL sessions but we'll never sessions between shards.
  60   const std::string ssl_session_cache_shard;
  61 };
  62
  63 // A client socket that uses SSL as the transport layer.
  64 //
  65 // NOTE: The SSL handshake occurs within the Connect method after a TCP
  66 // connection is established.  If a SSL error occurs during the handshake,
  67 // Connect will fail.
  68 //
  69 class NET_EXPORT SSLClientSocket : public SSLSocket {
  70  public:
  71   SSLClientSocket();
  72
  73   // Next Protocol Negotiation (NPN) allows a TLS client and server to come to
  74   // an agreement about the application level protocol to speak over a
  75   // connection.
  76   enum NextProtoStatus {
  77     // WARNING: These values are serialized to disk. Don't change them.
  78
  79     kNextProtoUnsupported = 0,  // The server doesn't support NPN.
  80     kNextProtoNegotiated = 1,   // We agreed on a protocol.
  81     kNextProtoNoOverlap = 2,    // No protocols in common. We requested
  82                                 // the first protocol in our list.
  83   };
  84
  85   // TLS extension used to negotiate protocol.
  86   enum SSLNegotiationExtension {
  87     kExtensionUnknown,
  88     kExtensionALPN,
  89     kExtensionNPN,
  90   };
  91
  92   // StreamSocket:
  93   bool WasNpnNegotiated() const override;
  94   NextProto GetNegotiatedProtocol() const override;
  95
  96   // Gets the SSL CertificateRequest info of the socket after Connect failed
  97   // with ERR_SSL_CLIENT_AUTH_CERT_NEEDED.
  98   virtual void GetSSLCertRequestInfo(
  99       SSLCertRequestInfo* cert_request_info) = 0;
 100
 101   // Get the application level protocol that we negotiated with the server.
 102   // *proto is set to the resulting protocol (n.b. that the string may have
 103   // embedded NULs).
 104   //   kNextProtoUnsupported: *proto is cleared.
 105   //   kNextProtoNegotiated:  *proto is set to the negotiated protocol.
 106   //   kNextProtoNoOverlap:   *proto is set to the first protocol in the
 107   //                          supported list.
 108   virtual NextProtoStatus GetNextProto(std::string* proto) = 0;
 109
 110   static NextProto NextProtoFromString(const std::string& proto_string);
 111
 112   static const char* NextProtoToString(NextProto next_proto);
 113
 114   static const char* NextProtoStatusToString(const NextProtoStatus status);
 115
 116   // Returns true if |error| is OK or |load_flags| ignores certificate errors
 117   // and |error| is a certificate error.
 118   static bool IgnoreCertError(int error, int load_flags);
 119
 120   // ClearSessionCache clears the SSL session cache, used to resume SSL
 121   // sessions.
 122   static void ClearSessionCache();
 123
 124   // Get the maximum SSL version supported by the underlying library and
 125   // cryptographic implementation.
 126   static uint16 GetMaxSupportedSSLVersion();
 127
 128   virtual bool set_was_npn_negotiated(bool negotiated);
 129
 130   virtual bool was_spdy_negotiated() const;
 131
 132   virtual bool set_was_spdy_negotiated(bool negotiated);
 133
 134   virtual void set_protocol_negotiated(NextProto protocol_negotiated);
 135
 136   void set_negotiation_extension(SSLNegotiationExtension negotiation_extension);
 137
 138   // Returns the ChannelIDService used by this socket, or NULL if
 139   // channel ids are not supported.
 140   virtual ChannelIDService* GetChannelIDService() const = 0;
 141
 142   // Returns true if a channel ID was sent on this connection.
 143   // This may be useful for protocols, like SPDY, which allow the same
 144   // connection to be shared between multiple domains, each of which need
 145   // a channel ID.
 146   //
 147   // Public for ssl_client_socket_openssl_unittest.cc.
 148   virtual bool WasChannelIDSent() const;
 149
 150   // Record which TLS extension was used to negotiate protocol and protocol
 151   // chosen in a UMA histogram.
 152   void RecordNegotiationExtension();
 153
 154  protected:
 155   virtual void set_channel_id_sent(bool channel_id_sent);
 156
 157   virtual void set_signed_cert_timestamps_received(
 158       bool signed_cert_timestamps_received);
 159
 160   virtual void set_stapled_ocsp_response_received(
 161       bool stapled_ocsp_response_received);
 162
 163   // Records histograms for channel id support during full handshakes - resumed
 164   // handshakes are ignored.
 165   static void RecordChannelIDSupport(
 166       ChannelIDService* channel_id_service,
 167       bool negotiated_channel_id,
 168       bool channel_id_enabled,
 169       bool supports_ecc);
 170
 171   // Returns whether TLS channel ID is enabled.
 172   static bool IsChannelIDEnabled(
 173       const SSLConfig& ssl_config,
 174       ChannelIDService* channel_id_service);
 175
 176   // Determine if there is at least one enabled cipher suite that satisfies
 177   // Section 9.2 of the HTTP/2 specification.  Note that the server might still
 178   // pick an inadequate cipher suite.
 179   static bool HasCipherAdequateForHTTP2(
 180       const std::vector<uint16>& cipher_suites);
 181
 182   // Determine if the TLS version required by Section 9.2 of the HTTP/2
 183   // specification is enabled.  Note that the server might still pick an
 184   // inadequate TLS version.
 185   static bool IsTLSVersionAdequateForHTTP2(const SSLConfig& ssl_config);
 186
 187   // Serializes |next_protos| in the wire format for ALPN: protocols are listed
 188   // in order, each prefixed by a one-byte length.  Any HTTP/2 protocols in
 189   // |next_protos| are ignored if |can_advertise_http2| is false.
 190   static std::vector<uint8_t> SerializeNextProtos(
 191       const NextProtoVector& next_protos,
 192       bool can_advertise_http2);
 193
 194   // For unit testing only.
 195   // Returns the unverified certificate chain as presented by server.
 196   // Note that chain may be different than the verified chain returned by
 197   // StreamSocket::GetSSLInfo().
 198   virtual scoped_refptr<X509Certificate> GetUnverifiedServerCertificateChain()
 199       const = 0;
 200
 201  private:
 202   FRIEND_TEST_ALL_PREFIXES(SSLClientSocket, SerializeNextProtos);
 203   // For signed_cert_timestamps_received_ and stapled_ocsp_response_received_.
 204   FRIEND_TEST_ALL_PREFIXES(SSLClientSocketTest,
 205                            ConnectSignedCertTimestampsEnabledTLSExtension);
 206   FRIEND_TEST_ALL_PREFIXES(SSLClientSocketTest,
 207                            ConnectSignedCertTimestampsEnabledOCSP);
 208   FRIEND_TEST_ALL_PREFIXES(SSLClientSocketTest,
 209                            ConnectSignedCertTimestampsDisabled);
 210   FRIEND_TEST_ALL_PREFIXES(SSLClientSocketTest,
 211                            VerifyServerChainProperlyOrdered);
 212
 213   // True if NPN was responded to, independent of selecting SPDY or HTTP.
 214   bool was_npn_negotiated_;
 215   // True if NPN successfully negotiated SPDY.
 216   bool was_spdy_negotiated_;
 217   // Protocol that we negotiated with the server.
 218   NextProto protocol_negotiated_;
 219   // True if a channel ID was sent.
 220   bool channel_id_sent_;
 221   // True if SCTs were received via a TLS extension.
 222   bool signed_cert_timestamps_received_;
 223   // True if a stapled OCSP response was received.
 224   bool stapled_ocsp_response_received_;
 225   // Protocol negotiation extension used.
 226   SSLNegotiationExtension negotiation_extension_;
 227 };
 228
 229 }  // namespace net
 230
 231 #endif  // NET_SOCKET_SSL_CLIENT_SOCKET_H_