sha3
Embeddable C11 SHA-3 implementation.
Data Structures | Functions
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]paramsTupleHash128 configuration parameters.
[out]dstDestination buffer.
[in]lenDestination 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));
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.
TupleHash configuration parameters.
Definition: sha3.h:1432
const tuplehash_str_t * strs
Definition: sha3.h:1433
Individual element of TupleHash tuple.
Definition: sha3.h:1423
const uint8_t * ptr
Definition: sha3.h:1424

◆ 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]xofTupleHash128 XOF context.
[in]paramsTupleHash 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);
void tuplehash128_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t len)
Squeeze data from TupleHash128 XOF context.
void tuplehash128_xof_init(sha3_xof_t *xof, const tuplehash_params_t params)
Initialize a TupleHash128 XOF context.
Iterative XOF context (all members are private).
Definition: sha3.h:346

◆ 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]paramsTupleHash128 configuration parameters.
[out]dstDestination buffer.
[in]lenDestination 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));
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.

◆ 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]xofTupleHash128 XOF context.
[out]dstDestination buffer.
[in]lenDestination 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]paramsTupleHash256 configuration parameters.
[out]dstDestination buffer.
[in]lenDestination 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));
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.

◆ 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]xofTupleHash256 XOF context.
[in]paramsTupleHash 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);
void tuplehash256_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t len)
Squeeze bytes from a TupleHash256 XOF context.
void tuplehash256_xof_init(sha3_xof_t *xof, const tuplehash_params_t params)
Initialize a TupleHash256 XOF context.

◆ 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]paramsTupleHash256 configuration parameters.
[out]dstDestination buffer.
[in]lenDestination 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));
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.

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