Operators#

cuHash operators are used to describe the operation to be performed, and configure the execution. They are combined via addition (+) to form a cuHash descriptor.

cuHash Operators#

Description Operators#

Algorithm#

template<algorithm Alg> Algorithm()#

Sets the algorithm Alg to use. Valid values are:

enum algorithm#

enumerator SHA3#: SHA-3 hash functions (FIPS-202)

enumerator SHAKE#: SHAKE extendable output functions (FIPS-202)

enumerator SHA2_32#: SHA-2 32-bit word size hash functions (FIPS-180-4)

enumerator SHA2_64#: SHA-2 64-bit word size hash functions (FIPS-180-4)

enumerator POSEIDON2#: Poseidon2 hash functions

enumerator MERKLE#: Tells the operator to use the Merkle Tree API

There is no default value.

SecurityCategory#

template<unsigned int Category> SecurityCategory()#

Sets the NIST security category, which determines the parameter set of the algorithm to be used. The valid values of Category depend on the value of the Algorithm operator. Poseidon2 and Merkle Tree do not require a security category.

There is no default value.

Name	`Algorithm`	`SecurityCategory`	Alias
SHA2-224	`algorithm::SHA2_32`	`1`	`SHA2_224()`
SHA2-256	`algorithm::SHA2_32`	`2`	`SHA2_256()`
SHA2-384	`algorithm::SHA2_64`	`4`	`SHA2_384()`
SHA2-512	`algorithm::SHA2_64`	`5`	`SHA2_512()`
SHA2-512/224	`algorithm::SHA2_64`	`1`	`SHA2_512_224()`
SHA2-512/256	`algorithm::SHA2_64`	`2`	`SHA2_512_256()`
SHA3-224	`algorithm::SHA3`	`1`	`SHA3_224()`
SHA3-256	`algorithm::SHA3`	`2`	`SHA3_256()`
SHA3-384	`algorithm::SHA3`	`4`	`SHA3_384()`
SHA3-512	`algorithm::SHA3`	`5`	`SHA3_512()`
SHAKE-128	`algorithm::SHAKE`	`1`	`SHAKE_128()`
SHAKE-256	`algorithm::SHAKE`	`2`	`SHAKE_256()`

Poseidon2 Specific Operators#

Currently, we only support Poseidon2-BabyBear with field 2³¹ - 2²⁷ + 1. The round constants and Maximum Distance Separable (MDS) matrix that are used in the algorithm can be accessed from here.

Width#

template<unsigned int Width> Width()#

Sets the width of the Poseidon2 function. Currently, the only supported widths are 16 and 24. The default value is 16.

Capacity#

template<unsigned int Capacity> Capacity()#

Sets the capacity of the Poseidon2 function. Currently, the only supported capacity is 8. The default value is 8.

For Poseidon2 we have the following combinations:

Name	`Width`	`Capacity`	Full Round	Partial Round	Sbox	Alias
Poseidon2-8-16	`16`	`8`	`8`	`13`	x⁷	`POSEIDON2_8_16()`
Poseidon2-8-24	`24`	`8`	`8`	`21`	x⁷	`POSEIDON2_8_24()`

Merkle Tree Specific Operators#

MerkleSize#

template<unsigned int Size> MerkleSize()#

Sets the size of the Merkle Tree. Sizes 2 to 2^21 are supported. The default value is 2048.

Precision#

template<typename Precision> Precision()#

Sets the precision of the Merkle Tree. Currently, the only supported precisions are uint8_t, and uint32_t. SHA2, SHA3, and SHAKE hashes use uint8_t, and Poseidon2 uses uint32_t. The default value is uint8_t.

Merkle Tree Aliases#

For convenience, we provide aliases for Merkle Trees with the supported sizes and precisions. They are in the following format: MERKLE_<PRECISION>_<SIZE> where <PRECISION> takes the values BYTE or FIELD representing uint8_t or uint32_t respectively, and <SIZE> is the size as a raw number, not the power of 2 exponent. For example, MERKLE_BYTE_2048 is an alias for decltype(Algorithm<algorithm::MERKLE>() + MerkleSize<2048>() + Precision<uint8_t>() + Function<function::Merkle>() + Block()). Recall that the precision is tied to the respective hash algorithm that will be used in tandem with the Merkle Tree, in the case of our example, this Merkle Tree will be used with SHA2, SHA3, or SHAKE.

Execution Operators#

Thread execution#

Thread()#

Specifies that the operator will execute independently for each thread.

Warp execution#

Warp()#

Specifies that the operator will execute on each CUDA warp (group of 32 threads). The device methods should be called with the same arguments for all threads in the warp.

Only the algorithm::SHA3 and algorithm::SHAKE algorithms are supported for this execution mode.

Block execution#

Block()#

Specifies that the operator will execute on each CUDA block. Only the algorithm::MERKLE algorithm is supported for this execution mode with cuHash. Essentially, the MERKLE algorithm will utilize a thread based Hash function to generate the Merkle Tree using a full block.