TupleHash

Misuse-resistant cryptographic hash function and XOF for hashing a tuple of byte strings, as defined in section 5 of SP 800-185. More...

Data Structures
struct	tuplehash_str_t
	Individual element of TupleHash tuple. More...
struct	tuplehash_params_t
	TupleHash configuration parameters. More...

Functions
void	tuplehash128 (const tuplehash_params_t params, uint8_t *dst, const size_t len)
	Absorb tuple and customization string into TupleHash128, then squeeze bytes out. More...
void	tuplehash256 (const tuplehash_params_t params, uint8_t *dst, const size_t len)
	Absorb tuple and customization string into TupleHash256, then squeeze bytes out. More...
void	tuplehash128_xof_init (sha3_xof_t *xof, const tuplehash_params_t params)
	Initialize a TupleHash128 XOF context. More...
void	tuplehash128_xof_squeeze (sha3_xof_t *xof, uint8_t *dst, const size_t len)
	Squeeze data from TupleHash128 XOF context. More...
void	tuplehash128_xof_once (const tuplehash_params_t params, uint8_t *dst, const size_t len)
	Absorb data into TupleHash128 XOF, then squeeze bytes out. More...
void	tuplehash256_xof_init (sha3_xof_t *xof, const tuplehash_params_t params)
	Initialize a TupleHash256 XOF context. More...
void	tuplehash256_xof_squeeze (sha3_xof_t *xof, uint8_t *dst, const size_t len)
	Squeeze bytes from a TupleHash256 XOF context. More...
void	tuplehash256_xof_once (const tuplehash_params_t params, uint8_t *dst, const size_t len)
	Absorb data into TupleHash256 XOF, then squeeze bytes out. More...

Detailed Description

Misuse-resistant cryptographic hash function and XOF for hashing a tuple of byte strings, as defined in section 5 of SP 800-185.

Function Documentation

tuplehash128()

void tuplehash128	(	const tuplehash_params_t	params,
		uint8_t *	dst,
		const size_t	len
	)

Absorb tuple and customization string into TupleHash128, then squeeze bytes out.

Initialize internal TupleHash128 (NIST SP 800-185, section 5) context with configuration parameters params, then squeeze len bytes of output from internal context into destination buffer dst.

Parameters

[in]	params	TupleHash128 configuration parameters.
[out]	dst	Destination buffer.
[in]	len	Destination buffer length, in bytes.

Example:

  // byte strings
  const tuplehash_str_t strs[] = {
    { .ptr = (uint8_t*) "foo", .len = 3 },
    { .ptr = (uint8_t*) "bar", .len = 3 },
    { .ptr = (uint8_t*) "blum", .len = 4 },
  };
  const uint8_t custom[] = "hello"; // customization string
 
  // tuplehash parameters
  const tuplehash_params_t params = {
    .strs = strs, // array of byte strings
    .num_strs = sizeof(strs) / sizeof(strs[0]), // byte string count
    .custom = custom, // customization string
    .custom_len = sizeof(custom) - 1, // customization string length, in bytes (w/o trailing NUL)
  };
 
  // absorb into TupleHash128 with fixed-length output, write 32 bytes to `out`
  uint8_t out[32] = { 0 };
  tuplehash128(params, out, sizeof(out));

tuplehash128_xof_init()

void tuplehash128_xof_init	(	sha3_xof_t *	xof,
		const tuplehash_params_t	params
	)

Initialize a TupleHash128 XOF context.

Initialize TupleHash128 XOF (TupleHash eXtendable Output Function, as defined in section 5.3.1 of NIST SP 800-185) context with configuration parameters params.

Note

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

Parameters

[out]	xof	TupleHash128 XOF context.
[in]	params	TupleHash configuration parameters.

Example:

  // byte strings
  const tuplehash_str_t strs[] = {
    { .ptr = (uint8_t*) "foo", .len = 3 },
    { .ptr = (uint8_t*) "bar", .len = 3 },
    { .ptr = (uint8_t*) "blum", .len = 4 },
  };
  const uint8_t custom[] = "hello"; // customization string
 
  // tuplehash parameters
  const tuplehash_params_t params = {
    .strs = strs, // array of byte strings
    .num_strs = sizeof(strs) / sizeof(strs[0]), // byte string count
    .custom = custom, // customization string
    .custom_len = sizeof(custom) - 1, // customization string length, in bytes (w/o trailing NUL)
  };
 
  // create TupleHash128 XOF context from parameters
  sha3_xof_t ctx = { 0 };
  tuplehash128_xof_init(&ctx, params);
 
  // 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 };
    tuplehash128_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);

tuplehash128_xof_once()

void tuplehash128_xof_once	(	const tuplehash_params_t	params,
		uint8_t *	dst,
		const size_t	len
	)

Absorb data into TupleHash128 XOF, then squeeze bytes out.

Initialize internal TupleHash128 XOF (TupleHash eXtendable Output Function, as defined in section 5 of NIST SP 800-185) context with configuration parameters params, then squeeze len bytes of output into destination buffer dst.

Note

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

Parameters

[in]	params	TupleHash128 configuration parameters.
[out]	dst	Destination buffer.
[in]	len	Destination buffer length, in bytes.

Example:

  // byte strings
  const tuplehash_str_t strs[] = {
    { .ptr = (uint8_t*) "foo", .len = 3 },
    { .ptr = (uint8_t*) "bar", .len = 3 },
    { .ptr = (uint8_t*) "blum", .len = 4 },
  };
  const uint8_t custom[] = "hello"; // customization string
 
  // tuplehash parameters
  const tuplehash_params_t params = {
    .strs = strs, // array of byte strings
    .num_strs = sizeof(strs) / sizeof(strs[0]), // byte string count
    .custom = custom, // customization string
    .custom_len = sizeof(custom) - 1, // customization string length, in bytes (w/o trailing NUL)
  };
 
  // absorb into TupleHash128 XOF, squeeze into `out`
  uint8_t out[128] = { 0 }; // output buffer
  tuplehash128_xof_once(params, out, sizeof(out));

tuplehash128_xof_squeeze()

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

Squeeze data from TupleHash128 XOF context.

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

Note

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

Parameters

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

Example:

  // byte strings
  const tuplehash_str_t strs[] = {
    { .ptr = (uint8_t*) "foo", .len = 3 },
    { .ptr = (uint8_t*) "bar", .len = 3 },
    { .ptr = (uint8_t*) "blum", .len = 4 },
  };
  const uint8_t custom[] = "hello"; // customization string
 
  // tuplehash parameters
  const tuplehash_params_t params = {
    .strs = strs, // array of byte strings
    .num_strs = sizeof(strs) / sizeof(strs[0]), // byte string count
    .custom = custom, // customization string
    .custom_len = sizeof(custom) - 1, // customization string length, in bytes (w/o trailing NUL)
  };
 
  // create TupleHash128 XOF context from parameters
  sha3_xof_t ctx = { 0 };
  tuplehash128_xof_init(&ctx, params);
 
  // 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 };
    tuplehash128_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);

tuplehash256()

void tuplehash256	(	const tuplehash_params_t	params,
		uint8_t *	dst,
		const size_t	len
	)

Absorb tuple and customization string into TupleHash256, then squeeze bytes out.

Initialize internal TupleHash256 (NIST SP 800-185, section 5) context with configuration parameters params, then squeeze len bytes of output from internal context into destination buffer dst.

Parameters

[in]	params	TupleHash256 configuration parameters.
[out]	dst	Destination buffer.
[in]	len	Destination buffer length, in bytes.

Example:

  // byte strings
  const tuplehash_str_t strs[] = {
    { .ptr = (uint8_t*) "foo", .len = 3 },
    { .ptr = (uint8_t*) "bar", .len = 3 },
    { .ptr = (uint8_t*) "blum", .len = 4 },
  };
  const uint8_t custom[] = "hello"; // customization string
 
  // tuplehash parameters
  const tuplehash_params_t params = {
    .strs = strs, // array of byte strings
    .num_strs = sizeof(strs) / sizeof(strs[0]), // byte string count
    .custom = custom, // customization string
    .custom_len = sizeof(custom) - 1, // customization string length, in bytes (w/o trailing NUL)
  };
 
  // absorb into TupleHash256 with fixed-length output, write 32 bytes to `out`
  uint8_t out[32] = { 0 };
  tuplehash256(params, out, sizeof(out));

tuplehash256_xof_init()

void tuplehash256_xof_init	(	sha3_xof_t *	xof,
		const tuplehash_params_t	params
	)

Initialize a TupleHash256 XOF context.

Initialize TupleHash256 XOF (TupleHash eXtendable Output Function, as defined in section 5.3.1 of NIST SP 800-185) context with configuration parameters params.

Note

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

Parameters

[out]	xof	TupleHash256 XOF context.
[in]	params	TupleHash configuration parameters.

Example:

  // byte strings
  const tuplehash_str_t strs[] = {
    { .ptr = (uint8_t*) "foo", .len = 3 },
    { .ptr = (uint8_t*) "bar", .len = 3 },
    { .ptr = (uint8_t*) "blum", .len = 4 },
  };
  const uint8_t custom[] = "hello"; // customization string
 
  // tuplehash parameters
  const tuplehash_params_t params = {
    .strs = strs, // array of byte strings
    .num_strs = sizeof(strs) / sizeof(strs[0]), // byte string count
    .custom = custom, // customization string
    .custom_len = sizeof(custom) - 1, // customization string length, in bytes (w/o trailing NUL)
  };
 
  // create TupleHash256 XOF context from parameters
  sha3_xof_t ctx = { 0 };
  tuplehash256_xof_init(&ctx, params);
 
  // 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 };
    tuplehash256_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);

tuplehash256_xof_once()

void tuplehash256_xof_once	(	const tuplehash_params_t	params,
		uint8_t *	dst,
		const size_t	len
	)

Absorb data into TupleHash256 XOF, then squeeze bytes out.

Initialize internal TupleHash256 XOF (TupleHash eXtendable Output Function, as defined in section 5 of NIST SP 800-185) context with configuration parameters params, then squeeze len bytes of output into destination buffer dst.

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

Parameters

[in]	params	TupleHash256 configuration parameters.
[out]	dst	Destination buffer.
[in]	len	Destination buffer length, in bytes.

Example:

  // byte strings
  const tuplehash_str_t strs[] = {
    { .ptr = (uint8_t*) "foo", .len = 3 },
    { .ptr = (uint8_t*) "bar", .len = 3 },
    { .ptr = (uint8_t*) "blum", .len = 4 },
  };
  const uint8_t custom[] = "hello"; // customization string
 
  // tuplehash parameters
  const tuplehash_params_t params = {
    .strs = strs, // array of byte strings
    .num_strs = sizeof(strs) / sizeof(strs[0]), // byte string count
    .custom = custom, // customization string
    .custom_len = sizeof(custom) - 1, // customization string length, in bytes (w/o trailing NUL)
  };
 
  // absorb into TupleHash256 XOF, squeeze into `out`
  uint8_t out[128] = { 0 }; // output buffer
  tuplehash256_xof_once(params, out, sizeof(out));

tuplehash256_xof_squeeze()

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

Squeeze bytes from a TupleHash256 XOF context.

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

Note

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

Parameters

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

Example:

  // byte strings
  const tuplehash_str_t strs[] = {
    { .ptr = (uint8_t*) "foo", .len = 3 },
    { .ptr = (uint8_t*) "bar", .len = 3 },
    { .ptr = (uint8_t*) "blum", .len = 4 },
  };
  const uint8_t custom[] = "hello"; // customization string
 
  // tuplehash parameters
  const tuplehash_params_t params = {
    .strs = strs, // array of byte strings
    .num_strs = sizeof(strs) / sizeof(strs[0]), // byte string count
    .custom = custom, // customization string
    .custom_len = sizeof(custom) - 1, // customization string length, in bytes (w/o trailing NUL)
  };
 
  // create TupleHash256 XOF context from parameters
  sha3_xof_t ctx = { 0 };
  tuplehash256_xof_init(&ctx, params);
 
  // 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 };
    tuplehash256_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);