HMAC

HMAC instantiated with SHA-3 hash functions, as specified in section 7 of FIPS 202, RFC 2104, and FIPS 198-1. More...

Data Structures
struct	hmac_sha3_t
	HMAC-SHA3 (Hash-based Message Authentication Code) context (all members are private). More...

Functions
void	hmac_sha3_224 (const uint8_t *key, const size_t key_len, const uint8_t *msg, const size_t msg_len, uint8_t mac[28])
	Calculate HMAC-SHA3-224 of given key and data. More...
void	hmac_sha3_256 (const uint8_t *key, const size_t key_len, const uint8_t *msg, const size_t msg_len, uint8_t mac[32])
	Calculate HMAC-SHA3-256 given key and data. More...
void	hmac_sha3_384 (const uint8_t *key, const size_t key_len, const uint8_t *msg, const size_t msg_len, uint8_t mac[48])
	Calculate HMAC-SHA3-384 of given key and data. More...
void	hmac_sha3_512 (const uint8_t *key, const size_t key_len, const uint8_t *msg, const size_t msg_len, uint8_t mac[64])
	Calculate HMAC-SHA3-512 of given key and data. More...
void	hmac_sha3_224_init (hmac_sha3_t *ctx, const uint8_t *key, const size_t key_len)
	Initialize HMAC-SHA3-224 (FIPS 202, Section 7) context. More...
_Bool	hmac_sha3_224_absorb (hmac_sha3_t *ctx, const uint8_t *src, const size_t len)
	Absorb data into HMAC-SHA3-224 context. More...
void	hmac_sha3_224_final (hmac_sha3_t *ctx, uint8_t mac[28])
	Finalize HMAC-SHA3-224 context and write 28 byte MAC to destination buffer. More...
void	hmac_sha3_256_init (hmac_sha3_t *ctx, const uint8_t *key, const size_t key_len)
	Initialize HMAC-SHA3-256 (FIPS 202, Section 7) context. More...
_Bool	hmac_sha3_256_absorb (hmac_sha3_t *ctx, const uint8_t *src, const size_t len)
	Absorb data into HMAC-SHA3-256 context. More...
void	hmac_sha3_256_final (hmac_sha3_t *ctx, uint8_t mac[32])
	Finalize HMAC-SHA3-256 context and write 32 byte MAC to destination buffer. More...
void	hmac_sha3_384_init (hmac_sha3_t *ctx, const uint8_t *key, const size_t key_len)
	Initialize HMAC-SHA3-384 (FIPS 202, Section 7) context. More...
_Bool	hmac_sha3_384_absorb (hmac_sha3_t *ctx, const uint8_t *src, const size_t len)
	Absorb data into HMAC-SHA3-384 context. More...
void	hmac_sha3_384_final (hmac_sha3_t *ctx, uint8_t mac[48])
	Finalize HMAC-SHA3-384 context and write 48 byte MAC to destination buffer. More...
void	hmac_sha3_512_init (hmac_sha3_t *ctx, const uint8_t *key, const size_t key_len)
	Initialize HMAC-SHA3-512 (FIPS 202, Section 7) context. More...
_Bool	hmac_sha3_512_absorb (hmac_sha3_t *ctx, const uint8_t *src, const size_t len)
	Absorb data into HMAC-SHA3-512 context. More...
void	hmac_sha3_512_final (hmac_sha3_t *ctx, uint8_t mac[64])
	Finalize HMAC-SHA3-512 context and write 64 byte MAC to destination buffer. More...

Detailed Description

HMAC instantiated with SHA-3 hash functions, as specified in section 7 of FIPS 202, RFC 2104, and FIPS 198-1.

Function Documentation

hmac_sha3_224()

void hmac_sha3_224	(	const uint8_t *	key,
		const size_t	key_len,
		const uint8_t *	msg,
		const size_t	msg_len,
		uint8_t	mac[28]
	)

Calculate HMAC-SHA3-224 of given key and data.

Calculate HMAC-SHA3-224 (FIPS 202, Section 7) of key in buffer key of length key_len and input message in buffer msg of length msg_len bytes and write 28 byte [message authentication code (MAC)][] to destination buffer mac.

Parameters

[in]	key	Key.
[in]	key_len	Key length, in bytes.
[in]	msg	Input message.
[in]	msg_len	Input message length, in bytes.
[out]	mac	MAC destination buffer. Must be at least 28 bytes in length.

Example:

  // key and key size, in bytes (w/o trailing NUL)
  const uint8_t key[] = "secret!"; // key
  const size_t key_len = sizeof(key) - 1; // key size
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // calculate HMAC-SHA3-224, write results to `mac`
  uint8_t mac[28] = { 0 };
  hmac_sha3_224(key, key_len, buf, sizeof(buf), mac);

hmac_sha3_224_absorb()

_Bool hmac_sha3_224_absorb	(	hmac_sha3_t *	ctx,
		const uint8_t *	src,
		const size_t	len
	)

Absorb data into HMAC-SHA3-224 context.

Absorb input data in src of length len bytes into HMAC-SHA3-224 context hmac. Can be called iteratively to absorb input data in chunks.

Parameters

[in,out]	ctx	HMAC-SHA3-224 context.
[in]	src	Input data.
[in]	len	Input data length, in bytes.

Returns

True if data was absorbed, and false otherwise (e.g., if context has already been finalized).

Example:

  // key and key size, in bytes (w/o trailing NUL)
  const uint8_t key[] = "secret!"; // key
  const size_t key_len = sizeof(key) - 1; // key size
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create HMAC-SHA3-224 context
  hmac_sha3_t ctx = { 0 };
  hmac_sha3_224_init(&ctx, key, key_len);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    hmac_sha3_224_absorb(&ctx, buf + i, 32);
  }
 
  // finalize context, write result to `mac`
  uint8_t mac[28] = { 0 };
  hmac_sha3_224_final(&ctx, mac);

hmac_sha3_224_final()

void hmac_sha3_224_final	(	hmac_sha3_t *	ctx,
		uint8_t	mac[28]
	)

Finalize HMAC-SHA3-224 context and write 28 byte MAC to destination buffer.

Parameters

[in,out]	ctx	HMAC-SHA3-224 context.
[out]	mac	MAC destination buffer. Must be at least 28 bytes in length.

Example:

  // key and key size, in bytes (w/o trailing NUL)
  const uint8_t key[] = "secret!"; // key
  const size_t key_len = sizeof(key) - 1; // key size
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create HMAC-SHA3-224 context
  hmac_sha3_t ctx = { 0 };
  hmac_sha3_224_init(&ctx, key, key_len);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    hmac_sha3_224_absorb(&ctx, buf + i, 32);
  }
 
  // finalize context, write result to `mac`
  uint8_t mac[28] = { 0 };
  hmac_sha3_224_final(&ctx, mac);

hmac_sha3_224_init()

void hmac_sha3_224_init	(	hmac_sha3_t *	ctx,
		const uint8_t *	key,
		const size_t	key_len
	)

Initialize HMAC-SHA3-224 (FIPS 202, Section 7) context.

Parameters

[out]	ctx	HMAC-SHA3-224 context.
[in]	key	Key.
[in]	key_len	Key length, in bytes.

Example:

  // key and key size, in bytes (w/o trailing NUL)
  const uint8_t key[] = "secret!"; // key
  const size_t key_len = sizeof(key) - 1; // key size
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create HMAC-SHA3-224 context
  hmac_sha3_t ctx = { 0 };
  hmac_sha3_224_init(&ctx, key, key_len);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    hmac_sha3_224_absorb(&ctx, buf + i, 32);
  }
 
  // finalize context, write result to `mac`
  uint8_t mac[28] = { 0 };
  hmac_sha3_224_final(&ctx, mac);

hmac_sha3_256()

void hmac_sha3_256	(	const uint8_t *	key,
		const size_t	key_len,
		const uint8_t *	msg,
		const size_t	msg_len,
		uint8_t	mac[32]
	)

Calculate HMAC-SHA3-256 given key and data.

Calculate HMAC-SHA3-256 (FIPS 202, Section 7) of key in buffer key of length key_len and input message in buffer msg of length msg_len bytes and write 32 byte message authentication code (MAC) destination buffer mac.

Parameters

[in]	key	Key.
[in]	key_len	Key length, in bytes.
[in]	msg	Input message.
[in]	msg_len	Input message length, in bytes.
[out]	mac	MAC destination buffer. Must be at least 32 bytes in length.

Example:

  // key and key size, in bytes (w/o trailing NUL)
  const uint8_t key[] = "secret!"; // key
  const size_t key_len = sizeof(key) - 1; // key size
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // calculate HMAC-SHA3-256, write results to `mac`
  uint8_t mac[32] = { 0 };
  hmac_sha3_256(key, key_len, buf, sizeof(buf), mac);

hmac_sha3_256_absorb()

_Bool hmac_sha3_256_absorb	(	hmac_sha3_t *	ctx,
		const uint8_t *	src,
		const size_t	len
	)

Absorb data into HMAC-SHA3-256 context.

Absorb input data in src of length len bytes into HMAC-SHA3-256 context ctx. Can be called iteratively to absorb input data in chunks.

Parameters

[in,out]	ctx	HMAC-SHA3-256 context.
[in]	src	Input data.
[in]	len	Input data length, in bytes.

Returns

True if data was absorbed, and false otherwise (e.g., if context has already been finalized).

Example:

  // key and key size, in bytes (w/o trailing NUL)
  const uint8_t key[] = "secret!"; // key
  const size_t key_len = sizeof(key) - 1; // key size
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create HMAC-SHA3-256 context
  hmac_sha3_t ctx = { 0 };
  hmac_sha3_256_init(&ctx, key, key_len);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    hmac_sha3_256_absorb(&ctx, buf + i, 32);
  }
 
  // finalize context, write result to `mac`
  uint8_t mac[32] = { 0 };
  hmac_sha3_256_final(&ctx, mac);

hmac_sha3_256_final()

void hmac_sha3_256_final	(	hmac_sha3_t *	ctx,
		uint8_t	mac[32]
	)

Finalize HMAC-SHA3-256 context and write 32 byte MAC to destination buffer.

Parameters

[in,out]	ctx	HMAC-SHA3-256 context.
[out]	mac	MAC destination buffer. Must be at least 32 bytes in length.

Example:

  // key and key size, in bytes (w/o trailing NUL)
  const uint8_t key[] = "secret!"; // key
  const size_t key_len = sizeof(key) - 1; // key size
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create HMAC-SHA3-256 context
  hmac_sha3_t ctx = { 0 };
  hmac_sha3_256_init(&ctx, key, key_len);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    hmac_sha3_256_absorb(&ctx, buf + i, 32);
  }
 
  // finalize context, write result to `mac`
  uint8_t mac[32] = { 0 };
  hmac_sha3_256_final(&ctx, mac);

hmac_sha3_256_init()

void hmac_sha3_256_init	(	hmac_sha3_t *	ctx,
		const uint8_t *	key,
		const size_t	key_len
	)

Initialize HMAC-SHA3-256 (FIPS 202, Section 7) context.

Parameters

[out]	ctx	HMAC-SHA3-256 context.
[in]	key	Key.
[in]	key_len	Key length, in bytes.

Example:

  // key and key size, in bytes (w/o trailing NUL)
  const uint8_t key[] = "secret!"; // key
  const size_t key_len = sizeof(key) - 1; // key size
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create HMAC-SHA3-256 context
  hmac_sha3_t ctx = { 0 };
  hmac_sha3_256_init(&ctx, key, key_len);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    hmac_sha3_256_absorb(&ctx, buf + i, 32);
  }
 
  // finalize context, write result to `mac`
  uint8_t mac[32] = { 0 };
  hmac_sha3_256_final(&ctx, mac);

hmac_sha3_384()

void hmac_sha3_384	(	const uint8_t *	key,
		const size_t	key_len,
		const uint8_t *	msg,
		const size_t	msg_len,
		uint8_t	mac[48]
	)

Calculate HMAC-SHA3-384 of given key and data.

Calculate HMAC-SHA3-384 (FIPS 202, Section 7) of key in buffer key of length key_len and input message in buffer msg of length msg_len bytes and write 48 byte message authentication code (MAC) destination buffer mac.

Parameters

[in]	key	Key.
[in]	key_len	Key length, in bytes.
[in]	msg	Input message.
[in]	msg_len	Input message length, in bytes.
[out]	mac	MAC destination buffer. Must be at least 48 bytes in length.

Example:

  // key and key size, in bytes (w/o trailing NUL)
  const uint8_t key[] = "secret!"; // key
  const size_t key_len = sizeof(key) - 1; // key size
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // calculate HMAC-SHA3-384, write results to `mac`
  uint8_t mac[48] = { 0 };
  hmac_sha3_384(key, key_len, buf, sizeof(buf), mac);

hmac_sha3_384_absorb()

_Bool hmac_sha3_384_absorb	(	hmac_sha3_t *	ctx,
		const uint8_t *	src,
		const size_t	len
	)

Absorb data into HMAC-SHA3-384 context.

Absorb input data in src of length len bytes into HMAC-SHA3-384 context ctx. Can be called iteratively to absorb input data in chunks.

Parameters

[in,out]	ctx	HMAC-SHA3-384 context.
[in]	src	Input data.
[in]	len	Input data length, in bytes.

Returns

True if data was absorbed, and false otherwise (e.g., if context has already been finalized).

Example:

  // key and key size, in bytes (w/o trailing NUL)
  const uint8_t key[] = "secret!"; // key
  const size_t key_len = sizeof(key) - 1; // key size
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create HMAC-SHA3-384 context
  hmac_sha3_t ctx = { 0 };
  hmac_sha3_384_init(&ctx, key, key_len);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    hmac_sha3_384_absorb(&ctx, buf + i, 32);
  }
 
  // finalize context, write result to `mac`
  uint8_t mac[48] = { 0 };
  hmac_sha3_384_final(&ctx, mac);

hmac_sha3_384_final()

void hmac_sha3_384_final	(	hmac_sha3_t *	ctx,
		uint8_t	mac[48]
	)

Finalize HMAC-SHA3-384 context and write 48 byte MAC to destination buffer.

Parameters

[in,out]	ctx	HMAC-SHA3-384 context.
[out]	mac	MAC destination buffer. Must be at least 48 bytes in length.

Example:

  // key and key size, in bytes (w/o trailing NUL)
  const uint8_t key[] = "secret!"; // key
  const size_t key_len = sizeof(key) - 1; // key size
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create HMAC-SHA3-512 context
  hmac_sha3_t ctx = { 0 };
  hmac_sha3_512_init(&ctx, key, key_len);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    hmac_sha3_512_absorb(&ctx, buf + i, 32);
  }
 
  // finalize context, write result to `mac`
  uint8_t mac[64] = { 0 };
  hmac_sha3_512_final(&ctx, mac);

hmac_sha3_384_init()

void hmac_sha3_384_init	(	hmac_sha3_t *	ctx,
		const uint8_t *	key,
		const size_t	key_len
	)

Initialize HMAC-SHA3-384 (FIPS 202, Section 7) context.

Parameters

[out]	ctx	HMAC-SHA3-384 context.
[in]	key	Key.
[in]	key_len	Key length, in bytes.

Example:

  // key and key size, in bytes (w/o trailing NUL)
  const uint8_t key[] = "secret!"; // key
  const size_t key_len = sizeof(key) - 1; // key size
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create HMAC-SHA3-384 context
  hmac_sha3_t ctx = { 0 };
  hmac_sha3_384_init(&ctx, key, key_len);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    hmac_sha3_384_absorb(&ctx, buf + i, 32);
  }
 
  // finalize context, write result to `mac`
  uint8_t mac[48] = { 0 };
  hmac_sha3_384_final(&ctx, mac);

hmac_sha3_512()

void hmac_sha3_512	(	const uint8_t *	key,
		const size_t	key_len,
		const uint8_t *	msg,
		const size_t	msg_len,
		uint8_t	mac[64]
	)

Calculate HMAC-SHA3-512 of given key and data.

Calculate HMAC-SHA3-512 (FIPS 202, Section 7) of key in buffer key of length key_len and input message in buffer msg of length msg_len bytes and write 64 byte message authentication code (MAC) destination buffer mac.

Parameters

[in]	key	Key.
[in]	key_len	Key length, in bytes.
[in]	msg	Input message.
[in]	msg_len	Input message length, in bytes.
[out]	mac	MAC destination buffer. Must be at least 64 bytes in length.

Example:

  // key and key size, in bytes (w/o trailing NUL)
  const uint8_t key[] = "secret!"; // key
  const size_t key_len = sizeof(key) - 1; // key size
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // calculate HMAC-SHA3-512, write results to `mac`
  uint8_t mac[64] = { 0 };
  hmac_sha3_512(key, key_len, buf, sizeof(buf), mac);

hmac_sha3_512_absorb()

_Bool hmac_sha3_512_absorb	(	hmac_sha3_t *	ctx,
		const uint8_t *	src,
		const size_t	len
	)

Absorb data into HMAC-SHA3-512 context.

Absorb input data in src of length len bytes into HMAC-SHA3-512 context ctx. Can be called iteratively to absorb input data in chunks.

Parameters

[in,out]	ctx	HMAC-SHA3-512 context.
[in]	src	Input data.
[in]	len	Input data length, in bytes.

Example:

  // key and key size, in bytes (w/o trailing NUL)
  const uint8_t key[] = "secret!"; // key
  const size_t key_len = sizeof(key) - 1; // key size
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create HMAC-SHA3-512 context
  hmac_sha3_t ctx = { 0 };
  hmac_sha3_512_init(&ctx, key, key_len);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    hmac_sha3_512_absorb(&ctx, buf + i, 32);
  }
 
  // finalize context, write result to `mac`
  uint8_t mac[64] = { 0 };
  hmac_sha3_512_final(&ctx, mac);

Returns

True if data was absorbed, and false otherwise (e.g., if context has already been finalized).

hmac_sha3_512_final()

void hmac_sha3_512_final	(	hmac_sha3_t *	ctx,
		uint8_t	mac[64]
	)

Finalize HMAC-SHA3-512 context and write 64 byte MAC to destination buffer.

Parameters

[in,out]	ctx	HMAC-SHA3-512 hash context.
[out]	mac	MAC destination buffer. Must be at least 64 bytes in length.

Example:

  // key and key size, in bytes (w/o trailing NUL)
  const uint8_t key[] = "secret!"; // key
  const size_t key_len = sizeof(key) - 1; // key size
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create HMAC-SHA3-512 context
  hmac_sha3_t ctx = { 0 };
  hmac_sha3_512_init(&ctx, key, key_len);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    hmac_sha3_512_absorb(&ctx, buf + i, 32);
  }
 
  // finalize context, write result to `mac`
  uint8_t mac[64] = { 0 };
  hmac_sha3_512_final(&ctx, mac);

hmac_sha3_512_init()

void hmac_sha3_512_init	(	hmac_sha3_t *	ctx,
		const uint8_t *	key,
		const size_t	key_len
	)

Initialize HMAC-SHA3-512 (FIPS 202, Section 7) context.

Parameters

[out]	ctx	HMAC-SHA3-512 context.
[in]	key	Key.
[in]	key_len	Key length, in bytes.

Example:

  // key and key size, in bytes (w/o trailing NUL)
  const uint8_t key[] = "secret!"; // key
  const size_t key_len = sizeof(key) - 1; // key size
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create HMAC-SHA3-512 context
  hmac_sha3_t ctx = { 0 };
  hmac_sha3_512_init(&ctx, key, key_len);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    hmac_sha3_512_absorb(&ctx, buf + i, 32);
  }
 
  // finalize context, write result to `mac`
  uint8_t mac[64] = { 0 };
  hmac_sha3_512_final(&ctx, mac);