key_schedule.go

     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  
     5  package tls
     6  
     7  import (
     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  
    24  const (
    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.
    37  func (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.
    72  func (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.
    80  func (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.
    89  func (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.
    94  func (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.
   103  func (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.
   112  func (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  
   122  type keySharePrivateKeys struct {
   123  	curveID CurveID
   124  	ecdhe   *ecdh.PrivateKey
   125  	kyber   *mlkem768.DecapsulationKey
   126  }
   127  
   128  // kyberDecapsulate implements decapsulation according to Kyber Round 3.
   129  func 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.
   138  func 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  
   146  func 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  
   159  const x25519PublicKeySize = 32
   160  
   161  // generateECDHEKey returns a PrivateKey that implements Diffie-Hellman
   162  // according to RFC 8446, Section 4.2.8.2.
   163  func 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  
   172  func 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  
   187  func 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
View as plain text