Design for support of HMAC precomputed keys

crypto/digest_extra/digest_test.cc

@@ -476,3 +476,46 @@ TEST(DigestTest, TransformBlocks) {
 
   EXPECT_TRUE(0 == OPENSSL_memcmp(ctx1.h, ctx2.h, sizeof(ctx1.h)));
 }
+
+// FIXME: Need to implement this for all hash functions used by HMAC
+TEST(DigestTest, InitAndGetStateSHA256) {
+  const size_t nb_blocks = 10;
+  const size_t block_size = SHA256_CBLOCK;
+  uint8_t data[block_size * nb_blocks];
+  for (size_t i = 0; i < sizeof(data); i++) {
+    data[i] = i*3;
+  }
+
+  // SHA-256
+
+  // Compute the hash of the data for the baseline
+  SHA256_CTX ctx1;
+  EXPECT_TRUE(SHA256_Init(&ctx1));
+  EXPECT_TRUE(SHA256_Update(&ctx1, data, sizeof(data)));
+  uint8_t hash1[SHA256_DIGEST_LENGTH];
+  EXPECT_TRUE(SHA256_Final(hash1, &ctx1));
+
+  // Compute it by stopping in the middle, getting the state, and restoring it
+  SHA256_CTX ctx2;
+  EXPECT_TRUE(SHA256_Init(&ctx2));
+  EXPECT_TRUE(SHA256_Update(&ctx2, data, 1));
+  uint8_t state_h[SHA256_DIGEST_LENGTH];
+  uint64_t state_n;
+  // we should not be able to export the state before a full block
+  EXPECT_FALSE(SHA256_get_state(&ctx2, state_h, &state_n));
+  // finish 2 blocks
+  EXPECT_TRUE(SHA256_Update(&ctx2, data+1, 2*block_size-1));
+  // now we should be able to export the state
+  EXPECT_TRUE(SHA256_get_state(&ctx2, state_h, &state_n));
+  // check that state_n corresponds to 2 blocks
+  EXPECT_EQ(2*block_size*8, state_n);
+
+  // and we continue on a fresh new context
+  SHA256_CTX ctx3;
+  EXPECT_TRUE(SHA256_Init_from_state(&ctx3, state_h, state_n));
+  EXPECT_TRUE(SHA256_Update(&ctx2, data+2*block_size, (nb_blocks-2)*block_size));
+  uint8_t hash2[SHA256_DIGEST_LENGTH];
+  EXPECT_TRUE(SHA256_Final(hash2, &ctx2));
+
+  EXPECT_EQ(Bytes(hash1), Bytes(hash2));
+}

crypto/fipsmodule/hmac/internal.h

@@ -0,0 +1,27 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0 OR ISC
+
+#ifndef AWSLC_HEADER_HMAC_INTERNAL_H
+#define AWSLC_HEADER_HMAC_INTERNAL_H
+
+#include <openssl/base.h>
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+// HMAC_with_precompute is only used in FIPS ACVP harness, in order to test
+// the computation of HMAC using precomputed keys (internally). It should not
+// be used for any other purposes as it outputs the same results as HMAC and is
+// slower than HMAC.
+OPENSSL_EXPORT uint8_t *HMAC_with_precompute(const EVP_MD *evp_md,
+                                             const void *key, size_t key_len,
+                                             const uint8_t *data,
+                                             size_t data_len, uint8_t *out,
+                                             unsigned int *out_len);
+
+#if defined(__cplusplus)
+}  // extern C
+#endif
+
+#endif  // AWSLC_HEADER_HMAC_INTERNAL_H

crypto/fipsmodule/sha/internal.h

@@ -19,6 +19,17 @@
 extern "C" {
 #endif
 
+// Internal SHA2 constants
+
+// SHA224_CHAINING_LENGTH is the chaining length in bytes of SHA-224
+// It corresponds to the length in bytes of the h part of the state
+#define SHA224_CHAINING_LENGTH 32
+
+// SHA256_CHAINING_LENGTH is the chaining length in bytes of SHA-256
+// It corresponds to the length in bytes of the h part of the state
+#define SHA256_CHAINING_LENGTH 32
+
+
 // SHA3 constants, from NIST FIPS202.
 // https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf
 #define SHA3_ROWS 5
@@ -92,6 +103,26 @@ void sha512_block_data_order(uint64_t *state, const uint8_t *in,
 #define KECCAK1600_ASM
 #endif
 
+// SHA256_Init_from_state is a low-level function that initializes |sha| with a
+// custom state. |h| is the hash state in big endian. |n| is the number of bits
+// processed at this point. It must be a multiple of |SHA256_CBLOCK*8|.
+// It returns one on success and zero on programmer error.
+// External users should never use directly this function.
+OPENSSL_EXPORT int SHA256_Init_from_state(
+    SHA256_CTX *sha, const uint8_t h[SHA256_CHAINING_LENGTH], uint64_t n);
+
+// SHA256_get_state is a low-level function that exports the hash state in big
+// endian into |out_n| and the number of bits processed at this point in
+// |out_n|. SHA256_Final must not have been called before (otherwise results
+// are not guaranteed). Furthermore, the number of bytes processed by
+// SHA256_Update must be a multiple of the block length |SHA256_CBLOCK|
+// (otherwise it fails). It returns one on success and zero on programmer
+// error.
+// External users should never use directly this function.
+OPENSSL_EXPORT int SHA256_get_state(SHA256_CTX *ctx,
+                                    uint8_t out_h[SHA256_CHAINING_LENGTH],
+                                    uint64_t *out_n);
+
 // SHA3_224 writes the digest of |len| bytes from |data| to |out| and returns |out|. 
 // There must be at least |SHA3_224_DIGEST_LENGTH| bytes of space in |out|.
 // On failure |SHA3_224| returns NULL.

crypto/fipsmodule/sha/sha256.c

@@ -93,6 +93,41 @@ int SHA256_Init(SHA256_CTX *sha) {
   return 1;
 }
 
+OPENSSL_STATIC_ASSERT(SHA256_CHAINING_LENGTH==SHA224_CHAINING_LENGTH,
+                      sha256_and_sha224_have_same_chaining_length)
+
+// sha256_init_from_state_impl is the implementation of
+// SHA256_Init_from_state and SHA224_Init_from_state
+// Note that the state h is always SHA256_CHAINING_LENGTH-byte long
+static int sha256_init_from_state_impl(SHA256_CTX *sha, int md_len,
+                                       const uint8_t h[SHA256_CHAINING_LENGTH],
+                                       uint64_t n) {
+  if(n % ((uint64_t) SHA256_CBLOCK * 8) != 0) {
+    // n is not a multiple of the block size in bits, so it fails
+    return 0;
+  }
+
+  OPENSSL_memset(sha, 0, sizeof(SHA256_CTX));
+  sha->md_len = md_len;
+
+  const size_t out_words = SHA256_CHAINING_LENGTH / 4;
+  for (size_t i = 0; i < out_words; i++) {
+    sha->h[i] = CRYPTO_load_u32_be(h);
+    h += 4;
+  }
+
+  sha->Nh = n >> 32;
+  sha->Nl = n & 0xffffffff;
+
+  return 1;
+}
+
+int SHA256_Init_from_state(SHA256_CTX *sha,
+                           const uint8_t h[SHA256_CHAINING_LENGTH],
+                           uint64_t n) {
+  return sha256_init_from_state_impl(sha, SHA256_DIGEST_LENGTH, h, n);
+}
+
 uint8_t *SHA224(const uint8_t *data, size_t len,
                 uint8_t out[SHA224_DIGEST_LENGTH]) {
   // We have to verify that all the SHA services actually succeed before
@@ -163,14 +198,41 @@ static int sha256_final_impl(uint8_t *out, size_t md_len, SHA256_CTX *c) {
   return 1;
 }
 
-int SHA256_Final(uint8_t out[SHA256_DIGEST_LENGTH], SHA256_CTX *c) {
+int SHA256_Final(uint8_t out[SHA256_CHAINING_LENGTH], SHA256_CTX *c) {
   return sha256_final_impl(out, SHA256_DIGEST_LENGTH, c);
 }
 
 int SHA224_Final(uint8_t out[SHA224_DIGEST_LENGTH], SHA256_CTX *ctx) {
   return sha256_final_impl(out, SHA224_DIGEST_LENGTH, ctx);
 }
 
+// sha256_get_state_impl is the implementation of
+// SHA256_get_state and SHA224_get_state
+// Note that the state out_h is always SHA256_CHAINING_LENGTH-byte long
+static int sha256_get_state_impl(SHA256_CTX *ctx,
+                                 uint8_t out_h[SHA256_CHAINING_LENGTH],
+                                 uint64_t *out_n) {
+  if (ctx->Nl % ((uint64_t)SHA256_CBLOCK * 8) != 0) {
+    // ctx->Nl is not a multiple of the block size in bits, so it fails
+    return 0;
+  }
+
+  const size_t out_words = SHA256_CHAINING_LENGTH / 4;
+  for (size_t i = 0; i < out_words; i++) {
+    CRYPTO_store_u32_be(out_h, ctx->h[i]);
+    out_h += 4;
+  }
+
+  *out_n = (((uint64_t)ctx->Nh) << 32) + ctx->Nl;
+
+  return 1;
+}
+
+int SHA256_get_state(SHA256_CTX *ctx, uint8_t out_h[SHA256_CHAINING_LENGTH],
+                     uint64_t *out_n) {
+  return sha256_get_state_impl(ctx, out_h, out_n);
+}
+
 #ifndef SHA256_ASM
 static const uint32_t K256[64] = {
     0x428a2f98UL, 0x71374491UL, 0xb5c0fbcfUL, 0xe9b5dba5UL, 0x3956c25bUL,

crypto/hmac_extra/hmac_test.cc

@@ -64,6 +64,7 @@
 #include <openssl/evp.h>
 #include <openssl/hmac.h>
 
+#include "../../../crypto/fipsmodule/hmac/internal.h"
 #include "../test/file_test.h"
 #include "../test/test_util.h"
 #include "../test/wycheproof_util.h"
@@ -210,14 +211,21 @@ TEST(HMACTest, TestVectors) {
     ASSERT_EQ(EVP_MD_size(digest), output.size());
 
     // Test using the one-shot API.
-    unsigned expected_mac_len = EVP_MD_size(digest);
+    const unsigned expected_mac_len = EVP_MD_size(digest);
     std::unique_ptr<uint8_t[]> mac(new uint8_t[expected_mac_len]);
     unsigned mac_len;
     ASSERT_TRUE(HMAC(digest, key.data(), key.size(), input.data(), input.size(),
                      mac.get(), &mac_len));
     EXPECT_EQ(Bytes(output), Bytes(mac.get(), mac_len));
     OPENSSL_memset(mac.get(), 0, expected_mac_len); // Clear the prior correct answer
 
+    // Test using the one-shot API with precompute
+    ASSERT_TRUE(HMAC_with_precompute(digest, key.data(), key.size(),
+                                     input.data(), input.size(), mac.get(),
+                                     &mac_len));
+    EXPECT_EQ(Bytes(output), Bytes(mac.get(), mac_len));
+    OPENSSL_memset(mac.get(), 0, expected_mac_len); // Clear the prior correct answer
+
     // Test using HMAC_CTX.
     bssl::ScopedHMAC_CTX ctx;
     ASSERT_TRUE(
@@ -227,20 +235,61 @@ TEST(HMACTest, TestVectors) {
     EXPECT_EQ(Bytes(output), Bytes(mac.get(), mac_len));
     OPENSSL_memset(mac.get(), 0, expected_mac_len); // Clear the prior correct answer
 
+    // Test the precomputed key size is at most HMAC_MAX_PRECOMPUTED_KEY_SIZE
+    const size_t precomputed_key_len = HMAC_precomputed_key_size(ctx.get());
+    ASSERT_LE(precomputed_key_len, (size_t) HMAC_MAX_PRECOMPUTED_KEY_SIZE);
+    uint8_t precomputed_key[HMAC_MAX_PRECOMPUTED_KEY_SIZE];
+
+    // Test that the precomputed key cannot be exported without calling
+    // HMAC_set_precomputed_key_export
+    size_t precomputed_key_len_out;
+    ASSERT_TRUE(HMAC_Init_ex(ctx.get(), key.data(), key.size(), digest, nullptr));
+    ASSERT_FALSE(HMAC_get_precomputed_key(ctx.get(), precomputed_key, &precomputed_key_len_out));
+
+    // Test that the precomputed key cannot be exported if ctx not initialized
+    // and the precomputed_key_export flag cannot be set
+    bssl::ScopedHMAC_CTX ctx2;
+    ASSERT_FALSE(HMAC_set_precomputed_key_export(ctx2.get()));
+    ASSERT_FALSE(HMAC_get_precomputed_key(ctx2.get(), precomputed_key, &precomputed_key_len_out));
+
+    // Export the precomputed key for later use
+    ASSERT_TRUE(HMAC_set_precomputed_key_export(ctx.get()));
+    ASSERT_TRUE(HMAC_get_precomputed_key(ctx.get(), precomputed_key, &precomputed_key_len_out));
+    ASSERT_EQ(precomputed_key_len, precomputed_key_len_out);
+
+    // Test that at this point the context cannot be used with HMAC_Update
+    // nor HMAC_Final
+    ASSERT_FALSE(HMAC_Update(ctx.get(), input.data(), input.size()));
+    ASSERT_FALSE(HMAC_Final(ctx.get(), mac.get(), &mac_len));
+
     // Test that an HMAC_CTX may be reset with the same key.
     ASSERT_TRUE(HMAC_Init_ex(ctx.get(), nullptr, 0, digest, nullptr));
     ASSERT_TRUE(HMAC_Update(ctx.get(), input.data(), input.size()));
     ASSERT_TRUE(HMAC_Final(ctx.get(), mac.get(), &mac_len));
     EXPECT_EQ(Bytes(output), Bytes(mac.get(), mac_len));
     OPENSSL_memset(mac.get(), 0, expected_mac_len); // Clear the prior correct answer
 
-    // Test that an HMAC_CTX may be reset with the same key and an null md
+    // Same test but with HMAC_Init_from_precomputed_key
+    ASSERT_TRUE(HMAC_Init_from_precomputed_key(ctx.get(), nullptr, 0, digest));
+    ASSERT_TRUE(HMAC_Update(ctx.get(), input.data(), input.size()));
+    ASSERT_TRUE(HMAC_Final(ctx.get(), mac.get(), &mac_len));
+    EXPECT_EQ(Bytes(output), Bytes(mac.get(), mac_len));
+    OPENSSL_memset(mac.get(), 0, expected_mac_len); // Clear the prior correct answer
+
+    // Test that an HMAC_CTX may be reset with the same key and a null md
     ASSERT_TRUE(HMAC_Init_ex(ctx.get(), nullptr, 0, nullptr, nullptr));
     ASSERT_TRUE(HMAC_Update(ctx.get(), input.data(), input.size()));
     ASSERT_TRUE(HMAC_Final(ctx.get(), mac.get(), &mac_len));
     EXPECT_EQ(Bytes(output), Bytes(mac.get(), mac_len));
     OPENSSL_memset(mac.get(), 0, expected_mac_len);  // Clear the prior correct answer
 
+    // Same test but using the Init_with_precompute instead
+    ASSERT_TRUE(HMAC_Init_from_precomputed_key(ctx.get(), nullptr, 0, nullptr));
+    ASSERT_TRUE(HMAC_Update(ctx.get(), input.data(), input.size()));
+    ASSERT_TRUE(HMAC_Final(ctx.get(), mac.get(), &mac_len));
+    EXPECT_EQ(Bytes(output), Bytes(mac.get(), mac_len));
+    OPENSSL_memset(mac.get(), 0, expected_mac_len);  // Clear the prior correct answer
+
     // Some callers will call init multiple times and we need to ensure that doesn't break anything
     ASSERT_TRUE(HMAC_Init_ex(ctx.get(), key.data(), key.size(), digest, nullptr));
     ASSERT_TRUE(HMAC_Init_ex(ctx.get(), nullptr, 0, nullptr, nullptr));
@@ -249,6 +298,59 @@ TEST(HMACTest, TestVectors) {
     EXPECT_EQ(Bytes(output), Bytes(mac.get(), mac_len));
     OPENSSL_memset(mac.get(), 0, expected_mac_len);  // Clear the prior correct answer
 
+    // Same test but using a mix of Init_ex and Init_with_precompute
+    ASSERT_TRUE(HMAC_Init_ex(ctx.get(), key.data(), key.size(), digest, nullptr));
+    ASSERT_TRUE(HMAC_Init_from_precomputed_key(ctx.get(), nullptr, 0, nullptr));
+    ASSERT_TRUE(HMAC_Init_ex(ctx.get(), nullptr, 0, nullptr, nullptr));
+    ASSERT_TRUE(HMAC_Init_from_precomputed_key(ctx.get(), nullptr, 0, nullptr));
+    ASSERT_TRUE(HMAC_Update(ctx.get(), input.data(), input.size()));
+    ASSERT_TRUE(HMAC_Final(ctx.get(), mac.get(), &mac_len));
+    EXPECT_EQ(Bytes(output), Bytes(mac.get(), mac_len));
+    OPENSSL_memset(mac.get(), 0, expected_mac_len);  // Clear the prior correct answer
+
+    // Test that the HMAC_CTX can be reset using the precomputed key
+    ASSERT_TRUE(HMAC_Init_from_precomputed_key(ctx.get(), precomputed_key, precomputed_key_len, nullptr));
+    ASSERT_TRUE(HMAC_Update(ctx.get(), input.data(), input.size()));
+    ASSERT_TRUE(HMAC_Final(ctx.get(), mac.get(), &mac_len));
+    EXPECT_EQ(Bytes(output), Bytes(mac.get(), mac_len));
+    OPENSSL_memset(mac.get(), 0, expected_mac_len);  // Clear the prior correct answer
+
+    // Same test but starting from an empty context
+    ctx.Reset();
+    ASSERT_TRUE(HMAC_Init_from_precomputed_key(ctx.get(), precomputed_key, precomputed_key_len, digest));
+    ASSERT_TRUE(HMAC_Update(ctx.get(), input.data(), input.size()));
+    ASSERT_TRUE(HMAC_Final(ctx.get(), mac.get(), &mac_len));
+    EXPECT_EQ(Bytes(output), Bytes(mac.get(), mac_len));
+    OPENSSL_memset(mac.get(), 0, expected_mac_len);  // Clear the prior correct answer
+
+    // Some callers will call init_from_precomputed_key multiple times and we need to ensure that doesn't break anything
+    ASSERT_TRUE(HMAC_Init_from_precomputed_key(ctx.get(), precomputed_key, precomputed_key_len, nullptr));
+    ASSERT_TRUE(HMAC_Init_from_precomputed_key(ctx.get(), nullptr, 0, nullptr));
+    ASSERT_TRUE(HMAC_Update(ctx.get(), input.data(), input.size()));
+    ASSERT_TRUE(HMAC_Final(ctx.get(), mac.get(), &mac_len));
+    EXPECT_EQ(Bytes(output), Bytes(mac.get(), mac_len));
+    OPENSSL_memset(mac.get(), 0, expected_mac_len);  // Clear the prior correct answer
+
+    // Test that we get the same precompute_key the second time
+    ASSERT_TRUE(HMAC_Init_ex(ctx.get(), key.data(), key.size(), digest, nullptr));
+    uint8_t precomputed_key2[HMAC_MAX_PRECOMPUTED_KEY_SIZE];
+    size_t precomputed_key_len_out2;
+    ASSERT_TRUE(HMAC_set_precomputed_key_export(ctx.get()));
+    ASSERT_TRUE(HMAC_set_precomputed_key_export(ctx.get())); // testing we can set it twice
+    ASSERT_TRUE(HMAC_get_precomputed_key(ctx.get(), precomputed_key2, &precomputed_key_len_out2));
+    ASSERT_EQ(precomputed_key_len, precomputed_key_len_out2);
+    ASSERT_EQ(Bytes(precomputed_key, precomputed_key_len), Bytes(precomputed_key2, precomputed_key_len));
+    OPENSSL_memset(precomputed_key2, 0, HMAC_MAX_PRECOMPUTED_KEY_SIZE);  // Clear the prior correct answer
+    precomputed_key_len_out2 = 0;  // Clear the prior correct answer
+
+    // Same but initializing the ctx using the precompute key in the first place
+    ctx.Reset();
+    ASSERT_TRUE(HMAC_Init_from_precomputed_key(ctx.get(), precomputed_key, precomputed_key_len, digest));
+    ASSERT_TRUE(HMAC_set_precomputed_key_export(ctx.get()));
+    ASSERT_TRUE(HMAC_get_precomputed_key(ctx.get(), precomputed_key2, &precomputed_key_len_out2));
+    ASSERT_EQ(precomputed_key_len, precomputed_key_len_out2);
+    ASSERT_EQ(Bytes(precomputed_key, precomputed_key_len), Bytes(precomputed_key2, precomputed_key_len));
+
     // Test feeding the input in byte by byte.
     ASSERT_TRUE(HMAC_Init_ex(ctx.get(), nullptr, 0, nullptr, nullptr));
     for (size_t i = 0; i < input.size(); i++) {