Source file src/crypto/tls/key_schedule.go

Documentation: crypto/tls

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

View as plain text