1// Copyright 2018 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/ecdh"
9	"crypto/hmac"
10	"crypto/internal/mlkem768"
11	"errors"
12	"fmt"
13	"hash"
14	"io"
15
16	"golang.org/x/crypto/cryptobyte"
17	"golang.org/x/crypto/hkdf"
18	"golang.org/x/crypto/sha3"
19)
20
21// This file contains the functions necessary to compute the TLS 1.3 key
22// schedule. See RFC 8446, Section 7.
23
24const (
25	resumptionBinderLabel         = "res binder"
26	clientEarlyTrafficLabel       = "c e traffic"
27	clientHandshakeTrafficLabel   = "c hs traffic"
28	serverHandshakeTrafficLabel   = "s hs traffic"
29	clientApplicationTrafficLabel = "c ap traffic"
30	serverApplicationTrafficLabel = "s ap traffic"
31	exporterLabel                 = "exp master"
32	resumptionLabel               = "res master"
33	trafficUpdateLabel            = "traffic upd"
34)
35
36// expandLabel implements HKDF-Expand-Label from RFC 8446, Section 7.1.
37func (c *cipherSuiteTLS13) expandLabel(secret []byte, label string, context []byte, length int) []byte {
38	var hkdfLabel cryptobyte.Builder
39	hkdfLabel.AddUint16(uint16(length))
40	hkdfLabel.AddUint8LengthPrefixed(func(b *cryptobyte.Builder) {
41		b.AddBytes([]byte("tls13 "))
42		b.AddBytes([]byte(label))
43	})
44	hkdfLabel.AddUint8LengthPrefixed(func(b *cryptobyte.Builder) {
45		b.AddBytes(context)
46	})
47	hkdfLabelBytes, err := hkdfLabel.Bytes()
48	if err != nil {
49		// Rather than calling BytesOrPanic, we explicitly handle this error, in
50		// order to provide a reasonable error message. It should be basically
51		// impossible for this to panic, and routing errors back through the
52		// tree rooted in this function is quite painful. The labels are fixed
53		// size, and the context is either a fixed-length computed hash, or
54		// parsed from a field which has the same length limitation. As such, an
55		// error here is likely to only be caused during development.
56		//
57		// NOTE: another reasonable approach here might be to return a
58		// randomized slice if we encounter an error, which would break the
59		// connection, but avoid panicking. This would perhaps be safer but
60		// significantly more confusing to users.
61		panic(fmt.Errorf("failed to construct HKDF label: %s", err))
62	}
63	out := make([]byte, length)
64	n, err := hkdf.Expand(c.hash.New, secret, hkdfLabelBytes).Read(out)
65	if err != nil || n != length {
66		panic("tls: HKDF-Expand-Label invocation failed unexpectedly")
67	}
68	return out
69}
70
71// deriveSecret implements Derive-Secret from RFC 8446, Section 7.1.
72func (c *cipherSuiteTLS13) deriveSecret(secret []byte, label string, transcript hash.Hash) []byte {
73	if transcript == nil {
74		transcript = c.hash.New()
75	}
76	return c.expandLabel(secret, label, transcript.Sum(nil), c.hash.Size())
77}
78
79// extract implements HKDF-Extract with the cipher suite hash.
80func (c *cipherSuiteTLS13) extract(newSecret, currentSecret []byte) []byte {
81	if newSecret == nil {
82		newSecret = make([]byte, c.hash.Size())
83	}
84	return hkdf.Extract(c.hash.New, newSecret, currentSecret)
85}
86
87// nextTrafficSecret generates the next traffic secret, given the current one,
88// according to RFC 8446, Section 7.2.
89func (c *cipherSuiteTLS13) nextTrafficSecret(trafficSecret []byte) []byte {
90	return c.expandLabel(trafficSecret, trafficUpdateLabel, nil, c.hash.Size())
91}
92
93// trafficKey generates traffic keys according to RFC 8446, Section 7.3.
94func (c *cipherSuiteTLS13) trafficKey(trafficSecret []byte) (key, iv []byte) {
95	key = c.expandLabel(trafficSecret, "key", nil, c.keyLen)
96	iv = c.expandLabel(trafficSecret, "iv", nil, aeadNonceLength)
97	return
98}
99
100// finishedHash generates the Finished verify_data or PskBinderEntry according
101// to RFC 8446, Section 4.4.4. See sections 4.4 and 4.2.11.2 for the baseKey
102// selection.
103func (c *cipherSuiteTLS13) finishedHash(baseKey []byte, transcript hash.Hash) []byte {
104	finishedKey := c.expandLabel(baseKey, "finished", nil, c.hash.Size())
105	verifyData := hmac.New(c.hash.New, finishedKey)
106	verifyData.Write(transcript.Sum(nil))
107	return verifyData.Sum(nil)
108}
109
110// exportKeyingMaterial implements RFC5705 exporters for TLS 1.3 according to
111// RFC 8446, Section 7.5.
112func (c *cipherSuiteTLS13) exportKeyingMaterial(masterSecret []byte, transcript hash.Hash) func(string, []byte, int) ([]byte, error) {
113	expMasterSecret := c.deriveSecret(masterSecret, exporterLabel, transcript)
114	return func(label string, context []byte, length int) ([]byte, error) {
115		secret := c.deriveSecret(expMasterSecret, label, nil)
116		h := c.hash.New()
117		h.Write(context)
118		return c.expandLabel(secret, "exporter", h.Sum(nil), length), nil
119	}
120}
121
122type keySharePrivateKeys struct {
123	curveID CurveID
124	ecdhe   *ecdh.PrivateKey
125	kyber   *mlkem768.DecapsulationKey
126}
127
128// kyberDecapsulate implements decapsulation according to Kyber Round 3.
129func kyberDecapsulate(dk *mlkem768.DecapsulationKey, c []byte) ([]byte, error) {
130	K, err := mlkem768.Decapsulate(dk, c)
131	if err != nil {
132		return nil, err
133	}
134	return kyberSharedSecret(K, c), nil
135}
136
137// kyberEncapsulate implements encapsulation according to Kyber Round 3.
138func kyberEncapsulate(ek []byte) (c, ss []byte, err error) {
139	c, ss, err = mlkem768.Encapsulate(ek)
140	if err != nil {
141		return nil, nil, err
142	}
143	return c, kyberSharedSecret(ss, c), nil
144}
145
146func kyberSharedSecret(K, c []byte) []byte {
147	// Package mlkem768 implements ML-KEM, which compared to Kyber removed a
148	// final hashing step. Compute SHAKE-256(K || SHA3-256(c), 32) to match Kyber.
149	// See https://words.filippo.io/mlkem768/#bonus-track-using-a-ml-kem-implementation-as-kyber-v3.
150	h := sha3.NewShake256()
151	h.Write(K)
152	ch := sha3.Sum256(c)
153	h.Write(ch[:])
154	out := make([]byte, 32)
155	h.Read(out)
156	return out
157}
158
159const x25519PublicKeySize = 32
160
161// generateECDHEKey returns a PrivateKey that implements Diffie-Hellman
162// according to RFC 8446, Section 4.2.8.2.
163func generateECDHEKey(rand io.Reader, curveID CurveID) (*ecdh.PrivateKey, error) {
164	curve, ok := curveForCurveID(curveID)
165	if !ok {
166		return nil, errors.New("tls: internal error: unsupported curve")
167	}
168
169	return curve.GenerateKey(rand)
170}
171
172func curveForCurveID(id CurveID) (ecdh.Curve, bool) {
173	switch id {
174	case X25519:
175		return ecdh.X25519(), true
176	case CurveP256:
177		return ecdh.P256(), true
178	case CurveP384:
179		return ecdh.P384(), true
180	case CurveP521:
181		return ecdh.P521(), true
182	default:
183		return nil, false
184	}
185}
186
187func curveIDForCurve(curve ecdh.Curve) (CurveID, bool) {
188	switch curve {
189	case ecdh.X25519():
190		return X25519, true
191	case ecdh.P256():
192		return CurveP256, true
193	case ecdh.P384():
194		return CurveP384, true
195	case ecdh.P521():
196		return CurveP521, true
197	default:
198		return 0, false
199	}
200}
201