SHA-3#

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

  • SHA3-224,

  • SHA3-256,

  • SHA3-384,

  • SHA3-512,

  • SHAKE128, and

  • SHAKE256.

The number in SHA3-* denotes the digest size, i.e., how many bits are produced by the hash function. SHAKE128 and SHAKE256 have a 128- or 256-bit security strength and can produce as many bytes as requested.

API Reference#

One-Shot#

Example

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

// This example uses SHA3-256.
//

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

uint8_t digest[HACL_HASH_SHA3_256_DIGEST_LENGTH];

Hacl_Hash_SHA3_sha3_256(digest, (uint8_t*)message, message_size);
void Hacl_Hash_SHA3_sha3_224(uint8_t *output, uint8_t *input, uint32_t input_len)#

Streaming#

Example

// Note: HACL Packages will provide this (or a similar) define in a later
// version.
#define HACL_HASH_SHA3_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_SHA3_256_DIGEST_LENGTH];
uint8_t digest_2[HACL_HASH_SHA3_256_DIGEST_LENGTH];

// Init
Hacl_Hash_SHA3_state_t* state =
  Hacl_Hash_SHA3_malloc(Spec_Hash_Definitions_SHA3_256);

// 1/2 Include `Hello, ` into the hash calculation and
// obtain the intermediate hash of "Hello, ".
uint32_t update_res =
  Hacl_Hash_SHA3_update(state, (uint8_t*)chunk_1, chunk_1_size);
ASSERT_EQ(0, update_res);
// This is optional when no intermediate results are required.
auto finish_res = Hacl_Hash_SHA3_digest(state, digest_1);
ASSERT_EQ(Hacl_Streaming_Types_Success, finish_res);

// 2/2 Include `World!` into the hash calculation and
// obtain the final hash of "Hello, World!".
uint32_t update_res_2 =
  Hacl_Hash_SHA3_update(state, (uint8_t*)chunk_2, chunk_2_size);
ASSERT_EQ(0, update_res_2);
auto finish_res_2 = Hacl_Hash_SHA3_digest(state, digest_2);
ASSERT_EQ(Hacl_Streaming_Types_Success, finish_res_2);

// Cleanup
Hacl_Hash_SHA3_free(state);

print_hex_ln(HACL_HASH_SHA3_256_DIGEST_LENGTH, digest_1);
print_hex_ln(HACL_HASH_SHA3_256_DIGEST_LENGTH, digest_2);
typedef struct Hacl_Hash_SHA3_state_t_s Hacl_Hash_SHA3_state_t#
Hacl_Hash_SHA3_state_t *Hacl_Hash_SHA3_malloc(Spec_Hash_Definitions_hash_alg a)#
Hacl_Streaming_Types_error_code Hacl_Hash_SHA3_update(Hacl_Hash_SHA3_state_t *state, uint8_t *chunk, uint32_t chunk_len)#
Hacl_Streaming_Types_error_code Hacl_Hash_SHA3_digest(Hacl_Hash_SHA3_state_t *state, uint8_t *output)#
void Hacl_Hash_SHA3_reset(Hacl_Hash_SHA3_state_t *state)#
void Hacl_Hash_SHA3_free(Hacl_Hash_SHA3_state_t *state)#

SHAKE#

API Reference#

One-Shot#

Example

// This example uses SHAKE-128.

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

// SHAKE will generate as many bytes as requested.
uint32_t digest_size = 42;
uint8_t digest[42];

Hacl_Hash_SHA3_shake128_hacl(
  message_size, (uint8_t*)message, digest_size, digest);
void Hacl_Hash_SHA3_shake128_hacl(uint32_t inputByteLen, uint8_t *input, uint32_t outputByteLen, uint8_t *output)#

Streaming#

No streaming API available.