SHA-2#

SHA-2 comes in six different variants (instantiations) …

  • SHA-224,

  • SHA-256,

  • SHA-384,

  • SHA-512,

  • SHA-512/224 (not supported by HACL), and

  • SHA-512/256 (not supported by HACL).

The number denotes the digest size, i.e., how many bits are produced by the hash function.

Note: While SHA-256 already denotes the hash function from the SHA-2 family that produces 256 bits of output, it is sometimes called SHA2-256 to avoid confusion with SHA-1 and SHA-3.

API Reference#

One-Shot#

Example

// Note: HACL Packages will provide this (or a similar) define in a later
// version.
#define HACL_HASH_SHA2_256_DIGEST_LENGTH 32

// This example uses SHA2-256.
//

const char* message = "Hello, World!";
uint32_t message_size = strlen(message);

uint8_t digest[HACL_HASH_SHA2_256_DIGEST_LENGTH];

Hacl_Hash_SHA2_hash_256(digest, (uint8_t*)message, message_size);
void Hacl_Hash_SHA2_hash_224(uint8_t *output, uint8_t *input, uint32_t input_len)#

Hash input, of len input_len, into output, an array of 28 bytes.

Streaming#

Example

// Note: HACL Packages will provide this (or a similar) define in a later
// version.
#define HACL_HASH_SHA2_256_DIGEST_LENGTH 32

void
print_hex_ln(size_t bytes_len, uint8_t* bytes)
{
  for (int i = 0; i < bytes_len; ++i) {
    printf("%02x", bytes[i]);
  }

  printf("\n");
}

// This example shows how to hash the byte sequence "Hello, World!" in two
// chunks. As a bonus, it also shows how to obtain intermediate results by
// calling `digest` more than once.

const char* chunk_1 = "Hello, ";
const char* chunk_2 = "World!";
uint32_t chunk_1_size = strlen(chunk_1);
uint32_t chunk_2_size = strlen(chunk_2);

uint8_t digest_1[HACL_HASH_SHA2_256_DIGEST_LENGTH];
uint8_t digest_2[HACL_HASH_SHA2_256_DIGEST_LENGTH];

// Init
Hacl_Hash_SHA2_state_t_256* state =
  Hacl_Hash_SHA2_malloc_256();

// 1/2 Include `Hello, ` into the hash calculation and
// obtain the intermediate hash of "Hello, ".
Hacl_Hash_SHA2_update_256(state, (uint8_t*)chunk_1, chunk_1_size);
// This is optional when no intermediate results are required.
Hacl_Hash_SHA2_digest_256(state, digest_1);

// 2/2 Include `World!` into the hash calculation and
// obtain the final hash of "Hello, World!".
Hacl_Hash_SHA2_update_256(state, (uint8_t*)chunk_2, chunk_2_size);
Hacl_Hash_SHA2_digest_256(state, digest_2);

// Cleanup
Hacl_Hash_SHA2_free_256(state);

print_hex_ln(HACL_HASH_SHA2_256_DIGEST_LENGTH, digest_1);
print_hex_ln(HACL_HASH_SHA2_256_DIGEST_LENGTH, digest_2);

Init

typedef Hacl_Streaming_MD_state_32 Hacl_Hash_SHA2_state_t_224#
Hacl_Streaming_MD_state_32 *Hacl_Hash_SHA2_malloc_224(void)#

Update

Hacl_Streaming_Types_error_code Hacl_Hash_SHA2_update_224(Hacl_Streaming_MD_state_32 *state, uint8_t *input, uint32_t input_len)#

Finish

void Hacl_Hash_SHA2_digest_224(Hacl_Streaming_MD_state_32 *state, uint8_t *output)#

Write the resulting hash into output, an array of 28 bytes. The state remains valid after a call to digest_224, meaning the user may feed more data into the hash via update_224.

void Hacl_Hash_SHA2_reset_224(Hacl_Streaming_MD_state_32 *state)#
void Hacl_Hash_SHA2_free_224(Hacl_Streaming_MD_state_32 *state)#