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