Run Format

Source file src/crypto/tls/common.go

Documentation: crypto/tls

  // Copyright 2009 The Go Authors. All rights reserved.
  // Use of this source code is governed by a BSD-style
  // license that can be found in the LICENSE file.
  package tls
  import (
  const (
  	VersionSSL30 = 0x0300
  	VersionTLS10 = 0x0301
  	VersionTLS11 = 0x0302
  	VersionTLS12 = 0x0303
  const (
  	maxPlaintext      = 16384        // maximum plaintext payload length
  	maxCiphertext     = 16384 + 2048 // maximum ciphertext payload length
  	recordHeaderLen   = 5            // record header length
  	maxHandshake      = 65536        // maximum handshake we support (protocol max is 16 MB)
  	maxWarnAlertCount = 5            // maximum number of consecutive warning alerts
  	minVersion = VersionTLS10
  	maxVersion = VersionTLS12
  // TLS record types.
  type recordType uint8
  const (
  	recordTypeChangeCipherSpec recordType = 20
  	recordTypeAlert            recordType = 21
  	recordTypeHandshake        recordType = 22
  	recordTypeApplicationData  recordType = 23
  // TLS handshake message types.
  const (
  	typeHelloRequest       uint8 = 0
  	typeClientHello        uint8 = 1
  	typeServerHello        uint8 = 2
  	typeNewSessionTicket   uint8 = 4
  	typeCertificate        uint8 = 11
  	typeServerKeyExchange  uint8 = 12
  	typeCertificateRequest uint8 = 13
  	typeServerHelloDone    uint8 = 14
  	typeCertificateVerify  uint8 = 15
  	typeClientKeyExchange  uint8 = 16
  	typeFinished           uint8 = 20
  	typeCertificateStatus  uint8 = 22
  	typeNextProtocol       uint8 = 67 // Not IANA assigned
  // TLS compression types.
  const (
  	compressionNone uint8 = 0
  // TLS extension numbers
  const (
  	extensionServerName          uint16 = 0
  	extensionStatusRequest       uint16 = 5
  	extensionSupportedCurves     uint16 = 10
  	extensionSupportedPoints     uint16 = 11
  	extensionSignatureAlgorithms uint16 = 13
  	extensionALPN                uint16 = 16
  	extensionSCT                 uint16 = 18 // https://tools.ietf.org/html/rfc6962#section-6
  	extensionSessionTicket       uint16 = 35
  	extensionNextProtoNeg        uint16 = 13172 // not IANA assigned
  	extensionRenegotiationInfo   uint16 = 0xff01
  // TLS signaling cipher suite values
  const (
  	scsvRenegotiation uint16 = 0x00ff
  // CurveID is the type of a TLS identifier for an elliptic curve. See
  // https://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-8
  type CurveID uint16
  const (
  	CurveP256 CurveID = 23
  	CurveP384 CurveID = 24
  	CurveP521 CurveID = 25
  	X25519    CurveID = 29
  // TLS Elliptic Curve Point Formats
  // https://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-9
  const (
  	pointFormatUncompressed uint8 = 0
  // TLS CertificateStatusType (RFC 3546)
  const (
  	statusTypeOCSP uint8 = 1
  // Certificate types (for certificateRequestMsg)
  const (
  	certTypeRSASign    = 1 // A certificate containing an RSA key
  	certTypeDSSSign    = 2 // A certificate containing a DSA key
  	certTypeRSAFixedDH = 3 // A certificate containing a static DH key
  	certTypeDSSFixedDH = 4 // A certificate containing a static DH key
  	// See RFC 4492 sections 3 and 5.5.
  	certTypeECDSASign      = 64 // A certificate containing an ECDSA-capable public key, signed with ECDSA.
  	certTypeRSAFixedECDH   = 65 // A certificate containing an ECDH-capable public key, signed with RSA.
  	certTypeECDSAFixedECDH = 66 // A certificate containing an ECDH-capable public key, signed with ECDSA.
  	// Rest of these are reserved by the TLS spec
  // Signature algorithms (for internal signaling use). Starting at 16 to avoid overlap with
  // TLS 1.2 codepoints (RFC 5246, section A.4.1), with which these have nothing to do.
  const (
  	signaturePKCS1v15 uint8 = iota + 16
  // supportedSignatureAlgorithms contains the signature and hash algorithms that
  // the code advertises as supported in a TLS 1.2 ClientHello and in a TLS 1.2
  // CertificateRequest. The two fields are merged to match with TLS 1.3.
  // Note that in TLS 1.2, the ECDSA algorithms are not constrained to P-256, etc.
  var supportedSignatureAlgorithms = []SignatureScheme{
  // ConnectionState records basic TLS details about the connection.
  type ConnectionState struct {
  	Version                     uint16                // TLS version used by the connection (e.g. VersionTLS12)
  	HandshakeComplete           bool                  // TLS handshake is complete
  	DidResume                   bool                  // connection resumes a previous TLS connection
  	CipherSuite                 uint16                // cipher suite in use (TLS_RSA_WITH_RC4_128_SHA, ...)
  	NegotiatedProtocol          string                // negotiated next protocol (not guaranteed to be from Config.NextProtos)
  	NegotiatedProtocolIsMutual  bool                  // negotiated protocol was advertised by server (client side only)
  	ServerName                  string                // server name requested by client, if any (server side only)
  	PeerCertificates            []*x509.Certificate   // certificate chain presented by remote peer
  	VerifiedChains              [][]*x509.Certificate // verified chains built from PeerCertificates
  	SignedCertificateTimestamps [][]byte              // SCTs from the server, if any
  	OCSPResponse                []byte                // stapled OCSP response from server, if any
  	// ekm is a closure exposed via ExportKeyingMaterial.
  	ekm func(label string, context []byte, length int) ([]byte, error)
  	// TLSUnique contains the "tls-unique" channel binding value (see RFC
  	// 5929, section 3). For resumed sessions this value will be nil
  	// because resumption does not include enough context (see
  	// https://mitls.org/pages/attacks/3SHAKE#channelbindings). This will
  	// change in future versions of Go once the TLS master-secret fix has
  	// been standardized and implemented.
  	TLSUnique []byte
  // ExportKeyingMaterial returns length bytes of exported key material in a new
  // slice as defined in https://tools.ietf.org/html/rfc5705. If context is nil,
  // it is not used as part of the seed. If the connection was set to allow
  // renegotiation via Config.Renegotiation, this function will return an error.
  func (cs *ConnectionState) ExportKeyingMaterial(label string, context []byte, length int) ([]byte, error) {
  	return cs.ekm(label, context, length)
  // ClientAuthType declares the policy the server will follow for
  // TLS Client Authentication.
  type ClientAuthType int
  const (
  	NoClientCert ClientAuthType = iota
  // ClientSessionState contains the state needed by clients to resume TLS
  // sessions.
  type ClientSessionState struct {
  	sessionTicket      []uint8               // Encrypted ticket used for session resumption with server
  	vers               uint16                // SSL/TLS version negotiated for the session
  	cipherSuite        uint16                // Ciphersuite negotiated for the session
  	masterSecret       []byte                // MasterSecret generated by client on a full handshake
  	serverCertificates []*x509.Certificate   // Certificate chain presented by the server
  	verifiedChains     [][]*x509.Certificate // Certificate chains we built for verification
  // ClientSessionCache is a cache of ClientSessionState objects that can be used
  // by a client to resume a TLS session with a given server. ClientSessionCache
  // implementations should expect to be called concurrently from different
  // goroutines. Only ticket-based resumption is supported, not SessionID-based
  // resumption.
  type ClientSessionCache interface {
  	// Get searches for a ClientSessionState associated with the given key.
  	// On return, ok is true if one was found.
  	Get(sessionKey string) (session *ClientSessionState, ok bool)
  	// Put adds the ClientSessionState to the cache with the given key.
  	Put(sessionKey string, cs *ClientSessionState)
  // SignatureScheme identifies a signature algorithm supported by TLS. See
  // https://tools.ietf.org/html/draft-ietf-tls-tls13-18#section-4.2.3.
  type SignatureScheme uint16
  const (
  	PKCS1WithSHA1   SignatureScheme = 0x0201
  	PKCS1WithSHA256 SignatureScheme = 0x0401
  	PKCS1WithSHA384 SignatureScheme = 0x0501
  	PKCS1WithSHA512 SignatureScheme = 0x0601
  	PSSWithSHA256 SignatureScheme = 0x0804
  	PSSWithSHA384 SignatureScheme = 0x0805
  	PSSWithSHA512 SignatureScheme = 0x0806
  	ECDSAWithP256AndSHA256 SignatureScheme = 0x0403
  	ECDSAWithP384AndSHA384 SignatureScheme = 0x0503
  	ECDSAWithP521AndSHA512 SignatureScheme = 0x0603
  	// Legacy signature and hash algorithms for TLS 1.2.
  	ECDSAWithSHA1 SignatureScheme = 0x0203
  // ClientHelloInfo contains information from a ClientHello message in order to
  // guide certificate selection in the GetCertificate callback.
  type ClientHelloInfo struct {
  	// CipherSuites lists the CipherSuites supported by the client (e.g.
  	// TLS_RSA_WITH_RC4_128_SHA).
  	CipherSuites []uint16
  	// ServerName indicates the name of the server requested by the client
  	// in order to support virtual hosting. ServerName is only set if the
  	// client is using SNI (see
  	// https://tools.ietf.org/html/rfc4366#section-3.1).
  	ServerName string
  	// SupportedCurves lists the elliptic curves supported by the client.
  	// SupportedCurves is set only if the Supported Elliptic Curves
  	// Extension is being used (see
  	// https://tools.ietf.org/html/rfc4492#section-5.1.1).
  	SupportedCurves []CurveID
  	// SupportedPoints lists the point formats supported by the client.
  	// SupportedPoints is set only if the Supported Point Formats Extension
  	// is being used (see
  	// https://tools.ietf.org/html/rfc4492#section-5.1.2).
  	SupportedPoints []uint8
  	// SignatureSchemes lists the signature and hash schemes that the client
  	// is willing to verify. SignatureSchemes is set only if the Signature
  	// Algorithms Extension is being used (see
  	// https://tools.ietf.org/html/rfc5246#section-
  	SignatureSchemes []SignatureScheme
  	// SupportedProtos lists the application protocols supported by the client.
  	// SupportedProtos is set only if the Application-Layer Protocol
  	// Negotiation Extension is being used (see
  	// https://tools.ietf.org/html/rfc7301#section-3.1).
  	// Servers can select a protocol by setting Config.NextProtos in a
  	// GetConfigForClient return value.
  	SupportedProtos []string
  	// SupportedVersions lists the TLS versions supported by the client.
  	// For TLS versions less than 1.3, this is extrapolated from the max
  	// version advertised by the client, so values other than the greatest
  	// might be rejected if used.
  	SupportedVersions []uint16
  	// Conn is the underlying net.Conn for the connection. Do not read
  	// from, or write to, this connection; that will cause the TLS
  	// connection to fail.
  	Conn net.Conn
  // CertificateRequestInfo contains information from a server's
  // CertificateRequest message, which is used to demand a certificate and proof
  // of control from a client.
  type CertificateRequestInfo struct {
  	// AcceptableCAs contains zero or more, DER-encoded, X.501
  	// Distinguished Names. These are the names of root or intermediate CAs
  	// that the server wishes the returned certificate to be signed by. An
  	// empty slice indicates that the server has no preference.
  	AcceptableCAs [][]byte
  	// SignatureSchemes lists the signature schemes that the server is
  	// willing to verify.
  	SignatureSchemes []SignatureScheme
  // RenegotiationSupport enumerates the different levels of support for TLS
  // renegotiation. TLS renegotiation is the act of performing subsequent
  // handshakes on a connection after the first. This significantly complicates
  // the state machine and has been the source of numerous, subtle security
  // issues. Initiating a renegotiation is not supported, but support for
  // accepting renegotiation requests may be enabled.
  // Even when enabled, the server may not change its identity between handshakes
  // (i.e. the leaf certificate must be the same). Additionally, concurrent
  // handshake and application data flow is not permitted so renegotiation can
  // only be used with protocols that synchronise with the renegotiation, such as
  // HTTPS.
  type RenegotiationSupport int
  const (
  	// RenegotiateNever disables renegotiation.
  	RenegotiateNever RenegotiationSupport = iota
  	// RenegotiateOnceAsClient allows a remote server to request
  	// renegotiation once per connection.
  	// RenegotiateFreelyAsClient allows a remote server to repeatedly
  	// request renegotiation.
  // A Config structure is used to configure a TLS client or server.
  // After one has been passed to a TLS function it must not be
  // modified. A Config may be reused; the tls package will also not
  // modify it.
  type Config struct {
  	// Rand provides the source of entropy for nonces and RSA blinding.
  	// If Rand is nil, TLS uses the cryptographic random reader in package
  	// crypto/rand.
  	// The Reader must be safe for use by multiple goroutines.
  	Rand io.Reader
  	// Time returns the current time as the number of seconds since the epoch.
  	// If Time is nil, TLS uses time.Now.
  	Time func() time.Time
  	// Certificates contains one or more certificate chains to present to
  	// the other side of the connection. Server configurations must include
  	// at least one certificate or else set GetCertificate. Clients doing
  	// client-authentication may set either Certificates or
  	// GetClientCertificate.
  	Certificates []Certificate
  	// NameToCertificate maps from a certificate name to an element of
  	// Certificates. Note that a certificate name can be of the form
  	// '*.example.com' and so doesn't have to be a domain name as such.
  	// See Config.BuildNameToCertificate
  	// The nil value causes the first element of Certificates to be used
  	// for all connections.
  	NameToCertificate map[string]*Certificate
  	// GetCertificate returns a Certificate based on the given
  	// ClientHelloInfo. It will only be called if the client supplies SNI
  	// information or if Certificates is empty.
  	// If GetCertificate is nil or returns nil, then the certificate is
  	// retrieved from NameToCertificate. If NameToCertificate is nil, the
  	// first element of Certificates will be used.
  	GetCertificate func(*ClientHelloInfo) (*Certificate, error)
  	// GetClientCertificate, if not nil, is called when a server requests a
  	// certificate from a client. If set, the contents of Certificates will
  	// be ignored.
  	// If GetClientCertificate returns an error, the handshake will be
  	// aborted and that error will be returned. Otherwise
  	// GetClientCertificate must return a non-nil Certificate. If
  	// Certificate.Certificate is empty then no certificate will be sent to
  	// the server. If this is unacceptable to the server then it may abort
  	// the handshake.
  	// GetClientCertificate may be called multiple times for the same
  	// connection if renegotiation occurs or if TLS 1.3 is in use.
  	GetClientCertificate func(*CertificateRequestInfo) (*Certificate, error)
  	// GetConfigForClient, if not nil, is called after a ClientHello is
  	// received from a client. It may return a non-nil Config in order to
  	// change the Config that will be used to handle this connection. If
  	// the returned Config is nil, the original Config will be used. The
  	// Config returned by this callback may not be subsequently modified.
  	// If GetConfigForClient is nil, the Config passed to Server() will be
  	// used for all connections.
  	// Uniquely for the fields in the returned Config, session ticket keys
  	// will be duplicated from the original Config if not set.
  	// Specifically, if SetSessionTicketKeys was called on the original
  	// config but not on the returned config then the ticket keys from the
  	// original config will be copied into the new config before use.
  	// Otherwise, if SessionTicketKey was set in the original config but
  	// not in the returned config then it will be copied into the returned
  	// config before use. If neither of those cases applies then the key
  	// material from the returned config will be used for session tickets.
  	GetConfigForClient func(*ClientHelloInfo) (*Config, error)
  	// VerifyPeerCertificate, if not nil, is called after normal
  	// certificate verification by either a TLS client or server. It
  	// receives the raw ASN.1 certificates provided by the peer and also
  	// any verified chains that normal processing found. If it returns a
  	// non-nil error, the handshake is aborted and that error results.
  	// If normal verification fails then the handshake will abort before
  	// considering this callback. If normal verification is disabled by
  	// setting InsecureSkipVerify, or (for a server) when ClientAuth is
  	// RequestClientCert or RequireAnyClientCert, then this callback will
  	// be considered but the verifiedChains argument will always be nil.
  	VerifyPeerCertificate func(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error
  	// RootCAs defines the set of root certificate authorities
  	// that clients use when verifying server certificates.
  	// If RootCAs is nil, TLS uses the host's root CA set.
  	RootCAs *x509.CertPool
  	// NextProtos is a list of supported, application level protocols.
  	NextProtos []string
  	// ServerName is used to verify the hostname on the returned
  	// certificates unless InsecureSkipVerify is given. It is also included
  	// in the client's handshake to support virtual hosting unless it is
  	// an IP address.
  	ServerName string
  	// ClientAuth determines the server's policy for
  	// TLS Client Authentication. The default is NoClientCert.
  	ClientAuth ClientAuthType
  	// ClientCAs defines the set of root certificate authorities
  	// that servers use if required to verify a client certificate
  	// by the policy in ClientAuth.
  	ClientCAs *x509.CertPool
  	// InsecureSkipVerify controls whether a client verifies the
  	// server's certificate chain and host name.
  	// If InsecureSkipVerify is true, TLS accepts any certificate
  	// presented by the server and any host name in that certificate.
  	// In this mode, TLS is susceptible to man-in-the-middle attacks.
  	// This should be used only for testing.
  	InsecureSkipVerify bool
  	// CipherSuites is a list of supported cipher suites. If CipherSuites
  	// is nil, TLS uses a list of suites supported by the implementation.
  	CipherSuites []uint16
  	// PreferServerCipherSuites controls whether the server selects the
  	// client's most preferred ciphersuite, or the server's most preferred
  	// ciphersuite. If true then the server's preference, as expressed in
  	// the order of elements in CipherSuites, is used.
  	PreferServerCipherSuites bool
  	// SessionTicketsDisabled may be set to true to disable session ticket
  	// (resumption) support. Note that on clients, session ticket support is
  	// also disabled if ClientSessionCache is nil.
  	SessionTicketsDisabled bool
  	// SessionTicketKey is used by TLS servers to provide session
  	// resumption. See RFC 5077. If zero, it will be filled with
  	// random data before the first server handshake.
  	// If multiple servers are terminating connections for the same host
  	// they should all have the same SessionTicketKey. If the
  	// SessionTicketKey leaks, previously recorded and future TLS
  	// connections using that key are compromised.
  	SessionTicketKey [32]byte
  	// ClientSessionCache is a cache of ClientSessionState entries for TLS
  	// session resumption. It is only used by clients.
  	ClientSessionCache ClientSessionCache
  	// MinVersion contains the minimum SSL/TLS version that is acceptable.
  	// If zero, then TLS 1.0 is taken as the minimum.
  	MinVersion uint16
  	// MaxVersion contains the maximum SSL/TLS version that is acceptable.
  	// If zero, then the maximum version supported by this package is used,
  	// which is currently TLS 1.2.
  	MaxVersion uint16
  	// CurvePreferences contains the elliptic curves that will be used in
  	// an ECDHE handshake, in preference order. If empty, the default will
  	// be used.
  	CurvePreferences []CurveID
  	// DynamicRecordSizingDisabled disables adaptive sizing of TLS records.
  	// When true, the largest possible TLS record size is always used. When
  	// false, the size of TLS records may be adjusted in an attempt to
  	// improve latency.
  	DynamicRecordSizingDisabled bool
  	// Renegotiation controls what types of renegotiation are supported.
  	// The default, none, is correct for the vast majority of applications.
  	Renegotiation RenegotiationSupport
  	// KeyLogWriter optionally specifies a destination for TLS master secrets
  	// in NSS key log format that can be used to allow external programs
  	// such as Wireshark to decrypt TLS connections.
  	// See https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format.
  	// Use of KeyLogWriter compromises security and should only be
  	// used for debugging.
  	KeyLogWriter io.Writer
  	serverInitOnce sync.Once // guards calling (*Config).serverInit
  	// mutex protects sessionTicketKeys.
  	mutex sync.RWMutex
  	// sessionTicketKeys contains zero or more ticket keys. If the length
  	// is zero, SessionTicketsDisabled must be true. The first key is used
  	// for new tickets and any subsequent keys can be used to decrypt old
  	// tickets.
  	sessionTicketKeys []ticketKey
  // ticketKeyNameLen is the number of bytes of identifier that is prepended to
  // an encrypted session ticket in order to identify the key used to encrypt it.
  const ticketKeyNameLen = 16
  // ticketKey is the internal representation of a session ticket key.
  type ticketKey struct {
  	// keyName is an opaque byte string that serves to identify the session
  	// ticket key. It's exposed as plaintext in every session ticket.
  	keyName [ticketKeyNameLen]byte
  	aesKey  [16]byte
  	hmacKey [16]byte
  // ticketKeyFromBytes converts from the external representation of a session
  // ticket key to a ticketKey. Externally, session ticket keys are 32 random
  // bytes and this function expands that into sufficient name and key material.
  func ticketKeyFromBytes(b [32]byte) (key ticketKey) {
  	hashed := sha512.Sum512(b[:])
  	copy(key.keyName[:], hashed[:ticketKeyNameLen])
  	copy(key.aesKey[:], hashed[ticketKeyNameLen:ticketKeyNameLen+16])
  	copy(key.hmacKey[:], hashed[ticketKeyNameLen+16:ticketKeyNameLen+32])
  	return key
  // Clone returns a shallow clone of c. It is safe to clone a Config that is
  // being used concurrently by a TLS client or server.
  func (c *Config) Clone() *Config {
  	// Running serverInit ensures that it's safe to read
  	// SessionTicketsDisabled.
  	c.serverInitOnce.Do(func() { c.serverInit(nil) })
  	var sessionTicketKeys []ticketKey
  	sessionTicketKeys = c.sessionTicketKeys
  	return &Config{
  		Rand:                        c.Rand,
  		Time:                        c.Time,
  		Certificates:                c.Certificates,
  		NameToCertificate:           c.NameToCertificate,
  		GetCertificate:              c.GetCertificate,
  		GetClientCertificate:        c.GetClientCertificate,
  		GetConfigForClient:          c.GetConfigForClient,
  		VerifyPeerCertificate:       c.VerifyPeerCertificate,
  		RootCAs:                     c.RootCAs,
  		NextProtos:                  c.NextProtos,
  		ServerName:                  c.ServerName,
  		ClientAuth:                  c.ClientAuth,
  		ClientCAs:                   c.ClientCAs,
  		InsecureSkipVerify:          c.InsecureSkipVerify,
  		CipherSuites:                c.CipherSuites,
  		PreferServerCipherSuites:    c.PreferServerCipherSuites,
  		SessionTicketsDisabled:      c.SessionTicketsDisabled,
  		SessionTicketKey:            c.SessionTicketKey,
  		ClientSessionCache:          c.ClientSessionCache,
  		MinVersion:                  c.MinVersion,
  		MaxVersion:                  c.MaxVersion,
  		CurvePreferences:            c.CurvePreferences,
  		DynamicRecordSizingDisabled: c.DynamicRecordSizingDisabled,
  		Renegotiation:               c.Renegotiation,
  		KeyLogWriter:                c.KeyLogWriter,
  		sessionTicketKeys:           sessionTicketKeys,
  // serverInit is run under c.serverInitOnce to do initialization of c. If c was
  // returned by a GetConfigForClient callback then the argument should be the
  // Config that was passed to Server, otherwise it should be nil.
  func (c *Config) serverInit(originalConfig *Config) {
  	if c.SessionTicketsDisabled || len(c.ticketKeys()) != 0 {
  	alreadySet := false
  	for _, b := range c.SessionTicketKey {
  		if b != 0 {
  			alreadySet = true
  	if !alreadySet {
  		if originalConfig != nil {
  			copy(c.SessionTicketKey[:], originalConfig.SessionTicketKey[:])
  		} else if _, err := io.ReadFull(c.rand(), c.SessionTicketKey[:]); err != nil {
  			c.SessionTicketsDisabled = true
  	if originalConfig != nil {
  		c.sessionTicketKeys = originalConfig.sessionTicketKeys
  	} else {
  		c.sessionTicketKeys = []ticketKey{ticketKeyFromBytes(c.SessionTicketKey)}
  func (c *Config) ticketKeys() []ticketKey {
  	// c.sessionTicketKeys is constant once created. SetSessionTicketKeys
  	// will only update it by replacing it with a new value.
  	ret := c.sessionTicketKeys
  	return ret
  // SetSessionTicketKeys updates the session ticket keys for a server. The first
  // key will be used when creating new tickets, while all keys can be used for
  // decrypting tickets. It is safe to call this function while the server is
  // running in order to rotate the session ticket keys. The function will panic
  // if keys is empty.
  func (c *Config) SetSessionTicketKeys(keys [][32]byte) {
  	if len(keys) == 0 {
  		panic("tls: keys must have at least one key")
  	newKeys := make([]ticketKey, len(keys))
  	for i, bytes := range keys {
  		newKeys[i] = ticketKeyFromBytes(bytes)
  	c.sessionTicketKeys = newKeys
  func (c *Config) rand() io.Reader {
  	r := c.Rand
  	if r == nil {
  		return rand.Reader
  	return r
  func (c *Config) time() time.Time {
  	t := c.Time
  	if t == nil {
  		t = time.Now
  	return t()
  func (c *Config) cipherSuites() []uint16 {
  	s := c.CipherSuites
  	if s == nil {
  		s = defaultCipherSuites()
  	return s
  func (c *Config) minVersion() uint16 {
  	if c == nil || c.MinVersion == 0 {
  		return minVersion
  	return c.MinVersion
  func (c *Config) maxVersion() uint16 {
  	if c == nil || c.MaxVersion == 0 {
  		return maxVersion
  	return c.MaxVersion
  var defaultCurvePreferences = []CurveID{X25519, CurveP256, CurveP384, CurveP521}
  func (c *Config) curvePreferences() []CurveID {
  	if c == nil || len(c.CurvePreferences) == 0 {
  		return defaultCurvePreferences
  	return c.CurvePreferences
  // mutualVersion returns the protocol version to use given the advertised
  // version of the peer.
  func (c *Config) mutualVersion(vers uint16) (uint16, bool) {
  	minVersion := c.minVersion()
  	maxVersion := c.maxVersion()
  	if vers < minVersion {
  		return 0, false
  	if vers > maxVersion {
  		vers = maxVersion
  	return vers, true
  // getCertificate returns the best certificate for the given ClientHelloInfo,
  // defaulting to the first element of c.Certificates.
  func (c *Config) getCertificate(clientHello *ClientHelloInfo) (*Certificate, error) {
  	if c.GetCertificate != nil &&
  		(len(c.Certificates) == 0 || len(clientHello.ServerName) > 0) {
  		cert, err := c.GetCertificate(clientHello)
  		if cert != nil || err != nil {
  			return cert, err
  	if len(c.Certificates) == 0 {
  		return nil, errors.New("tls: no certificates configured")
  	if len(c.Certificates) == 1 || c.NameToCertificate == nil {
  		// There's only one choice, so no point doing any work.
  		return &c.Certificates[0], nil
  	name := strings.ToLower(clientHello.ServerName)
  	for len(name) > 0 && name[len(name)-1] == '.' {
  		name = name[:len(name)-1]
  	if cert, ok := c.NameToCertificate[name]; ok {
  		return cert, nil
  	// try replacing labels in the name with wildcards until we get a
  	// match.
  	labels := strings.Split(name, ".")
  	for i := range labels {
  		labels[i] = "*"
  		candidate := strings.Join(labels, ".")
  		if cert, ok := c.NameToCertificate[candidate]; ok {
  			return cert, nil
  	// If nothing matches, return the first certificate.
  	return &c.Certificates[0], nil
  // BuildNameToCertificate parses c.Certificates and builds c.NameToCertificate
  // from the CommonName and SubjectAlternateName fields of each of the leaf
  // certificates.
  func (c *Config) BuildNameToCertificate() {
  	c.NameToCertificate = make(map[string]*Certificate)
  	for i := range c.Certificates {
  		cert := &c.Certificates[i]
  		x509Cert, err := x509.ParseCertificate(cert.Certificate[0])
  		if err != nil {
  		if len(x509Cert.Subject.CommonName) > 0 {
  			c.NameToCertificate[x509Cert.Subject.CommonName] = cert
  		for _, san := range x509Cert.DNSNames {
  			c.NameToCertificate[san] = cert
  // writeKeyLog logs client random and master secret if logging was enabled by
  // setting c.KeyLogWriter.
  func (c *Config) writeKeyLog(clientRandom, masterSecret []byte) error {
  	if c.KeyLogWriter == nil {
  		return nil
  	logLine := []byte(fmt.Sprintf("CLIENT_RANDOM %x %x\n", clientRandom, masterSecret))
  	_, err := c.KeyLogWriter.Write(logLine)
  	return err
  // writerMutex protects all KeyLogWriters globally. It is rarely enabled,
  // and is only for debugging, so a global mutex saves space.
  var writerMutex sync.Mutex
  // A Certificate is a chain of one or more certificates, leaf first.
  type Certificate struct {
  	Certificate [][]byte
  	// PrivateKey contains the private key corresponding to the public key
  	// in Leaf. For a server, this must implement crypto.Signer and/or
  	// crypto.Decrypter, with an RSA or ECDSA PublicKey. For a client
  	// (performing client authentication), this must be a crypto.Signer
  	// with an RSA or ECDSA PublicKey.
  	PrivateKey crypto.PrivateKey
  	// OCSPStaple contains an optional OCSP response which will be served
  	// to clients that request it.
  	OCSPStaple []byte
  	// SignedCertificateTimestamps contains an optional list of Signed
  	// Certificate Timestamps which will be served to clients that request it.
  	SignedCertificateTimestamps [][]byte
  	// Leaf is the parsed form of the leaf certificate, which may be
  	// initialized using x509.ParseCertificate to reduce per-handshake
  	// processing for TLS clients doing client authentication. If nil, the
  	// leaf certificate will be parsed as needed.
  	Leaf *x509.Certificate
  type handshakeMessage interface {
  	marshal() []byte
  	unmarshal([]byte) bool
  // lruSessionCache is a ClientSessionCache implementation that uses an LRU
  // caching strategy.
  type lruSessionCache struct {
  	m        map[string]*list.Element
  	q        *list.List
  	capacity int
  type lruSessionCacheEntry struct {
  	sessionKey string
  	state      *ClientSessionState
  // NewLRUClientSessionCache returns a ClientSessionCache with the given
  // capacity that uses an LRU strategy. If capacity is < 1, a default capacity
  // is used instead.
  func NewLRUClientSessionCache(capacity int) ClientSessionCache {
  	const defaultSessionCacheCapacity = 64
  	if capacity < 1 {
  		capacity = defaultSessionCacheCapacity
  	return &lruSessionCache{
  		m:        make(map[string]*list.Element),
  		q:        list.New(),
  		capacity: capacity,
  // Put adds the provided (sessionKey, cs) pair to the cache.
  func (c *lruSessionCache) Put(sessionKey string, cs *ClientSessionState) {
  	defer c.Unlock()
  	if elem, ok := c.m[sessionKey]; ok {
  		entry := elem.Value.(*lruSessionCacheEntry)
  		entry.state = cs
  	if c.q.Len() < c.capacity {
  		entry := &lruSessionCacheEntry{sessionKey, cs}
  		c.m[sessionKey] = c.q.PushFront(entry)
  	elem := c.q.Back()
  	entry := elem.Value.(*lruSessionCacheEntry)
  	delete(c.m, entry.sessionKey)
  	entry.sessionKey = sessionKey
  	entry.state = cs
  	c.m[sessionKey] = elem
  // Get returns the ClientSessionState value associated with a given key. It
  // returns (nil, false) if no value is found.
  func (c *lruSessionCache) Get(sessionKey string) (*ClientSessionState, bool) {
  	defer c.Unlock()
  	if elem, ok := c.m[sessionKey]; ok {
  		return elem.Value.(*lruSessionCacheEntry).state, true
  	return nil, false
  // TODO(jsing): Make these available to both crypto/x509 and crypto/tls.
  type dsaSignature struct {
  	R, S *big.Int
  type ecdsaSignature dsaSignature
  var emptyConfig Config
  func defaultConfig() *Config {
  	return &emptyConfig
  var (
  	once                   sync.Once
  	varDefaultCipherSuites []uint16
  func defaultCipherSuites() []uint16 {
  	return varDefaultCipherSuites
  func initDefaultCipherSuites() {
  	var topCipherSuites []uint16
  	// Check the cpu flags for each platform that has optimized GCM implementations.
  	// Worst case, these variables will just all be false
  	hasGCMAsmAMD64 := cpu.X86.HasAES && cpu.X86.HasPCLMULQDQ
  	hasGCMAsmARM64 := cpu.ARM64.HasAES && cpu.ARM64.HasPMULL
  	// Keep in sync with crypto/aes/cipher_s390x.go.
  	hasGCMAsmS390X := cpu.S390X.HasAES && cpu.S390X.HasAESCBC && cpu.S390X.HasAESCTR && (cpu.S390X.HasGHASH || cpu.S390X.HasAESGCM)
  	hasGCMAsm := hasGCMAsmAMD64 || hasGCMAsmARM64 || hasGCMAsmS390X
  	if hasGCMAsm {
  		// If AES-GCM hardware is provided then prioritise AES-GCM
  		// cipher suites.
  		topCipherSuites = []uint16{
  	} else {
  		// Without AES-GCM hardware, we put the ChaCha20-Poly1305
  		// cipher suites first.
  		topCipherSuites = []uint16{
  	varDefaultCipherSuites = make([]uint16, 0, len(cipherSuites))
  	varDefaultCipherSuites = append(varDefaultCipherSuites, topCipherSuites...)
  	for _, suite := range cipherSuites {
  		if suite.flags&suiteDefaultOff != 0 {
  		for _, existing := range varDefaultCipherSuites {
  			if existing == suite.id {
  				continue NextCipherSuite
  		varDefaultCipherSuites = append(varDefaultCipherSuites, suite.id)
  func unexpectedMessageError(wanted, got interface{}) error {
  	return fmt.Errorf("tls: received unexpected handshake message of type %T when waiting for %T", got, wanted)
  func isSupportedSignatureAlgorithm(sigAlg SignatureScheme, supportedSignatureAlgorithms []SignatureScheme) bool {
  	for _, s := range supportedSignatureAlgorithms {
  		if s == sigAlg {
  			return true
  	return false
  // signatureFromSignatureScheme maps a signature algorithm to the underlying
  // signature method (without hash function).
  func signatureFromSignatureScheme(signatureAlgorithm SignatureScheme) uint8 {
  	switch signatureAlgorithm {
  	case PKCS1WithSHA1, PKCS1WithSHA256, PKCS1WithSHA384, PKCS1WithSHA512:
  		return signaturePKCS1v15
  	case PSSWithSHA256, PSSWithSHA384, PSSWithSHA512:
  		return signatureRSAPSS
  	case ECDSAWithSHA1, ECDSAWithP256AndSHA256, ECDSAWithP384AndSHA384, ECDSAWithP521AndSHA512:
  		return signatureECDSA
  		return 0

View as plain text