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/elliptic" 9 "crypto/hmac" 10 "errors" 11 "hash" 12 "io" 13 "math/big" 14 15 "golang.org/x/crypto/cryptobyte" 16 "golang.org/x/crypto/curve25519" 17 "golang.org/x/crypto/hkdf" 18) 19 20// This file contains the functions necessary to compute the TLS 1.3 key 21// schedule. See RFC 8446, Section 7. 22 23const ( 24 resumptionBinderLabel = "res binder" 25 clientHandshakeTrafficLabel = "c hs traffic" 26 serverHandshakeTrafficLabel = "s hs traffic" 27 clientApplicationTrafficLabel = "c ap traffic" 28 serverApplicationTrafficLabel = "s ap traffic" 29 exporterLabel = "exp master" 30 resumptionLabel = "res master" 31 trafficUpdateLabel = "traffic upd" 32) 33 34// expandLabel implements HKDF-Expand-Label from RFC 8446, Section 7.1. 35func (c *cipherSuiteTLS13) expandLabel(secret []byte, label string, context []byte, length int) []byte { 36 var hkdfLabel cryptobyte.Builder 37 hkdfLabel.AddUint16(uint16(length)) 38 hkdfLabel.AddUint8LengthPrefixed(func(b *cryptobyte.Builder) { 39 b.AddBytes([]byte("tls13 ")) 40 b.AddBytes([]byte(label)) 41 }) 42 hkdfLabel.AddUint8LengthPrefixed(func(b *cryptobyte.Builder) { 43 b.AddBytes(context) 44 }) 45 out := make([]byte, length) 46 n, err := hkdf.Expand(c.hash.New, secret, hkdfLabel.BytesOrPanic()).Read(out) 47 if err != nil || n != length { 48 panic("tls: HKDF-Expand-Label invocation failed unexpectedly") 49 } 50 return out 51} 52 53// deriveSecret implements Derive-Secret from RFC 8446, Section 7.1. 54func (c *cipherSuiteTLS13) deriveSecret(secret []byte, label string, transcript hash.Hash) []byte { 55 if transcript == nil { 56 transcript = c.hash.New() 57 } 58 return c.expandLabel(secret, label, transcript.Sum(nil), c.hash.Size()) 59} 60 61// extract implements HKDF-Extract with the cipher suite hash. 62func (c *cipherSuiteTLS13) extract(newSecret, currentSecret []byte) []byte { 63 if newSecret == nil { 64 newSecret = make([]byte, c.hash.Size()) 65 } 66 return hkdf.Extract(c.hash.New, newSecret, currentSecret) 67} 68 69// nextTrafficSecret generates the next traffic secret, given the current one, 70// according to RFC 8446, Section 7.2. 71func (c *cipherSuiteTLS13) nextTrafficSecret(trafficSecret []byte) []byte { 72 return c.expandLabel(trafficSecret, trafficUpdateLabel, nil, c.hash.Size()) 73} 74 75// trafficKey generates traffic keys according to RFC 8446, Section 7.3. 76func (c *cipherSuiteTLS13) trafficKey(trafficSecret []byte) (key, iv []byte) { 77 key = c.expandLabel(trafficSecret, "key", nil, c.keyLen) 78 iv = c.expandLabel(trafficSecret, "iv", nil, aeadNonceLength) 79 return 80} 81 82// finishedHash generates the Finished verify_data or PskBinderEntry according 83// to RFC 8446, Section 4.4.4. See sections 4.4 and 4.2.11.2 for the baseKey 84// selection. 85func (c *cipherSuiteTLS13) finishedHash(baseKey []byte, transcript hash.Hash) []byte { 86 finishedKey := c.expandLabel(baseKey, "finished", nil, c.hash.Size()) 87 verifyData := hmac.New(c.hash.New, finishedKey) 88 verifyData.Write(transcript.Sum(nil)) 89 return verifyData.Sum(nil) 90} 91 92// exportKeyingMaterial implements RFC5705 exporters for TLS 1.3 according to 93// RFC 8446, Section 7.5. 94func (c *cipherSuiteTLS13) exportKeyingMaterial(masterSecret []byte, transcript hash.Hash) func(string, []byte, int) ([]byte, error) { 95 expMasterSecret := c.deriveSecret(masterSecret, exporterLabel, transcript) 96 return func(label string, context []byte, length int) ([]byte, error) { 97 secret := c.deriveSecret(expMasterSecret, label, nil) 98 h := c.hash.New() 99 h.Write(context) 100 return c.expandLabel(secret, "exporter", h.Sum(nil), length), nil 101 } 102} 103 104// ecdheParameters implements Diffie-Hellman with either NIST curves or X25519, 105// according to RFC 8446, Section 4.2.8.2. 106type ecdheParameters interface { 107 CurveID() CurveID 108 PublicKey() []byte 109 SharedKey(peerPublicKey []byte) []byte 110} 111 112func generateECDHEParameters(rand io.Reader, curveID CurveID) (ecdheParameters, error) { 113 if curveID == X25519 { 114 privateKey := make([]byte, curve25519.ScalarSize) 115 if _, err := io.ReadFull(rand, privateKey); err != nil { 116 return nil, err 117 } 118 publicKey, err := curve25519.X25519(privateKey, curve25519.Basepoint) 119 if err != nil { 120 return nil, err 121 } 122 return &x25519Parameters{privateKey: privateKey, publicKey: publicKey}, nil 123 } 124 125 curve, ok := curveForCurveID(curveID) 126 if !ok { 127 return nil, errors.New("tls: internal error: unsupported curve") 128 } 129 130 p := &nistParameters{curveID: curveID} 131 var err error 132 p.privateKey, p.x, p.y, err = elliptic.GenerateKey(curve, rand) 133 if err != nil { 134 return nil, err 135 } 136 return p, nil 137} 138 139func curveForCurveID(id CurveID) (elliptic.Curve, bool) { 140 switch id { 141 case CurveP256: 142 return elliptic.P256(), true 143 case CurveP384: 144 return elliptic.P384(), true 145 case CurveP521: 146 return elliptic.P521(), true 147 default: 148 return nil, false 149 } 150} 151 152type nistParameters struct { 153 privateKey []byte 154 x, y *big.Int // public key 155 curveID CurveID 156} 157 158func (p *nistParameters) CurveID() CurveID { 159 return p.curveID 160} 161 162func (p *nistParameters) PublicKey() []byte { 163 curve, _ := curveForCurveID(p.curveID) 164 return elliptic.Marshal(curve, p.x, p.y) 165} 166 167func (p *nistParameters) SharedKey(peerPublicKey []byte) []byte { 168 curve, _ := curveForCurveID(p.curveID) 169 // Unmarshal also checks whether the given point is on the curve. 170 x, y := elliptic.Unmarshal(curve, peerPublicKey) 171 if x == nil { 172 return nil 173 } 174 175 xShared, _ := curve.ScalarMult(x, y, p.privateKey) 176 sharedKey := make([]byte, (curve.Params().BitSize+7)/8) 177 return xShared.FillBytes(sharedKey) 178} 179 180type x25519Parameters struct { 181 privateKey []byte 182 publicKey []byte 183} 184 185func (p *x25519Parameters) CurveID() CurveID { 186 return X25519 187} 188 189func (p *x25519Parameters) PublicKey() []byte { 190 return p.publicKey[:] 191} 192 193func (p *x25519Parameters) SharedKey(peerPublicKey []byte) []byte { 194 sharedKey, err := curve25519.X25519(p.privateKey, peerPublicKey) 195 if err != nil { 196 return nil 197 } 198 return sharedKey 199} 200