TurboSHAKE

Faster, reduced-round XOFs, as defined in the draft KangarooTwelve and TurboSHAKE specification. More...

Data Structures
struct	sha3_xof12_t
	Iterative XOF context (all members are private) for XOFs with 12 round permutations. More...
struct	turboshake_t
	TurboShake XOF context (all members are private). More...

Functions
void	turboshake128 (const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len)
	Absorb bytes into TurboSHAKE128 XOF, then squeeze bytes out. More...
void	turboshake128_custom (const uint8_t pad, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len)
	Absorb bytes into TurboSHAKE128 XOF with custom padding byte, then squeeze bytes out. More...
void	turboshake256 (const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len)
	Absorb bytes into TurboSHAKE256 XOF, then squeeze bytes out. More...
void	turboshake256_custom (const uint8_t pad, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len)
	Absorb bytes into TurboSHAKE256 XOF with custom padding byte, then squeeze bytes out. More...
void	turboshake128_init (turboshake_t *ts)
	Initialize TurboSHAKE128 XOF context. More...
_Bool	turboshake128_init_custom (turboshake_t *ts, const uint8_t pad)
	Initialize TurboSHAKE128 XOF context with custom padding byte. More...
_Bool	turboshake128_absorb (turboshake_t *ts, const uint8_t *src, const size_t len)
	Absorb data into TurboSHAKE128 XOF context. More...
void	turboshake128_squeeze (turboshake_t *ts, uint8_t *dst, const size_t len)
	Squeeze bytes from TurboSHAKE128 XOF context. More...
void	turboshake256_init (turboshake_t *ts)
	Initialize TurboSHAKE256 XOF context. More...
_Bool	turboshake256_init_custom (turboshake_t *ts, const uint8_t pad)
	Initialize TurboSHAKE256 XOF context with custom padding byte. More...
_Bool	turboshake256_absorb (turboshake_t *ts, const uint8_t *src, const size_t len)
	Absorb data into TurboSHAKE256 XOF context. More...
void	turboshake256_squeeze (turboshake_t *ts, uint8_t *dst, const size_t len)
	Squeeze bytes from TurboSHAKE256 XOF context. More...

Detailed Description

Faster, reduced-round XOFs, as defined in the draft KangarooTwelve and TurboSHAKE specification.

Function Documentation

turboshake128()

void turboshake128	(	const uint8_t *	src,
		const size_t	src_len,
		uint8_t *	dst,
		const size_t	dst_len
	)

Absorb bytes into TurboSHAKE128 XOF, then squeeze bytes out.

Initialize internal TurboSHAKE128 XOF context, absorb src_len bytes of input from source buffer src, then squeeze dst_len bytes of output into destination buffer dst.

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:

  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // absorb into TurboSHAKE128 with fixed-length output, write 32 bytes to `out`
  uint8_t out[32] = { 0 };
  turboshake128(buf, sizeof(buf), out, sizeof(out));

turboshake128_absorb()

_Bool turboshake128_absorb	(	turboshake_t *	ts,
		const uint8_t *	src,
		const size_t	len
	)

Absorb data into TurboSHAKE128 XOF context.

Absorb src_len bytes of input from source buffer src into TurboSHAKE128 XOF context ts. Can be called iteratively to absorb input data in chunks.

Parameters

[in,out]	ts	TurboSHAKE128 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 finalized).

Example:

  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create TurboSHAKE128 XOF context which supports arbitrary-length
  // output
  turboshake_t ctx = { 0 };
  turboshake128_init(&ctx);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    turboshake128_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 };
    turboshake128_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);

turboshake128_custom()

void turboshake128_custom	(	const uint8_t	pad,
		const uint8_t *	src,
		const size_t	src_len,
		uint8_t *	dst,
		const size_t	dst_len
	)

Absorb bytes into TurboSHAKE128 XOF with custom padding byte, then squeeze bytes out.

Initialize internal TurboSHAKE128 XOF context with custom padding byte pad, absorb src_len bytes of input from source buffer src, then squeeze dst_len bytes of output into destination buffer dst.

Note

The padding byte value must be in the range [0x01, 0x7F] and can be used for domain separation.

Parameters

[in]	pad	Padding byte.
[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 pad = 3; // custom padding byte
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // absorb into TurboSHAKE128 with fixed-length output, write 32 bytes to `out`
  uint8_t out[32] = { 0 };
  turboshake128_custom(pad, buf, sizeof(buf), out, sizeof(out));

turboshake128_init()

void turboshake128_init

(

turboshake_t *

ts

)

Initialize TurboSHAKE128 XOF context.

Parameters

[out]

ts

TurboSHAKE128 XOF context.

Example:

  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create TurboSHAKE128 XOF context which supports arbitrary-length
  // output
  turboshake_t ctx = { 0 };
  turboshake128_init(&ctx);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    turboshake128_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 };
    turboshake128_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);

turboshake128_init_custom()

_Bool turboshake128_init_custom	(	turboshake_t *	ts,
		const uint8_t	pad
	)

Initialize TurboSHAKE128 XOF context with custom padding byte.

Initialize TurboSHAKE128 XOF context with custom padding byte. The custom padding byte can be used as a domain separator and must be in the range [0x01, 0x7f].

Parameters

[out]	ts	TurboSHAKE128 XOF context.
[in]	pad	Padding byte (used for domain separation).

Returns

False if the padding byte is out of range and true otherwise.

Example:

  const uint8_t pad = 3; // custom padding byte
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create TurboSHAKE128 XOF context with custom padding byte which
  // supports arbitrary-length output
  turboshake_t ctx = { 0 };
  turboshake128_init_custom(&ctx, pad);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    turboshake128_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 };
    turboshake128_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);

turboshake128_squeeze()

void turboshake128_squeeze	(	turboshake_t *	ts,
		uint8_t *	dst,
		const size_t	len
	)

Squeeze bytes from TurboSHAKE128 XOF context.

Squeeze dst_len bytes of output into destination buffer dst from TurboSHAKE128 XOF context ts. Can be called iteratively to squeeze output data in chunks.

Parameters

[in,out]	ts	TurboSHAKE128 XOF context.
[out]	dst	Destination buffer.
[in]	len	Destination buffer length, in bytes.

Example:

  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create TurboSHAKE128 XOF context which supports arbitrary-length
  // output
  turboshake_t ctx = { 0 };
  turboshake128_init(&ctx);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    turboshake128_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 };
    turboshake128_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);

turboshake256()

void turboshake256	(	const uint8_t *	src,
		const size_t	src_len,
		uint8_t *	dst,
		const size_t	dst_len
	)

Absorb bytes into TurboSHAKE256 XOF, then squeeze bytes out.

Initialize internal TurboSHAKE256 XOF context, absorb src_len bytes of input from source buffer src, then squeeze dst_len bytes of output into destination buffer dst.

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:

  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // absorb into TurboSHAKE256 with fixed-length output, write 32 bytes to `out`
  uint8_t out[32] = { 0 };
  turboshake256(buf, sizeof(buf), out, sizeof(out));

turboshake256_absorb()

_Bool turboshake256_absorb	(	turboshake_t *	ts,
		const uint8_t *	src,
		const size_t	len
	)

Absorb data into TurboSHAKE256 XOF context.

Absorb len bytes of input from source buffer src into TurboSHAKE256 XOF context ts. Can be called iteratively to absorb input data in chunks.

Parameters

[in,out]	ts	TurboSHAKE256 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 finalized).

Example:

  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create TurboSHAKE256 XOF context which supports arbitrary-length
  // output
  turboshake_t ctx = { 0 };
  turboshake256_init(&ctx);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    turboshake256_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 };
    turboshake256_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);

turboshake256_custom()

void turboshake256_custom	(	const uint8_t	pad,
		const uint8_t *	src,
		const size_t	src_len,
		uint8_t *	dst,
		const size_t	dst_len
	)

Absorb bytes into TurboSHAKE256 XOF with custom padding byte, then squeeze bytes out.

Initialize internal TurboSHAKE256 XOF context with custom padding byte pad, absorb src_len bytes of input from source buffer src, then squeeze dst_len bytes of output into destination buffer dst.

Note

The padding byte value must be in the range [0x01, 0x7F] and can be used for domain separation.

Parameters

[in]	pad	Padding byte.
[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 pad = 3; // custom padding byte
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // absorb into TurboSHAKE256 with fixed-length output, write 32 bytes to `out`
  uint8_t out[32] = { 0 };
  turboshake256_custom(pad, buf, sizeof(buf), out, sizeof(out));

turboshake256_init()

void turboshake256_init

(

turboshake_t *

ts

)

Initialize TurboSHAKE256 XOF context.

Parameters

[out]

ts

TurboSHAKE256 XOF context.

Example:

  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create TurboSHAKE256 XOF context which supports arbitrary-length
  // output
  turboshake_t ctx = { 0 };
  turboshake256_init(&ctx);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    turboshake256_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 };
    turboshake256_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);

turboshake256_init_custom()

_Bool turboshake256_init_custom	(	turboshake_t *	ts,
		const uint8_t	pad
	)

Initialize TurboSHAKE256 XOF context with custom padding byte.

Initialize TurboSHAKE256 XOF context with custom padding byte. The custom padding byte can be used as a domain separator and must be in the range [0x01, 0x7f].

Parameters

[out]	ts	TurboSHAKE256 XOF context.
[in]	pad	Padding byte (used for domain separation).

Returns

False if the padding byte is out of range and true otherwise.

Example:

  const uint8_t pad = 3; // custom padding byte
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create TurboSHAKE256 XOF context with custom padding byte which
  // supports arbitrary-length output
  turboshake_t ctx = { 0 };
  turboshake256_init_custom(&ctx, pad);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    turboshake256_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 };
    turboshake256_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);

turboshake256_squeeze()

void turboshake256_squeeze	(	turboshake_t *	ts,
		uint8_t *	dst,
		const size_t	len
	)

Squeeze bytes from TurboSHAKE256 XOF context.

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

Parameters

[in,out]	ts	TurboSHAKE256 XOF context.
[out]	dst	Destination buffer.
[in]	len	Destination buffer length, in bytes.

Example:

  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // create TurboSHAKE256 XOF context which supports arbitrary-length
  // output
  turboshake_t ctx = { 0 };
  turboshake256_init(&ctx);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    turboshake256_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 };
    turboshake256_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);