sha3
Embeddable C11 SHA-3 implementation.
Data Structures | Functions
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]paramscSHAKE customization parameters.
[in]srcSource buffer.
[in]src_lenSource buffer length, in bytes.
[out]dstDestination buffer.
[in]dst_lenDestination 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));
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.
cSHAKE parameters.
Definition: sha3.h:860
const uint8_t * custom
Definition: sha3.h:863

◆ 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]xofcSHAKE128 XOF context.
[in]srcSource buffer.
[in]lenSource 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);
void cshake128_xof_init(sha3_xof_t *xof, const cshake_params_t params)
Initialize cSHAKE128 XOF context.
void cshake128_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t len)
Squeeze bytes from cSHAKE128 XOF context.
_Bool cshake128_xof_absorb(sha3_xof_t *xof, const uint8_t *src, const size_t len)
Absorb data into cSHAKE128 XOF context.
Iterative XOF context (all members are private).
Definition: sha3.h:346

◆ 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]xofcSHAKE128 XOF context.
[in]paramscSHAKE128 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]xofcSHAKE128 XOF context.
[out]dstDestination buffer.
[in]lenDestination 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]paramscSHAKE customization parameters.
[in]srcSource buffer.
[in]src_lenSource buffer length, in bytes.
[out]dstDestination buffer.
[in]dst_lenDestination 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));
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.

◆ 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]xofcSHAKE256 XOF context.
[in]srcSource buffer.
[in]lenSource 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);
void cshake256_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t len)
Squeeze bytes from cSHAKE256 XOF context.
_Bool cshake256_xof_absorb(sha3_xof_t *xof, const uint8_t *src, const size_t len)
Absorb data into cSHAKE256 XOF context.
void cshake256_xof_init(sha3_xof_t *xof, const cshake_params_t params)
Initialize cSHAKE256 XOF context.

◆ 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]xofcSHAKE256 XOF context.
[in]paramscSHAKE256 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]xofcSHAKE256 XOF context.
[out]dstDestination buffer.
[in]lenDestination 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);