cSHAKE

Customizable SHAKE (cSHAKE) extendable-output function (XOF), as defined in section 3 of SP 800-185. More...

Data Structures
struct	cshake_params_t
	cSHAKE parameters. More...

Functions
void	cshake128 (const cshake_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len)
	Initialize cSHAKE128, absorb data, then squeeze bytes out. More...
void	cshake256 (const cshake_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len)
	Initialize cSHAKE256, absorb data, then squeeze bytes out. More...
void	cshake128_xof_init (sha3_xof_t *xof, const cshake_params_t params)
	Initialize cSHAKE128 XOF context. More...
_Bool	cshake128_xof_absorb (sha3_xof_t *xof, const uint8_t *src, const size_t len)
	Absorb data into cSHAKE128 XOF context. More...
void	cshake128_xof_squeeze (sha3_xof_t *xof, uint8_t *dst, const size_t len)
	Squeeze bytes from cSHAKE128 XOF context. More...
void	cshake256_xof_init (sha3_xof_t *xof, const cshake_params_t params)
	Initialize cSHAKE256 XOF context. More...
_Bool	cshake256_xof_absorb (sha3_xof_t *xof, const uint8_t *src, const size_t len)
	Absorb data into cSHAKE256 XOF context. More...
void	cshake256_xof_squeeze (sha3_xof_t *xof, uint8_t *dst, const size_t len)
	Squeeze bytes from cSHAKE256 XOF context. More...

Detailed Description

Customizable SHAKE (cSHAKE) extendable-output function (XOF), as defined in section 3 of SP 800-185.

Function Documentation

cshake128()

void cshake128	(	const cshake_params_t	params,
		const uint8_t *	src,
		const size_t	src_len,
		uint8_t *	dst,
		const size_t	dst_len
	)

Initialize cSHAKE128, absorb data, then squeeze bytes out.

Initialize internal cSHAKE128 (customizable SHAKE128, as defined in section 3 of NIST SP 800-185) context with customization 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

cSHAKE is used to implement the extendable output functions (XOFs) defined in NIST SP 800-185 and should generally not be used directly.

Parameters

[in]	params	cSHAKE customization 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 custom[] = "hello"; // customization string
 
  // cSHAKE parameters
  const cshake_params_t params = {
    .custom = custom,
    .custom_len = sizeof(custom) - 1, // length, in bytes (w/o trailing NUL)
  };
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // absorb into cSHAKE128 with fixed-length output, write 32 bytes to `out`
  uint8_t out[32] = { 0 };
  cshake128(params, buf, sizeof(buf), out, sizeof(out));

cshake128_xof_absorb()

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

Absorb data into cSHAKE128 XOF context.

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

Note

cSHAKE is used to implement the extendable output functions (XOFs) defined in NIST SP 800-185 and should generally not be used directly.

Parameters

[in,out]	xof	cSHAKE128 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 custom[] = "hello"; // customization string
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // cSHAKE parameters
  const cshake_params_t params = {
    .custom = custom,
    .custom_len = sizeof(custom) - 1, // length, in bytes (w/o trailing NUL)
  };
 
  // create cSHAKE128 context from parameters
  sha3_xof_t ctx = { 0 };
  cshake128_xof_init(&ctx, params);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    cshake128_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 };
    cshake128_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);

cshake128_xof_init()

void cshake128_xof_init	(	sha3_xof_t *	xof,
		const cshake_params_t	params
	)

Initialize cSHAKE128 XOF context.

Initialize cSHAKE128 (customizable SHAKE128, as defined in section 3 of NIST SP 800-185) XOF context with customization parameters params.

Note

cSHAKE is used to implement the extendable output functions (XOFs) defined in NIST SP 800-185 and should generally not be used directly.

Parameters

[out]	xof	cSHAKE128 XOF context.
[in]	params	cSHAKE128 customization parameters.

Example:

  const uint8_t custom[] = "hello"; // customization string
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // cSHAKE parameters
  const cshake_params_t params = {
    .custom = custom,
    .custom_len = sizeof(custom) - 1, // length, in bytes (w/o trailing NUL)
  };
 
  // create cSHAKE128 context from parameters
  sha3_xof_t ctx = { 0 };
  cshake128_xof_init(&ctx, params);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    cshake128_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 };
    cshake128_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);

cshake128_xof_squeeze()

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

Squeeze bytes from cSHAKE128 XOF context.

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

Note

cSHAKE is used to implement the extendable output functions (XOFs) defined in NIST SP 800-185 and should generally not be used directly.

Parameters

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

Example:

  const uint8_t custom[] = "hello"; // customization string
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // cSHAKE parameters
  const cshake_params_t params = {
    .custom = custom,
    .custom_len = sizeof(custom) - 1, // length, in bytes (w/o trailing NUL)
  };
 
  // create cSHAKE128 context from parameters
  sha3_xof_t ctx = { 0 };
  cshake128_xof_init(&ctx, params);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    cshake128_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 };
    cshake128_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);

cshake256()

void cshake256	(	const cshake_params_t	params,
		const uint8_t *	src,
		const size_t	src_len,
		uint8_t *	dst,
		const size_t	dst_len
	)

Initialize cSHAKE256, absorb data, then squeeze bytes out.

Initialize internal cSHAKE256 (customizable SHAKE256, as defined in section 3 of NIST SP 800-185) context with customization 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

cSHAKE is used to implement the extendable output functions (XOFs) defined in NIST SP 800-185 and should generally not be used directly.

Parameters

[in]	params	cSHAKE customization 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 custom[] = "hello"; // customization string
 
  // cSHAKE parameters
  const cshake_params_t params = {
    .custom = custom,
    .custom_len = sizeof(custom) - 1, // length, in bytes (w/o trailing NUL)
  };
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // absorb into cshake256 with fixed-length output, write 32 bytes to `out`
  uint8_t out[32] = { 0 };
  cshake256(params, buf, sizeof(buf), out, sizeof(out));

cshake256_xof_absorb()

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

Absorb data into cSHAKE256 XOF context.

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

Note

cSHAKE is used to implement the hash and extendable output functions (XOFs) defined in NIST SP 800-185 and should generally not be used directly.

Parameters

[in,out]	xof	cSHAKE256 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 custom[] = "hello"; // customization string
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // cSHAKE parameters
  const cshake_params_t params = {
    .custom = custom,
    .custom_len = sizeof(custom) - 1, // length, in bytes (w/o trailing NUL)
  };
 
  // create cSHAKE256 context from parameters
  sha3_xof_t ctx = { 0 };
  cshake256_xof_init(&ctx, params);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    cshake256_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 };
    cshake256_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);

cshake256_xof_init()

void cshake256_xof_init	(	sha3_xof_t *	xof,
		const cshake_params_t	params
	)

Initialize cSHAKE256 XOF context.

Initialize cSHAKE256 (customizable SHAKE256, as defined in section 3 of NIST SP 800-185) XOF context with customization parameters params.

Note

cSHAKE is used to implement the extendable output functions (XOFs) defined in NIST SP 800-185 and should generally not be used directly.

Parameters

[out]	xof	cSHAKE256 XOF context.
[in]	params	cSHAKE256 customization parameters.

Example:

  const uint8_t custom[] = "hello"; // customization string
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // cSHAKE parameters
  const cshake_params_t params = {
    .custom = custom,
    .custom_len = sizeof(custom) - 1, // length, in bytes (w/o trailing NUL)
  };
 
  // create cSHAKE256 context from parameters
  sha3_xof_t ctx = { 0 };
  cshake256_xof_init(&ctx, params);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    cshake256_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 };
    cshake256_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);

cshake256_xof_squeeze()

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

Squeeze bytes from cSHAKE256 XOF context.

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

Note

cSHAKE is used to implement the hash and extendable output functions (XOFs) defined in NIST SP 800-185 and should generally not be used directly.

Parameters

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

Example:

  const uint8_t custom[] = "hello"; // customization string
 
  // get 1024 random bytes
  uint8_t buf[1024] = { 0 };
  rand_bytes(buf, sizeof(buf));
 
  // cSHAKE parameters
  const cshake_params_t params = {
    .custom = custom,
    .custom_len = sizeof(custom) - 1, // length, in bytes (w/o trailing NUL)
  };
 
  // create cSHAKE256 context from parameters
  sha3_xof_t ctx = { 0 };
  cshake256_xof_init(&ctx, params);
 
  // absorb `buf` in 32 byte chunks
  for (size_t i = 0; i < sizeof(buf); i += 32) {
    cshake256_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 };
    cshake256_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);