Separating HKDF into HKDFExtract and HKDFExpand.

The key schedule in TLS 1.3 requires a separate Extract and Expand phase
for the cryptographic computations.

Change-Id: Ifdac1237bda5212de5d4f7e8db54e202151d45ec
Reviewed-on: https://boringssl-review.googlesource.com/7983
Reviewed-by: David Benjamin <davidben@google.com>

crypto/hkdf/hkdf.c

@@ -21,22 +21,50 @@
 #include <openssl/hmac.h>
 
 
-int HKDF(uint8_t *out_key, size_t out_len,
-         const EVP_MD *digest,
-         const uint8_t *secret, size_t secret_len,
-         const uint8_t *salt, size_t salt_len,
-         const uint8_t *info, size_t info_len) {
+int HKDF(uint8_t *out_key, size_t out_len, const EVP_MD *digest,
+         const uint8_t *secret, size_t secret_len, const uint8_t *salt,
+         size_t salt_len, const uint8_t *info, size_t info_len) {
+  /* https://tools.ietf.org/html/rfc5869#section-2 */
+  uint8_t prk[EVP_MAX_MD_SIZE];
+  size_t prk_len;
+
+  if (!HKDF_extract(prk, &prk_len, digest, secret, secret_len, salt,
+                    salt_len) ||
+      !HKDF_expand(out_key, out_len, digest, prk, prk_len, info, info_len)) {
+    return 0;
+  }
+
+  return 1;
+}
+
+int HKDF_extract(uint8_t *out_key, size_t *out_len, const EVP_MD *digest,
+                 const uint8_t *secret, size_t secret_len, const uint8_t *salt,
+                 size_t salt_len) {
   /* https://tools.ietf.org/html/rfc5869#section-2.2 */
+
+  /* If salt is not given, HashLength zeros are used. However, HMAC does that
+   * internally already so we can ignore it.*/
+  unsigned len;
+  if (HMAC(digest, salt, salt_len, secret, secret_len, out_key, &len) == NULL) {
+    OPENSSL_PUT_ERROR(HKDF, ERR_R_HMAC_LIB);
+    return 0;
+  }
+  *out_len = len;
+  assert(*out_len == EVP_MD_size(digest));
+  return 1;
+}
+
+int HKDF_expand(uint8_t *out_key, size_t out_len, const EVP_MD *digest,
+                uint8_t *prk, size_t prk_len, const uint8_t *info,
+                size_t info_len) {
+  /* https://tools.ietf.org/html/rfc5869#section-2.3 */
   const size_t digest_len = EVP_MD_size(digest);
-  uint8_t prk[EVP_MAX_MD_SIZE], previous[EVP_MAX_MD_SIZE];
+  uint8_t previous[EVP_MAX_MD_SIZE];
   size_t n, done = 0;
-  unsigned i, prk_len;
+  unsigned i;
   int ret = 0;
   HMAC_CTX hmac;
 
-  /* If salt is not given, HashLength zeros are used. However, HMAC does that
-   * internally already so we can ignore it.*/
-
   /* Expand key material to desired length. */
   n = (out_len + digest_len - 1) / digest_len;
   if (out_len + digest_len < out_len || n > 255) {
@@ -45,13 +73,6 @@ int HKDF(uint8_t *out_key, size_t out_len,
   }
 
   HMAC_CTX_init(&hmac);
-
-  /* Extract input keying material into pseudorandom key |prk|. */
-  if (HMAC(digest, salt, salt_len, secret, secret_len, prk, &prk_len) == NULL) {
-    goto out;
-  }
-  assert(prk_len == digest_len);
-
   if (!HMAC_Init_ex(&hmac, prk, prk_len, digest, NULL)) {
     goto out;
   }
@@ -81,7 +102,6 @@ int HKDF(uint8_t *out_key, size_t out_len,
   ret = 1;
 
 out:
-  HMAC_CTX_cleanup(&hmac);
   if (ret != 1) {
     OPENSSL_PUT_ERROR(HKDF, ERR_R_HMAC_LIB);
   }

crypto/hkdf/hkdf_test.c

@@ -31,6 +31,8 @@ typedef struct {
   const size_t salt_len;
   const uint8_t info[80];
   const size_t info_len;
+  const uint8_t prk[EVP_MAX_MD_SIZE];
+  const size_t prk_len;
   const size_t out_len;
   const uint8_t out[82];
 } hkdf_test_vector_t;
@@ -50,6 +52,11 @@ static const hkdf_test_vector_t kTests[] = {
     {
       0xf0, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7, 0xf8, 0xf9,
     }, 10,
+    {
+      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,
+    }, 32,
     42, {
       0x3c, 0xb2, 0x5f, 0x25, 0xfa, 0xac, 0xd5, 0x7a, 0x90, 0x43, 0x4f, 0x64,
       0xd0, 0x36, 0x2f, 0x2a, 0x2d, 0x2d, 0x0a, 0x90, 0xcf, 0x1a, 0x5a, 0x4c,
@@ -86,6 +93,11 @@ static const hkdf_test_vector_t kTests[] = {
       0xec, 0xed, 0xee, 0xef, 0xf0, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7,
       0xf8, 0xf9, 0xfa, 0xfb, 0xfc, 0xfd, 0xfe, 0xff
     }, 80,
+    {
+       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,
+    }, 32,
     82, {
       0xb1, 0x1e, 0x39, 0x8d, 0xc8, 0x03, 0x27, 0xa1, 0xc8, 0xe7, 0xf7, 0x8c,
       0x59, 0x6a, 0x49, 0x34, 0x4f, 0x01, 0x2e, 0xda, 0x2d, 0x4e, 0xfa, 0xd8,
@@ -108,6 +120,11 @@ static const hkdf_test_vector_t kTests[] = {
     {
        0,
     }, 0,
+    {
+      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
+    }, 32,
     42, {
       0x8d, 0xa4, 0xe7, 0x75, 0xa5, 0x63, 0xc1, 0x8f, 0x71, 0x5f, 0x80, 0x2a,
       0x06, 0x3c, 0x5a, 0x31, 0xb8, 0xa1, 0x1f, 0x5c, 0x5e, 0xe1, 0x87, 0x9e,
@@ -127,6 +144,10 @@ static const hkdf_test_vector_t kTests[] = {
     {
       0xf0, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7, 0xf8, 0xf9,
     }, 10,
+    {
+      0x9b, 0x6c, 0x18, 0xc4, 0x32, 0xa7, 0xbf, 0x8f, 0x0e, 0x71, 0xc8, 0xeb,
+      0x88, 0xf4, 0xb3, 0x0b, 0xaa, 0x2b, 0xa2, 0x43
+    }, 20,
     42, {
       0x08, 0x5a, 0x01, 0xea, 0x1b, 0x10, 0xf3, 0x69, 0x33, 0x06, 0x8b, 0x56,
       0xef, 0xa5, 0xad, 0x81, 0xa4, 0xf1, 0x4b, 0x82, 0x2f, 0x5b, 0x09, 0x15,
@@ -163,6 +184,10 @@ static const hkdf_test_vector_t kTests[] = {
       0xec, 0xed, 0xee, 0xef, 0xf0, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7,
       0xf8, 0xf9, 0xfa, 0xfb, 0xfc, 0xfd, 0xfe, 0xff
     }, 80,
+    {
+      0x8a, 0xda, 0xe0, 0x9a, 0x2a, 0x30, 0x70, 0x59, 0x47, 0x8d, 0x30, 0x9b,
+      0x26, 0xc4, 0x11, 0x5a, 0x22, 0x4c, 0xfa, 0xf6,
+    }, 20,
     82, {
       0x0b, 0xd7, 0x70, 0xa7, 0x4d, 0x11, 0x60, 0xf7, 0xc9, 0xf1, 0x2c, 0xd5,
       0x91, 0x2a, 0x06, 0xeb, 0xff, 0x6a, 0xdc, 0xae, 0x89, 0x9d, 0x92, 0x19,
@@ -185,6 +210,10 @@ static const hkdf_test_vector_t kTests[] = {
     {
        0,
     }, 0,
+    {
+      0xda, 0x8c, 0x8a, 0x73, 0xc7, 0xfa, 0x77, 0x28, 0x8e, 0xc6, 0xf5, 0xe7,
+      0xc2, 0x97, 0x78, 0x6a, 0xa0, 0xd3, 0x2d, 0x01,
+    }, 20,
     42, {
       0x0a, 0xc1, 0xaf, 0x70, 0x02, 0xb3, 0xd7, 0x61, 0xd1, 0xe5, 0x52, 0x98,
       0xda, 0x9d, 0x05, 0x06, 0xb9, 0xae, 0x52, 0x05, 0x72, 0x20, 0xa3, 0x06,
@@ -204,6 +233,10 @@ static const hkdf_test_vector_t kTests[] = {
     {
        0,
     }, 0,
+    {
+      0x2a, 0xdc, 0xca, 0xda, 0x18, 0x77, 0x9e, 0x7c, 0x20, 0x77, 0xad, 0x2e,
+      0xb1, 0x9d, 0x3f, 0x3e, 0x73, 0x13, 0x85, 0xdd,
+    }, 20,
     42, {
       0x2c, 0x91, 0x11, 0x72, 0x04, 0xd7, 0x45, 0xf3, 0x50, 0x0d, 0x63, 0x6a,
       0x62, 0xf6, 0x4f, 0x0a, 0xb3, 0xba, 0xe5, 0x48, 0xaa, 0x53, 0xd4, 0x23,
@@ -214,13 +247,36 @@ static const hkdf_test_vector_t kTests[] = {
 };
 
 int main(void) {
-  uint8_t buf[82];
-  size_t i;
+  uint8_t buf[82], prk[EVP_MAX_MD_SIZE];
+  size_t i, prk_len;
 
   CRYPTO_library_init();
 
   for (i = 0; i < sizeof(kTests) / sizeof(kTests[0]); i++) {
     const hkdf_test_vector_t *test = &kTests[i];
+    if (!HKDF_extract(prk, &prk_len, test->md_func(), test->ikm, test->ikm_len,
+                      test->salt, test->salt_len)) {
+      fprintf(stderr, "Call to HKDF_extract failed\n");
+      ERR_print_errors_fp(stderr);
+      return 1;
+    }
+    if (prk_len != test->prk_len ||
+        memcmp(prk, test->prk, test->prk_len) != 0) {
+      fprintf(stderr, "%zu: Resulting PRK does not match test vector\n", i);
+      return 1;
+    }
+    if (!HKDF_expand(buf, test->out_len, test->md_func(), prk, prk_len,
+                     test->info, test->info_len)) {
+      fprintf(stderr, "Call to HKDF_expand failed\n");
+      ERR_print_errors_fp(stderr);
+      return 1;
+    }
+    if (memcmp(buf, test->out, test->out_len) != 0) {
+      fprintf(stderr,
+              "%zu: Resulting key material does not match test vector\n", i);
+      return 1;
+    }
+
     if (!HKDF(buf, test->out_len, test->md_func(), test->ikm, test->ikm_len,
               test->salt, test->salt_len, test->info, test->info_len)) {
       fprintf(stderr, "Call to HKDF failed\n");

include/openssl/hkdf.h

@@ -37,6 +37,23 @@ OPENSSL_EXPORT int HKDF(uint8_t *out_key, size_t out_len, const EVP_MD *digest,
                         const uint8_t *salt, size_t salt_len,
                         const uint8_t *info, size_t info_len);
 
+/* HKDF_extract computes a HKDF PRK (as specified by RFC 5869) from initial
+ * keying material |secret| and salt |salt| using |digest|, and outputs
+ * |out_len| bytes to |out_key|. The maximum output size is |EVP_MAX_MD_SIZE|.
+ * It returns one on success and zero on error. */
+OPENSSL_EXPORT int HKDF_extract(uint8_t *out_key, size_t *out_len,
+                                const EVP_MD *digest, const uint8_t *secret,
+                                size_t secret_len, const uint8_t *salt,
+                                size_t salt_len);
+
+/* HKDF_expand computes a HKDF OKM (as specified by RFC 5869) of length
+ * |out_len| from the PRK |prk| and info |info| using |digest|, and outputs
+ * the result to |out_key|. It returns one on success and zero on error. */
+OPENSSL_EXPORT int HKDF_expand(uint8_t *out_key, size_t out_len,
+                               const EVP_MD *digest, uint8_t *prk,
+                               size_t prk_len, const uint8_t *info,
+                               size_t info_len);
+
 
 #if defined(__cplusplus)
 }  /* extern C */