hkdf: add Extract and Expand

RFC 5869, Section 3.3 suggests it might be sometimes appropriate to use
Expand without Extract, and it is reasonable to reuse (secret, salt)
with different info values, in which case the Extract can be performed
once as an optimization.

TLS 1.3 also needs direct access to both Extract and Expand.

pseudorandomKey is ugly to look at, but that's intentional, as it
signals that this should have non-obvious properties to the user. The
docs will make it clear it's not the thing you should use in most cases.

Fixes golang/go#28237

Change-Id: Ib43ae8cdde0663aa4752172c39aadfb0e1c35f10
Reviewed-on: https://go-review.googlesource.com/c/144398
Reviewed-by: Adam Langley <agl@golang.org>

hkdf/hkdf.go

@@ -8,8 +8,6 @@
 // HKDF is a cryptographic key derivation function (KDF) with the goal of
 // expanding limited input keying material into one or more cryptographically
 // strong secret keys.
-//
-// RFC 5869: https://tools.ietf.org/html/rfc5869
 package hkdf // import "golang.org/x/crypto/hkdf"
 
 import (
@@ -19,6 +17,21 @@ import (
 	"io"
 )
 
+// Extract generates a pseudorandom key for use with Expand from an input secret
+// and an optional independent salt.
+//
+// Only use this function if you need to reuse the extracted key with multiple
+// Expand invocations and different context values. Most common scenarios,
+// including the generation of multiple keys, should use New instead.
+func Extract(hash func() hash.Hash, secret, salt []byte) []byte {
+	if salt == nil {
+		salt = make([]byte, hash().Size())
+	}
+	extractor := hmac.New(hash, salt)
+	extractor.Write(secret)
+	return extractor.Sum(nil)
+}
+
 type hkdf struct {
 	expander hash.Hash
 	size     int
@@ -26,22 +39,22 @@ type hkdf struct {
 	info    []byte
 	counter byte
 
-	prev  []byte
-	cache []byte
+	prev []byte
+	buf  []byte
 }
 
 func (f *hkdf) Read(p []byte) (int, error) {
 	// Check whether enough data can be generated
 	need := len(p)
-	remains := len(f.cache) + int(255-f.counter+1)*f.size
+	remains := len(f.buf) + int(255-f.counter+1)*f.size
 	if remains < need {
 		return 0, errors.New("hkdf: entropy limit reached")
 	}
-	// Read from the cache, if enough data is present
-	n := copy(p, f.cache)
+	// Read any leftover from the buffer
+	n := copy(p, f.buf)
 	p = p[n:]
 
-	// Fill the buffer
+	// Fill the rest of the buffer
 	for len(p) > 0 {
 		f.expander.Reset()
 		f.expander.Write(f.prev)
@@ -51,25 +64,30 @@ func (f *hkdf) Read(p []byte) (int, error) {
 		f.counter++
 
 		// Copy the new batch into p
-		f.cache = f.prev
-		n = copy(p, f.cache)
+		f.buf = f.prev
+		n = copy(p, f.buf)
 		p = p[n:]
 	}
 	// Save leftovers for next run
-	f.cache = f.cache[n:]
+	f.buf = f.buf[n:]
 
 	return need, nil
 }
 
-// New returns a new HKDF using the given hash, the secret keying material to expand
-// and optional salt and info fields.
-func New(hash func() hash.Hash, secret, salt, info []byte) io.Reader {
-	if salt == nil {
-		salt = make([]byte, hash().Size())
-	}
-	extractor := hmac.New(hash, salt)
-	extractor.Write(secret)
-	prk := extractor.Sum(nil)
+// Expand returns a Reader, from which keys can be read, using the given
+// pseudorandom key and optional context info, skipping the extraction step.
+//
+// The pseudorandomKey should have been generated by Extract, or be a uniformly
+// random or pseudorandom cryptographically strong key. See RFC 5869, Section
+// 3.3. Most common scenarios will want to use New instead.
+func Expand(hash func() hash.Hash, pseudorandomKey, info []byte) io.Reader {
+	expander := hmac.New(hash, pseudorandomKey)
+	return &hkdf{expander, expander.Size(), info, 1, nil, nil}
+}
 
-	return &hkdf{hmac.New(hash, prk), extractor.Size(), info, 1, nil, nil}
+// New returns a Reader, from which keys can be read, using the given hash,
+// secret, salt and context info. Salt and info can be nil.
+func New(hash func() hash.Hash, secret, salt, info []byte) io.Reader {
+	prk := Extract(hash, secret, salt)
+	return Expand(hash, prk, info)
 }

hkdf/hkdf_test.go

@@ -18,6 +18,7 @@ type hkdfTest struct {
 	hash   func() hash.Hash
 	master []byte
 	salt   []byte
+	prk    []byte
 	info   []byte
 	out    []byte
 }
@@ -35,6 +36,12 @@ var hkdfTests = []hkdfTest{
 			0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
 			0x08, 0x09, 0x0a, 0x0b, 0x0c,
 		},
+		[]byte{
+			0x07, 0x77, 0x09, 0x36, 0x2c, 0x2e, 0x32, 0xdf,
+			0x0d, 0xdc, 0x3f, 0x0d, 0xc4, 0x7b, 0xba, 0x63,
+			0x90, 0xb6, 0xc7, 0x3b, 0xb5, 0x0f, 0x9c, 0x31,
+			0x22, 0xec, 0x84, 0x4a, 0xd7, 0xc2, 0xb3, 0xe5,
+		},
 		[]byte{
 			0xf0, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7,
 			0xf8, 0xf9,
@@ -74,6 +81,12 @@ var hkdfTests = []hkdfTest{
 			0xa0, 0xa1, 0xa2, 0xa3, 0xa4, 0xa5, 0xa6, 0xa7,
 			0xa8, 0xa9, 0xaa, 0xab, 0xac, 0xad, 0xae, 0xaf,
 		},
+		[]byte{
+			0x06, 0xa6, 0xb8, 0x8c, 0x58, 0x53, 0x36, 0x1a,
+			0x06, 0x10, 0x4c, 0x9c, 0xeb, 0x35, 0xb4, 0x5c,
+			0xef, 0x76, 0x00, 0x14, 0x90, 0x46, 0x71, 0x01,
+			0x4a, 0x19, 0x3f, 0x40, 0xc1, 0x5f, 0xc2, 0x44,
+		},
 		[]byte{
 			0xb0, 0xb1, 0xb2, 0xb3, 0xb4, 0xb5, 0xb6, 0xb7,
 			0xb8, 0xb9, 0xba, 0xbb, 0xbc, 0xbd, 0xbe, 0xbf,
@@ -108,6 +121,12 @@ var hkdfTests = []hkdfTest{
 			0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b,
 		},
 		[]byte{},
+		[]byte{
+			0x19, 0xef, 0x24, 0xa3, 0x2c, 0x71, 0x7b, 0x16,
+			0x7f, 0x33, 0xa9, 0x1d, 0x6f, 0x64, 0x8b, 0xdf,
+			0x96, 0x59, 0x67, 0x76, 0xaf, 0xdb, 0x63, 0x77,
+			0xac, 0x43, 0x4c, 0x1c, 0x29, 0x3c, 0xcb, 0x04,
+		},
 		[]byte{},
 		[]byte{
 			0x8d, 0xa4, 0xe7, 0x75, 0xa5, 0x63, 0xc1, 0x8f,
@@ -118,6 +137,30 @@ var hkdfTests = []hkdfTest{
 			0x96, 0xc8,
 		},
 	},
+	{
+		sha256.New,
+		[]byte{
+			0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b,
+			0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b,
+			0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b,
+		},
+		nil,
+		[]byte{
+			0x19, 0xef, 0x24, 0xa3, 0x2c, 0x71, 0x7b, 0x16,
+			0x7f, 0x33, 0xa9, 0x1d, 0x6f, 0x64, 0x8b, 0xdf,
+			0x96, 0x59, 0x67, 0x76, 0xaf, 0xdb, 0x63, 0x77,
+			0xac, 0x43, 0x4c, 0x1c, 0x29, 0x3c, 0xcb, 0x04,
+		},
+		nil,
+		[]byte{
+			0x8d, 0xa4, 0xe7, 0x75, 0xa5, 0x63, 0xc1, 0x8f,
+			0x71, 0x5f, 0x80, 0x2a, 0x06, 0x3c, 0x5a, 0x31,
+			0xb8, 0xa1, 0x1f, 0x5c, 0x5e, 0xe1, 0x87, 0x9e,
+			0xc3, 0x45, 0x4e, 0x5f, 0x3c, 0x73, 0x8d, 0x2d,
+			0x9d, 0x20, 0x13, 0x95, 0xfa, 0xa4, 0xb6, 0x1a,
+			0x96, 0xc8,
+		},
+	},
 	{
 		sha1.New,
 		[]byte{
@@ -128,6 +171,11 @@ var hkdfTests = []hkdfTest{
 			0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
 			0x08, 0x09, 0x0a, 0x0b, 0x0c,
 		},
+		[]byte{
+			0x9b, 0x6c, 0x18, 0xc4, 0x32, 0xa7, 0xbf, 0x8f,
+			0x0e, 0x71, 0xc8, 0xeb, 0x88, 0xf4, 0xb3, 0x0b,
+			0xaa, 0x2b, 0xa2, 0x43,
+		},
 		[]byte{
 			0xf0, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7,
 			0xf8, 0xf9,
@@ -167,6 +215,11 @@ var hkdfTests = []hkdfTest{
 			0xa0, 0xa1, 0xa2, 0xa3, 0xa4, 0xa5, 0xa6, 0xa7,
 			0xa8, 0xa9, 0xaa, 0xab, 0xac, 0xad, 0xae, 0xaf,
 		},
+		[]byte{
+			0x8a, 0xda, 0xe0, 0x9a, 0x2a, 0x30, 0x70, 0x59,
+			0x47, 0x8d, 0x30, 0x9b, 0x26, 0xc4, 0x11, 0x5a,
+			0x22, 0x4c, 0xfa, 0xf6,
+		},
 		[]byte{
 			0xb0, 0xb1, 0xb2, 0xb3, 0xb4, 0xb5, 0xb6, 0xb7,
 			0xb8, 0xb9, 0xba, 0xbb, 0xbc, 0xbd, 0xbe, 0xbf,
@@ -201,6 +254,11 @@ var hkdfTests = []hkdfTest{
 			0x0b, 0x0b, 0x0b, 0x0b, 0x0b, 0x0b,
 		},
 		[]byte{},
+		[]byte{
+			0xda, 0x8c, 0x8a, 0x73, 0xc7, 0xfa, 0x77, 0x28,
+			0x8e, 0xc6, 0xf5, 0xe7, 0xc2, 0x97, 0x78, 0x6a,
+			0xa0, 0xd3, 0x2d, 0x01,
+		},
 		[]byte{},
 		[]byte{
 			0x0a, 0xc1, 0xaf, 0x70, 0x02, 0xb3, 0xd7, 0x61,
@@ -219,7 +277,12 @@ var hkdfTests = []hkdfTest{
 			0x0c, 0x0c, 0x0c, 0x0c, 0x0c, 0x0c,
 		},
 		nil,
-		[]byte{},
+		[]byte{
+			0x2a, 0xdc, 0xca, 0xda, 0x18, 0x77, 0x9e, 0x7c,
+			0x20, 0x77, 0xad, 0x2e, 0xb1, 0x9d, 0x3f, 0x3e,
+			0x73, 0x13, 0x85, 0xdd,
+		},
+		nil,
 		[]byte{
 			0x2c, 0x91, 0x11, 0x72, 0x04, 0xd7, 0x45, 0xf3,
 			0x50, 0x0d, 0x63, 0x6a, 0x62, 0xf6, 0x4f, 0x0a,
@@ -233,6 +296,11 @@ var hkdfTests = []hkdfTest{
 
 func TestHKDF(t *testing.T) {
 	for i, tt := range hkdfTests {
+		prk := Extract(tt.hash, tt.master, tt.salt)
+		if !bytes.Equal(prk, tt.prk) {
+			t.Errorf("test %d: incorrect PRK: have %v, need %v.", i, prk, tt.prk)
+		}
+
 		hkdf := New(tt.hash, tt.master, tt.salt, tt.info)
 		out := make([]byte, len(tt.out))
 
@@ -244,6 +312,17 @@ func TestHKDF(t *testing.T) {
 		if !bytes.Equal(out, tt.out) {
 			t.Errorf("test %d: incorrect output: have %v, need %v.", i, out, tt.out)
 		}
+
+		hkdf = Expand(tt.hash, prk, tt.info)
+
+		n, err = io.ReadFull(hkdf, out)
+		if n != len(tt.out) || err != nil {
+			t.Errorf("test %d: not enough output bytes from Expand: %d.", i, n)
+		}
+
+		if !bytes.Equal(out, tt.out) {
+			t.Errorf("test %d: incorrect output from Expand: have %v, need %v.", i, out, tt.out)
+		}
 	}
 }