#include "ext_headers.h"
#include "lc_ascon_hash.h"
#include "lc_hash.h"
#include "lc_rng.h"
#include "lc_sha3.h"

Include dependency graph for lc_sphincs_shake_256f.h:

Data Structures
struct	lc_sphincs_shake_256f_sk
	Sphincs secret key. More...
struct	lc_sphincs_shake_256f_pk
	Sphincs public key. More...
struct	lc_sphincs_shake_256f_sig
	Sphincs signature. More...
struct	lc_sphincs_ctx

Macros
#define	LC_SPHINCS_CTX_ON_STACK(name)
	Allocate stack memory for the Sphincs stream context or additional parameter relevant for the signature operation.

Functions
int	lc_sphincs_shake_256f_ctx_alloc (struct lc_sphincs_ctx **ctx)
	Allocate Sphincs stream context on heap.
void	lc_sphincs_shake_256f_ctx_zero_free (struct lc_sphincs_ctx *ctx)
	Zeroize and free Sphincs stream context.
static void	lc_sphincs_shake_256f_ctx_zero (struct lc_sphincs_ctx *ctx)
	Zeroize Sphincs context allocated with LC_SPHINCS_CTX_ON_STACK or lc_sphincs_ctx_alloc.
static LC_PURE unsigned int	lc_sphincs_shake_256f_sk_size (void)
	Return the size of the Sphincs secret key.
static LC_PURE unsigned int	lc_sphincs_shake_256f_pk_size (void)
	Return the size of the Sphincs public key.
static LC_PURE unsigned int	lc_sphincs_shake_256f_sig_size (void)
	Return the size of the Sphincs signature.
int	lc_sphincs_shake_256f_keypair (struct lc_sphincs_shake_256f_pk pk, struct lc_sphincs_shake_256f_sk sk, struct lc_rng_ctx *rng_ctx)
	Generates Sphincs public and private key.
int	lc_sphincs_shake_256f_keypair_from_seed (struct lc_sphincs_shake_256f_pk pk, struct lc_sphincs_shake_256f_sk sk, const uint8_t *seed, size_t seedlen)
	Generates Sphincs public and private key from a given seed.
int	lc_sphincs_shake_256f_sign (struct lc_sphincs_shake_256f_sig sig, const uint8_t m, size_t mlen, const struct lc_sphincs_shake_256f_sk sk, struct lc_rng_ctx rng_ctx)
	Computes SLH-DSA signature in one shot.
int	lc_sphincs_shake_256f_sign_ctx (struct lc_sphincs_shake_256f_sig sig, struct lc_sphincs_ctx ctx, const uint8_t m, size_t mlen, const struct lc_sphincs_shake_256f_sk sk, struct lc_rng_ctx *rng_ctx)
	Computes signature with Sphincs context in one shot.
int	lc_sphincs_shake_256f_sign_init (struct lc_sphincs_ctx ctx, const struct lc_sphincs_shake_256f_sk sk)
	Initializes a signature operation.
int	lc_sphincs_shake_256f_sign_update (struct lc_sphincs_ctx ctx, const uint8_t m, size_t mlen)
	Add more data to an already initialized signature state.
int	lc_sphincs_shake_256f_sign_final (struct lc_sphincs_shake_256f_sig sig, struct lc_sphincs_ctx ctx, const struct lc_sphincs_shake_256f_sk sk, struct lc_rng_ctx rng_ctx)
	Computes signature.
int	lc_sphincs_shake_256f_verify (const struct lc_sphincs_shake_256f_sig sig, const uint8_t m, size_t mlen, const struct lc_sphincs_shake_256f_pk *pk)
	Verifies SLH-DSA signature in one shot.
int	lc_sphincs_shake_256f_verify_ctx (const struct lc_sphincs_shake_256f_sig sig, struct lc_sphincs_ctx ctx, const uint8_t m, size_t mlen, const struct lc_sphincs_shake_256f_pk pk)
	Verifies signature with Sphincs context in one shot.
int	lc_sphincs_shake_256f_verify_init (struct lc_sphincs_ctx ctx, const struct lc_sphincs_shake_256f_pk pk)
	Initializes a signature verification operation.
int	lc_sphincs_shake_256f_verify_update (struct lc_sphincs_ctx ctx, const uint8_t m, size_t mlen)
	Add more data to an already initialized signature state.
int	lc_sphincs_shake_256f_verify_final (const struct lc_sphincs_shake_256f_sig sig, struct lc_sphincs_ctx ctx, const struct lc_sphincs_shake_256f_pk *pk)
	Verifies signature.

Data Structure Documentation

◆ lc_sphincs_shake_256f_sk

struct lc_sphincs_shake_256f_sk

Sphincs secret key.

Definition at line 526 of file lc_sphincs_shake_256f.h.

Data Fields
uint8_t	pk[2 *LC_SPX_N]
uint8_t	sk_prf[LC_SPX_N]
uint8_t	sk_seed[LC_SPX_N]

◆ lc_sphincs_shake_256f_pk

struct lc_sphincs_shake_256f_pk

Sphincs public key.

Definition at line 535 of file lc_sphincs_shake_256f.h.

Data Fields
uint8_t	pk[2 *LC_SPX_N]

◆ lc_sphincs_shake_256f_sig

struct lc_sphincs_shake_256f_sig

Sphincs signature.

Definition at line 542 of file lc_sphincs_shake_256f.h.

Data Fields
uint8_t	r[LC_SPX_N]
uint8_t	sigfors[LC_SPX_FORS_BYTES]
uint8_t	sight[LC_SPX_D LC_SPX_WOTS_BYTES+LC_SPX_FULL_HEIGHT LC_SPX_N]

◆ lc_sphincs_ctx

struct lc_sphincs_ctx

Definition at line 550 of file lc_sphincs_shake_128f.h.

Data Fields
uint8_t	shake_state[LC_SHA3_STATE_SIZE_ALIGN(LC_SHA3_256_CTX_SIZE)]	State memory of the hash context used internally to the library - it should not be touched by the user.
unsigned int	slh_dsa_internal:1	When set to true, only the SLH-DSA.Sign_internal or SLH-DSA.Verify_internal are performed (see FIPS 205 chapter 6). Otherwise the SLH-DSA.Sign / SLH-DSA.Verify (see FIPS chapter 5) is applied. Note Use `lc_sphincs_ctx_internal` to set this value. Warning Only set this value to true if you exactly know what you are doing!.
struct lc_hash_ctx	sphincs_hash_ctx	Hash context used internally to the library - it should not be touched by the user.
const struct lc_hash *	sphincs_prehash_type	When using HashSLH-DSA, set the hash reference used for the hash operation. Allowed values are lc_sha256, lc_sha512, lc_sha3_256, lc_sha3_384, lc_sha3_512, lc_shake128 and lc_shake256. Note, the actual message digest operation can be performed external to leancrypto. This parameter only shall indicate the used hash operation. Note Use `lc_sphincs_ctx_hash` to set this value.
const uint8_t *	userctx	buffer with a caller-specified context string Note Use `lc_sphincs_ctx_userctx` to set this value.
size_t	userctxlen	length of the user context (allowed range between 0 and 255 bytes) Note Use `lc_sphincs_ctx_userctx` to set this value.

Macro Definition Documentation

◆ LC_SPHINCS_CTX_ON_STACK

#define LC_SPHINCS_CTX_ON_STACK ( name )

Value:

        _Pragma("GCC diagnostic push") _Pragma(                                \
                "GCC diagnostic ignored \"-Wdeclaration-after-statement\"")    \
                LC_ALIGNED_BUFFER(                                             \
                        name##_ctx_buf, LC_SPHINCS_CTX_SIZE,                   \
                        LC_HASH_COMMON_ALIGNMENT);                             \
        struct lc_sphincs_ctx *name =                                          \
                (struct lc_sphincs_ctx *)name##_ctx_buf;                       \
        LC_SPHINCS_SET_CTX(name);                                              \
        _Pragma("GCC diagnostic pop")

Allocate stack memory for the Sphincs stream context or additional parameter relevant for the signature operation.

Parameters

[in] name Name of the stack variable

Definition at line 624 of file lc_sphincs_shake_256f.h.

Function Documentation

◆ lc_sphincs_shake_256f_ctx_alloc()

int lc_sphincs_shake_256f_ctx_alloc ( struct lc_sphincs_ctx ** ctx )

Allocate Sphincs stream context on heap.

Parameters

[out] ctx Allocated Sphincs stream context

Returns: : 0 on success, < 0 on error

◆ lc_sphincs_shake_256f_ctx_zero()

void lc_sphincs_shake_256f_ctx_zero ( struct lc_sphincs_ctx * ctx )

inlinestatic

Zeroize Sphincs context allocated with LC_SPHINCS_CTX_ON_STACK or lc_sphincs_ctx_alloc.

Parameters

[in] ctx Sphincs context to be zeroized

Definition at line 658 of file lc_sphincs_shake_256f.h.

◆ lc_sphincs_shake_256f_ctx_zero_free()

void lc_sphincs_shake_256f_ctx_zero_free ( struct lc_sphincs_ctx * ctx )

Zeroize and free Sphincs stream context.

Parameters

[in] ctx Sphincs stream context to be zeroized and freed

◆ lc_sphincs_shake_256f_keypair()

int lc_sphincs_shake_256f_keypair	(	struct lc_sphincs_shake_256f_pk *	pk,
		struct lc_sphincs_shake_256f_sk *	sk,
		struct lc_rng_ctx *	rng_ctx )

Generates Sphincs public and private key.

Parameters

[out]	pk	pointer to allocated output public key
[out]	sk	pointer to allocated output private key
[in]	rng_ctx	pointer to seeded random number generator context

Returns: 0 (success) or < 0 on error

◆ lc_sphincs_shake_256f_keypair_from_seed()

int lc_sphincs_shake_256f_keypair_from_seed	(	struct lc_sphincs_shake_256f_pk *	pk,
		struct lc_sphincs_shake_256f_sk *	sk,
		const uint8_t *	seed,
		size_t	seedlen )

Generates Sphincs public and private key from a given seed.

The idea of the function is the allowance of FIPS 205 to maintain the seed used to generate a key pair in lieu of maintaining a private key or the key pair (which used much more memory). The seed must be treated equally sensitive as a private key.

The seed is generated by simply obtaining 32 bytes from a properly seeded DRNG, i.e. the same way as a symmetric key would be generated.

Parameters

[out]	pk	pointer to allocated output public key
[out]	sk	pointer to allocated output private key
[in]	seed	buffer with the seed data which must be exactly 32 bytes in size
[in]	seedlen	length of the seed buffer

Returns: 0 (success) or < 0 on error

◆ lc_sphincs_shake_256f_pk_size()

LC_PURE unsigned int lc_sphincs_shake_256f_pk_size ( void )

inlinestatic

Return the size of the Sphincs public key.

Definition at line 681 of file lc_sphincs_shake_256f.h.

◆ lc_sphincs_shake_256f_sig_size()

LC_PURE unsigned int lc_sphincs_shake_256f_sig_size ( void )

inlinestatic

Return the size of the Sphincs signature.

Definition at line 690 of file lc_sphincs_shake_256f.h.

◆ lc_sphincs_shake_256f_sign()

int lc_sphincs_shake_256f_sign	(	struct lc_sphincs_shake_256f_sig *	sig,
		const uint8_t *	m,
		size_t	mlen,
		const struct lc_sphincs_shake_256f_sk *	sk,
		struct lc_rng_ctx *	rng_ctx )

Computes SLH-DSA signature in one shot.

Parameters

[out]	sig	pointer to output signature
[in]	m	pointer to message to be signed
[in]	mlen	length of message
[in]	sk	pointer to bit-packed secret key
[in]	rng_ctx	pointer to seeded random number generator context - when pointer is non-NULL, perform a randomized signing. Otherwise use deterministic signing.

Returns: 0 (success) or < 0 on error

◆ lc_sphincs_shake_256f_sign_ctx()

int lc_sphincs_shake_256f_sign_ctx	(	struct lc_sphincs_shake_256f_sig *	sig,
		struct lc_sphincs_ctx *	ctx,
		const uint8_t *	m,
		size_t	mlen,
		const struct lc_sphincs_shake_256f_sk *	sk,
		struct lc_rng_ctx *	rng_ctx )

Computes signature with Sphincs context in one shot.

This API allows the caller to provide an arbitrary context buffer which is hashed together with the message to form the message digest to be signed.

Parameters

[out]	sig	pointer to output signature
[in]	ctx	reference to the allocated Sphincs context handle
[in]	m	pointer to message to be signed
[in]	mlen	length of message
[in]	sk	pointer to bit-packed secret key
[in]	rng_ctx	pointer to seeded random number generator context - when pointer is non-NULL, perform a randomized signing. Otherwise use deterministic signing.

Returns: 0 (success) or < 0 on error

◆ lc_sphincs_shake_256f_sign_final()

int lc_sphincs_shake_256f_sign_final	(	struct lc_sphincs_shake_256f_sig *	sig,
		struct lc_sphincs_ctx *	ctx,
		const struct lc_sphincs_shake_256f_sk *	sk,
		struct lc_rng_ctx *	rng_ctx )

Computes signature.

Parameters

[out]	sig	pointer to output signature
[in]	ctx	pointer to Sphincs context that was initialized with lc_sphincs_sign_init and filled with lc_sphincs_sign_update
[in]	sk	pointer to bit-packed secret key
[in]	rng_ctx	pointer to seeded random number generator context - when pointer is non-NULL, perform a randomized signing. Otherwise use deterministic signing.

Returns: 0 (success) or < 0 on error

◆ lc_sphincs_shake_256f_sign_init()

int lc_sphincs_shake_256f_sign_init	(	struct lc_sphincs_ctx *	ctx,
		const struct lc_sphincs_shake_256f_sk *	sk )

Initializes a signature operation.

This call is intended to support messages that are located in non-contiguous places and even becomes available at different times. This call is to be used together with the lc_sphincs_sign_update and lc_sphincs_sign_final.

NOTE: The use of the init/update/final API implies that automatically HashSLH-DSA is used. This is due to the fact that SLH-DSA cannot be used in the init/update/final mode due to mathematical issues. By default, the following hashes are used which are compliant to the requirement that the message digest must be twice as large as the parameter n:

Sphincs 256s/f: SHA3-512 Sphincs 192s/f: SHA3-384 Sphincs 128s/f: SHA3-256

It is permissible for the caller to select other message digest algorithms by using setting the requested algorithm in the ctx using the lc_sphincs_ctx_hash method before this init function is used.

Parameters

[in,out]	ctx	pointer to an allocated Sphincs context
[in]	sk	pointer to bit-packed secret key

Returns: 0 (success) or < 0 on error; -EOPNOTSUPP is returned if a different hash than lc_shake256 is used.

◆ lc_sphincs_shake_256f_sign_update()

int lc_sphincs_shake_256f_sign_update	(	struct lc_sphincs_ctx *	ctx,
		const uint8_t *	m,
		size_t	mlen )

Add more data to an already initialized signature state.

This call is intended to support messages that are located in non-contiguous places and even becomes available at different times. This call is to be used together with the lc_sphincs_sign_init and lc_sphincs_sign_final.

Parameters

[in]	ctx	pointer to Sphincs context that was initialized with lc_sphincs_sign_init
[in]	m	pointer to message to be signed
[in]	mlen	length of message

Returns: 0 (success) or < 0 on error

◆ lc_sphincs_shake_256f_sk_size()

LC_PURE unsigned int lc_sphincs_shake_256f_sk_size ( void )

inlinestatic

Return the size of the Sphincs secret key.

Definition at line 672 of file lc_sphincs_shake_256f.h.

◆ lc_sphincs_shake_256f_verify()

int lc_sphincs_shake_256f_verify	(	const struct lc_sphincs_shake_256f_sig *	sig,
		const uint8_t *	m,
		size_t	mlen,
		const struct lc_sphincs_shake_256f_pk *	pk )

Verifies SLH-DSA signature in one shot.

Parameters

[in]	sig	pointer to input signature
[in]	m	pointer to message
[in]	mlen	length of message
[in]	pk	pointer to bit-packed public key

Returns: 0 if signature could be verified correctly and -EBADMSG when signature cannot be verified, < 0 on other errors

◆ lc_sphincs_shake_256f_verify_ctx()

int lc_sphincs_shake_256f_verify_ctx	(	const struct lc_sphincs_shake_256f_sig *	sig,
		struct lc_sphincs_ctx *	ctx,
		const uint8_t *	m,
		size_t	mlen,
		const struct lc_sphincs_shake_256f_pk *	pk )

Verifies signature with Sphincs context in one shot.

This API allows the caller to provide an arbitrary context buffer which is hashed together with the message to form the message digest to be signed.

Parameters

[in]	sig	pointer to input signature
[in]	ctx	reference to the allocated Sphincs context handle
[in]	m	pointer to message
[in]	mlen	length of message
[in]	pk	pointer to bit-packed public key

Returns: 0 if signature could be verified correctly and -EBADMSG when signature cannot be verified, < 0 on other errors

◆ lc_sphincs_shake_256f_verify_final()

int lc_sphincs_shake_256f_verify_final	(	const struct lc_sphincs_shake_256f_sig *	sig,
		struct lc_sphincs_ctx *	ctx,
		const struct lc_sphincs_shake_256f_pk *	pk )

Verifies signature.

Parameters

[in]	sig	pointer to output signature
[in]	ctx	pointer to Sphincs context that was initialized with lc_sphincs_sign_init and filled with lc_sphincs_sign_update
[in]	pk	pointer to bit-packed public key

Returns: 0 if signature could be verified correctly and -EBADMSG when signature cannot be verified, < 0 on other errors

◆ lc_sphincs_shake_256f_verify_init()

int lc_sphincs_shake_256f_verify_init	(	struct lc_sphincs_ctx *	ctx,
		const struct lc_sphincs_shake_256f_pk *	pk )

Initializes a signature verification operation.

This call is intended to support messages that are located in non-contiguous places and even becomes available at different times. This call is to be used together with the lc_sphincs_verify_update and lc_sphincs_verify_final.

NOTE: The use of the init/update/final API implies that automatically HashSLH-DSA is used. This is due to the fact that SLH-DSA cannot be used in the init/update/final mode due to mathematical issues. By default, the following hashes are used which are compliant to the requirement that the message digest must be twice as large as the parameter n:

Sphincs 256s/f: SHA3-512 Sphincs 192s/f: SHA3-384 Sphincs 128s/f: SHA3-256

It is permissible for the caller to select other message digest algorithms by using setting the requested algorithm in the ctx using the lc_sphincs_ctx_hash method before this init function is used.

Parameters

[in,out]	ctx	pointer to an allocated Sphincs context
[in]	pk	pointer to bit-packed public key

Returns: 0 (success) or < 0 on error; -EOPNOTSUPP is returned if a different hash than lc_shake256 is used.

◆ lc_sphincs_shake_256f_verify_update()

int lc_sphincs_shake_256f_verify_update	(	struct lc_sphincs_ctx *	ctx,
		const uint8_t *	m,
		size_t	mlen )

Add more data to an already initialized signature state.

This call is intended to support messages that are located in non-contiguous places and even becomes available at different times. This call is to be used together with the lc_sphincs_verify_init and lc_sphincs_verify_final.

Parameters

[in,out]	ctx	pointer to Sphincs context that was initialized with lc_sphincs_sign_init
[in]	m	pointer to message to be signed
[in]	mlen	length of message

Returns: 0 (success) or < 0 on error

Data Structures

Macros

Functions

Data Structure Documentation

◆ lc_sphincs_shake_256f_sk

◆ lc_sphincs_shake_256f_pk

◆ lc_sphincs_shake_256f_sig

◆ lc_sphincs_ctx

Macro Definition Documentation

◆ LC_SPHINCS_CTX_ON_STACK

Function Documentation

◆ lc_sphincs_shake_256f_ctx_alloc()

◆ lc_sphincs_shake_256f_ctx_zero()

◆ lc_sphincs_shake_256f_ctx_zero_free()

◆ lc_sphincs_shake_256f_keypair()

◆ lc_sphincs_shake_256f_keypair_from_seed()

◆ lc_sphincs_shake_256f_pk_size()

◆ lc_sphincs_shake_256f_sig_size()

◆ lc_sphincs_shake_256f_sign()

◆ lc_sphincs_shake_256f_sign_ctx()

◆ lc_sphincs_shake_256f_sign_final()

◆ lc_sphincs_shake_256f_sign_init()

◆ lc_sphincs_shake_256f_sign_update()

◆ lc_sphincs_shake_256f_sk_size()

◆ lc_sphincs_shake_256f_verify()

◆ lc_sphincs_shake_256f_verify_ctx()

◆ lc_sphincs_shake_256f_verify_final()

◆ lc_sphincs_shake_256f_verify_init()

◆ lc_sphincs_shake_256f_verify_update()