github.com/mtsmfm/go/src@v0.0.0-20221020090648-44bdcb9f8fde/crypto/tls/key_schedule.go (about)

     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  	"errors"
    11  	"hash"
    12  	"io"
    13  
    14  	"golang.org/x/crypto/cryptobyte"
    15  	"golang.org/x/crypto/hkdf"
    16  )
    17  
    18  // This file contains the functions necessary to compute the TLS 1.3 key
    19  // schedule. See RFC 8446, Section 7.
    20  
    21  const (
    22  	resumptionBinderLabel         = "res binder"
    23  	clientHandshakeTrafficLabel   = "c hs traffic"
    24  	serverHandshakeTrafficLabel   = "s hs traffic"
    25  	clientApplicationTrafficLabel = "c ap traffic"
    26  	serverApplicationTrafficLabel = "s ap traffic"
    27  	exporterLabel                 = "exp master"
    28  	resumptionLabel               = "res master"
    29  	trafficUpdateLabel            = "traffic upd"
    30  )
    31  
    32  // expandLabel implements HKDF-Expand-Label from RFC 8446, Section 7.1.
    33  func (c *cipherSuiteTLS13) expandLabel(secret []byte, label string, context []byte, length int) []byte {
    34  	var hkdfLabel cryptobyte.Builder
    35  	hkdfLabel.AddUint16(uint16(length))
    36  	hkdfLabel.AddUint8LengthPrefixed(func(b *cryptobyte.Builder) {
    37  		b.AddBytes([]byte("tls13 "))
    38  		b.AddBytes([]byte(label))
    39  	})
    40  	hkdfLabel.AddUint8LengthPrefixed(func(b *cryptobyte.Builder) {
    41  		b.AddBytes(context)
    42  	})
    43  	out := make([]byte, length)
    44  	n, err := hkdf.Expand(c.hash.New, secret, hkdfLabel.BytesOrPanic()).Read(out)
    45  	if err != nil || n != length {
    46  		panic("tls: HKDF-Expand-Label invocation failed unexpectedly")
    47  	}
    48  	return out
    49  }
    50  
    51  // deriveSecret implements Derive-Secret from RFC 8446, Section 7.1.
    52  func (c *cipherSuiteTLS13) deriveSecret(secret []byte, label string, transcript hash.Hash) []byte {
    53  	if transcript == nil {
    54  		transcript = c.hash.New()
    55  	}
    56  	return c.expandLabel(secret, label, transcript.Sum(nil), c.hash.Size())
    57  }
    58  
    59  // extract implements HKDF-Extract with the cipher suite hash.
    60  func (c *cipherSuiteTLS13) extract(newSecret, currentSecret []byte) []byte {
    61  	if newSecret == nil {
    62  		newSecret = make([]byte, c.hash.Size())
    63  	}
    64  	return hkdf.Extract(c.hash.New, newSecret, currentSecret)
    65  }
    66  
    67  // nextTrafficSecret generates the next traffic secret, given the current one,
    68  // according to RFC 8446, Section 7.2.
    69  func (c *cipherSuiteTLS13) nextTrafficSecret(trafficSecret []byte) []byte {
    70  	return c.expandLabel(trafficSecret, trafficUpdateLabel, nil, c.hash.Size())
    71  }
    72  
    73  // trafficKey generates traffic keys according to RFC 8446, Section 7.3.
    74  func (c *cipherSuiteTLS13) trafficKey(trafficSecret []byte) (key, iv []byte) {
    75  	key = c.expandLabel(trafficSecret, "key", nil, c.keyLen)
    76  	iv = c.expandLabel(trafficSecret, "iv", nil, aeadNonceLength)
    77  	return
    78  }
    79  
    80  // finishedHash generates the Finished verify_data or PskBinderEntry according
    81  // to RFC 8446, Section 4.4.4. See sections 4.4 and 4.2.11.2 for the baseKey
    82  // selection.
    83  func (c *cipherSuiteTLS13) finishedHash(baseKey []byte, transcript hash.Hash) []byte {
    84  	finishedKey := c.expandLabel(baseKey, "finished", nil, c.hash.Size())
    85  	verifyData := hmac.New(c.hash.New, finishedKey)
    86  	verifyData.Write(transcript.Sum(nil))
    87  	return verifyData.Sum(nil)
    88  }
    89  
    90  // exportKeyingMaterial implements RFC5705 exporters for TLS 1.3 according to
    91  // RFC 8446, Section 7.5.
    92  func (c *cipherSuiteTLS13) exportKeyingMaterial(masterSecret []byte, transcript hash.Hash) func(string, []byte, int) ([]byte, error) {
    93  	expMasterSecret := c.deriveSecret(masterSecret, exporterLabel, transcript)
    94  	return func(label string, context []byte, length int) ([]byte, error) {
    95  		secret := c.deriveSecret(expMasterSecret, label, nil)
    96  		h := c.hash.New()
    97  		h.Write(context)
    98  		return c.expandLabel(secret, "exporter", h.Sum(nil), length), nil
    99  	}
   100  }
   101  
   102  // generateECDHEKey returns a PrivateKey that implements Diffie-Hellman
   103  // according to RFC 8446, Section 4.2.8.2.
   104  func generateECDHEKey(rand io.Reader, curveID CurveID) (*ecdh.PrivateKey, error) {
   105  	curve, ok := curveForCurveID(curveID)
   106  	if !ok {
   107  		return nil, errors.New("tls: internal error: unsupported curve")
   108  	}
   109  
   110  	return curve.GenerateKey(rand)
   111  }
   112  
   113  func curveForCurveID(id CurveID) (ecdh.Curve, bool) {
   114  	switch id {
   115  	case X25519:
   116  		return ecdh.X25519(), true
   117  	case CurveP256:
   118  		return ecdh.P256(), true
   119  	case CurveP384:
   120  		return ecdh.P384(), true
   121  	case CurveP521:
   122  		return ecdh.P521(), true
   123  	default:
   124  		return nil, false
   125  	}
   126  }
   127  
   128  func curveIDForCurve(curve ecdh.Curve) (CurveID, bool) {
   129  	switch curve {
   130  	case ecdh.X25519():
   131  		return X25519, true
   132  	case ecdh.P256():
   133  		return CurveP256, true
   134  	case ecdh.P384():
   135  		return CurveP384, true
   136  	case ecdh.P521():
   137  		return CurveP521, true
   138  	default:
   139  		return 0, false
   140  	}
   141  }