KMAC

Keccak Message Authentication Code (MAC), as defined in section 4 of SP 800-185. More...

Data Structures
struct	kmac_params_t
	KMAC configuration parameters (key and customization string). More...

Functions
void	kmac128 (const kmac_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len)
	Absorb data into KMAC128, then squeeze bytes out. More...
void	kmac256 (const kmac_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len)
	Absorb data into KMAC256, then squeeze bytes out. More...
void	kmac128_xof_init (sha3_xof_t *xof, const kmac_params_t params)
	Initialize KMAC128 XOF context. More...
_Bool	kmac128_xof_absorb (sha3_xof_t *xof, const uint8_t *src, const size_t len)
	Absorb data into KMAC128 XOF context. More...
void	kmac128_xof_squeeze (sha3_xof_t *xof, uint8_t *dst, const size_t len)
	Squeeze data from KMAC128 XOF context. More...
void	kmac128_xof_once (const kmac_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len)
	Absorb data into KMAC128 XOF context, then squeeze bytes out. More...
void	kmac256_xof_init (sha3_xof_t *xof, const kmac_params_t params)
	Initialize KMAC256 XOF context. More...
_Bool	kmac256_xof_absorb (sha3_xof_t *xof, const uint8_t *src, const size_t len)
	Absorb data into KMAC256 XOF context. More...
void	kmac256_xof_squeeze (sha3_xof_t *xof, uint8_t *dst, const size_t len)
	Squeeze data from KMAC256 XOF context. More...
void	kmac256_xof_once (const kmac_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len)
	Absorb data into KMAC256 XOF context, then squeeze bytes out. More...

Detailed Description

Keccak Message Authentication Code (MAC), as defined in section 4 of SP 800-185.

Function Documentation

kmac128()

void kmac128	(	const kmac_params_t	params,
		const uint8_t *	src,
		const size_t	src_len,
		uint8_t *	dst,
		const size_t	dst_len
	)

Absorb data into KMAC128, then squeeze bytes out.

Initialize internal KMAC128 (Keccak Message Authentication Code, as defined in section 4 of NIST SP 800-185) context with configuration parameters params, absorb data in buffer src of length src_len bytes into internal context, then squeeze dst_len bytes of output into destination buffer dst.

Parameters

[in]	params	KMAC configuration parameters.
[in]	src	Source buffer.
[in]	src_len	Source buffer length, in bytes.
[out]	dst	Destination buffer.
[in]	dst_len	Destination buffer length, in bytes.

Example:

  const uint8_t key[] = "secret!"; // secret key
  const uint8_t custom[] = "hello"; // customization string
 
  // kmac parameters
  const kmac_params_t params = {
    .key = key, // secret key
    .key_len = sizeof(custom) - 1, // key length, in bytes (w/o trailing NUL)
    .custom = custom, // customization string
    .custom_len = sizeof(custom) - 1, // customization string length, in bytes (w/o trailing NUL)
  };
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // absorb into kmac128 with fixed-length output, write 32 bytes to `out`
  uint8_t out[32] = { 0 };
  kmac128(params, buf, sizeof(buf), out, sizeof(out));

kmac128_xof_absorb()

_Bool kmac128_xof_absorb	(	sha3_xof_t *	xof,
		const uint8_t *	src,
		const size_t	len
	)

Absorb data into KMAC128 XOF context.

Absorb data in buffer src of length len bytes into KMAC128 XOF context. Can be called iteratively to absorb input data in chunks.

Parameters

[in,out]	xof	KMAC128 XOF context.
[in]	src	Source buffer.
[in]	len	Source buffer length, in bytes.

Returns

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

Example:

  const uint8_t key[] = "secret!"; // secret key
  const uint8_t custom[] = "hello"; // customization string
 
  // kmac parameters
  const kmac_params_t params = {
    .key = key, // secret key
    .key_len = sizeof(custom) - 1, // key length, in bytes (w/o trailing NUL)
    .custom = custom, // customization string
    .custom_len = sizeof(custom) - 1, // customization string length, in bytes (w/o trailing NUL)
  };
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create KMAC128 XOF context from parameters
  sha3_xof_t ctx = { 0 };
  kmac128_xof_init(&ctx, params);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    kmac128_xof_absorb(&ctx, buf + i, 32);
  }
 
  // print result prefix to stdout
  printf("%s: ", __func__);
 
  // squeeze first 128 bytes of of result in 32 byte chunks
  for (size_t i = 0; i < 128; i += 32) {
    // squeeze 32 bytes of result into `out`
    uint8_t out[32] = { 0 };
    kmac128_xof_squeeze(&ctx, out, sizeof(out));
 
    // encode as hex, print to stdout
    hex_write(stdout, out, sizeof(out));
  }
 
  // print result suffix to stdout
  fputs("\n", stdout);

kmac128_xof_init()

void kmac128_xof_init	(	sha3_xof_t *	xof,
		const kmac_params_t	params
	)

Initialize KMAC128 XOF context.

Initialize KMAC128 XOF (Keccak Message Authentication Code eXtendable Output Function, as defined in section 4.3.1 of NIST SP 800-185) context with configuration parameters params.

Note

KMAC128 and KMAC128 XOF produce different output, because KMAC128 encodes the fixed output size as part of the input while KMAC128 XOF does not. See section 4.3.1 of NIST SP 800-185 for details.

Parameters

[out]	xof	KMAC128 XOF context.
[in]	params	KMAC configuration parameters.

Example:

  const uint8_t key[] = "secret!"; // secret key
  const uint8_t custom[] = "hello"; // customization string
 
  // kmac parameters
  const kmac_params_t params = {
    .key = key, // secret key
    .key_len = sizeof(custom) - 1, // key length, in bytes (w/o trailing NUL)
    .custom = custom, // customization string
    .custom_len = sizeof(custom) - 1, // customization string length, in bytes (w/o trailing NUL)
  };
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create KMAC128 XOF context from parameters
  sha3_xof_t ctx = { 0 };
  kmac128_xof_init(&ctx, params);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    kmac128_xof_absorb(&ctx, buf + i, 32);
  }
 
  // print result prefix to stdout
  printf("%s: ", __func__);
 
  // squeeze first 128 bytes of of result in 32 byte chunks
  for (size_t i = 0; i < 128; i += 32) {
    // squeeze 32 bytes of result into `out`
    uint8_t out[32] = { 0 };
    kmac128_xof_squeeze(&ctx, out, sizeof(out));
 
    // encode as hex, print to stdout
    hex_write(stdout, out, sizeof(out));
  }
 
  // print result suffix to stdout
  fputs("\n", stdout);

kmac128_xof_once()

void kmac128_xof_once	(	const kmac_params_t	params,
		const uint8_t *	src,
		const size_t	src_len,
		uint8_t *	dst,
		const size_t	dst_len
	)

Absorb data into KMAC128 XOF context, then squeeze bytes out.

Initialize internal KMAC128 XOF (Keccak Message Authentication Code eXtendable Output Function, as defined in section 4 of NIST SP 800-185) context with configuration parameters params, absorb data in buffer src of length src_len bytes into internal context, then squeeze dst_len bytes of output into destination buffer dst.

Note

KMAC128 and KMAC128 XOF produce different output, because KMAC128 encodes the fixed output size as part of the input while KMAC128 XOF does not. See section 4.3.1 of NIST SP 800-185 for details.

Parameters

[in]	params	KMAC configuration parameters.
[in]	src	Source buffer.
[in]	src_len	Source buffer length, in bytes.
[out]	dst	Destination buffer.
[in]	dst_len	Destination buffer length, in bytes.

Example:

  const uint8_t key[] = "secret!"; // secret key
  const uint8_t custom[] = "hello"; // customization string
 
  // kmac parameters
  const kmac_params_t params = {
    .key = key, // secret key
    .key_len = sizeof(custom) - 1, // key length, in bytes (w/o trailing NUL)
    .custom = custom, // customization string
    .custom_len = sizeof(custom) - 1, // customization string length, in bytes (w/o trailing NUL)
  };
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // absorb into KMAC256 XOF, squeeze into `out`
  uint8_t out[128] = { 0 }; // output buffer
  kmac256_xof_once(params, buf, sizeof(buf), out, sizeof(out));

kmac128_xof_squeeze()

void kmac128_xof_squeeze	(	sha3_xof_t *	xof,
		uint8_t *	dst,
		const size_t	len
	)

Squeeze data from KMAC128 XOF context.

Squeeze len bytes of output into destination buffer dst from KMAC128 XOF context xof. Can be called iteratively to squeeze output data in chunks.

Note

KMAC128 and KMAC128 XOF produce different output, because KMAC128 encodes the fixed output size as part of the input while KMAC128 XOF does not. See section 4.3.1 of NIST SP 800-185 for details.

Parameters

[in,out]	xof	KMAC128 XOF context.
[out]	dst	Destination buffer.
[in]	len	Destination buffer length, in bytes.

Example:

  const uint8_t key[] = "secret!"; // secret key
  const uint8_t custom[] = "hello"; // customization string
 
  // kmac parameters
  const kmac_params_t params = {
    .key = key, // secret key
    .key_len = sizeof(custom) - 1, // key length, in bytes (w/o trailing NUL)
    .custom = custom, // customization string
    .custom_len = sizeof(custom) - 1, // customization string length, in bytes (w/o trailing NUL)
  };
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create KMAC128 XOF context from parameters
  sha3_xof_t ctx = { 0 };
  kmac128_xof_init(&ctx, params);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    kmac128_xof_absorb(&ctx, buf + i, 32);
  }
 
  // print result prefix to stdout
  printf("%s: ", __func__);
 
  // squeeze first 128 bytes of of result in 32 byte chunks
  for (size_t i = 0; i < 128; i += 32) {
    // squeeze 32 bytes of result into `out`
    uint8_t out[32] = { 0 };
    kmac128_xof_squeeze(&ctx, out, sizeof(out));
 
    // encode as hex, print to stdout
    hex_write(stdout, out, sizeof(out));
  }
 
  // print result suffix to stdout
  fputs("\n", stdout);

kmac256()

void kmac256	(	const kmac_params_t	params,
		const uint8_t *	src,
		const size_t	src_len,
		uint8_t *	dst,
		const size_t	dst_len
	)

Absorb data into KMAC256, then squeeze bytes out.

Initialize internal KMAC256 (Keccak Message Authentication Code, as defined in section 4 of NIST SP 800-185) context with configuration parameters params, absorb data in buffer src of length src_len bytes into internal context, then squeeze dst_len bytes of output into destination buffer dst.

Parameters

[in]	params	KMAC configuration parameters.
[in]	src	Source buffer.
[in]	src_len	Source buffer length, in bytes.
[out]	dst	Destination buffer.
[in]	dst_len	Destination buffer length, in bytes.

Example:

  const uint8_t key[] = "secret!"; // secret key
  const uint8_t custom[] = "hello"; // customization string
 
  // kmac parameters
  const kmac_params_t params = {
    .key = key, // secret key
    .key_len = sizeof(custom) - 1, // key length, in bytes (w/o trailing NUL)
    .custom = custom, // customization string
    .custom_len = sizeof(custom) - 1, // customization string length, in bytes (w/o trailing NUL)
  };
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // absorb into KMAC256 with fixed-length output, write 32 bytes to `out`
  uint8_t out[32] = { 0 };
  kmac256(params, buf, sizeof(buf), out, sizeof(out));

kmac256_xof_absorb()

_Bool kmac256_xof_absorb	(	sha3_xof_t *	xof,
		const uint8_t *	src,
		const size_t	len
	)

Absorb data into KMAC256 XOF context.

Absorb data in buffer src of length len bytes into KMAC256 XOF context. Can be called iteratively to absorb input data in chunks.

Parameters

[in,out]	xof	KMAC256 XOF context.
[in]	src	Source buffer.
[in]	len	Source buffer length, in bytes.

Returns

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

Example:

  const uint8_t key[] = "secret!"; // secret key
  const uint8_t custom[] = "hello"; // customization string
 
  // kmac parameters
  const kmac_params_t params = {
    .key = key, // secret key
    .key_len = sizeof(custom) - 1, // key length, in bytes (w/o trailing NUL)
    .custom = custom, // customization string
    .custom_len = sizeof(custom) - 1, // customization string length, in bytes (w/o trailing NUL)
  };
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create KMAC256 XOF context from parameters
  sha3_xof_t ctx = { 0 };
  kmac256_xof_init(&ctx, params);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    kmac256_xof_absorb(&ctx, buf + i, 32);
  }
 
  // print result prefix to stdout
  printf("%s: ", __func__);
 
  // squeeze first 128 bytes of of result in 32 byte chunks
  for (size_t i = 0; i < 128; i += 32) {
    // squeeze 32 bytes of result into `out`
    uint8_t out[32] = { 0 };
    kmac256_xof_squeeze(&ctx, out, sizeof(out));
 
    // encode as hex, print to stdout
    hex_write(stdout, out, sizeof(out));
  }
 
  // print result suffix to stdout
  fputs("\n", stdout);

kmac256_xof_init()

void kmac256_xof_init	(	sha3_xof_t *	xof,
		const kmac_params_t	params
	)

Initialize KMAC256 XOF context.

Initialize KMAC256 XOF (Keccak Message Authentication Code eXtendable Output Function, as defined in section 4.3.1 of NIST SP 800-185) context with configuration parameters params.

Note

KMAC256 and KMAC256 XOF produce different output, because KMAC256 encodes the fixed output size as part of the input while KMAC256 XOF does not. See section 4.3.1 of NIST SP 800-185 for details.

Parameters

[out]	xof	KMAC256 XOF context.
[in]	params	KMAC configuration parameters.

Example:

  const uint8_t key[] = "secret!"; // secret key
  const uint8_t custom[] = "hello"; // customization string
 
  // kmac parameters
  const kmac_params_t params = {
    .key = key, // secret key
    .key_len = sizeof(custom) - 1, // key length, in bytes (w/o trailing NUL)
    .custom = custom, // customization string
    .custom_len = sizeof(custom) - 1, // customization string length, in bytes (w/o trailing NUL)
  };
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create KMAC256 XOF context from parameters
  sha3_xof_t ctx = { 0 };
  kmac256_xof_init(&ctx, params);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    kmac256_xof_absorb(&ctx, buf + i, 32);
  }
 
  // print result prefix to stdout
  printf("%s: ", __func__);
 
  // squeeze first 128 bytes of of result in 32 byte chunks
  for (size_t i = 0; i < 128; i += 32) {
    // squeeze 32 bytes of result into `out`
    uint8_t out[32] = { 0 };
    kmac256_xof_squeeze(&ctx, out, sizeof(out));
 
    // encode as hex, print to stdout
    hex_write(stdout, out, sizeof(out));
  }
 
  // print result suffix to stdout
  fputs("\n", stdout);

kmac256_xof_once()

void kmac256_xof_once	(	const kmac_params_t	params,
		const uint8_t *	src,
		const size_t	src_len,
		uint8_t *	dst,
		const size_t	dst_len
	)

Absorb data into KMAC256 XOF context, then squeeze bytes out.

Initialize internal KMAC256 XOF (Keccak Message Authentication Code eXtendable Output Function, as defined in section 4 of NIST SP 800-185) context with configuration parameters params, absorb data in buffer src of length src_len bytes into internal context, then squeeze dst_len bytes of output into destination buffer dst.

Note

KMAC256 and KMAC256 XOF produce different output, because KMAC256 encodes the fixed output size as part of the input while KMAC256 XOF does not. See section 4.3.1 of NIST SP 800-185 for details.

Parameters

[in]	params	KMAC configuration parameters.
[in]	src	Source buffer.
[in]	src_len	Source buffer length, in bytes.
[out]	dst	Destination buffer.
[in]	dst_len	Destination buffer length, in bytes.

Example:

  const uint8_t key[] = "secret!"; // secret key
  const uint8_t custom[] = "hello"; // customization string
 
  // kmac parameters
  const kmac_params_t params = {
    .key = key, // secret key
    .key_len = sizeof(custom) - 1, // key length, in bytes (w/o trailing NUL)
    .custom = custom, // customization string
    .custom_len = sizeof(custom) - 1, // customization string length, in bytes (w/o trailing NUL)
  };
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // absorb into KMAC256 XOF, squeeze into `out`
  uint8_t out[128] = { 0 }; // output buffer
  kmac256_xof_once(params, buf, sizeof(buf), out, sizeof(out));

kmac256_xof_squeeze()

void kmac256_xof_squeeze	(	sha3_xof_t *	xof,
		uint8_t *	dst,
		const size_t	len
	)

Squeeze data from KMAC256 XOF context.

Squeeze len bytes of output into destination buffer dst from KMAC256 XOF context xof. Can be called iteratively to squeeze output data in chunks.

Note

KMAC256 and KMAC256 XOF produce different output, because KMAC256 encodes the fixed output size as part of the input while KMAC256 XOF does not. See section 4.3.1 of NIST SP 800-185 for details.

Parameters

[in,out]	xof	KMAC256 XOF context.
[out]	dst	Destination buffer.
[in]	len	Destination buffer length, in bytes.

Example:

  const uint8_t key[] = "secret!"; // secret key
  const uint8_t custom[] = "hello"; // customization string
 
  // kmac parameters
  const kmac_params_t params = {
    .key = key, // secret key
    .key_len = sizeof(custom) - 1, // key length, in bytes (w/o trailing NUL)
    .custom = custom, // customization string
    .custom_len = sizeof(custom) - 1, // customization string length, in bytes (w/o trailing NUL)
  };
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create KMAC256 XOF context from parameters
  sha3_xof_t ctx = { 0 };
  kmac256_xof_init(&ctx, params);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    kmac256_xof_absorb(&ctx, buf + i, 32);
  }
 
  // print result prefix to stdout
  printf("%s: ", __func__);
 
  // squeeze first 128 bytes of of result in 32 byte chunks
  for (size_t i = 0; i < 128; i += 32) {
    // squeeze 32 bytes of result into `out`
    uint8_t out[32] = { 0 };
    kmac256_xof_squeeze(&ctx, out, sizeof(out));
 
    // encode as hex, print to stdout
    hex_write(stdout, out, sizeof(out));
  }
 
  // print result suffix to stdout
  fputs("\n", stdout);