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.
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.
26 // In the case that the key agreement protocol doesn't use a
27 // ServerKeyExchange message, generateServerKeyExchange can return nil,
29 generateServerKeyExchange(*Config, *Certificate, *clientHelloMsg, *serverHelloMsg) (*serverKeyExchangeMsg, error)
30 processClientKeyExchange(*Config, *Certificate, *clientKeyExchangeMsg, uint16) ([]byte, error)
32 // On the client side, the next two methods are called in order.
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)
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
51 // suiteTLS12 indicates that the cipher suite should only be advertised
52 // and accepted when using TLS 1.2.
54 // suiteSHA384 indicates that the cipher suite uses SHA384 as the
57 // suiteNoDTLS indicates that the cipher suite cannot be used
60 // suitePSK indicates that the cipher suite authenticates with
61 // a pre-shared key rather than a server private key.
65 // A cipherSuite is a specific combination of key agreement, cipher and MAC
66 // function. All cipher suites currently assume RSA key agreement.
67 type cipherSuite struct {
69 // the lengths, in bytes, of the key material needed for each component.
73 ka func(version uint16) keyAgreement
74 // flags is a bitmask of the suite* values, above.
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
81 var cipherSuites = []*cipherSuite{
82 // Ciphersuite order is chosen so that ECDHE comes before plain RSA
83 // and RC4 comes before AES (because of the Lucky13 attack).
84 {TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, 16, 0, 4, ecdheRSAKA, suiteECDHE | suiteTLS12, nil, nil, aeadAESGCM},
85 {TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, 16, 0, 4, ecdheECDSAKA, suiteECDHE | suiteECDSA | suiteTLS12, nil, nil, aeadAESGCM},
86 {TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, 32, 0, 4, ecdheRSAKA, suiteECDHE | suiteTLS12 | suiteSHA384, nil, nil, aeadAESGCM},
87 {TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, 32, 0, 4, ecdheECDSAKA, suiteECDHE | suiteECDSA | suiteTLS12 | suiteSHA384, nil, nil, aeadAESGCM},
88 {TLS_ECDHE_RSA_WITH_RC4_128_SHA, 16, 20, 0, ecdheRSAKA, suiteECDHE | suiteNoDTLS, cipherRC4, macSHA1, nil},
89 {TLS_ECDHE_ECDSA_WITH_RC4_128_SHA, 16, 20, 0, ecdheECDSAKA, suiteECDHE | suiteECDSA | suiteNoDTLS, cipherRC4, macSHA1, nil},
90 {TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, 16, 32, 16, ecdheRSAKA, suiteECDHE | suiteTLS12, cipherAES, macSHA256, nil},
91 {TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, 16, 32, 16, ecdheECDSAKA, suiteECDHE | suiteECDSA | suiteTLS12, cipherAES, macSHA256, nil},
92 {TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, 16, 20, 16, ecdheRSAKA, suiteECDHE, cipherAES, macSHA1, nil},
93 {TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, 16, 20, 16, ecdheECDSAKA, suiteECDHE | suiteECDSA, cipherAES, macSHA1, nil},
94 {TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, 32, 48, 16, ecdheRSAKA, suiteECDHE | suiteTLS12 | suiteSHA384, cipherAES, macSHA384, nil},
95 {TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384, 32, 48, 16, ecdheECDSAKA, suiteECDHE | suiteECDSA | suiteTLS12 | suiteSHA384, cipherAES, macSHA384, nil},
96 {TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, 32, 20, 16, ecdheRSAKA, suiteECDHE, cipherAES, macSHA1, nil},
97 {TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, 32, 20, 16, ecdheECDSAKA, suiteECDHE | suiteECDSA, cipherAES, macSHA1, nil},
98 {TLS_DHE_RSA_WITH_AES_128_GCM_SHA256, 16, 0, 4, dheRSAKA, suiteTLS12, nil, nil, aeadAESGCM},
99 {TLS_DHE_RSA_WITH_AES_256_GCM_SHA384, 32, 0, 4, dheRSAKA, suiteTLS12 | suiteSHA384, nil, nil, aeadAESGCM},
100 {TLS_DHE_RSA_WITH_AES_128_CBC_SHA256, 16, 32, 16, dheRSAKA, suiteTLS12, cipherAES, macSHA256, nil},
101 {TLS_DHE_RSA_WITH_AES_256_CBC_SHA256, 32, 32, 16, dheRSAKA, suiteTLS12, cipherAES, macSHA256, nil},
102 {TLS_DHE_RSA_WITH_AES_128_CBC_SHA, 16, 20, 16, dheRSAKA, 0, cipherAES, macSHA1, nil},
103 {TLS_DHE_RSA_WITH_AES_256_CBC_SHA, 32, 20, 16, dheRSAKA, 0, cipherAES, macSHA1, nil},
104 {TLS_RSA_WITH_AES_128_GCM_SHA256, 16, 0, 4, rsaKA, suiteTLS12, nil, nil, aeadAESGCM},
105 {TLS_RSA_WITH_AES_256_GCM_SHA384, 32, 0, 4, rsaKA, suiteTLS12 | suiteSHA384, nil, nil, aeadAESGCM},
106 {TLS_RSA_WITH_RC4_128_SHA, 16, 20, 0, rsaKA, suiteNoDTLS, cipherRC4, macSHA1, nil},
107 {TLS_RSA_WITH_RC4_128_MD5, 16, 16, 0, rsaKA, suiteNoDTLS, cipherRC4, macMD5, nil},
108 {TLS_RSA_WITH_AES_128_CBC_SHA256, 16, 32, 16, rsaKA, suiteTLS12, cipherAES, macSHA256, nil},
109 {TLS_RSA_WITH_AES_256_CBC_SHA256, 32, 32, 16, rsaKA, suiteTLS12, cipherAES, macSHA256, nil},
110 {TLS_RSA_WITH_AES_128_CBC_SHA, 16, 20, 16, rsaKA, 0, cipherAES, macSHA1, nil},
111 {TLS_RSA_WITH_AES_256_CBC_SHA, 32, 20, 16, rsaKA, 0, cipherAES, macSHA1, nil},
112 {TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA, 24, 20, 8, ecdheRSAKA, suiteECDHE, cipher3DES, macSHA1, nil},
113 {TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA, 24, 20, 8, dheRSAKA, 0, cipher3DES, macSHA1, nil},
114 {TLS_RSA_WITH_3DES_EDE_CBC_SHA, 24, 20, 8, rsaKA, 0, cipher3DES, macSHA1, nil},
115 {TLS_ECDHE_PSK_WITH_AES_128_GCM_SHA256, 16, 0, 4, ecdhePSKKA, suiteECDHE | suiteTLS12 | suitePSK, nil, nil, aeadAESGCM},
116 {TLS_PSK_WITH_RC4_128_SHA, 16, 20, 0, pskKA, suiteNoDTLS | suitePSK, cipherRC4, macSHA1, nil},
117 {TLS_PSK_WITH_AES_128_CBC_SHA, 16, 20, 16, pskKA, suitePSK, cipherAES, macSHA1, nil},
118 {TLS_PSK_WITH_AES_256_CBC_SHA, 32, 20, 16, pskKA, suitePSK, cipherAES, macSHA1, nil},
121 func cipherRC4(key, iv []byte, isRead bool) interface{} {
122 cipher, _ := rc4.NewCipher(key)
126 func cipher3DES(key, iv []byte, isRead bool) interface{} {
127 block, _ := des.NewTripleDESCipher(key)
129 return cipher.NewCBCDecrypter(block, iv)
131 return cipher.NewCBCEncrypter(block, iv)
134 func cipherAES(key, iv []byte, isRead bool) interface{} {
135 block, _ := aes.NewCipher(key)
137 return cipher.NewCBCDecrypter(block, iv)
139 return cipher.NewCBCEncrypter(block, iv)
142 // macSHA1 returns a macFunction for the given protocol version.
143 func macSHA1(version uint16, key []byte) macFunction {
144 if version == VersionSSL30 {
147 key: make([]byte, len(key)),
152 return tls10MAC{hmac.New(sha1.New, key)}
155 func macMD5(version uint16, key []byte) macFunction {
156 if version == VersionSSL30 {
159 key: make([]byte, len(key)),
164 return tls10MAC{hmac.New(md5.New, key)}
167 func macSHA256(version uint16, key []byte) macFunction {
168 if version == VersionSSL30 {
171 key: make([]byte, len(key)),
176 return tls10MAC{hmac.New(sha256.New, key)}
179 func macSHA384(version uint16, key []byte) macFunction {
180 if version == VersionSSL30 {
183 key: make([]byte, len(key)),
188 return tls10MAC{hmac.New(sha512.New384, key)}
191 type macFunction interface {
193 MAC(digestBuf, seq, header, length, data []byte) []byte
196 // fixedNonceAEAD wraps an AEAD and prefixes a fixed portion of the nonce to
198 type fixedNonceAEAD struct {
199 // sealNonce and openNonce are buffers where the larger nonce will be
200 // constructed. Since a seal and open operation may be running
201 // concurrently, there is a separate buffer for each.
202 sealNonce, openNonce []byte
206 func (f *fixedNonceAEAD) NonceSize() int { return 8 }
207 func (f *fixedNonceAEAD) Overhead() int { return f.aead.Overhead() }
209 func (f *fixedNonceAEAD) Seal(out, nonce, plaintext, additionalData []byte) []byte {
210 copy(f.sealNonce[len(f.sealNonce)-8:], nonce)
211 return f.aead.Seal(out, f.sealNonce, plaintext, additionalData)
214 func (f *fixedNonceAEAD) Open(out, nonce, plaintext, additionalData []byte) ([]byte, error) {
215 copy(f.openNonce[len(f.openNonce)-8:], nonce)
216 return f.aead.Open(out, f.openNonce, plaintext, additionalData)
219 func aeadAESGCM(key, fixedNonce []byte) cipher.AEAD {
220 aes, err := aes.NewCipher(key)
224 aead, err := cipher.NewGCM(aes)
229 nonce1, nonce2 := make([]byte, 12), make([]byte, 12)
230 copy(nonce1, fixedNonce)
231 copy(nonce2, fixedNonce)
233 return &fixedNonceAEAD{nonce1, nonce2, aead}
236 // ssl30MAC implements the SSLv3 MAC function, as defined in
237 // www.mozilla.org/projects/security/pki/nss/ssl/draft302.txt section 5.2.3.1
238 type ssl30MAC struct {
243 func (s ssl30MAC) Size() int {
247 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}
249 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}
251 func (s ssl30MAC) MAC(digestBuf, seq, header, length, data []byte) []byte {
253 if s.h.Size() == 20 {
259 s.h.Write(ssl30Pad1[:padLength])
261 s.h.Write(header[:1])
264 digestBuf = s.h.Sum(digestBuf[:0])
268 s.h.Write(ssl30Pad2[:padLength])
270 return s.h.Sum(digestBuf[:0])
273 // tls10MAC implements the TLS 1.0 MAC function. RFC 2246, section 6.2.3.
274 type tls10MAC struct {
278 func (s tls10MAC) Size() int {
282 func (s tls10MAC) MAC(digestBuf, seq, header, length, data []byte) []byte {
288 return s.h.Sum(digestBuf[:0])
291 func rsaKA(version uint16) keyAgreement {
292 return rsaKeyAgreement{}
295 func ecdheECDSAKA(version uint16) keyAgreement {
296 return &ecdheKeyAgreement{
297 auth: &signedKeyAgreement{
298 sigType: signatureECDSA,
304 func ecdheRSAKA(version uint16) keyAgreement {
305 return &ecdheKeyAgreement{
306 auth: &signedKeyAgreement{
307 sigType: signatureRSA,
313 func dheRSAKA(version uint16) keyAgreement {
314 return &dheKeyAgreement{
315 auth: &signedKeyAgreement{
316 sigType: signatureRSA,
322 func pskKA(version uint16) keyAgreement {
323 return &pskKeyAgreement{
324 base: &nilKeyAgreement{},
328 func ecdhePSKKA(version uint16) keyAgreement {
329 return &pskKeyAgreement{
330 base: &ecdheKeyAgreement{
331 auth: &nilKeyAgreementAuthentication{},
336 // mutualCipherSuite returns a cipherSuite given a list of supported
337 // ciphersuites and the id requested by the peer.
338 func mutualCipherSuite(have []uint16, want uint16) *cipherSuite {
339 for _, id := range have {
341 for _, suite := range cipherSuites {
342 if suite.id == want {
352 // A list of the possible cipher suite ids. Taken from
353 // http://www.iana.org/assignments/tls-parameters/tls-parameters.xml
355 TLS_RSA_WITH_RC4_128_MD5 uint16 = 0x0004
356 TLS_RSA_WITH_RC4_128_SHA uint16 = 0x0005
357 TLS_RSA_WITH_3DES_EDE_CBC_SHA uint16 = 0x000a
358 TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA uint16 = 0x0016
359 TLS_RSA_WITH_AES_128_CBC_SHA uint16 = 0x002f
360 TLS_DHE_RSA_WITH_AES_128_CBC_SHA uint16 = 0x0033
361 TLS_RSA_WITH_AES_256_CBC_SHA uint16 = 0x0035
362 TLS_DHE_RSA_WITH_AES_256_CBC_SHA uint16 = 0x0039
363 TLS_RSA_WITH_AES_128_CBC_SHA256 uint16 = 0x003c
364 TLS_RSA_WITH_AES_256_CBC_SHA256 uint16 = 0x003d
365 TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 uint16 = 0x0067
366 TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 uint16 = 0x006b
367 TLS_PSK_WITH_RC4_128_SHA uint16 = 0x008a
368 TLS_PSK_WITH_AES_128_CBC_SHA uint16 = 0x008c
369 TLS_PSK_WITH_AES_256_CBC_SHA uint16 = 0x008d
370 TLS_RSA_WITH_AES_128_GCM_SHA256 uint16 = 0x009c
371 TLS_RSA_WITH_AES_256_GCM_SHA384 uint16 = 0x009d
372 TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 uint16 = 0x009e
373 TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 uint16 = 0x009f
374 TLS_ECDHE_ECDSA_WITH_RC4_128_SHA uint16 = 0xc007
375 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA uint16 = 0xc009
376 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA uint16 = 0xc00a
377 TLS_ECDHE_RSA_WITH_RC4_128_SHA uint16 = 0xc011
378 TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA uint16 = 0xc012
379 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA uint16 = 0xc013
380 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA uint16 = 0xc014
381 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 uint16 = 0xc023
382 TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 uint16 = 0xc024
383 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 uint16 = 0xc027
384 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 uint16 = 0xc028
385 TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 uint16 = 0xc02b
386 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 uint16 = 0xc02c
387 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 uint16 = 0xc02f
388 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 uint16 = 0xc030
389 fallbackSCSV uint16 = 0x5600
392 // Additional cipher suite IDs, not IANA-assigned.
394 TLS_ECDHE_PSK_WITH_AES_128_GCM_SHA256 uint16 = 0xcafe