cipher_suites.go

Documentation: crypto/tls

		 1  // Copyright 2010 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  	"crypto"
		 9  	"crypto/aes"
		10  	"crypto/cipher"
		11  	"crypto/des"
		12  	"crypto/hmac"
		13  	"crypto/rc4"
		14  	"crypto/sha1"
		15  	"crypto/sha256"
		16  	"fmt"
		17  	"hash"
		18  	"internal/cpu"
		19  	"runtime"
		20  
		21  	"golang.org/x/crypto/chacha20poly1305"
		22  )
		23  
		24  // CipherSuite is a TLS cipher suite. Note that most functions in this package
		25  // accept and expose cipher suite IDs instead of this type.
		26  type CipherSuite struct {
		27  	ID	 uint16
		28  	Name string
		29  
		30  	// Supported versions is the list of TLS protocol versions that can
		31  	// negotiate this cipher suite.
		32  	SupportedVersions []uint16
		33  
		34  	// Insecure is true if the cipher suite has known security issues
		35  	// due to its primitives, design, or implementation.
		36  	Insecure bool
		37  }
		38  
		39  var (
		40  	supportedUpToTLS12 = []uint16{VersionTLS10, VersionTLS11, VersionTLS12}
		41  	supportedOnlyTLS12 = []uint16{VersionTLS12}
		42  	supportedOnlyTLS13 = []uint16{VersionTLS13}
		43  )
		44  
		45  // CipherSuites returns a list of cipher suites currently implemented by this
		46  // package, excluding those with security issues, which are returned by
		47  // InsecureCipherSuites.
		48  //
		49  // The list is sorted by ID. Note that the default cipher suites selected by
		50  // this package might depend on logic that can't be captured by a static list,
		51  // and might not match those returned by this function.
		52  func CipherSuites() []*CipherSuite {
		53  	return []*CipherSuite{
		54  		{TLS_RSA_WITH_AES_128_CBC_SHA, "TLS_RSA_WITH_AES_128_CBC_SHA", supportedUpToTLS12, false},
		55  		{TLS_RSA_WITH_AES_256_CBC_SHA, "TLS_RSA_WITH_AES_256_CBC_SHA", supportedUpToTLS12, false},
		56  		{TLS_RSA_WITH_AES_128_GCM_SHA256, "TLS_RSA_WITH_AES_128_GCM_SHA256", supportedOnlyTLS12, false},
		57  		{TLS_RSA_WITH_AES_256_GCM_SHA384, "TLS_RSA_WITH_AES_256_GCM_SHA384", supportedOnlyTLS12, false},
		58  
		59  		{TLS_AES_128_GCM_SHA256, "TLS_AES_128_GCM_SHA256", supportedOnlyTLS13, false},
		60  		{TLS_AES_256_GCM_SHA384, "TLS_AES_256_GCM_SHA384", supportedOnlyTLS13, false},
		61  		{TLS_CHACHA20_POLY1305_SHA256, "TLS_CHACHA20_POLY1305_SHA256", supportedOnlyTLS13, false},
		62  
		63  		{TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA", supportedUpToTLS12, false},
		64  		{TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, "TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA", supportedUpToTLS12, false},
		65  		{TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA", supportedUpToTLS12, false},
		66  		{TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA", supportedUpToTLS12, false},
		67  		{TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256", supportedOnlyTLS12, false},
		68  		{TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", supportedOnlyTLS12, false},
		69  		{TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", supportedOnlyTLS12, false},
		70  		{TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", supportedOnlyTLS12, false},
		71  		{TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256, "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256", supportedOnlyTLS12, false},
		72  		{TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256, "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256", supportedOnlyTLS12, false},
		73  	}
		74  }
		75  
		76  // InsecureCipherSuites returns a list of cipher suites currently implemented by
		77  // this package and which have security issues.
		78  //
		79  // Most applications should not use the cipher suites in this list, and should
		80  // only use those returned by CipherSuites.
		81  func InsecureCipherSuites() []*CipherSuite {
		82  	// This list includes RC4, CBC_SHA256, and 3DES cipher suites. See
		83  	// cipherSuitesPreferenceOrder for details.
		84  	return []*CipherSuite{
		85  		{TLS_RSA_WITH_RC4_128_SHA, "TLS_RSA_WITH_RC4_128_SHA", supportedUpToTLS12, true},
		86  		{TLS_RSA_WITH_3DES_EDE_CBC_SHA, "TLS_RSA_WITH_3DES_EDE_CBC_SHA", supportedUpToTLS12, true},
		87  		{TLS_RSA_WITH_AES_128_CBC_SHA256, "TLS_RSA_WITH_AES_128_CBC_SHA256", supportedOnlyTLS12, true},
		88  		{TLS_ECDHE_ECDSA_WITH_RC4_128_SHA, "TLS_ECDHE_ECDSA_WITH_RC4_128_SHA", supportedUpToTLS12, true},
		89  		{TLS_ECDHE_RSA_WITH_RC4_128_SHA, "TLS_ECDHE_RSA_WITH_RC4_128_SHA", supportedUpToTLS12, true},
		90  		{TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA, "TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA", supportedUpToTLS12, true},
		91  		{TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256", supportedOnlyTLS12, true},
		92  		{TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256", supportedOnlyTLS12, true},
		93  	}
		94  }
		95  
		96  // CipherSuiteName returns the standard name for the passed cipher suite ID
		97  // (e.g. "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"), or a fallback representation
		98  // of the ID value if the cipher suite is not implemented by this package.
		99  func CipherSuiteName(id uint16) string {
	 100  	for _, c := range CipherSuites() {
	 101  		if c.ID == id {
	 102  			return c.Name
	 103  		}
	 104  	}
	 105  	for _, c := range InsecureCipherSuites() {
	 106  		if c.ID == id {
	 107  			return c.Name
	 108  		}
	 109  	}
	 110  	return fmt.Sprintf("0x%04X", id)
	 111  }
	 112  
	 113  const (
	 114  	// suiteECDHE indicates that the cipher suite involves elliptic curve
	 115  	// Diffie-Hellman. This means that it should only be selected when the
	 116  	// client indicates that it supports ECC with a curve and point format
	 117  	// that we're happy with.
	 118  	suiteECDHE = 1 << iota
	 119  	// suiteECSign indicates that the cipher suite involves an ECDSA or
	 120  	// EdDSA signature and therefore may only be selected when the server's
	 121  	// certificate is ECDSA or EdDSA. If this is not set then the cipher suite
	 122  	// is RSA based.
	 123  	suiteECSign
	 124  	// suiteTLS12 indicates that the cipher suite should only be advertised
	 125  	// and accepted when using TLS 1.2.
	 126  	suiteTLS12
	 127  	// suiteSHA384 indicates that the cipher suite uses SHA384 as the
	 128  	// handshake hash.
	 129  	suiteSHA384
	 130  )
	 131  
	 132  // A cipherSuite is a TLS 1.0–1.2 cipher suite, and defines the key exchange
	 133  // mechanism, as well as the cipher+MAC pair or the AEAD.
	 134  type cipherSuite struct {
	 135  	id uint16
	 136  	// the lengths, in bytes, of the key material needed for each component.
	 137  	keyLen int
	 138  	macLen int
	 139  	ivLen	int
	 140  	ka		 func(version uint16) keyAgreement
	 141  	// flags is a bitmask of the suite* values, above.
	 142  	flags	int
	 143  	cipher func(key, iv []byte, isRead bool) interface{}
	 144  	mac		func(key []byte) hash.Hash
	 145  	aead	 func(key, fixedNonce []byte) aead
	 146  }
	 147  
	 148  var cipherSuites = []*cipherSuite{ // TODO: replace with a map, since the order doesn't matter.
	 149  	{TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305, 32, 0, 12, ecdheRSAKA, suiteECDHE | suiteTLS12, nil, nil, aeadChaCha20Poly1305},
	 150  	{TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305, 32, 0, 12, ecdheECDSAKA, suiteECDHE | suiteECSign | suiteTLS12, nil, nil, aeadChaCha20Poly1305},
	 151  	{TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, 16, 0, 4, ecdheRSAKA, suiteECDHE | suiteTLS12, nil, nil, aeadAESGCM},
	 152  	{TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, 16, 0, 4, ecdheECDSAKA, suiteECDHE | suiteECSign | suiteTLS12, nil, nil, aeadAESGCM},
	 153  	{TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, 32, 0, 4, ecdheRSAKA, suiteECDHE | suiteTLS12 | suiteSHA384, nil, nil, aeadAESGCM},
	 154  	{TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, 32, 0, 4, ecdheECDSAKA, suiteECDHE | suiteECSign | suiteTLS12 | suiteSHA384, nil, nil, aeadAESGCM},
	 155  	{TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, 16, 32, 16, ecdheRSAKA, suiteECDHE | suiteTLS12, cipherAES, macSHA256, nil},
	 156  	{TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, 16, 20, 16, ecdheRSAKA, suiteECDHE, cipherAES, macSHA1, nil},
	 157  	{TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, 16, 32, 16, ecdheECDSAKA, suiteECDHE | suiteECSign | suiteTLS12, cipherAES, macSHA256, nil},
	 158  	{TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, 16, 20, 16, ecdheECDSAKA, suiteECDHE | suiteECSign, cipherAES, macSHA1, nil},
	 159  	{TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, 32, 20, 16, ecdheRSAKA, suiteECDHE, cipherAES, macSHA1, nil},
	 160  	{TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, 32, 20, 16, ecdheECDSAKA, suiteECDHE | suiteECSign, cipherAES, macSHA1, nil},
	 161  	{TLS_RSA_WITH_AES_128_GCM_SHA256, 16, 0, 4, rsaKA, suiteTLS12, nil, nil, aeadAESGCM},
	 162  	{TLS_RSA_WITH_AES_256_GCM_SHA384, 32, 0, 4, rsaKA, suiteTLS12 | suiteSHA384, nil, nil, aeadAESGCM},
	 163  	{TLS_RSA_WITH_AES_128_CBC_SHA256, 16, 32, 16, rsaKA, suiteTLS12, cipherAES, macSHA256, nil},
	 164  	{TLS_RSA_WITH_AES_128_CBC_SHA, 16, 20, 16, rsaKA, 0, cipherAES, macSHA1, nil},
	 165  	{TLS_RSA_WITH_AES_256_CBC_SHA, 32, 20, 16, rsaKA, 0, cipherAES, macSHA1, nil},
	 166  	{TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA, 24, 20, 8, ecdheRSAKA, suiteECDHE, cipher3DES, macSHA1, nil},
	 167  	{TLS_RSA_WITH_3DES_EDE_CBC_SHA, 24, 20, 8, rsaKA, 0, cipher3DES, macSHA1, nil},
	 168  	{TLS_RSA_WITH_RC4_128_SHA, 16, 20, 0, rsaKA, 0, cipherRC4, macSHA1, nil},
	 169  	{TLS_ECDHE_RSA_WITH_RC4_128_SHA, 16, 20, 0, ecdheRSAKA, suiteECDHE, cipherRC4, macSHA1, nil},
	 170  	{TLS_ECDHE_ECDSA_WITH_RC4_128_SHA, 16, 20, 0, ecdheECDSAKA, suiteECDHE | suiteECSign, cipherRC4, macSHA1, nil},
	 171  }
	 172  
	 173  // selectCipherSuite returns the first TLS 1.0–1.2 cipher suite from ids which
	 174  // is also in supportedIDs and passes the ok filter.
	 175  func selectCipherSuite(ids, supportedIDs []uint16, ok func(*cipherSuite) bool) *cipherSuite {
	 176  	for _, id := range ids {
	 177  		candidate := cipherSuiteByID(id)
	 178  		if candidate == nil || !ok(candidate) {
	 179  			continue
	 180  		}
	 181  
	 182  		for _, suppID := range supportedIDs {
	 183  			if id == suppID {
	 184  				return candidate
	 185  			}
	 186  		}
	 187  	}
	 188  	return nil
	 189  }
	 190  
	 191  // A cipherSuiteTLS13 defines only the pair of the AEAD algorithm and hash
	 192  // algorithm to be used with HKDF. See RFC 8446, Appendix B.4.
	 193  type cipherSuiteTLS13 struct {
	 194  	id		 uint16
	 195  	keyLen int
	 196  	aead	 func(key, fixedNonce []byte) aead
	 197  	hash	 crypto.Hash
	 198  }
	 199  
	 200  var cipherSuitesTLS13 = []*cipherSuiteTLS13{ // TODO: replace with a map.
	 201  	{TLS_AES_128_GCM_SHA256, 16, aeadAESGCMTLS13, crypto.SHA256},
	 202  	{TLS_CHACHA20_POLY1305_SHA256, 32, aeadChaCha20Poly1305, crypto.SHA256},
	 203  	{TLS_AES_256_GCM_SHA384, 32, aeadAESGCMTLS13, crypto.SHA384},
	 204  }
	 205  
	 206  // cipherSuitesPreferenceOrder is the order in which we'll select (on the
	 207  // server) or advertise (on the client) TLS 1.0–1.2 cipher suites.
	 208  //
	 209  // Cipher suites are filtered but not reordered based on the application and
	 210  // peer's preferences, meaning we'll never select a suite lower in this list if
	 211  // any higher one is available. This makes it more defensible to keep weaker
	 212  // cipher suites enabled, especially on the server side where we get the last
	 213  // word, since there are no known downgrade attacks on cipher suites selection.
	 214  //
	 215  // The list is sorted by applying the following priority rules, stopping at the
	 216  // first (most important) applicable one:
	 217  //
	 218  //	 - Anything else comes before RC4
	 219  //
	 220  //			 RC4 has practically exploitable biases. See https://www.rc4nomore.com.
	 221  //
	 222  //	 - Anything else comes before CBC_SHA256
	 223  //
	 224  //			 SHA-256 variants of the CBC ciphersuites don't implement any Lucky13
	 225  //			 countermeasures. See http://www.isg.rhul.ac.uk/tls/Lucky13.html and
	 226  //			 https://www.imperialviolet.org/2013/02/04/luckythirteen.html.
	 227  //
	 228  //	 - Anything else comes before 3DES
	 229  //
	 230  //			 3DES has 64-bit blocks, which makes it fundamentally susceptible to
	 231  //			 birthday attacks. See https://sweet32.info.
	 232  //
	 233  //	 - ECDHE comes before anything else
	 234  //
	 235  //			 Once we got the broken stuff out of the way, the most important
	 236  //			 property a cipher suite can have is forward secrecy. We don't
	 237  //			 implement FFDHE, so that means ECDHE.
	 238  //
	 239  //	 - AEADs come before CBC ciphers
	 240  //
	 241  //			 Even with Lucky13 countermeasures, MAC-then-Encrypt CBC cipher suites
	 242  //			 are fundamentally fragile, and suffered from an endless sequence of
	 243  //			 padding oracle attacks. See https://eprint.iacr.org/2015/1129,
	 244  //			 https://www.imperialviolet.org/2014/12/08/poodleagain.html, and
	 245  //			 https://blog.cloudflare.com/yet-another-padding-oracle-in-openssl-cbc-ciphersuites/.
	 246  //
	 247  //	 - AES comes before ChaCha20
	 248  //
	 249  //			 When AES hardware is available, AES-128-GCM and AES-256-GCM are faster
	 250  //			 than ChaCha20Poly1305.
	 251  //
	 252  //			 When AES hardware is not available, AES-128-GCM is one or more of: much
	 253  //			 slower, way more complex, and less safe (because not constant time)
	 254  //			 than ChaCha20Poly1305.
	 255  //
	 256  //			 We use this list if we think both peers have AES hardware, and
	 257  //			 cipherSuitesPreferenceOrderNoAES otherwise.
	 258  //
	 259  //	 - AES-128 comes before AES-256
	 260  //
	 261  //			 The only potential advantages of AES-256 are better multi-target
	 262  //			 margins, and hypothetical post-quantum properties. Neither apply to
	 263  //			 TLS, and AES-256 is slower due to its four extra rounds (which don't
	 264  //			 contribute to the advantages above).
	 265  //
	 266  //	 - ECDSA comes before RSA
	 267  //
	 268  //			 The relative order of ECDSA and RSA cipher suites doesn't matter,
	 269  //			 as they depend on the certificate. Pick one to get a stable order.
	 270  //
	 271  var cipherSuitesPreferenceOrder = []uint16{
	 272  	// AEADs w/ ECDHE
	 273  	TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
	 274  	TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
	 275  	TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305, TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,
	 276  
	 277  	// CBC w/ ECDHE
	 278  	TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,
	 279  	TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,
	 280  
	 281  	// AEADs w/o ECDHE
	 282  	TLS_RSA_WITH_AES_128_GCM_SHA256,
	 283  	TLS_RSA_WITH_AES_256_GCM_SHA384,
	 284  
	 285  	// CBC w/o ECDHE
	 286  	TLS_RSA_WITH_AES_128_CBC_SHA,
	 287  	TLS_RSA_WITH_AES_256_CBC_SHA,
	 288  
	 289  	// 3DES
	 290  	TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,
	 291  	TLS_RSA_WITH_3DES_EDE_CBC_SHA,
	 292  
	 293  	// CBC_SHA256
	 294  	TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,
	 295  	TLS_RSA_WITH_AES_128_CBC_SHA256,
	 296  
	 297  	// RC4
	 298  	TLS_ECDHE_ECDSA_WITH_RC4_128_SHA, TLS_ECDHE_RSA_WITH_RC4_128_SHA,
	 299  	TLS_RSA_WITH_RC4_128_SHA,
	 300  }
	 301  
	 302  var cipherSuitesPreferenceOrderNoAES = []uint16{
	 303  	// ChaCha20Poly1305
	 304  	TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305, TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,
	 305  
	 306  	// AES-GCM w/ ECDHE
	 307  	TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
	 308  	TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
	 309  
	 310  	// The rest of cipherSuitesPreferenceOrder.
	 311  	TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,
	 312  	TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,
	 313  	TLS_RSA_WITH_AES_128_GCM_SHA256,
	 314  	TLS_RSA_WITH_AES_256_GCM_SHA384,
	 315  	TLS_RSA_WITH_AES_128_CBC_SHA,
	 316  	TLS_RSA_WITH_AES_256_CBC_SHA,
	 317  	TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,
	 318  	TLS_RSA_WITH_3DES_EDE_CBC_SHA,
	 319  	TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,
	 320  	TLS_RSA_WITH_AES_128_CBC_SHA256,
	 321  	TLS_ECDHE_ECDSA_WITH_RC4_128_SHA, TLS_ECDHE_RSA_WITH_RC4_128_SHA,
	 322  	TLS_RSA_WITH_RC4_128_SHA,
	 323  }
	 324  
	 325  // disabledCipherSuites are not used unless explicitly listed in
	 326  // Config.CipherSuites. They MUST be at the end of cipherSuitesPreferenceOrder.
	 327  var disabledCipherSuites = []uint16{
	 328  	// CBC_SHA256
	 329  	TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,
	 330  	TLS_RSA_WITH_AES_128_CBC_SHA256,
	 331  
	 332  	// RC4
	 333  	TLS_ECDHE_ECDSA_WITH_RC4_128_SHA, TLS_ECDHE_RSA_WITH_RC4_128_SHA,
	 334  	TLS_RSA_WITH_RC4_128_SHA,
	 335  }
	 336  
	 337  var (
	 338  	defaultCipherSuitesLen = len(cipherSuitesPreferenceOrder) - len(disabledCipherSuites)
	 339  	defaultCipherSuites		= cipherSuitesPreferenceOrder[:defaultCipherSuitesLen]
	 340  )
	 341  
	 342  // defaultCipherSuitesTLS13 is also the preference order, since there are no
	 343  // disabled by default TLS 1.3 cipher suites. The same AES vs ChaCha20 logic as
	 344  // cipherSuitesPreferenceOrder applies.
	 345  var defaultCipherSuitesTLS13 = []uint16{
	 346  	TLS_AES_128_GCM_SHA256,
	 347  	TLS_AES_256_GCM_SHA384,
	 348  	TLS_CHACHA20_POLY1305_SHA256,
	 349  }
	 350  
	 351  var defaultCipherSuitesTLS13NoAES = []uint16{
	 352  	TLS_CHACHA20_POLY1305_SHA256,
	 353  	TLS_AES_128_GCM_SHA256,
	 354  	TLS_AES_256_GCM_SHA384,
	 355  }
	 356  
	 357  var (
	 358  	hasGCMAsmAMD64 = cpu.X86.HasAES && cpu.X86.HasPCLMULQDQ
	 359  	hasGCMAsmARM64 = cpu.ARM64.HasAES && cpu.ARM64.HasPMULL
	 360  	// Keep in sync with crypto/aes/cipher_s390x.go.
	 361  	hasGCMAsmS390X = cpu.S390X.HasAES && cpu.S390X.HasAESCBC && cpu.S390X.HasAESCTR &&
	 362  		(cpu.S390X.HasGHASH || cpu.S390X.HasAESGCM)
	 363  
	 364  	hasAESGCMHardwareSupport = runtime.GOARCH == "amd64" && hasGCMAsmAMD64 ||
	 365  		runtime.GOARCH == "arm64" && hasGCMAsmARM64 ||
	 366  		runtime.GOARCH == "s390x" && hasGCMAsmS390X
	 367  )
	 368  
	 369  var aesgcmCiphers = map[uint16]bool{
	 370  	// TLS 1.2
	 371  	TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256:	 true,
	 372  	TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384:	 true,
	 373  	TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256: true,
	 374  	TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384: true,
	 375  	// TLS 1.3
	 376  	TLS_AES_128_GCM_SHA256: true,
	 377  	TLS_AES_256_GCM_SHA384: true,
	 378  }
	 379  
	 380  var nonAESGCMAEADCiphers = map[uint16]bool{
	 381  	// TLS 1.2
	 382  	TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305:	 true,
	 383  	TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305: true,
	 384  	// TLS 1.3
	 385  	TLS_CHACHA20_POLY1305_SHA256: true,
	 386  }
	 387  
	 388  // aesgcmPreferred returns whether the first known cipher in the preference list
	 389  // is an AES-GCM cipher, implying the peer has hardware support for it.
	 390  func aesgcmPreferred(ciphers []uint16) bool {
	 391  	for _, cID := range ciphers {
	 392  		if c := cipherSuiteByID(cID); c != nil {
	 393  			return aesgcmCiphers[cID]
	 394  		}
	 395  		if c := cipherSuiteTLS13ByID(cID); c != nil {
	 396  			return aesgcmCiphers[cID]
	 397  		}
	 398  	}
	 399  	return false
	 400  }
	 401  
	 402  func cipherRC4(key, iv []byte, isRead bool) interface{} {
	 403  	cipher, _ := rc4.NewCipher(key)
	 404  	return cipher
	 405  }
	 406  
	 407  func cipher3DES(key, iv []byte, isRead bool) interface{} {
	 408  	block, _ := des.NewTripleDESCipher(key)
	 409  	if isRead {
	 410  		return cipher.NewCBCDecrypter(block, iv)
	 411  	}
	 412  	return cipher.NewCBCEncrypter(block, iv)
	 413  }
	 414  
	 415  func cipherAES(key, iv []byte, isRead bool) interface{} {
	 416  	block, _ := aes.NewCipher(key)
	 417  	if isRead {
	 418  		return cipher.NewCBCDecrypter(block, iv)
	 419  	}
	 420  	return cipher.NewCBCEncrypter(block, iv)
	 421  }
	 422  
	 423  // macSHA1 returns a SHA-1 based constant time MAC.
	 424  func macSHA1(key []byte) hash.Hash {
	 425  	return hmac.New(newConstantTimeHash(sha1.New), key)
	 426  }
	 427  
	 428  // macSHA256 returns a SHA-256 based MAC. This is only supported in TLS 1.2 and
	 429  // is currently only used in disabled-by-default cipher suites.
	 430  func macSHA256(key []byte) hash.Hash {
	 431  	return hmac.New(sha256.New, key)
	 432  }
	 433  
	 434  type aead interface {
	 435  	cipher.AEAD
	 436  
	 437  	// explicitNonceLen returns the number of bytes of explicit nonce
	 438  	// included in each record. This is eight for older AEADs and
	 439  	// zero for modern ones.
	 440  	explicitNonceLen() int
	 441  }
	 442  
	 443  const (
	 444  	aeadNonceLength	 = 12
	 445  	noncePrefixLength = 4
	 446  )
	 447  
	 448  // prefixNonceAEAD wraps an AEAD and prefixes a fixed portion of the nonce to
	 449  // each call.
	 450  type prefixNonceAEAD struct {
	 451  	// nonce contains the fixed part of the nonce in the first four bytes.
	 452  	nonce [aeadNonceLength]byte
	 453  	aead	cipher.AEAD
	 454  }
	 455  
	 456  func (f *prefixNonceAEAD) NonceSize() int				{ return aeadNonceLength - noncePrefixLength }
	 457  func (f *prefixNonceAEAD) Overhead() int				 { return f.aead.Overhead() }
	 458  func (f *prefixNonceAEAD) explicitNonceLen() int { return f.NonceSize() }
	 459  
	 460  func (f *prefixNonceAEAD) Seal(out, nonce, plaintext, additionalData []byte) []byte {
	 461  	copy(f.nonce[4:], nonce)
	 462  	return f.aead.Seal(out, f.nonce[:], plaintext, additionalData)
	 463  }
	 464  
	 465  func (f *prefixNonceAEAD) Open(out, nonce, ciphertext, additionalData []byte) ([]byte, error) {
	 466  	copy(f.nonce[4:], nonce)
	 467  	return f.aead.Open(out, f.nonce[:], ciphertext, additionalData)
	 468  }
	 469  
	 470  // xoredNonceAEAD wraps an AEAD by XORing in a fixed pattern to the nonce
	 471  // before each call.
	 472  type xorNonceAEAD struct {
	 473  	nonceMask [aeadNonceLength]byte
	 474  	aead			cipher.AEAD
	 475  }
	 476  
	 477  func (f *xorNonceAEAD) NonceSize() int				{ return 8 } // 64-bit sequence number
	 478  func (f *xorNonceAEAD) Overhead() int				 { return f.aead.Overhead() }
	 479  func (f *xorNonceAEAD) explicitNonceLen() int { return 0 }
	 480  
	 481  func (f *xorNonceAEAD) Seal(out, nonce, plaintext, additionalData []byte) []byte {
	 482  	for i, b := range nonce {
	 483  		f.nonceMask[4+i] ^= b
	 484  	}
	 485  	result := f.aead.Seal(out, f.nonceMask[:], plaintext, additionalData)
	 486  	for i, b := range nonce {
	 487  		f.nonceMask[4+i] ^= b
	 488  	}
	 489  
	 490  	return result
	 491  }
	 492  
	 493  func (f *xorNonceAEAD) Open(out, nonce, ciphertext, additionalData []byte) ([]byte, error) {
	 494  	for i, b := range nonce {
	 495  		f.nonceMask[4+i] ^= b
	 496  	}
	 497  	result, err := f.aead.Open(out, f.nonceMask[:], ciphertext, additionalData)
	 498  	for i, b := range nonce {
	 499  		f.nonceMask[4+i] ^= b
	 500  	}
	 501  
	 502  	return result, err
	 503  }
	 504  
	 505  func aeadAESGCM(key, noncePrefix []byte) aead {
	 506  	if len(noncePrefix) != noncePrefixLength {
	 507  		panic("tls: internal error: wrong nonce length")
	 508  	}
	 509  	aes, err := aes.NewCipher(key)
	 510  	if err != nil {
	 511  		panic(err)
	 512  	}
	 513  	aead, err := cipher.NewGCM(aes)
	 514  	if err != nil {
	 515  		panic(err)
	 516  	}
	 517  
	 518  	ret := &prefixNonceAEAD{aead: aead}
	 519  	copy(ret.nonce[:], noncePrefix)
	 520  	return ret
	 521  }
	 522  
	 523  func aeadAESGCMTLS13(key, nonceMask []byte) aead {
	 524  	if len(nonceMask) != aeadNonceLength {
	 525  		panic("tls: internal error: wrong nonce length")
	 526  	}
	 527  	aes, err := aes.NewCipher(key)
	 528  	if err != nil {
	 529  		panic(err)
	 530  	}
	 531  	aead, err := cipher.NewGCM(aes)
	 532  	if err != nil {
	 533  		panic(err)
	 534  	}
	 535  
	 536  	ret := &xorNonceAEAD{aead: aead}
	 537  	copy(ret.nonceMask[:], nonceMask)
	 538  	return ret
	 539  }
	 540  
	 541  func aeadChaCha20Poly1305(key, nonceMask []byte) aead {
	 542  	if len(nonceMask) != aeadNonceLength {
	 543  		panic("tls: internal error: wrong nonce length")
	 544  	}
	 545  	aead, err := chacha20poly1305.New(key)
	 546  	if err != nil {
	 547  		panic(err)
	 548  	}
	 549  
	 550  	ret := &xorNonceAEAD{aead: aead}
	 551  	copy(ret.nonceMask[:], nonceMask)
	 552  	return ret
	 553  }
	 554  
	 555  type constantTimeHash interface {
	 556  	hash.Hash
	 557  	ConstantTimeSum(b []byte) []byte
	 558  }
	 559  
	 560  // cthWrapper wraps any hash.Hash that implements ConstantTimeSum, and replaces
	 561  // with that all calls to Sum. It's used to obtain a ConstantTimeSum-based HMAC.
	 562  type cthWrapper struct {
	 563  	h constantTimeHash
	 564  }
	 565  
	 566  func (c *cthWrapper) Size() int									 { return c.h.Size() }
	 567  func (c *cthWrapper) BlockSize() int							{ return c.h.BlockSize() }
	 568  func (c *cthWrapper) Reset()											{ c.h.Reset() }
	 569  func (c *cthWrapper) Write(p []byte) (int, error) { return c.h.Write(p) }
	 570  func (c *cthWrapper) Sum(b []byte) []byte				 { return c.h.ConstantTimeSum(b) }
	 571  
	 572  func newConstantTimeHash(h func() hash.Hash) func() hash.Hash {
	 573  	return func() hash.Hash {
	 574  		return &cthWrapper{h().(constantTimeHash)}
	 575  	}
	 576  }
	 577  
	 578  // tls10MAC implements the TLS 1.0 MAC function. RFC 2246, Section 6.2.3.
	 579  func tls10MAC(h hash.Hash, out, seq, header, data, extra []byte) []byte {
	 580  	h.Reset()
	 581  	h.Write(seq)
	 582  	h.Write(header)
	 583  	h.Write(data)
	 584  	res := h.Sum(out)
	 585  	if extra != nil {
	 586  		h.Write(extra)
	 587  	}
	 588  	return res
	 589  }
	 590  
	 591  func rsaKA(version uint16) keyAgreement {
	 592  	return rsaKeyAgreement{}
	 593  }
	 594  
	 595  func ecdheECDSAKA(version uint16) keyAgreement {
	 596  	return &ecdheKeyAgreement{
	 597  		isRSA:	 false,
	 598  		version: version,
	 599  	}
	 600  }
	 601  
	 602  func ecdheRSAKA(version uint16) keyAgreement {
	 603  	return &ecdheKeyAgreement{
	 604  		isRSA:	 true,
	 605  		version: version,
	 606  	}
	 607  }
	 608  
	 609  // mutualCipherSuite returns a cipherSuite given a list of supported
	 610  // ciphersuites and the id requested by the peer.
	 611  func mutualCipherSuite(have []uint16, want uint16) *cipherSuite {
	 612  	for _, id := range have {
	 613  		if id == want {
	 614  			return cipherSuiteByID(id)
	 615  		}
	 616  	}
	 617  	return nil
	 618  }
	 619  
	 620  func cipherSuiteByID(id uint16) *cipherSuite {
	 621  	for _, cipherSuite := range cipherSuites {
	 622  		if cipherSuite.id == id {
	 623  			return cipherSuite
	 624  		}
	 625  	}
	 626  	return nil
	 627  }
	 628  
	 629  func mutualCipherSuiteTLS13(have []uint16, want uint16) *cipherSuiteTLS13 {
	 630  	for _, id := range have {
	 631  		if id == want {
	 632  			return cipherSuiteTLS13ByID(id)
	 633  		}
	 634  	}
	 635  	return nil
	 636  }
	 637  
	 638  func cipherSuiteTLS13ByID(id uint16) *cipherSuiteTLS13 {
	 639  	for _, cipherSuite := range cipherSuitesTLS13 {
	 640  		if cipherSuite.id == id {
	 641  			return cipherSuite
	 642  		}
	 643  	}
	 644  	return nil
	 645  }
	 646  
	 647  // A list of cipher suite IDs that are, or have been, implemented by this
	 648  // package.
	 649  //
	 650  // See https://www.iana.org/assignments/tls-parameters/tls-parameters.xml
	 651  const (
	 652  	// TLS 1.0 - 1.2 cipher suites.
	 653  	TLS_RSA_WITH_RC4_128_SHA											uint16 = 0x0005
	 654  	TLS_RSA_WITH_3DES_EDE_CBC_SHA								 uint16 = 0x000a
	 655  	TLS_RSA_WITH_AES_128_CBC_SHA									uint16 = 0x002f
	 656  	TLS_RSA_WITH_AES_256_CBC_SHA									uint16 = 0x0035
	 657  	TLS_RSA_WITH_AES_128_CBC_SHA256							 uint16 = 0x003c
	 658  	TLS_RSA_WITH_AES_128_GCM_SHA256							 uint16 = 0x009c
	 659  	TLS_RSA_WITH_AES_256_GCM_SHA384							 uint16 = 0x009d
	 660  	TLS_ECDHE_ECDSA_WITH_RC4_128_SHA							uint16 = 0xc007
	 661  	TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA					uint16 = 0xc009
	 662  	TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA					uint16 = 0xc00a
	 663  	TLS_ECDHE_RSA_WITH_RC4_128_SHA								uint16 = 0xc011
	 664  	TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA					 uint16 = 0xc012
	 665  	TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA						uint16 = 0xc013
	 666  	TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA						uint16 = 0xc014
	 667  	TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256			 uint16 = 0xc023
	 668  	TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256				 uint16 = 0xc027
	 669  	TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256				 uint16 = 0xc02f
	 670  	TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256			 uint16 = 0xc02b
	 671  	TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384				 uint16 = 0xc030
	 672  	TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384			 uint16 = 0xc02c
	 673  	TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256	 uint16 = 0xcca8
	 674  	TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 uint16 = 0xcca9
	 675  
	 676  	// TLS 1.3 cipher suites.
	 677  	TLS_AES_128_GCM_SHA256			 uint16 = 0x1301
	 678  	TLS_AES_256_GCM_SHA384			 uint16 = 0x1302
	 679  	TLS_CHACHA20_POLY1305_SHA256 uint16 = 0x1303
	 680  
	 681  	// TLS_FALLBACK_SCSV isn't a standard cipher suite but an indicator
	 682  	// that the client is doing version fallback. See RFC 7507.
	 683  	TLS_FALLBACK_SCSV uint16 = 0x5600
	 684  
	 685  	// Legacy names for the corresponding cipher suites with the correct _SHA256
	 686  	// suffix, retained for backward compatibility.
	 687  	TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305	 = TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
	 688  	TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305 = TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
	 689  )
	 690
View as plain text