override_shake256_256_internal.h File Reference

Prototypes for the SHAKE256/256 hash function override using the internal interface. More...

#include <stdint.h>
#include "types.h"

Include dependency graph for override_shake256_256_internal.h:

Go to the source code of this file.

Macros
#define	XMSS_OVERRIDE_SHAKE256_256_INTERNAL_H_INCLUDED
	Include guard.

Functions
void	xmss_sponge_absorb (uint64_t *A, uint_fast8_t offset, const uint8_t *bytes, uint_fast8_t byte_count)
	Absorbs additional bytes into the state array A. More...
void	xmss_sponge_absorb_native (uint64_t *A, const uint32_t *words, uint_fast8_t word_count)
	Absorbs additional native words into the state array A. More...
void	xmss_sponge_squeeze (XmssValue256 *digest, const uint64_t *A)
	Extracts the digest from the state array A. More...
void	xmss_sponge_squeeze_native (XmssNativeValue256 *native_digest, const uint64_t *A)
	Extracts the digest from the state array A. More...
void	xmss_keccak_p_1600_24 (uint64_t *A)
	Perform an in-place $\Keccak$-$p[1600,24]$ transform of the state array A. More...

Detailed Description

Prototypes for the SHAKE256/256 hash function override using the internal interface.

Include this file in your override implementation for SHAKE256/256 using the internal interface.

The library allows to override its internal implementation for SHAKE256/256. The main use case is hardware acceleration. However, unlike SHA-256, the performance of software implementations of SHAKE256/256 is strongly dependent on the bitness and byte ordering of the platform. The default implementation is optimized for 64-bit little-endian. For other types of platforms a software override can improve performance.

If your platform is compatible with the internal format of the library, then it is preferred to use the internal interface specified here rather than the generic interface.

The internal interface has the following properties:

• Allocation free
• The internal state array is 64-bit aligned.

The implementation is free to choose the layout of the state array A such that it optimizes performance for the target platform. The state array is 1600 bits (200 bytes) in size; i.e., 5x5 lanes of $w$=64. The library treats the state array as opaque; it is only passed as uint64_t to ensure memory alignment; there are no restrictions on how the 1600 bits are organized within the uint64_t[25] data block.

The library handles the high level SHAKE256/256 algorithm: absorption, padding, and the final squeeze by calling the low level functions that the override implementation provides.

This interface prevents unnecessary copying of memory, unnecessary byte swapping, and alignment issues.

Compile the library with CMake as follows:

cmake -DXMSS_SHAKE256_256=OverrideInternal

Function Documentation

xmss_keccak_p_1600_24()

void xmss_keccak_p_1600_24

(

uint64_t *

A

)

Perform an in-place $\Keccak$-$p[1600,24]$ transform of the state array A.

This function implements $\Keccak$-$p[b=1600,n_{r}=24]$ as defined by NIST FIPS 202, Section 3.3.

Note that instead of accepting a string $S$, this function accepts a state array A, see NIST FIPS 202, Section 3.1.2.

Note that instead of returning the result, this function transforms the input state array in-place.

For performance reasons, it is recommended not to validate the input. This function is guaranteed to be called by the library with valid input.

Parameters

[in,out]

A

The state array.

xmss_sponge_absorb()

void xmss_sponge_absorb	(	uint64_t *	A,
		uint_fast8_t	offset,
		const uint8_t *	bytes,
		uint_fast8_t	byte_count
	)

Absorbs additional bytes into the state array A.

offset + byte_count does not extend beyond the block size of 136 bytes for SHAKE256/256. This function XORs the additional bytes into the internal layout of the state array A.

This function is never called with empty data; i.e. byte_count >= 1.

For performance reasons, it is recommended not to validate the input. This function is guaranteed to be called by the library with valid input.

Parameters

[in,out]	A	The state array.
[in]	offset	The offset into the 136-byte block where to start absorbing the bytes.
[in]	bytes	Input bytes.
[in]	byte_count	Length in bytes of the input.

xmss_sponge_absorb_native()

void xmss_sponge_absorb_native	(	uint64_t *	A,
		const uint32_t *	words,
		uint_fast8_t	word_count
	)

Absorbs additional native words into the state array A.

Absorption starts at the beginning of the 136 bytes block for SHAKE256/256. word_count does not extend beyond the block size of 136 bytes for SHAKE256/256; i.e., word_count <= 34. This function XORs the words into the internal layout of the state array A.

This function is never called with empty data; i.e. word_count >= 1.

For performance reasons, it is recommended not to validate the input. This function is guaranteed to be called by the library with valid input.

Parameters

[in,out]	A	The state array.
[in]	words	Input words.
[in]	word_count	Length in 32-bit words of the input.

xmss_sponge_squeeze()

void xmss_sponge_squeeze	(	XmssValue256 *	digest,
		const uint64_t *	A
	)

Extracts the digest from the state array A.

For performance reasons, it is recommended not to validate the input. This function is guaranteed to be called by the library with valid input.

Parameters

[out]	digest	The output digest.
[in]	A	The final state array.

xmss_sponge_squeeze_native()

void xmss_sponge_squeeze_native	(	XmssNativeValue256 *	native_digest,
		const uint64_t *	A
	)

Extracts the digest from the state array A.

For performance reasons, it is recommended not to validate the input. This function is guaranteed to be called by the library with valid input.

Parameters

[out]	native_digest	The output digest.
[in]	A	The final state array.