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