Black Lives Matter. Support the Equal Justice Initiative.

Source file src/crypto/tls/common.go

Documentation: crypto/tls

     1  // Copyright 2009 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package tls
     6  
     7  import (
     8  	"bytes"
     9  	"container/list"
    10  	"context"
    11  	"crypto"
    12  	"crypto/ecdsa"
    13  	"crypto/ed25519"
    14  	"crypto/elliptic"
    15  	"crypto/rand"
    16  	"crypto/rsa"
    17  	"crypto/sha512"
    18  	"crypto/x509"
    19  	"errors"
    20  	"fmt"
    21  	"io"
    22  	"net"
    23  	"strings"
    24  	"sync"
    25  	"time"
    26  )
    27  
    28  const (
    29  	VersionTLS10 = 0x0301
    30  	VersionTLS11 = 0x0302
    31  	VersionTLS12 = 0x0303
    32  	VersionTLS13 = 0x0304
    33  
    34  	// Deprecated: SSLv3 is cryptographically broken, and is no longer
    35  	// supported by this package. See golang.org/issue/32716.
    36  	VersionSSL30 = 0x0300
    37  )
    38  
    39  const (
    40  	maxPlaintext       = 16384        // maximum plaintext payload length
    41  	maxCiphertext      = 16384 + 2048 // maximum ciphertext payload length
    42  	maxCiphertextTLS13 = 16384 + 256  // maximum ciphertext length in TLS 1.3
    43  	recordHeaderLen    = 5            // record header length
    44  	maxHandshake       = 65536        // maximum handshake we support (protocol max is 16 MB)
    45  	maxUselessRecords  = 16           // maximum number of consecutive non-advancing records
    46  )
    47  
    48  // TLS record types.
    49  type recordType uint8
    50  
    51  const (
    52  	recordTypeChangeCipherSpec recordType = 20
    53  	recordTypeAlert            recordType = 21
    54  	recordTypeHandshake        recordType = 22
    55  	recordTypeApplicationData  recordType = 23
    56  )
    57  
    58  // TLS handshake message types.
    59  const (
    60  	typeHelloRequest        uint8 = 0
    61  	typeClientHello         uint8 = 1
    62  	typeServerHello         uint8 = 2
    63  	typeNewSessionTicket    uint8 = 4
    64  	typeEndOfEarlyData      uint8 = 5
    65  	typeEncryptedExtensions uint8 = 8
    66  	typeCertificate         uint8 = 11
    67  	typeServerKeyExchange   uint8 = 12
    68  	typeCertificateRequest  uint8 = 13
    69  	typeServerHelloDone     uint8 = 14
    70  	typeCertificateVerify   uint8 = 15
    71  	typeClientKeyExchange   uint8 = 16
    72  	typeFinished            uint8 = 20
    73  	typeCertificateStatus   uint8 = 22
    74  	typeKeyUpdate           uint8 = 24
    75  	typeNextProtocol        uint8 = 67  // Not IANA assigned
    76  	typeMessageHash         uint8 = 254 // synthetic message
    77  )
    78  
    79  // TLS compression types.
    80  const (
    81  	compressionNone uint8 = 0
    82  )
    83  
    84  // TLS extension numbers
    85  const (
    86  	extensionServerName              uint16 = 0
    87  	extensionStatusRequest           uint16 = 5
    88  	extensionSupportedCurves         uint16 = 10 // supported_groups in TLS 1.3, see RFC 8446, Section 4.2.7
    89  	extensionSupportedPoints         uint16 = 11
    90  	extensionSignatureAlgorithms     uint16 = 13
    91  	extensionALPN                    uint16 = 16
    92  	extensionSCT                     uint16 = 18
    93  	extensionSessionTicket           uint16 = 35
    94  	extensionPreSharedKey            uint16 = 41
    95  	extensionEarlyData               uint16 = 42
    96  	extensionSupportedVersions       uint16 = 43
    97  	extensionCookie                  uint16 = 44
    98  	extensionPSKModes                uint16 = 45
    99  	extensionCertificateAuthorities  uint16 = 47
   100  	extensionSignatureAlgorithmsCert uint16 = 50
   101  	extensionKeyShare                uint16 = 51
   102  	extensionRenegotiationInfo       uint16 = 0xff01
   103  )
   104  
   105  // TLS signaling cipher suite values
   106  const (
   107  	scsvRenegotiation uint16 = 0x00ff
   108  )
   109  
   110  // CurveID is the type of a TLS identifier for an elliptic curve. See
   111  // https://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-8.
   112  //
   113  // In TLS 1.3, this type is called NamedGroup, but at this time this library
   114  // only supports Elliptic Curve based groups. See RFC 8446, Section 4.2.7.
   115  type CurveID uint16
   116  
   117  const (
   118  	CurveP256 CurveID = 23
   119  	CurveP384 CurveID = 24
   120  	CurveP521 CurveID = 25
   121  	X25519    CurveID = 29
   122  )
   123  
   124  // TLS 1.3 Key Share. See RFC 8446, Section 4.2.8.
   125  type keyShare struct {
   126  	group CurveID
   127  	data  []byte
   128  }
   129  
   130  // TLS 1.3 PSK Key Exchange Modes. See RFC 8446, Section 4.2.9.
   131  const (
   132  	pskModePlain uint8 = 0
   133  	pskModeDHE   uint8 = 1
   134  )
   135  
   136  // TLS 1.3 PSK Identity. Can be a Session Ticket, or a reference to a saved
   137  // session. See RFC 8446, Section 4.2.11.
   138  type pskIdentity struct {
   139  	label               []byte
   140  	obfuscatedTicketAge uint32
   141  }
   142  
   143  // TLS Elliptic Curve Point Formats
   144  // https://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-9
   145  const (
   146  	pointFormatUncompressed uint8 = 0
   147  )
   148  
   149  // TLS CertificateStatusType (RFC 3546)
   150  const (
   151  	statusTypeOCSP uint8 = 1
   152  )
   153  
   154  // Certificate types (for certificateRequestMsg)
   155  const (
   156  	certTypeRSASign   = 1
   157  	certTypeECDSASign = 64 // ECDSA or EdDSA keys, see RFC 8422, Section 3.
   158  )
   159  
   160  // Signature algorithms (for internal signaling use). Starting at 225 to avoid overlap with
   161  // TLS 1.2 codepoints (RFC 5246, Appendix A.4.1), with which these have nothing to do.
   162  const (
   163  	signaturePKCS1v15 uint8 = iota + 225
   164  	signatureRSAPSS
   165  	signatureECDSA
   166  	signatureEd25519
   167  )
   168  
   169  // directSigning is a standard Hash value that signals that no pre-hashing
   170  // should be performed, and that the input should be signed directly. It is the
   171  // hash function associated with the Ed25519 signature scheme.
   172  var directSigning crypto.Hash = 0
   173  
   174  // supportedSignatureAlgorithms contains the signature and hash algorithms that
   175  // the code advertises as supported in a TLS 1.2+ ClientHello and in a TLS 1.2+
   176  // CertificateRequest. The two fields are merged to match with TLS 1.3.
   177  // Note that in TLS 1.2, the ECDSA algorithms are not constrained to P-256, etc.
   178  var supportedSignatureAlgorithms = []SignatureScheme{
   179  	PSSWithSHA256,
   180  	ECDSAWithP256AndSHA256,
   181  	Ed25519,
   182  	PSSWithSHA384,
   183  	PSSWithSHA512,
   184  	PKCS1WithSHA256,
   185  	PKCS1WithSHA384,
   186  	PKCS1WithSHA512,
   187  	ECDSAWithP384AndSHA384,
   188  	ECDSAWithP521AndSHA512,
   189  	PKCS1WithSHA1,
   190  	ECDSAWithSHA1,
   191  }
   192  
   193  // helloRetryRequestRandom is set as the Random value of a ServerHello
   194  // to signal that the message is actually a HelloRetryRequest.
   195  var helloRetryRequestRandom = []byte{ // See RFC 8446, Section 4.1.3.
   196  	0xCF, 0x21, 0xAD, 0x74, 0xE5, 0x9A, 0x61, 0x11,
   197  	0xBE, 0x1D, 0x8C, 0x02, 0x1E, 0x65, 0xB8, 0x91,
   198  	0xC2, 0xA2, 0x11, 0x16, 0x7A, 0xBB, 0x8C, 0x5E,
   199  	0x07, 0x9E, 0x09, 0xE2, 0xC8, 0xA8, 0x33, 0x9C,
   200  }
   201  
   202  const (
   203  	// downgradeCanaryTLS12 or downgradeCanaryTLS11 is embedded in the server
   204  	// random as a downgrade protection if the server would be capable of
   205  	// negotiating a higher version. See RFC 8446, Section 4.1.3.
   206  	downgradeCanaryTLS12 = "DOWNGRD\x01"
   207  	downgradeCanaryTLS11 = "DOWNGRD\x00"
   208  )
   209  
   210  // testingOnlyForceDowngradeCanary is set in tests to force the server side to
   211  // include downgrade canaries even if it's using its highers supported version.
   212  var testingOnlyForceDowngradeCanary bool
   213  
   214  // ConnectionState records basic TLS details about the connection.
   215  type ConnectionState struct {
   216  	// Version is the TLS version used by the connection (e.g. VersionTLS12).
   217  	Version uint16
   218  
   219  	// HandshakeComplete is true if the handshake has concluded.
   220  	HandshakeComplete bool
   221  
   222  	// DidResume is true if this connection was successfully resumed from a
   223  	// previous session with a session ticket or similar mechanism.
   224  	DidResume bool
   225  
   226  	// CipherSuite is the cipher suite negotiated for the connection (e.g.
   227  	// TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_AES_128_GCM_SHA256).
   228  	CipherSuite uint16
   229  
   230  	// NegotiatedProtocol is the application protocol negotiated with ALPN.
   231  	NegotiatedProtocol string
   232  
   233  	// NegotiatedProtocolIsMutual used to indicate a mutual NPN negotiation.
   234  	//
   235  	// Deprecated: this value is always true.
   236  	NegotiatedProtocolIsMutual bool
   237  
   238  	// ServerName is the value of the Server Name Indication extension sent by
   239  	// the client. It's available both on the server and on the client side.
   240  	ServerName string
   241  
   242  	// PeerCertificates are the parsed certificates sent by the peer, in the
   243  	// order in which they were sent. The first element is the leaf certificate
   244  	// that the connection is verified against.
   245  	//
   246  	// On the client side, it can't be empty. On the server side, it can be
   247  	// empty if Config.ClientAuth is not RequireAnyClientCert or
   248  	// RequireAndVerifyClientCert.
   249  	PeerCertificates []*x509.Certificate
   250  
   251  	// VerifiedChains is a list of one or more chains where the first element is
   252  	// PeerCertificates[0] and the last element is from Config.RootCAs (on the
   253  	// client side) or Config.ClientCAs (on the server side).
   254  	//
   255  	// On the client side, it's set if Config.InsecureSkipVerify is false. On
   256  	// the server side, it's set if Config.ClientAuth is VerifyClientCertIfGiven
   257  	// (and the peer provided a certificate) or RequireAndVerifyClientCert.
   258  	VerifiedChains [][]*x509.Certificate
   259  
   260  	// SignedCertificateTimestamps is a list of SCTs provided by the peer
   261  	// through the TLS handshake for the leaf certificate, if any.
   262  	SignedCertificateTimestamps [][]byte
   263  
   264  	// OCSPResponse is a stapled Online Certificate Status Protocol (OCSP)
   265  	// response provided by the peer for the leaf certificate, if any.
   266  	OCSPResponse []byte
   267  
   268  	// TLSUnique contains the "tls-unique" channel binding value (see RFC 5929,
   269  	// Section 3). This value will be nil for TLS 1.3 connections and for all
   270  	// resumed connections.
   271  	//
   272  	// Deprecated: there are conditions in which this value might not be unique
   273  	// to a connection. See the Security Considerations sections of RFC 5705 and
   274  	// RFC 7627, and https://mitls.org/pages/attacks/3SHAKE#channelbindings.
   275  	TLSUnique []byte
   276  
   277  	// ekm is a closure exposed via ExportKeyingMaterial.
   278  	ekm func(label string, context []byte, length int) ([]byte, error)
   279  }
   280  
   281  // ExportKeyingMaterial returns length bytes of exported key material in a new
   282  // slice as defined in RFC 5705. If context is nil, it is not used as part of
   283  // the seed. If the connection was set to allow renegotiation via
   284  // Config.Renegotiation, this function will return an error.
   285  func (cs *ConnectionState) ExportKeyingMaterial(label string, context []byte, length int) ([]byte, error) {
   286  	return cs.ekm(label, context, length)
   287  }
   288  
   289  // ClientAuthType declares the policy the server will follow for
   290  // TLS Client Authentication.
   291  type ClientAuthType int
   292  
   293  const (
   294  	// NoClientCert indicates that no client certificate should be requested
   295  	// during the handshake, and if any certificates are sent they will not
   296  	// be verified.
   297  	NoClientCert ClientAuthType = iota
   298  	// RequestClientCert indicates that a client certificate should be requested
   299  	// during the handshake, but does not require that the client send any
   300  	// certificates.
   301  	RequestClientCert
   302  	// RequireAnyClientCert indicates that a client certificate should be requested
   303  	// during the handshake, and that at least one certificate is required to be
   304  	// sent by the client, but that certificate is not required to be valid.
   305  	RequireAnyClientCert
   306  	// VerifyClientCertIfGiven indicates that a client certificate should be requested
   307  	// during the handshake, but does not require that the client sends a
   308  	// certificate. If the client does send a certificate it is required to be
   309  	// valid.
   310  	VerifyClientCertIfGiven
   311  	// RequireAndVerifyClientCert indicates that a client certificate should be requested
   312  	// during the handshake, and that at least one valid certificate is required
   313  	// to be sent by the client.
   314  	RequireAndVerifyClientCert
   315  )
   316  
   317  // requiresClientCert reports whether the ClientAuthType requires a client
   318  // certificate to be provided.
   319  func requiresClientCert(c ClientAuthType) bool {
   320  	switch c {
   321  	case RequireAnyClientCert, RequireAndVerifyClientCert:
   322  		return true
   323  	default:
   324  		return false
   325  	}
   326  }
   327  
   328  // ClientSessionState contains the state needed by clients to resume TLS
   329  // sessions.
   330  type ClientSessionState struct {
   331  	sessionTicket      []uint8               // Encrypted ticket used for session resumption with server
   332  	vers               uint16                // TLS version negotiated for the session
   333  	cipherSuite        uint16                // Ciphersuite negotiated for the session
   334  	masterSecret       []byte                // Full handshake MasterSecret, or TLS 1.3 resumption_master_secret
   335  	serverCertificates []*x509.Certificate   // Certificate chain presented by the server
   336  	verifiedChains     [][]*x509.Certificate // Certificate chains we built for verification
   337  	receivedAt         time.Time             // When the session ticket was received from the server
   338  	ocspResponse       []byte                // Stapled OCSP response presented by the server
   339  	scts               [][]byte              // SCTs presented by the server
   340  
   341  	// TLS 1.3 fields.
   342  	nonce  []byte    // Ticket nonce sent by the server, to derive PSK
   343  	useBy  time.Time // Expiration of the ticket lifetime as set by the server
   344  	ageAdd uint32    // Random obfuscation factor for sending the ticket age
   345  }
   346  
   347  // ClientSessionCache is a cache of ClientSessionState objects that can be used
   348  // by a client to resume a TLS session with a given server. ClientSessionCache
   349  // implementations should expect to be called concurrently from different
   350  // goroutines. Up to TLS 1.2, only ticket-based resumption is supported, not
   351  // SessionID-based resumption. In TLS 1.3 they were merged into PSK modes, which
   352  // are supported via this interface.
   353  type ClientSessionCache interface {
   354  	// Get searches for a ClientSessionState associated with the given key.
   355  	// On return, ok is true if one was found.
   356  	Get(sessionKey string) (session *ClientSessionState, ok bool)
   357  
   358  	// Put adds the ClientSessionState to the cache with the given key. It might
   359  	// get called multiple times in a connection if a TLS 1.3 server provides
   360  	// more than one session ticket. If called with a nil *ClientSessionState,
   361  	// it should remove the cache entry.
   362  	Put(sessionKey string, cs *ClientSessionState)
   363  }
   364  
   365  //go:generate stringer -type=SignatureScheme,CurveID,ClientAuthType -output=common_string.go
   366  
   367  // SignatureScheme identifies a signature algorithm supported by TLS. See
   368  // RFC 8446, Section 4.2.3.
   369  type SignatureScheme uint16
   370  
   371  const (
   372  	// RSASSA-PKCS1-v1_5 algorithms.
   373  	PKCS1WithSHA256 SignatureScheme = 0x0401
   374  	PKCS1WithSHA384 SignatureScheme = 0x0501
   375  	PKCS1WithSHA512 SignatureScheme = 0x0601
   376  
   377  	// RSASSA-PSS algorithms with public key OID rsaEncryption.
   378  	PSSWithSHA256 SignatureScheme = 0x0804
   379  	PSSWithSHA384 SignatureScheme = 0x0805
   380  	PSSWithSHA512 SignatureScheme = 0x0806
   381  
   382  	// ECDSA algorithms. Only constrained to a specific curve in TLS 1.3.
   383  	ECDSAWithP256AndSHA256 SignatureScheme = 0x0403
   384  	ECDSAWithP384AndSHA384 SignatureScheme = 0x0503
   385  	ECDSAWithP521AndSHA512 SignatureScheme = 0x0603
   386  
   387  	// EdDSA algorithms.
   388  	Ed25519 SignatureScheme = 0x0807
   389  
   390  	// Legacy signature and hash algorithms for TLS 1.2.
   391  	PKCS1WithSHA1 SignatureScheme = 0x0201
   392  	ECDSAWithSHA1 SignatureScheme = 0x0203
   393  )
   394  
   395  // ClientHelloInfo contains information from a ClientHello message in order to
   396  // guide application logic in the GetCertificate and GetConfigForClient callbacks.
   397  type ClientHelloInfo struct {
   398  	// CipherSuites lists the CipherSuites supported by the client (e.g.
   399  	// TLS_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256).
   400  	CipherSuites []uint16
   401  
   402  	// ServerName indicates the name of the server requested by the client
   403  	// in order to support virtual hosting. ServerName is only set if the
   404  	// client is using SNI (see RFC 4366, Section 3.1).
   405  	ServerName string
   406  
   407  	// SupportedCurves lists the elliptic curves supported by the client.
   408  	// SupportedCurves is set only if the Supported Elliptic Curves
   409  	// Extension is being used (see RFC 4492, Section 5.1.1).
   410  	SupportedCurves []CurveID
   411  
   412  	// SupportedPoints lists the point formats supported by the client.
   413  	// SupportedPoints is set only if the Supported Point Formats Extension
   414  	// is being used (see RFC 4492, Section 5.1.2).
   415  	SupportedPoints []uint8
   416  
   417  	// SignatureSchemes lists the signature and hash schemes that the client
   418  	// is willing to verify. SignatureSchemes is set only if the Signature
   419  	// Algorithms Extension is being used (see RFC 5246, Section 7.4.1.4.1).
   420  	SignatureSchemes []SignatureScheme
   421  
   422  	// SupportedProtos lists the application protocols supported by the client.
   423  	// SupportedProtos is set only if the Application-Layer Protocol
   424  	// Negotiation Extension is being used (see RFC 7301, Section 3.1).
   425  	//
   426  	// Servers can select a protocol by setting Config.NextProtos in a
   427  	// GetConfigForClient return value.
   428  	SupportedProtos []string
   429  
   430  	// SupportedVersions lists the TLS versions supported by the client.
   431  	// For TLS versions less than 1.3, this is extrapolated from the max
   432  	// version advertised by the client, so values other than the greatest
   433  	// might be rejected if used.
   434  	SupportedVersions []uint16
   435  
   436  	// Conn is the underlying net.Conn for the connection. Do not read
   437  	// from, or write to, this connection; that will cause the TLS
   438  	// connection to fail.
   439  	Conn net.Conn
   440  
   441  	// config is embedded by the GetCertificate or GetConfigForClient caller,
   442  	// for use with SupportsCertificate.
   443  	config *Config
   444  
   445  	// ctx is the context of the handshake that is in progress.
   446  	ctx context.Context
   447  }
   448  
   449  // Context returns the context of the handshake that is in progress.
   450  // This context is a child of the context passed to HandshakeContext,
   451  // if any, and is canceled when the handshake concludes.
   452  func (c *ClientHelloInfo) Context() context.Context {
   453  	return c.ctx
   454  }
   455  
   456  // CertificateRequestInfo contains information from a server's
   457  // CertificateRequest message, which is used to demand a certificate and proof
   458  // of control from a client.
   459  type CertificateRequestInfo struct {
   460  	// AcceptableCAs contains zero or more, DER-encoded, X.501
   461  	// Distinguished Names. These are the names of root or intermediate CAs
   462  	// that the server wishes the returned certificate to be signed by. An
   463  	// empty slice indicates that the server has no preference.
   464  	AcceptableCAs [][]byte
   465  
   466  	// SignatureSchemes lists the signature schemes that the server is
   467  	// willing to verify.
   468  	SignatureSchemes []SignatureScheme
   469  
   470  	// Version is the TLS version that was negotiated for this connection.
   471  	Version uint16
   472  
   473  	// ctx is the context of the handshake that is in progress.
   474  	ctx context.Context
   475  }
   476  
   477  // Context returns the context of the handshake that is in progress.
   478  // This context is a child of the context passed to HandshakeContext,
   479  // if any, and is canceled when the handshake concludes.
   480  func (c *CertificateRequestInfo) Context() context.Context {
   481  	return c.ctx
   482  }
   483  
   484  // RenegotiationSupport enumerates the different levels of support for TLS
   485  // renegotiation. TLS renegotiation is the act of performing subsequent
   486  // handshakes on a connection after the first. This significantly complicates
   487  // the state machine and has been the source of numerous, subtle security
   488  // issues. Initiating a renegotiation is not supported, but support for
   489  // accepting renegotiation requests may be enabled.
   490  //
   491  // Even when enabled, the server may not change its identity between handshakes
   492  // (i.e. the leaf certificate must be the same). Additionally, concurrent
   493  // handshake and application data flow is not permitted so renegotiation can
   494  // only be used with protocols that synchronise with the renegotiation, such as
   495  // HTTPS.
   496  //
   497  // Renegotiation is not defined in TLS 1.3.
   498  type RenegotiationSupport int
   499  
   500  const (
   501  	// RenegotiateNever disables renegotiation.
   502  	RenegotiateNever RenegotiationSupport = iota
   503  
   504  	// RenegotiateOnceAsClient allows a remote server to request
   505  	// renegotiation once per connection.
   506  	RenegotiateOnceAsClient
   507  
   508  	// RenegotiateFreelyAsClient allows a remote server to repeatedly
   509  	// request renegotiation.
   510  	RenegotiateFreelyAsClient
   511  )
   512  
   513  // A Config structure is used to configure a TLS client or server.
   514  // After one has been passed to a TLS function it must not be
   515  // modified. A Config may be reused; the tls package will also not
   516  // modify it.
   517  type Config struct {
   518  	// Rand provides the source of entropy for nonces and RSA blinding.
   519  	// If Rand is nil, TLS uses the cryptographic random reader in package
   520  	// crypto/rand.
   521  	// The Reader must be safe for use by multiple goroutines.
   522  	Rand io.Reader
   523  
   524  	// Time returns the current time as the number of seconds since the epoch.
   525  	// If Time is nil, TLS uses time.Now.
   526  	Time func() time.Time
   527  
   528  	// Certificates contains one or more certificate chains to present to the
   529  	// other side of the connection. The first certificate compatible with the
   530  	// peer's requirements is selected automatically.
   531  	//
   532  	// Server configurations must set one of Certificates, GetCertificate or
   533  	// GetConfigForClient. Clients doing client-authentication may set either
   534  	// Certificates or GetClientCertificate.
   535  	//
   536  	// Note: if there are multiple Certificates, and they don't have the
   537  	// optional field Leaf set, certificate selection will incur a significant
   538  	// per-handshake performance cost.
   539  	Certificates []Certificate
   540  
   541  	// NameToCertificate maps from a certificate name to an element of
   542  	// Certificates. Note that a certificate name can be of the form
   543  	// '*.example.com' and so doesn't have to be a domain name as such.
   544  	//
   545  	// Deprecated: NameToCertificate only allows associating a single
   546  	// certificate with a given name. Leave this field nil to let the library
   547  	// select the first compatible chain from Certificates.
   548  	NameToCertificate map[string]*Certificate
   549  
   550  	// GetCertificate returns a Certificate based on the given
   551  	// ClientHelloInfo. It will only be called if the client supplies SNI
   552  	// information or if Certificates is empty.
   553  	//
   554  	// If GetCertificate is nil or returns nil, then the certificate is
   555  	// retrieved from NameToCertificate. If NameToCertificate is nil, the
   556  	// best element of Certificates will be used.
   557  	GetCertificate func(*ClientHelloInfo) (*Certificate, error)
   558  
   559  	// GetClientCertificate, if not nil, is called when a server requests a
   560  	// certificate from a client. If set, the contents of Certificates will
   561  	// be ignored.
   562  	//
   563  	// If GetClientCertificate returns an error, the handshake will be
   564  	// aborted and that error will be returned. Otherwise
   565  	// GetClientCertificate must return a non-nil Certificate. If
   566  	// Certificate.Certificate is empty then no certificate will be sent to
   567  	// the server. If this is unacceptable to the server then it may abort
   568  	// the handshake.
   569  	//
   570  	// GetClientCertificate may be called multiple times for the same
   571  	// connection if renegotiation occurs or if TLS 1.3 is in use.
   572  	GetClientCertificate func(*CertificateRequestInfo) (*Certificate, error)
   573  
   574  	// GetConfigForClient, if not nil, is called after a ClientHello is
   575  	// received from a client. It may return a non-nil Config in order to
   576  	// change the Config that will be used to handle this connection. If
   577  	// the returned Config is nil, the original Config will be used. The
   578  	// Config returned by this callback may not be subsequently modified.
   579  	//
   580  	// If GetConfigForClient is nil, the Config passed to Server() will be
   581  	// used for all connections.
   582  	//
   583  	// If SessionTicketKey was explicitly set on the returned Config, or if
   584  	// SetSessionTicketKeys was called on the returned Config, those keys will
   585  	// be used. Otherwise, the original Config keys will be used (and possibly
   586  	// rotated if they are automatically managed).
   587  	GetConfigForClient func(*ClientHelloInfo) (*Config, error)
   588  
   589  	// VerifyPeerCertificate, if not nil, is called after normal
   590  	// certificate verification by either a TLS client or server. It
   591  	// receives the raw ASN.1 certificates provided by the peer and also
   592  	// any verified chains that normal processing found. If it returns a
   593  	// non-nil error, the handshake is aborted and that error results.
   594  	//
   595  	// If normal verification fails then the handshake will abort before
   596  	// considering this callback. If normal verification is disabled by
   597  	// setting InsecureSkipVerify, or (for a server) when ClientAuth is
   598  	// RequestClientCert or RequireAnyClientCert, then this callback will
   599  	// be considered but the verifiedChains argument will always be nil.
   600  	VerifyPeerCertificate func(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error
   601  
   602  	// VerifyConnection, if not nil, is called after normal certificate
   603  	// verification and after VerifyPeerCertificate by either a TLS client
   604  	// or server. If it returns a non-nil error, the handshake is aborted
   605  	// and that error results.
   606  	//
   607  	// If normal verification fails then the handshake will abort before
   608  	// considering this callback. This callback will run for all connections
   609  	// regardless of InsecureSkipVerify or ClientAuth settings.
   610  	VerifyConnection func(ConnectionState) error
   611  
   612  	// RootCAs defines the set of root certificate authorities
   613  	// that clients use when verifying server certificates.
   614  	// If RootCAs is nil, TLS uses the host's root CA set.
   615  	RootCAs *x509.CertPool
   616  
   617  	// NextProtos is a list of supported application level protocols, in
   618  	// order of preference. If both peers support ALPN, the selected
   619  	// protocol will be one from this list, and the connection will fail
   620  	// if there is no mutually supported protocol. If NextProtos is empty
   621  	// or the peer doesn't support ALPN, the connection will succeed and
   622  	// ConnectionState.NegotiatedProtocol will be empty.
   623  	NextProtos []string
   624  
   625  	// ServerName is used to verify the hostname on the returned
   626  	// certificates unless InsecureSkipVerify is given. It is also included
   627  	// in the client's handshake to support virtual hosting unless it is
   628  	// an IP address.
   629  	ServerName string
   630  
   631  	// ClientAuth determines the server's policy for
   632  	// TLS Client Authentication. The default is NoClientCert.
   633  	ClientAuth ClientAuthType
   634  
   635  	// ClientCAs defines the set of root certificate authorities
   636  	// that servers use if required to verify a client certificate
   637  	// by the policy in ClientAuth.
   638  	ClientCAs *x509.CertPool
   639  
   640  	// InsecureSkipVerify controls whether a client verifies the server's
   641  	// certificate chain and host name. If InsecureSkipVerify is true, crypto/tls
   642  	// accepts any certificate presented by the server and any host name in that
   643  	// certificate. In this mode, TLS is susceptible to machine-in-the-middle
   644  	// attacks unless custom verification is used. This should be used only for
   645  	// testing or in combination with VerifyConnection or VerifyPeerCertificate.
   646  	InsecureSkipVerify bool
   647  
   648  	// CipherSuites is a list of enabled TLS 1.0–1.2 cipher suites. The order of
   649  	// the list is ignored. Note that TLS 1.3 ciphersuites are not configurable.
   650  	//
   651  	// If CipherSuites is nil, a safe default list is used. The default cipher
   652  	// suites might change over time.
   653  	CipherSuites []uint16
   654  
   655  	// PreferServerCipherSuites is a legacy field and has no effect.
   656  	//
   657  	// It used to control whether the server would follow the client's or the
   658  	// server's preference. Servers now select the best mutually supported
   659  	// cipher suite based on logic that takes into account inferred client
   660  	// hardware, server hardware, and security.
   661  	//
   662  	// Deprected: PreferServerCipherSuites is ignored.
   663  	PreferServerCipherSuites bool
   664  
   665  	// SessionTicketsDisabled may be set to true to disable session ticket and
   666  	// PSK (resumption) support. Note that on clients, session ticket support is
   667  	// also disabled if ClientSessionCache is nil.
   668  	SessionTicketsDisabled bool
   669  
   670  	// SessionTicketKey is used by TLS servers to provide session resumption.
   671  	// See RFC 5077 and the PSK mode of RFC 8446. If zero, it will be filled
   672  	// with random data before the first server handshake.
   673  	//
   674  	// Deprecated: if this field is left at zero, session ticket keys will be
   675  	// automatically rotated every day and dropped after seven days. For
   676  	// customizing the rotation schedule or synchronizing servers that are
   677  	// terminating connections for the same host, use SetSessionTicketKeys.
   678  	SessionTicketKey [32]byte
   679  
   680  	// ClientSessionCache is a cache of ClientSessionState entries for TLS
   681  	// session resumption. It is only used by clients.
   682  	ClientSessionCache ClientSessionCache
   683  
   684  	// MinVersion contains the minimum TLS version that is acceptable.
   685  	// If zero, TLS 1.0 is currently taken as the minimum.
   686  	MinVersion uint16
   687  
   688  	// MaxVersion contains the maximum TLS version that is acceptable.
   689  	// If zero, the maximum version supported by this package is used,
   690  	// which is currently TLS 1.3.
   691  	MaxVersion uint16
   692  
   693  	// CurvePreferences contains the elliptic curves that will be used in
   694  	// an ECDHE handshake, in preference order. If empty, the default will
   695  	// be used. The client will use the first preference as the type for
   696  	// its key share in TLS 1.3. This may change in the future.
   697  	CurvePreferences []CurveID
   698  
   699  	// DynamicRecordSizingDisabled disables adaptive sizing of TLS records.
   700  	// When true, the largest possible TLS record size is always used. When
   701  	// false, the size of TLS records may be adjusted in an attempt to
   702  	// improve latency.
   703  	DynamicRecordSizingDisabled bool
   704  
   705  	// Renegotiation controls what types of renegotiation are supported.
   706  	// The default, none, is correct for the vast majority of applications.
   707  	Renegotiation RenegotiationSupport
   708  
   709  	// KeyLogWriter optionally specifies a destination for TLS master secrets
   710  	// in NSS key log format that can be used to allow external programs
   711  	// such as Wireshark to decrypt TLS connections.
   712  	// See https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format.
   713  	// Use of KeyLogWriter compromises security and should only be
   714  	// used for debugging.
   715  	KeyLogWriter io.Writer
   716  
   717  	// mutex protects sessionTicketKeys and autoSessionTicketKeys.
   718  	mutex sync.RWMutex
   719  	// sessionTicketKeys contains zero or more ticket keys. If set, it means the
   720  	// the keys were set with SessionTicketKey or SetSessionTicketKeys. The
   721  	// first key is used for new tickets and any subsequent keys can be used to
   722  	// decrypt old tickets. The slice contents are not protected by the mutex
   723  	// and are immutable.
   724  	sessionTicketKeys []ticketKey
   725  	// autoSessionTicketKeys is like sessionTicketKeys but is owned by the
   726  	// auto-rotation logic. See Config.ticketKeys.
   727  	autoSessionTicketKeys []ticketKey
   728  }
   729  
   730  const (
   731  	// ticketKeyNameLen is the number of bytes of identifier that is prepended to
   732  	// an encrypted session ticket in order to identify the key used to encrypt it.
   733  	ticketKeyNameLen = 16
   734  
   735  	// ticketKeyLifetime is how long a ticket key remains valid and can be used to
   736  	// resume a client connection.
   737  	ticketKeyLifetime = 7 * 24 * time.Hour // 7 days
   738  
   739  	// ticketKeyRotation is how often the server should rotate the session ticket key
   740  	// that is used for new tickets.
   741  	ticketKeyRotation = 24 * time.Hour
   742  )
   743  
   744  // ticketKey is the internal representation of a session ticket key.
   745  type ticketKey struct {
   746  	// keyName is an opaque byte string that serves to identify the session
   747  	// ticket key. It's exposed as plaintext in every session ticket.
   748  	keyName [ticketKeyNameLen]byte
   749  	aesKey  [16]byte
   750  	hmacKey [16]byte
   751  	// created is the time at which this ticket key was created. See Config.ticketKeys.
   752  	created time.Time
   753  }
   754  
   755  // ticketKeyFromBytes converts from the external representation of a session
   756  // ticket key to a ticketKey. Externally, session ticket keys are 32 random
   757  // bytes and this function expands that into sufficient name and key material.
   758  func (c *Config) ticketKeyFromBytes(b [32]byte) (key ticketKey) {
   759  	hashed := sha512.Sum512(b[:])
   760  	copy(key.keyName[:], hashed[:ticketKeyNameLen])
   761  	copy(key.aesKey[:], hashed[ticketKeyNameLen:ticketKeyNameLen+16])
   762  	copy(key.hmacKey[:], hashed[ticketKeyNameLen+16:ticketKeyNameLen+32])
   763  	key.created = c.time()
   764  	return key
   765  }
   766  
   767  // maxSessionTicketLifetime is the maximum allowed lifetime of a TLS 1.3 session
   768  // ticket, and the lifetime we set for tickets we send.
   769  const maxSessionTicketLifetime = 7 * 24 * time.Hour
   770  
   771  // Clone returns a shallow clone of c or nil if c is nil. It is safe to clone a Config that is
   772  // being used concurrently by a TLS client or server.
   773  func (c *Config) Clone() *Config {
   774  	if c == nil {
   775  		return nil
   776  	}
   777  	c.mutex.RLock()
   778  	defer c.mutex.RUnlock()
   779  	return &Config{
   780  		Rand:                        c.Rand,
   781  		Time:                        c.Time,
   782  		Certificates:                c.Certificates,
   783  		NameToCertificate:           c.NameToCertificate,
   784  		GetCertificate:              c.GetCertificate,
   785  		GetClientCertificate:        c.GetClientCertificate,
   786  		GetConfigForClient:          c.GetConfigForClient,
   787  		VerifyPeerCertificate:       c.VerifyPeerCertificate,
   788  		VerifyConnection:            c.VerifyConnection,
   789  		RootCAs:                     c.RootCAs,
   790  		NextProtos:                  c.NextProtos,
   791  		ServerName:                  c.ServerName,
   792  		ClientAuth:                  c.ClientAuth,
   793  		ClientCAs:                   c.ClientCAs,
   794  		InsecureSkipVerify:          c.InsecureSkipVerify,
   795  		CipherSuites:                c.CipherSuites,
   796  		PreferServerCipherSuites:    c.PreferServerCipherSuites,
   797  		SessionTicketsDisabled:      c.SessionTicketsDisabled,
   798  		SessionTicketKey:            c.SessionTicketKey,
   799  		ClientSessionCache:          c.ClientSessionCache,
   800  		MinVersion:                  c.MinVersion,
   801  		MaxVersion:                  c.MaxVersion,
   802  		CurvePreferences:            c.CurvePreferences,
   803  		DynamicRecordSizingDisabled: c.DynamicRecordSizingDisabled,
   804  		Renegotiation:               c.Renegotiation,
   805  		KeyLogWriter:                c.KeyLogWriter,
   806  		sessionTicketKeys:           c.sessionTicketKeys,
   807  		autoSessionTicketKeys:       c.autoSessionTicketKeys,
   808  	}
   809  }
   810  
   811  // deprecatedSessionTicketKey is set as the prefix of SessionTicketKey if it was
   812  // randomized for backwards compatibility but is not in use.
   813  var deprecatedSessionTicketKey = []byte("DEPRECATED")
   814  
   815  // initLegacySessionTicketKeyRLocked ensures the legacy SessionTicketKey field is
   816  // randomized if empty, and that sessionTicketKeys is populated from it otherwise.
   817  func (c *Config) initLegacySessionTicketKeyRLocked() {
   818  	// Don't write if SessionTicketKey is already defined as our deprecated string,
   819  	// or if it is defined by the user but sessionTicketKeys is already set.
   820  	if c.SessionTicketKey != [32]byte{} &&
   821  		(bytes.HasPrefix(c.SessionTicketKey[:], deprecatedSessionTicketKey) || len(c.sessionTicketKeys) > 0) {
   822  		return
   823  	}
   824  
   825  	// We need to write some data, so get an exclusive lock and re-check any conditions.
   826  	c.mutex.RUnlock()
   827  	defer c.mutex.RLock()
   828  	c.mutex.Lock()
   829  	defer c.mutex.Unlock()
   830  	if c.SessionTicketKey == [32]byte{} {
   831  		if _, err := io.ReadFull(c.rand(), c.SessionTicketKey[:]); err != nil {
   832  			panic(fmt.Sprintf("tls: unable to generate random session ticket key: %v", err))
   833  		}
   834  		// Write the deprecated prefix at the beginning so we know we created
   835  		// it. This key with the DEPRECATED prefix isn't used as an actual
   836  		// session ticket key, and is only randomized in case the application
   837  		// reuses it for some reason.
   838  		copy(c.SessionTicketKey[:], deprecatedSessionTicketKey)
   839  	} else if !bytes.HasPrefix(c.SessionTicketKey[:], deprecatedSessionTicketKey) && len(c.sessionTicketKeys) == 0 {
   840  		c.sessionTicketKeys = []ticketKey{c.ticketKeyFromBytes(c.SessionTicketKey)}
   841  	}
   842  
   843  }
   844  
   845  // ticketKeys returns the ticketKeys for this connection.
   846  // If configForClient has explicitly set keys, those will
   847  // be returned. Otherwise, the keys on c will be used and
   848  // may be rotated if auto-managed.
   849  // During rotation, any expired session ticket keys are deleted from
   850  // c.sessionTicketKeys. If the session ticket key that is currently
   851  // encrypting tickets (ie. the first ticketKey in c.sessionTicketKeys)
   852  // is not fresh, then a new session ticket key will be
   853  // created and prepended to c.sessionTicketKeys.
   854  func (c *Config) ticketKeys(configForClient *Config) []ticketKey {
   855  	// If the ConfigForClient callback returned a Config with explicitly set
   856  	// keys, use those, otherwise just use the original Config.
   857  	if configForClient != nil {
   858  		configForClient.mutex.RLock()
   859  		if configForClient.SessionTicketsDisabled {
   860  			return nil
   861  		}
   862  		configForClient.initLegacySessionTicketKeyRLocked()
   863  		if len(configForClient.sessionTicketKeys) != 0 {
   864  			ret := configForClient.sessionTicketKeys
   865  			configForClient.mutex.RUnlock()
   866  			return ret
   867  		}
   868  		configForClient.mutex.RUnlock()
   869  	}
   870  
   871  	c.mutex.RLock()
   872  	defer c.mutex.RUnlock()
   873  	if c.SessionTicketsDisabled {
   874  		return nil
   875  	}
   876  	c.initLegacySessionTicketKeyRLocked()
   877  	if len(c.sessionTicketKeys) != 0 {
   878  		return c.sessionTicketKeys
   879  	}
   880  	// Fast path for the common case where the key is fresh enough.
   881  	if len(c.autoSessionTicketKeys) > 0 && c.time().Sub(c.autoSessionTicketKeys[0].created) < ticketKeyRotation {
   882  		return c.autoSessionTicketKeys
   883  	}
   884  
   885  	// autoSessionTicketKeys are managed by auto-rotation.
   886  	c.mutex.RUnlock()
   887  	defer c.mutex.RLock()
   888  	c.mutex.Lock()
   889  	defer c.mutex.Unlock()
   890  	// Re-check the condition in case it changed since obtaining the new lock.
   891  	if len(c.autoSessionTicketKeys) == 0 || c.time().Sub(c.autoSessionTicketKeys[0].created) >= ticketKeyRotation {
   892  		var newKey [32]byte
   893  		if _, err := io.ReadFull(c.rand(), newKey[:]); err != nil {
   894  			panic(fmt.Sprintf("unable to generate random session ticket key: %v", err))
   895  		}
   896  		valid := make([]ticketKey, 0, len(c.autoSessionTicketKeys)+1)
   897  		valid = append(valid, c.ticketKeyFromBytes(newKey))
   898  		for _, k := range c.autoSessionTicketKeys {
   899  			// While rotating the current key, also remove any expired ones.
   900  			if c.time().Sub(k.created) < ticketKeyLifetime {
   901  				valid = append(valid, k)
   902  			}
   903  		}
   904  		c.autoSessionTicketKeys = valid
   905  	}
   906  	return c.autoSessionTicketKeys
   907  }
   908  
   909  // SetSessionTicketKeys updates the session ticket keys for a server.
   910  //
   911  // The first key will be used when creating new tickets, while all keys can be
   912  // used for decrypting tickets. It is safe to call this function while the
   913  // server is running in order to rotate the session ticket keys. The function
   914  // will panic if keys is empty.
   915  //
   916  // Calling this function will turn off automatic session ticket key rotation.
   917  //
   918  // If multiple servers are terminating connections for the same host they should
   919  // all have the same session ticket keys. If the session ticket keys leaks,
   920  // previously recorded and future TLS connections using those keys might be
   921  // compromised.
   922  func (c *Config) SetSessionTicketKeys(keys [][32]byte) {
   923  	if len(keys) == 0 {
   924  		panic("tls: keys must have at least one key")
   925  	}
   926  
   927  	newKeys := make([]ticketKey, len(keys))
   928  	for i, bytes := range keys {
   929  		newKeys[i] = c.ticketKeyFromBytes(bytes)
   930  	}
   931  
   932  	c.mutex.Lock()
   933  	c.sessionTicketKeys = newKeys
   934  	c.mutex.Unlock()
   935  }
   936  
   937  func (c *Config) rand() io.Reader {
   938  	r := c.Rand
   939  	if r == nil {
   940  		return rand.Reader
   941  	}
   942  	return r
   943  }
   944  
   945  func (c *Config) time() time.Time {
   946  	t := c.Time
   947  	if t == nil {
   948  		t = time.Now
   949  	}
   950  	return t()
   951  }
   952  
   953  func (c *Config) cipherSuites() []uint16 {
   954  	if c.CipherSuites != nil {
   955  		return c.CipherSuites
   956  	}
   957  	return defaultCipherSuites
   958  }
   959  
   960  var supportedVersions = []uint16{
   961  	VersionTLS13,
   962  	VersionTLS12,
   963  	VersionTLS11,
   964  	VersionTLS10,
   965  }
   966  
   967  func (c *Config) supportedVersions() []uint16 {
   968  	versions := make([]uint16, 0, len(supportedVersions))
   969  	for _, v := range supportedVersions {
   970  		if c != nil && c.MinVersion != 0 && v < c.MinVersion {
   971  			continue
   972  		}
   973  		if c != nil && c.MaxVersion != 0 && v > c.MaxVersion {
   974  			continue
   975  		}
   976  		versions = append(versions, v)
   977  	}
   978  	return versions
   979  }
   980  
   981  func (c *Config) maxSupportedVersion() uint16 {
   982  	supportedVersions := c.supportedVersions()
   983  	if len(supportedVersions) == 0 {
   984  		return 0
   985  	}
   986  	return supportedVersions[0]
   987  }
   988  
   989  // supportedVersionsFromMax returns a list of supported versions derived from a
   990  // legacy maximum version value. Note that only versions supported by this
   991  // library are returned. Any newer peer will use supportedVersions anyway.
   992  func supportedVersionsFromMax(maxVersion uint16) []uint16 {
   993  	versions := make([]uint16, 0, len(supportedVersions))
   994  	for _, v := range supportedVersions {
   995  		if v > maxVersion {
   996  			continue
   997  		}
   998  		versions = append(versions, v)
   999  	}
  1000  	return versions
  1001  }
  1002  
  1003  var defaultCurvePreferences = []CurveID{X25519, CurveP256, CurveP384, CurveP521}
  1004  
  1005  func (c *Config) curvePreferences() []CurveID {
  1006  	if c == nil || len(c.CurvePreferences) == 0 {
  1007  		return defaultCurvePreferences
  1008  	}
  1009  	return c.CurvePreferences
  1010  }
  1011  
  1012  func (c *Config) supportsCurve(curve CurveID) bool {
  1013  	for _, cc := range c.curvePreferences() {
  1014  		if cc == curve {
  1015  			return true
  1016  		}
  1017  	}
  1018  	return false
  1019  }
  1020  
  1021  // mutualVersion returns the protocol version to use given the advertised
  1022  // versions of the peer. Priority is given to the peer preference order.
  1023  func (c *Config) mutualVersion(peerVersions []uint16) (uint16, bool) {
  1024  	supportedVersions := c.supportedVersions()
  1025  	for _, peerVersion := range peerVersions {
  1026  		for _, v := range supportedVersions {
  1027  			if v == peerVersion {
  1028  				return v, true
  1029  			}
  1030  		}
  1031  	}
  1032  	return 0, false
  1033  }
  1034  
  1035  var errNoCertificates = errors.New("tls: no certificates configured")
  1036  
  1037  // getCertificate returns the best certificate for the given ClientHelloInfo,
  1038  // defaulting to the first element of c.Certificates.
  1039  func (c *Config) getCertificate(clientHello *ClientHelloInfo) (*Certificate, error) {
  1040  	if c.GetCertificate != nil &&
  1041  		(len(c.Certificates) == 0 || len(clientHello.ServerName) > 0) {
  1042  		cert, err := c.GetCertificate(clientHello)
  1043  		if cert != nil || err != nil {
  1044  			return cert, err
  1045  		}
  1046  	}
  1047  
  1048  	if len(c.Certificates) == 0 {
  1049  		return nil, errNoCertificates
  1050  	}
  1051  
  1052  	if len(c.Certificates) == 1 {
  1053  		// There's only one choice, so no point doing any work.
  1054  		return &c.Certificates[0], nil
  1055  	}
  1056  
  1057  	if c.NameToCertificate != nil {
  1058  		name := strings.ToLower(clientHello.ServerName)
  1059  		if cert, ok := c.NameToCertificate[name]; ok {
  1060  			return cert, nil
  1061  		}
  1062  		if len(name) > 0 {
  1063  			labels := strings.Split(name, ".")
  1064  			labels[0] = "*"
  1065  			wildcardName := strings.Join(labels, ".")
  1066  			if cert, ok := c.NameToCertificate[wildcardName]; ok {
  1067  				return cert, nil
  1068  			}
  1069  		}
  1070  	}
  1071  
  1072  	for _, cert := range c.Certificates {
  1073  		if err := clientHello.SupportsCertificate(&cert); err == nil {
  1074  			return &cert, nil
  1075  		}
  1076  	}
  1077  
  1078  	// If nothing matches, return the first certificate.
  1079  	return &c.Certificates[0], nil
  1080  }
  1081  
  1082  // SupportsCertificate returns nil if the provided certificate is supported by
  1083  // the client that sent the ClientHello. Otherwise, it returns an error
  1084  // describing the reason for the incompatibility.
  1085  //
  1086  // If this ClientHelloInfo was passed to a GetConfigForClient or GetCertificate
  1087  // callback, this method will take into account the associated Config. Note that
  1088  // if GetConfigForClient returns a different Config, the change can't be
  1089  // accounted for by this method.
  1090  //
  1091  // This function will call x509.ParseCertificate unless c.Leaf is set, which can
  1092  // incur a significant performance cost.
  1093  func (chi *ClientHelloInfo) SupportsCertificate(c *Certificate) error {
  1094  	// Note we don't currently support certificate_authorities nor
  1095  	// signature_algorithms_cert, and don't check the algorithms of the
  1096  	// signatures on the chain (which anyway are a SHOULD, see RFC 8446,
  1097  	// Section 4.4.2.2).
  1098  
  1099  	config := chi.config
  1100  	if config == nil {
  1101  		config = &Config{}
  1102  	}
  1103  	vers, ok := config.mutualVersion(chi.SupportedVersions)
  1104  	if !ok {
  1105  		return errors.New("no mutually supported protocol versions")
  1106  	}
  1107  
  1108  	// If the client specified the name they are trying to connect to, the
  1109  	// certificate needs to be valid for it.
  1110  	if chi.ServerName != "" {
  1111  		x509Cert, err := c.leaf()
  1112  		if err != nil {
  1113  			return fmt.Errorf("failed to parse certificate: %w", err)
  1114  		}
  1115  		if err := x509Cert.VerifyHostname(chi.ServerName); err != nil {
  1116  			return fmt.Errorf("certificate is not valid for requested server name: %w", err)
  1117  		}
  1118  	}
  1119  
  1120  	// supportsRSAFallback returns nil if the certificate and connection support
  1121  	// the static RSA key exchange, and unsupported otherwise. The logic for
  1122  	// supporting static RSA is completely disjoint from the logic for
  1123  	// supporting signed key exchanges, so we just check it as a fallback.
  1124  	supportsRSAFallback := func(unsupported error) error {
  1125  		// TLS 1.3 dropped support for the static RSA key exchange.
  1126  		if vers == VersionTLS13 {
  1127  			return unsupported
  1128  		}
  1129  		// The static RSA key exchange works by decrypting a challenge with the
  1130  		// RSA private key, not by signing, so check the PrivateKey implements
  1131  		// crypto.Decrypter, like *rsa.PrivateKey does.
  1132  		if priv, ok := c.PrivateKey.(crypto.Decrypter); ok {
  1133  			if _, ok := priv.Public().(*rsa.PublicKey); !ok {
  1134  				return unsupported
  1135  			}
  1136  		} else {
  1137  			return unsupported
  1138  		}
  1139  		// Finally, there needs to be a mutual cipher suite that uses the static
  1140  		// RSA key exchange instead of ECDHE.
  1141  		rsaCipherSuite := selectCipherSuite(chi.CipherSuites, config.cipherSuites(), func(c *cipherSuite) bool {
  1142  			if c.flags&suiteECDHE != 0 {
  1143  				return false
  1144  			}
  1145  			if vers < VersionTLS12 && c.flags&suiteTLS12 != 0 {
  1146  				return false
  1147  			}
  1148  			return true
  1149  		})
  1150  		if rsaCipherSuite == nil {
  1151  			return unsupported
  1152  		}
  1153  		return nil
  1154  	}
  1155  
  1156  	// If the client sent the signature_algorithms extension, ensure it supports
  1157  	// schemes we can use with this certificate and TLS version.
  1158  	if len(chi.SignatureSchemes) > 0 {
  1159  		if _, err := selectSignatureScheme(vers, c, chi.SignatureSchemes); err != nil {
  1160  			return supportsRSAFallback(err)
  1161  		}
  1162  	}
  1163  
  1164  	// In TLS 1.3 we are done because supported_groups is only relevant to the
  1165  	// ECDHE computation, point format negotiation is removed, cipher suites are
  1166  	// only relevant to the AEAD choice, and static RSA does not exist.
  1167  	if vers == VersionTLS13 {
  1168  		return nil
  1169  	}
  1170  
  1171  	// The only signed key exchange we support is ECDHE.
  1172  	if !supportsECDHE(config, chi.SupportedCurves, chi.SupportedPoints) {
  1173  		return supportsRSAFallback(errors.New("client doesn't support ECDHE, can only use legacy RSA key exchange"))
  1174  	}
  1175  
  1176  	var ecdsaCipherSuite bool
  1177  	if priv, ok := c.PrivateKey.(crypto.Signer); ok {
  1178  		switch pub := priv.Public().(type) {
  1179  		case *ecdsa.PublicKey:
  1180  			var curve CurveID
  1181  			switch pub.Curve {
  1182  			case elliptic.P256():
  1183  				curve = CurveP256
  1184  			case elliptic.P384():
  1185  				curve = CurveP384
  1186  			case elliptic.P521():
  1187  				curve = CurveP521
  1188  			default:
  1189  				return supportsRSAFallback(unsupportedCertificateError(c))
  1190  			}
  1191  			var curveOk bool
  1192  			for _, c := range chi.SupportedCurves {
  1193  				if c == curve && config.supportsCurve(c) {
  1194  					curveOk = true
  1195  					break
  1196  				}
  1197  			}
  1198  			if !curveOk {
  1199  				return errors.New("client doesn't support certificate curve")
  1200  			}
  1201  			ecdsaCipherSuite = true
  1202  		case ed25519.PublicKey:
  1203  			if vers < VersionTLS12 || len(chi.SignatureSchemes) == 0 {
  1204  				return errors.New("connection doesn't support Ed25519")
  1205  			}
  1206  			ecdsaCipherSuite = true
  1207  		case *rsa.PublicKey:
  1208  		default:
  1209  			return supportsRSAFallback(unsupportedCertificateError(c))
  1210  		}
  1211  	} else {
  1212  		return supportsRSAFallback(unsupportedCertificateError(c))
  1213  	}
  1214  
  1215  	// Make sure that there is a mutually supported cipher suite that works with
  1216  	// this certificate. Cipher suite selection will then apply the logic in
  1217  	// reverse to pick it. See also serverHandshakeState.cipherSuiteOk.
  1218  	cipherSuite := selectCipherSuite(chi.CipherSuites, config.cipherSuites(), func(c *cipherSuite) bool {
  1219  		if c.flags&suiteECDHE == 0 {
  1220  			return false
  1221  		}
  1222  		if c.flags&suiteECSign != 0 {
  1223  			if !ecdsaCipherSuite {
  1224  				return false
  1225  			}
  1226  		} else {
  1227  			if ecdsaCipherSuite {
  1228  				return false
  1229  			}
  1230  		}
  1231  		if vers < VersionTLS12 && c.flags&suiteTLS12 != 0 {
  1232  			return false
  1233  		}
  1234  		return true
  1235  	})
  1236  	if cipherSuite == nil {
  1237  		return supportsRSAFallback(errors.New("client doesn't support any cipher suites compatible with the certificate"))
  1238  	}
  1239  
  1240  	return nil
  1241  }
  1242  
  1243  // SupportsCertificate returns nil if the provided certificate is supported by
  1244  // the server that sent the CertificateRequest. Otherwise, it returns an error
  1245  // describing the reason for the incompatibility.
  1246  func (cri *CertificateRequestInfo) SupportsCertificate(c *Certificate) error {
  1247  	if _, err := selectSignatureScheme(cri.Version, c, cri.SignatureSchemes); err != nil {
  1248  		return err
  1249  	}
  1250  
  1251  	if len(cri.AcceptableCAs) == 0 {
  1252  		return nil
  1253  	}
  1254  
  1255  	for j, cert := range c.Certificate {
  1256  		x509Cert := c.Leaf
  1257  		// Parse the certificate if this isn't the leaf node, or if
  1258  		// chain.Leaf was nil.
  1259  		if j != 0 || x509Cert == nil {
  1260  			var err error
  1261  			if x509Cert, err = x509.ParseCertificate(cert); err != nil {
  1262  				return fmt.Errorf("failed to parse certificate #%d in the chain: %w", j, err)
  1263  			}
  1264  		}
  1265  
  1266  		for _, ca := range cri.AcceptableCAs {
  1267  			if bytes.Equal(x509Cert.RawIssuer, ca) {
  1268  				return nil
  1269  			}
  1270  		}
  1271  	}
  1272  	return errors.New("chain is not signed by an acceptable CA")
  1273  }
  1274  
  1275  // BuildNameToCertificate parses c.Certificates and builds c.NameToCertificate
  1276  // from the CommonName and SubjectAlternateName fields of each of the leaf
  1277  // certificates.
  1278  //
  1279  // Deprecated: NameToCertificate only allows associating a single certificate
  1280  // with a given name. Leave that field nil to let the library select the first
  1281  // compatible chain from Certificates.
  1282  func (c *Config) BuildNameToCertificate() {
  1283  	c.NameToCertificate = make(map[string]*Certificate)
  1284  	for i := range c.Certificates {
  1285  		cert := &c.Certificates[i]
  1286  		x509Cert, err := cert.leaf()
  1287  		if err != nil {
  1288  			continue
  1289  		}
  1290  		// If SANs are *not* present, some clients will consider the certificate
  1291  		// valid for the name in the Common Name.
  1292  		if x509Cert.Subject.CommonName != "" && len(x509Cert.DNSNames) == 0 {
  1293  			c.NameToCertificate[x509Cert.Subject.CommonName] = cert
  1294  		}
  1295  		for _, san := range x509Cert.DNSNames {
  1296  			c.NameToCertificate[san] = cert
  1297  		}
  1298  	}
  1299  }
  1300  
  1301  const (
  1302  	keyLogLabelTLS12           = "CLIENT_RANDOM"
  1303  	keyLogLabelClientHandshake = "CLIENT_HANDSHAKE_TRAFFIC_SECRET"
  1304  	keyLogLabelServerHandshake = "SERVER_HANDSHAKE_TRAFFIC_SECRET"
  1305  	keyLogLabelClientTraffic   = "CLIENT_TRAFFIC_SECRET_0"
  1306  	keyLogLabelServerTraffic   = "SERVER_TRAFFIC_SECRET_0"
  1307  )
  1308  
  1309  func (c *Config) writeKeyLog(label string, clientRandom, secret []byte) error {
  1310  	if c.KeyLogWriter == nil {
  1311  		return nil
  1312  	}
  1313  
  1314  	logLine := []byte(fmt.Sprintf("%s %x %x\n", label, clientRandom, secret))
  1315  
  1316  	writerMutex.Lock()
  1317  	_, err := c.KeyLogWriter.Write(logLine)
  1318  	writerMutex.Unlock()
  1319  
  1320  	return err
  1321  }
  1322  
  1323  // writerMutex protects all KeyLogWriters globally. It is rarely enabled,
  1324  // and is only for debugging, so a global mutex saves space.
  1325  var writerMutex sync.Mutex
  1326  
  1327  // A Certificate is a chain of one or more certificates, leaf first.
  1328  type Certificate struct {
  1329  	Certificate [][]byte
  1330  	// PrivateKey contains the private key corresponding to the public key in
  1331  	// Leaf. This must implement crypto.Signer with an RSA, ECDSA or Ed25519 PublicKey.
  1332  	// For a server up to TLS 1.2, it can also implement crypto.Decrypter with
  1333  	// an RSA PublicKey.
  1334  	PrivateKey crypto.PrivateKey
  1335  	// SupportedSignatureAlgorithms is an optional list restricting what
  1336  	// signature algorithms the PrivateKey can be used for.
  1337  	SupportedSignatureAlgorithms []SignatureScheme
  1338  	// OCSPStaple contains an optional OCSP response which will be served
  1339  	// to clients that request it.
  1340  	OCSPStaple []byte
  1341  	// SignedCertificateTimestamps contains an optional list of Signed
  1342  	// Certificate Timestamps which will be served to clients that request it.
  1343  	SignedCertificateTimestamps [][]byte
  1344  	// Leaf is the parsed form of the leaf certificate, which may be initialized
  1345  	// using x509.ParseCertificate to reduce per-handshake processing. If nil,
  1346  	// the leaf certificate will be parsed as needed.
  1347  	Leaf *x509.Certificate
  1348  }
  1349  
  1350  // leaf returns the parsed leaf certificate, either from c.Leaf or by parsing
  1351  // the corresponding c.Certificate[0].
  1352  func (c *Certificate) leaf() (*x509.Certificate, error) {
  1353  	if c.Leaf != nil {
  1354  		return c.Leaf, nil
  1355  	}
  1356  	return x509.ParseCertificate(c.Certificate[0])
  1357  }
  1358  
  1359  type handshakeMessage interface {
  1360  	marshal() []byte
  1361  	unmarshal([]byte) bool
  1362  }
  1363  
  1364  // lruSessionCache is a ClientSessionCache implementation that uses an LRU
  1365  // caching strategy.
  1366  type lruSessionCache struct {
  1367  	sync.Mutex
  1368  
  1369  	m        map[string]*list.Element
  1370  	q        *list.List
  1371  	capacity int
  1372  }
  1373  
  1374  type lruSessionCacheEntry struct {
  1375  	sessionKey string
  1376  	state      *ClientSessionState
  1377  }
  1378  
  1379  // NewLRUClientSessionCache returns a ClientSessionCache with the given
  1380  // capacity that uses an LRU strategy. If capacity is < 1, a default capacity
  1381  // is used instead.
  1382  func NewLRUClientSessionCache(capacity int) ClientSessionCache {
  1383  	const defaultSessionCacheCapacity = 64
  1384  
  1385  	if capacity < 1 {
  1386  		capacity = defaultSessionCacheCapacity
  1387  	}
  1388  	return &lruSessionCache{
  1389  		m:        make(map[string]*list.Element),
  1390  		q:        list.New(),
  1391  		capacity: capacity,
  1392  	}
  1393  }
  1394  
  1395  // Put adds the provided (sessionKey, cs) pair to the cache. If cs is nil, the entry
  1396  // corresponding to sessionKey is removed from the cache instead.
  1397  func (c *lruSessionCache) Put(sessionKey string, cs *ClientSessionState) {
  1398  	c.Lock()
  1399  	defer c.Unlock()
  1400  
  1401  	if elem, ok := c.m[sessionKey]; ok {
  1402  		if cs == nil {
  1403  			c.q.Remove(elem)
  1404  			delete(c.m, sessionKey)
  1405  		} else {
  1406  			entry := elem.Value.(*lruSessionCacheEntry)
  1407  			entry.state = cs
  1408  			c.q.MoveToFront(elem)
  1409  		}
  1410  		return
  1411  	}
  1412  
  1413  	if c.q.Len() < c.capacity {
  1414  		entry := &lruSessionCacheEntry{sessionKey, cs}
  1415  		c.m[sessionKey] = c.q.PushFront(entry)
  1416  		return
  1417  	}
  1418  
  1419  	elem := c.q.Back()
  1420  	entry := elem.Value.(*lruSessionCacheEntry)
  1421  	delete(c.m, entry.sessionKey)
  1422  	entry.sessionKey = sessionKey
  1423  	entry.state = cs
  1424  	c.q.MoveToFront(elem)
  1425  	c.m[sessionKey] = elem
  1426  }
  1427  
  1428  // Get returns the ClientSessionState value associated with a given key. It
  1429  // returns (nil, false) if no value is found.
  1430  func (c *lruSessionCache) Get(sessionKey string) (*ClientSessionState, bool) {
  1431  	c.Lock()
  1432  	defer c.Unlock()
  1433  
  1434  	if elem, ok := c.m[sessionKey]; ok {
  1435  		c.q.MoveToFront(elem)
  1436  		return elem.Value.(*lruSessionCacheEntry).state, true
  1437  	}
  1438  	return nil, false
  1439  }
  1440  
  1441  var emptyConfig Config
  1442  
  1443  func defaultConfig() *Config {
  1444  	return &emptyConfig
  1445  }
  1446  
  1447  func unexpectedMessageError(wanted, got interface{}) error {
  1448  	return fmt.Errorf("tls: received unexpected handshake message of type %T when waiting for %T", got, wanted)
  1449  }
  1450  
  1451  func isSupportedSignatureAlgorithm(sigAlg SignatureScheme, supportedSignatureAlgorithms []SignatureScheme) bool {
  1452  	for _, s := range supportedSignatureAlgorithms {
  1453  		if s == sigAlg {
  1454  			return true
  1455  		}
  1456  	}
  1457  	return false
  1458  }
  1459  

View as plain text