key_agreement.mx raw
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/ecdh"
10 "crypto/md5"
11 "crypto/rsa"
12 "crypto/sha1"
13 "crypto/x509"
14 "errors"
15 "fmt"
16 "io"
17 "slices"
18 )
19
20 // A keyAgreement implements the client and server side of a TLS 1.0–1.2 key
21 // agreement protocol by generating and processing key exchange messages.
22 type keyAgreement interface {
23 // On the server side, the first two methods are called in order.
24
25 // In the case that the key agreement protocol doesn't use a
26 // ServerKeyExchange message, generateServerKeyExchange can return nil,
27 // nil.
28 generateServerKeyExchange(*Config, *Certificate, *clientHelloMsg, *serverHelloMsg) (*serverKeyExchangeMsg, error)
29 processClientKeyExchange(*Config, *Certificate, *clientKeyExchangeMsg, uint16) ([]byte, error)
30
31 // On the client side, the next two methods are called in order.
32
33 // This method may not be called if the server doesn't send a
34 // ServerKeyExchange message.
35 processServerKeyExchange(*Config, *clientHelloMsg, *serverHelloMsg, *x509.Certificate, *serverKeyExchangeMsg) error
36 generateClientKeyExchange(*Config, *clientHelloMsg, *x509.Certificate) ([]byte, *clientKeyExchangeMsg, error)
37 }
38
39 var errClientKeyExchange = errors.New("tls: invalid ClientKeyExchange message")
40 var errServerKeyExchange = errors.New("tls: invalid ServerKeyExchange message")
41
42 // rsaKeyAgreement implements the standard TLS key agreement where the client
43 // encrypts the pre-master secret to the server's public key.
44 type rsaKeyAgreement struct{}
45
46 func (ka rsaKeyAgreement) generateServerKeyExchange(config *Config, cert *Certificate, clientHello *clientHelloMsg, hello *serverHelloMsg) (*serverKeyExchangeMsg, error) {
47 return nil, nil
48 }
49
50 func (ka rsaKeyAgreement) processClientKeyExchange(config *Config, cert *Certificate, ckx *clientKeyExchangeMsg, version uint16) ([]byte, error) {
51 if len(ckx.ciphertext) < 2 {
52 return nil, errClientKeyExchange
53 }
54 ciphertextLen := int(ckx.ciphertext[0])<<8 | int(ckx.ciphertext[1])
55 if ciphertextLen != len(ckx.ciphertext)-2 {
56 return nil, errClientKeyExchange
57 }
58 ciphertext := ckx.ciphertext[2:]
59
60 priv, ok := cert.PrivateKey.(crypto.Decrypter)
61 if !ok {
62 return nil, errors.New("tls: certificate private key does not implement crypto.Decrypter")
63 }
64 // Perform constant time RSA PKCS #1 v1.5 decryption
65 preMasterSecret, err := priv.Decrypt(config.rand(), ciphertext, &rsa.PKCS1v15DecryptOptions{SessionKeyLen: 48})
66 if err != nil {
67 return nil, err
68 }
69 // We don't check the version number in the premaster secret. For one,
70 // by checking it, we would leak information about the validity of the
71 // encrypted pre-master secret. Secondly, it provides only a small
72 // benefit against a downgrade attack and some implementations send the
73 // wrong version anyway. See the discussion at the end of section
74 // 7.4.7.1 of RFC 4346.
75 return preMasterSecret, nil
76 }
77
78 func (ka rsaKeyAgreement) processServerKeyExchange(config *Config, clientHello *clientHelloMsg, serverHello *serverHelloMsg, cert *x509.Certificate, skx *serverKeyExchangeMsg) error {
79 return errors.New("tls: unexpected ServerKeyExchange")
80 }
81
82 func (ka rsaKeyAgreement) generateClientKeyExchange(config *Config, clientHello *clientHelloMsg, cert *x509.Certificate) ([]byte, *clientKeyExchangeMsg, error) {
83 preMasterSecret := []byte{:48}
84 preMasterSecret[0] = byte(clientHello.vers >> 8)
85 preMasterSecret[1] = byte(clientHello.vers)
86 _, err := io.ReadFull(config.rand(), preMasterSecret[2:])
87 if err != nil {
88 return nil, nil, err
89 }
90
91 rsaKey, ok := cert.PublicKey.(*rsa.PublicKey)
92 if !ok {
93 return nil, nil, errors.New("tls: server certificate contains incorrect key type for selected ciphersuite")
94 }
95 encrypted, err := rsa.EncryptPKCS1v15(config.rand(), rsaKey, preMasterSecret)
96 if err != nil {
97 return nil, nil, err
98 }
99 ckx := &clientKeyExchangeMsg{}
100 ckx.ciphertext = []byte{:len(encrypted)+2}
101 ckx.ciphertext[0] = byte(len(encrypted) >> 8)
102 ckx.ciphertext[1] = byte(len(encrypted))
103 copy(ckx.ciphertext[2:], encrypted)
104 return preMasterSecret, ckx, nil
105 }
106
107 // sha1Hash calculates a SHA1 hash over the given byte slices.
108 func sha1Hash(slices [][]byte) []byte {
109 hsha1 := sha1.New()
110 for _, slice := range slices {
111 hsha1.Write(slice)
112 }
113 return hsha1.Sum(nil)
114 }
115
116 // md5SHA1Hash implements TLS 1.0's hybrid hash function which consists of the
117 // concatenation of an MD5 and SHA1 hash.
118 func md5SHA1Hash(slices [][]byte) []byte {
119 md5sha1 := []byte{:md5.Size+sha1.Size}
120 hmd5 := md5.New()
121 for _, slice := range slices {
122 hmd5.Write(slice)
123 }
124 copy(md5sha1, hmd5.Sum(nil))
125 copy(md5sha1[md5.Size:], sha1Hash(slices))
126 return md5sha1
127 }
128
129 // hashForServerKeyExchange hashes the given slices and returns their digest
130 // using a hash based on the sigType. It can only be used for TLS 1.0 and 1.1.
131 func hashForServerKeyExchange(sigType uint8, slices ...[]byte) []byte {
132 if sigType == signatureECDSA {
133 return sha1Hash(slices)
134 }
135 return md5SHA1Hash(slices)
136 }
137
138 // ecdheKeyAgreement implements a TLS key agreement where the server
139 // generates an ephemeral EC public/private key pair and signs it. The
140 // pre-master secret is then calculated using ECDH. The signature may
141 // be ECDSA, Ed25519 or RSA.
142 type ecdheKeyAgreement struct {
143 version uint16
144 isRSA bool
145
146 // ckx and preMasterSecret are generated in processServerKeyExchange
147 // and returned in generateClientKeyExchange.
148 ckx *clientKeyExchangeMsg
149 preMasterSecret []byte
150
151 // curveID, signatureAlgorithm, and key are set by processServerKeyExchange
152 // and generateServerKeyExchange.
153 curveID CurveID
154 signatureAlgorithm SignatureScheme
155 key *ecdh.PrivateKey
156 }
157
158 func (ka *ecdheKeyAgreement) generateServerKeyExchange(config *Config, cert *Certificate, clientHello *clientHelloMsg, hello *serverHelloMsg) (*serverKeyExchangeMsg, error) {
159 for _, c := range clientHello.supportedCurves {
160 if config.supportsCurve(ka.version, c) {
161 ka.curveID = c
162 break
163 }
164 }
165
166 if ka.curveID == 0 {
167 return nil, errors.New("tls: no supported elliptic curves offered")
168 }
169 if _, ok := curveForCurveID(ka.curveID); !ok {
170 return nil, errors.New("tls: CurvePreferences includes unsupported curve")
171 }
172
173 key, err := generateECDHEKey(config.rand(), ka.curveID)
174 if err != nil {
175 return nil, err
176 }
177 ka.key = key
178
179 // See RFC 4492, Section 5.4.
180 ecdhePublic := key.PublicKey().Bytes()
181 serverECDHEParams := []byte{:1+2+1+len(ecdhePublic)}
182 serverECDHEParams[0] = 3 // named curve
183 serverECDHEParams[1] = byte(ka.curveID >> 8)
184 serverECDHEParams[2] = byte(ka.curveID)
185 serverECDHEParams[3] = byte(len(ecdhePublic))
186 copy(serverECDHEParams[4:], ecdhePublic)
187
188 priv, ok := cert.PrivateKey.(crypto.Signer)
189 if !ok {
190 return nil, fmt.Errorf("tls: certificate private key of type %T does not implement crypto.Signer", cert.PrivateKey)
191 }
192
193 var sig []byte
194 if ka.version >= VersionTLS12 {
195 ka.signatureAlgorithm, err = selectSignatureScheme(ka.version, cert, clientHello.supportedSignatureAlgorithms)
196 if err != nil {
197 return nil, err
198 }
199 sigType, sigHash, err := typeAndHashFromSignatureScheme(ka.signatureAlgorithm)
200 if err != nil {
201 return nil, err
202 }
203 if sigHash == crypto.SHA1 {
204 tlssha1.Value() // ensure godebug is initialized
205 tlssha1.IncNonDefault()
206 }
207 signed := slices.Concat(clientHello.random, hello.random, serverECDHEParams)
208 if (sigType == signaturePKCS1v15 || sigType == signatureRSAPSS) != ka.isRSA {
209 return nil, errors.New("tls: certificate cannot be used with the selected cipher suite")
210 }
211 signOpts := crypto.SignerOpts(sigHash)
212 if sigType == signatureRSAPSS {
213 signOpts = &rsa.PSSOptions{SaltLength: rsa.PSSSaltLengthEqualsHash, Hash: sigHash}
214 }
215 sig, err = crypto.SignMessage(priv, config.rand(), signed, signOpts)
216 if err != nil {
217 return nil, errors.New("tls: failed to sign ECDHE parameters: " + err.Error())
218 }
219 } else {
220 sigType, sigHash, err := legacyTypeAndHashFromPublicKey(priv.Public())
221 if err != nil {
222 return nil, err
223 }
224 signed := hashForServerKeyExchange(sigType, clientHello.random, hello.random, serverECDHEParams)
225 if (sigType == signaturePKCS1v15) != ka.isRSA {
226 return nil, errors.New("tls: certificate cannot be used with the selected cipher suite")
227 }
228 sig, err = priv.Sign(config.rand(), signed, sigHash)
229 if err != nil {
230 return nil, errors.New("tls: failed to sign ECDHE parameters: " + err.Error())
231 }
232 }
233
234 skx := &serverKeyExchangeMsg{}
235 sigAndHashLen := 0
236 if ka.version >= VersionTLS12 {
237 sigAndHashLen = 2
238 }
239 skx.key = []byte{:len(serverECDHEParams)+sigAndHashLen+2+len(sig)}
240 copy(skx.key, serverECDHEParams)
241 k := skx.key[len(serverECDHEParams):]
242 if ka.version >= VersionTLS12 {
243 k[0] = byte(ka.signatureAlgorithm >> 8)
244 k[1] = byte(ka.signatureAlgorithm)
245 k = k[2:]
246 }
247 k[0] = byte(len(sig) >> 8)
248 k[1] = byte(len(sig))
249 copy(k[2:], sig)
250
251 return skx, nil
252 }
253
254 func (ka *ecdheKeyAgreement) processClientKeyExchange(config *Config, cert *Certificate, ckx *clientKeyExchangeMsg, version uint16) ([]byte, error) {
255 if len(ckx.ciphertext) == 0 || int(ckx.ciphertext[0]) != len(ckx.ciphertext)-1 {
256 return nil, errClientKeyExchange
257 }
258
259 peerKey, err := ka.key.Curve().NewPublicKey(ckx.ciphertext[1:])
260 if err != nil {
261 return nil, errClientKeyExchange
262 }
263 preMasterSecret, err := ka.key.ECDH(peerKey)
264 if err != nil {
265 return nil, errClientKeyExchange
266 }
267
268 return preMasterSecret, nil
269 }
270
271 func (ka *ecdheKeyAgreement) processServerKeyExchange(config *Config, clientHello *clientHelloMsg, serverHello *serverHelloMsg, cert *x509.Certificate, skx *serverKeyExchangeMsg) error {
272 if len(skx.key) < 4 {
273 return errServerKeyExchange
274 }
275 if skx.key[0] != 3 { // named curve
276 return errors.New("tls: server selected unsupported curve")
277 }
278 ka.curveID = CurveID(skx.key[1])<<8 | CurveID(skx.key[2])
279
280 publicLen := int(skx.key[3])
281 if publicLen+4 > len(skx.key) {
282 return errServerKeyExchange
283 }
284 serverECDHEParams := skx.key[:4+publicLen]
285 publicKey := serverECDHEParams[4:]
286
287 sig := skx.key[4+publicLen:]
288 if len(sig) < 2 {
289 return errServerKeyExchange
290 }
291 if ka.version >= VersionTLS12 {
292 ka.signatureAlgorithm = SignatureScheme(sig[0])<<8 | SignatureScheme(sig[1])
293 sig = sig[2:]
294 if len(sig) < 2 {
295 return errServerKeyExchange
296 }
297 }
298 sigLen := int(sig[0])<<8 | int(sig[1])
299 if sigLen+2 != len(sig) {
300 return errServerKeyExchange
301 }
302 sig = sig[2:]
303
304 if !slices.Contains(clientHello.supportedCurves, ka.curveID) {
305 return errors.New("tls: server selected unoffered curve")
306 }
307
308 if _, ok := curveForCurveID(ka.curveID); !ok {
309 return errors.New("tls: server selected unsupported curve")
310 }
311
312 key, err := generateECDHEKey(config.rand(), ka.curveID)
313 if err != nil {
314 return err
315 }
316 ka.key = key
317
318 peerKey, err := key.Curve().NewPublicKey(publicKey)
319 if err != nil {
320 return errServerKeyExchange
321 }
322 ka.preMasterSecret, err = key.ECDH(peerKey)
323 if err != nil {
324 return errServerKeyExchange
325 }
326
327 ourPublicKey := key.PublicKey().Bytes()
328 ka.ckx = &clientKeyExchangeMsg{}
329 ka.ckx.ciphertext = []byte{:1+len(ourPublicKey)}
330 ka.ckx.ciphertext[0] = byte(len(ourPublicKey))
331 copy(ka.ckx.ciphertext[1:], ourPublicKey)
332
333 var sigType uint8
334 var sigHash crypto.Hash
335 if ka.version >= VersionTLS12 {
336 if !isSupportedSignatureAlgorithm(ka.signatureAlgorithm, clientHello.supportedSignatureAlgorithms) {
337 return errors.New("tls: certificate used with invalid signature algorithm")
338 }
339 sigType, sigHash, err = typeAndHashFromSignatureScheme(ka.signatureAlgorithm)
340 if err != nil {
341 return err
342 }
343 if sigHash == crypto.SHA1 {
344 tlssha1.Value() // ensure godebug is initialized
345 tlssha1.IncNonDefault()
346 }
347 if (sigType == signaturePKCS1v15 || sigType == signatureRSAPSS) != ka.isRSA {
348 return errServerKeyExchange
349 }
350 signed := slices.Concat(clientHello.random, serverHello.random, serverECDHEParams)
351 if err := verifyHandshakeSignature(sigType, cert.PublicKey, sigHash, signed, sig); err != nil {
352 return errors.New("tls: invalid signature by the server certificate: " + err.Error())
353 }
354 } else {
355 sigType, sigHash, err = legacyTypeAndHashFromPublicKey(cert.PublicKey)
356 if err != nil {
357 return err
358 }
359 if (sigType == signaturePKCS1v15) != ka.isRSA {
360 return errServerKeyExchange
361 }
362 signed := hashForServerKeyExchange(sigType, clientHello.random, serverHello.random, serverECDHEParams)
363 if err := verifyLegacyHandshakeSignature(sigType, cert.PublicKey, sigHash, signed, sig); err != nil {
364 return errors.New("tls: invalid signature by the server certificate: " + err.Error())
365 }
366 }
367
368 return nil
369 }
370
371 func (ka *ecdheKeyAgreement) generateClientKeyExchange(config *Config, clientHello *clientHelloMsg, cert *x509.Certificate) ([]byte, *clientKeyExchangeMsg, error) {
372 if ka.ckx == nil {
373 return nil, nil, errors.New("tls: missing ServerKeyExchange message")
374 }
375
376 return ka.preMasterSecret, ka.ckx, nil
377 }
378
379 // generateECDHEKey returns a PrivateKey that implements Diffie-Hellman
380 // according to RFC 8446, Section 4.2.8.2.
381 func generateECDHEKey(rand io.Reader, curveID CurveID) (*ecdh.PrivateKey, error) {
382 curve, ok := curveForCurveID(curveID)
383 if !ok {
384 return nil, errors.New("tls: internal error: unsupported curve")
385 }
386
387 return curve.GenerateKey(rand)
388 }
389
390 func curveForCurveID(id CurveID) (ecdh.Curve, bool) {
391 switch id {
392 case X25519:
393 return ecdh.X25519(), true
394 case CurveP256:
395 return ecdh.P256(), true
396 case CurveP384:
397 return ecdh.P384(), true
398 case CurveP521:
399 return ecdh.P521(), true
400 default:
401 return nil, false
402 }
403 }
404