...
Run Format

Source file src/crypto/tls/cipher_suites.go

     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/aes"
     9		"crypto/cipher"
    10		"crypto/des"
    11		"crypto/hmac"
    12		"crypto/rc4"
    13		"crypto/sha1"
    14		"crypto/sha256"
    15		"crypto/x509"
    16		"hash"
    17	
    18		"golang_org/x/crypto/chacha20poly1305"
    19	)
    20	
    21	// a keyAgreement implements the client and server side of a TLS key agreement
    22	// protocol by generating and processing key exchange messages.
    23	type keyAgreement interface {
    24		// On the server side, the first two methods are called in order.
    25	
    26		// In the case that the key agreement protocol doesn't use a
    27		// ServerKeyExchange message, generateServerKeyExchange can return nil,
    28		// nil.
    29		generateServerKeyExchange(*Config, *Certificate, *clientHelloMsg, *serverHelloMsg) (*serverKeyExchangeMsg, error)
    30		processClientKeyExchange(*Config, *Certificate, *clientKeyExchangeMsg, uint16) ([]byte, error)
    31	
    32		// On the client side, the next two methods are called in order.
    33	
    34		// This method may not be called if the server doesn't send a
    35		// ServerKeyExchange message.
    36		processServerKeyExchange(*Config, *clientHelloMsg, *serverHelloMsg, *x509.Certificate, *serverKeyExchangeMsg) error
    37		generateClientKeyExchange(*Config, *clientHelloMsg, *x509.Certificate) ([]byte, *clientKeyExchangeMsg, error)
    38	}
    39	
    40	const (
    41		// suiteECDH indicates that the cipher suite involves elliptic curve
    42		// Diffie-Hellman. This means that it should only be selected when the
    43		// client indicates that it supports ECC with a curve and point format
    44		// that we're happy with.
    45		suiteECDHE = 1 << iota
    46		// suiteECDSA indicates that the cipher suite involves an ECDSA
    47		// signature and therefore may only be selected when the server's
    48		// certificate is ECDSA. If this is not set then the cipher suite is
    49		// RSA based.
    50		suiteECDSA
    51		// suiteTLS12 indicates that the cipher suite should only be advertised
    52		// and accepted when using TLS 1.2.
    53		suiteTLS12
    54		// suiteSHA384 indicates that the cipher suite uses SHA384 as the
    55		// handshake hash.
    56		suiteSHA384
    57		// suiteDefaultOff indicates that this cipher suite is not included by
    58		// default.
    59		suiteDefaultOff
    60	)
    61	
    62	// A cipherSuite is a specific combination of key agreement, cipher and MAC
    63	// function. All cipher suites currently assume RSA key agreement.
    64	type cipherSuite struct {
    65		id uint16
    66		// the lengths, in bytes, of the key material needed for each component.
    67		keyLen int
    68		macLen int
    69		ivLen  int
    70		ka     func(version uint16) keyAgreement
    71		// flags is a bitmask of the suite* values, above.
    72		flags  int
    73		cipher func(key, iv []byte, isRead bool) interface{}
    74		mac    func(version uint16, macKey []byte) macFunction
    75		aead   func(key, fixedNonce []byte) cipher.AEAD
    76	}
    77	
    78	var cipherSuites = []*cipherSuite{
    79		// Ciphersuite order is chosen so that ECDHE comes before plain RSA and
    80		// AEADs are the top preference.
    81		{TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305, 32, 0, 12, ecdheRSAKA, suiteECDHE | suiteTLS12, nil, nil, aeadChaCha20Poly1305},
    82		{TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305, 32, 0, 12, ecdheECDSAKA, suiteECDHE | suiteECDSA | suiteTLS12, nil, nil, aeadChaCha20Poly1305},
    83		{TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, 16, 0, 4, ecdheRSAKA, suiteECDHE | suiteTLS12, nil, nil, aeadAESGCM},
    84		{TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, 16, 0, 4, ecdheECDSAKA, suiteECDHE | suiteECDSA | suiteTLS12, nil, nil, aeadAESGCM},
    85		{TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, 32, 0, 4, ecdheRSAKA, suiteECDHE | suiteTLS12 | suiteSHA384, nil, nil, aeadAESGCM},
    86		{TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, 32, 0, 4, ecdheECDSAKA, suiteECDHE | suiteECDSA | suiteTLS12 | suiteSHA384, nil, nil, aeadAESGCM},
    87		{TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, 16, 32, 16, ecdheRSAKA, suiteECDHE | suiteTLS12 | suiteDefaultOff, cipherAES, macSHA256, nil},
    88		{TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, 16, 20, 16, ecdheRSAKA, suiteECDHE, cipherAES, macSHA1, nil},
    89		{TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, 16, 32, 16, ecdheECDSAKA, suiteECDHE | suiteECDSA | suiteTLS12 | suiteDefaultOff, cipherAES, macSHA256, nil},
    90		{TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, 16, 20, 16, ecdheECDSAKA, suiteECDHE | suiteECDSA, cipherAES, macSHA1, nil},
    91		{TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, 32, 20, 16, ecdheRSAKA, suiteECDHE, cipherAES, macSHA1, nil},
    92		{TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, 32, 20, 16, ecdheECDSAKA, suiteECDHE | suiteECDSA, cipherAES, macSHA1, nil},
    93		{TLS_RSA_WITH_AES_128_GCM_SHA256, 16, 0, 4, rsaKA, suiteTLS12, nil, nil, aeadAESGCM},
    94		{TLS_RSA_WITH_AES_256_GCM_SHA384, 32, 0, 4, rsaKA, suiteTLS12 | suiteSHA384, nil, nil, aeadAESGCM},
    95		{TLS_RSA_WITH_AES_128_CBC_SHA256, 16, 32, 16, rsaKA, suiteTLS12 | suiteDefaultOff, cipherAES, macSHA256, nil},
    96		{TLS_RSA_WITH_AES_128_CBC_SHA, 16, 20, 16, rsaKA, 0, cipherAES, macSHA1, nil},
    97		{TLS_RSA_WITH_AES_256_CBC_SHA, 32, 20, 16, rsaKA, 0, cipherAES, macSHA1, nil},
    98		{TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA, 24, 20, 8, ecdheRSAKA, suiteECDHE, cipher3DES, macSHA1, nil},
    99		{TLS_RSA_WITH_3DES_EDE_CBC_SHA, 24, 20, 8, rsaKA, 0, cipher3DES, macSHA1, nil},
   100	
   101		// RC4-based cipher suites are disabled by default.
   102		{TLS_RSA_WITH_RC4_128_SHA, 16, 20, 0, rsaKA, suiteDefaultOff, cipherRC4, macSHA1, nil},
   103		{TLS_ECDHE_RSA_WITH_RC4_128_SHA, 16, 20, 0, ecdheRSAKA, suiteECDHE | suiteDefaultOff, cipherRC4, macSHA1, nil},
   104		{TLS_ECDHE_ECDSA_WITH_RC4_128_SHA, 16, 20, 0, ecdheECDSAKA, suiteECDHE | suiteECDSA | suiteDefaultOff, cipherRC4, macSHA1, nil},
   105	}
   106	
   107	func cipherRC4(key, iv []byte, isRead bool) interface{} {
   108		cipher, _ := rc4.NewCipher(key)
   109		return cipher
   110	}
   111	
   112	func cipher3DES(key, iv []byte, isRead bool) interface{} {
   113		block, _ := des.NewTripleDESCipher(key)
   114		if isRead {
   115			return cipher.NewCBCDecrypter(block, iv)
   116		}
   117		return cipher.NewCBCEncrypter(block, iv)
   118	}
   119	
   120	func cipherAES(key, iv []byte, isRead bool) interface{} {
   121		block, _ := aes.NewCipher(key)
   122		if isRead {
   123			return cipher.NewCBCDecrypter(block, iv)
   124		}
   125		return cipher.NewCBCEncrypter(block, iv)
   126	}
   127	
   128	// macSHA1 returns a macFunction for the given protocol version.
   129	func macSHA1(version uint16, key []byte) macFunction {
   130		if version == VersionSSL30 {
   131			mac := ssl30MAC{
   132				h:   sha1.New(),
   133				key: make([]byte, len(key)),
   134			}
   135			copy(mac.key, key)
   136			return mac
   137		}
   138		return tls10MAC{hmac.New(newConstantTimeHash(sha1.New), key)}
   139	}
   140	
   141	// macSHA256 returns a SHA-256 based MAC. These are only supported in TLS 1.2
   142	// so the given version is ignored.
   143	func macSHA256(version uint16, key []byte) macFunction {
   144		return tls10MAC{hmac.New(sha256.New, key)}
   145	}
   146	
   147	type macFunction interface {
   148		Size() int
   149		MAC(digestBuf, seq, header, data, extra []byte) []byte
   150	}
   151	
   152	type aead interface {
   153		cipher.AEAD
   154	
   155		// explicitIVLen returns the number of bytes used by the explicit nonce
   156		// that is included in the record. This is eight for older AEADs and
   157		// zero for modern ones.
   158		explicitNonceLen() int
   159	}
   160	
   161	// fixedNonceAEAD wraps an AEAD and prefixes a fixed portion of the nonce to
   162	// each call.
   163	type fixedNonceAEAD struct {
   164		// nonce contains the fixed part of the nonce in the first four bytes.
   165		nonce [12]byte
   166		aead  cipher.AEAD
   167	}
   168	
   169	func (f *fixedNonceAEAD) NonceSize() int        { return 8 }
   170	func (f *fixedNonceAEAD) Overhead() int         { return f.aead.Overhead() }
   171	func (f *fixedNonceAEAD) explicitNonceLen() int { return 8 }
   172	
   173	func (f *fixedNonceAEAD) Seal(out, nonce, plaintext, additionalData []byte) []byte {
   174		copy(f.nonce[4:], nonce)
   175		return f.aead.Seal(out, f.nonce[:], plaintext, additionalData)
   176	}
   177	
   178	func (f *fixedNonceAEAD) Open(out, nonce, plaintext, additionalData []byte) ([]byte, error) {
   179		copy(f.nonce[4:], nonce)
   180		return f.aead.Open(out, f.nonce[:], plaintext, additionalData)
   181	}
   182	
   183	// xoredNonceAEAD wraps an AEAD by XORing in a fixed pattern to the nonce
   184	// before each call.
   185	type xorNonceAEAD struct {
   186		nonceMask [12]byte
   187		aead      cipher.AEAD
   188	}
   189	
   190	func (f *xorNonceAEAD) NonceSize() int        { return 8 }
   191	func (f *xorNonceAEAD) Overhead() int         { return f.aead.Overhead() }
   192	func (f *xorNonceAEAD) explicitNonceLen() int { return 0 }
   193	
   194	func (f *xorNonceAEAD) Seal(out, nonce, plaintext, additionalData []byte) []byte {
   195		for i, b := range nonce {
   196			f.nonceMask[4+i] ^= b
   197		}
   198		result := f.aead.Seal(out, f.nonceMask[:], plaintext, additionalData)
   199		for i, b := range nonce {
   200			f.nonceMask[4+i] ^= b
   201		}
   202	
   203		return result
   204	}
   205	
   206	func (f *xorNonceAEAD) Open(out, nonce, plaintext, additionalData []byte) ([]byte, error) {
   207		for i, b := range nonce {
   208			f.nonceMask[4+i] ^= b
   209		}
   210		result, err := f.aead.Open(out, f.nonceMask[:], plaintext, additionalData)
   211		for i, b := range nonce {
   212			f.nonceMask[4+i] ^= b
   213		}
   214	
   215		return result, err
   216	}
   217	
   218	func aeadAESGCM(key, fixedNonce []byte) cipher.AEAD {
   219		aes, err := aes.NewCipher(key)
   220		if err != nil {
   221			panic(err)
   222		}
   223		aead, err := cipher.NewGCM(aes)
   224		if err != nil {
   225			panic(err)
   226		}
   227	
   228		ret := &fixedNonceAEAD{aead: aead}
   229		copy(ret.nonce[:], fixedNonce)
   230		return ret
   231	}
   232	
   233	func aeadChaCha20Poly1305(key, fixedNonce []byte) cipher.AEAD {
   234		aead, err := chacha20poly1305.New(key)
   235		if err != nil {
   236			panic(err)
   237		}
   238	
   239		ret := &xorNonceAEAD{aead: aead}
   240		copy(ret.nonceMask[:], fixedNonce)
   241		return ret
   242	}
   243	
   244	// ssl30MAC implements the SSLv3 MAC function, as defined in
   245	// www.mozilla.org/projects/security/pki/nss/ssl/draft302.txt section 5.2.3.1
   246	type ssl30MAC struct {
   247		h   hash.Hash
   248		key []byte
   249	}
   250	
   251	func (s ssl30MAC) Size() int {
   252		return s.h.Size()
   253	}
   254	
   255	var ssl30Pad1 = [48]byte{0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36, 0x36}
   256	
   257	var ssl30Pad2 = [48]byte{0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c, 0x5c}
   258	
   259	// MAC does not offer constant timing guarantees for SSL v3.0, since it's deemed
   260	// useless considering the similar, protocol-level POODLE vulnerability.
   261	func (s ssl30MAC) MAC(digestBuf, seq, header, data, extra []byte) []byte {
   262		padLength := 48
   263		if s.h.Size() == 20 {
   264			padLength = 40
   265		}
   266	
   267		s.h.Reset()
   268		s.h.Write(s.key)
   269		s.h.Write(ssl30Pad1[:padLength])
   270		s.h.Write(seq)
   271		s.h.Write(header[:1])
   272		s.h.Write(header[3:5])
   273		s.h.Write(data)
   274		digestBuf = s.h.Sum(digestBuf[:0])
   275	
   276		s.h.Reset()
   277		s.h.Write(s.key)
   278		s.h.Write(ssl30Pad2[:padLength])
   279		s.h.Write(digestBuf)
   280		return s.h.Sum(digestBuf[:0])
   281	}
   282	
   283	type constantTimeHash interface {
   284		hash.Hash
   285		ConstantTimeSum(b []byte) []byte
   286	}
   287	
   288	// cthWrapper wraps any hash.Hash that implements ConstantTimeSum, and replaces
   289	// with that all calls to Sum. It's used to obtain a ConstantTimeSum-based HMAC.
   290	type cthWrapper struct {
   291		h constantTimeHash
   292	}
   293	
   294	func (c *cthWrapper) Size() int                   { return c.h.Size() }
   295	func (c *cthWrapper) BlockSize() int              { return c.h.BlockSize() }
   296	func (c *cthWrapper) Reset()                      { c.h.Reset() }
   297	func (c *cthWrapper) Write(p []byte) (int, error) { return c.h.Write(p) }
   298	func (c *cthWrapper) Sum(b []byte) []byte         { return c.h.ConstantTimeSum(b) }
   299	
   300	func newConstantTimeHash(h func() hash.Hash) func() hash.Hash {
   301		return func() hash.Hash {
   302			return &cthWrapper{h().(constantTimeHash)}
   303		}
   304	}
   305	
   306	// tls10MAC implements the TLS 1.0 MAC function. RFC 2246, section 6.2.3.
   307	type tls10MAC struct {
   308		h hash.Hash
   309	}
   310	
   311	func (s tls10MAC) Size() int {
   312		return s.h.Size()
   313	}
   314	
   315	// MAC is guaranteed to take constant time, as long as
   316	// len(seq)+len(header)+len(data)+len(extra) is constant. extra is not fed into
   317	// the MAC, but is only provided to make the timing profile constant.
   318	func (s tls10MAC) MAC(digestBuf, seq, header, data, extra []byte) []byte {
   319		s.h.Reset()
   320		s.h.Write(seq)
   321		s.h.Write(header)
   322		s.h.Write(data)
   323		res := s.h.Sum(digestBuf[:0])
   324		if extra != nil {
   325			s.h.Write(extra)
   326		}
   327		return res
   328	}
   329	
   330	func rsaKA(version uint16) keyAgreement {
   331		return rsaKeyAgreement{}
   332	}
   333	
   334	func ecdheECDSAKA(version uint16) keyAgreement {
   335		return &ecdheKeyAgreement{
   336			sigType: signatureECDSA,
   337			version: version,
   338		}
   339	}
   340	
   341	func ecdheRSAKA(version uint16) keyAgreement {
   342		return &ecdheKeyAgreement{
   343			sigType: signatureRSA,
   344			version: version,
   345		}
   346	}
   347	
   348	// mutualCipherSuite returns a cipherSuite given a list of supported
   349	// ciphersuites and the id requested by the peer.
   350	func mutualCipherSuite(have []uint16, want uint16) *cipherSuite {
   351		for _, id := range have {
   352			if id == want {
   353				for _, suite := range cipherSuites {
   354					if suite.id == want {
   355						return suite
   356					}
   357				}
   358				return nil
   359			}
   360		}
   361		return nil
   362	}
   363	
   364	// A list of cipher suite IDs that are, or have been, implemented by this
   365	// package.
   366	//
   367	// Taken from http://www.iana.org/assignments/tls-parameters/tls-parameters.xml
   368	const (
   369		TLS_RSA_WITH_RC4_128_SHA                uint16 = 0x0005
   370		TLS_RSA_WITH_3DES_EDE_CBC_SHA           uint16 = 0x000a
   371		TLS_RSA_WITH_AES_128_CBC_SHA            uint16 = 0x002f
   372		TLS_RSA_WITH_AES_256_CBC_SHA            uint16 = 0x0035
   373		TLS_RSA_WITH_AES_128_CBC_SHA256         uint16 = 0x003c
   374		TLS_RSA_WITH_AES_128_GCM_SHA256         uint16 = 0x009c
   375		TLS_RSA_WITH_AES_256_GCM_SHA384         uint16 = 0x009d
   376		TLS_ECDHE_ECDSA_WITH_RC4_128_SHA        uint16 = 0xc007
   377		TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA    uint16 = 0xc009
   378		TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA    uint16 = 0xc00a
   379		TLS_ECDHE_RSA_WITH_RC4_128_SHA          uint16 = 0xc011
   380		TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA     uint16 = 0xc012
   381		TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA      uint16 = 0xc013
   382		TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA      uint16 = 0xc014
   383		TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 uint16 = 0xc023
   384		TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256   uint16 = 0xc027
   385		TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256   uint16 = 0xc02f
   386		TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 uint16 = 0xc02b
   387		TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384   uint16 = 0xc030
   388		TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 uint16 = 0xc02c
   389		TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305    uint16 = 0xcca8
   390		TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305  uint16 = 0xcca9
   391	
   392		// TLS_FALLBACK_SCSV isn't a standard cipher suite but an indicator
   393		// that the client is doing version fallback. See
   394		// https://tools.ietf.org/html/rfc7507.
   395		TLS_FALLBACK_SCSV uint16 = 0x5600
   396	)
   397	

View as plain text