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