Functions
static int	lc_dilithium_ctx_alloc (struct lc_dilithium_ctx **ctx)
	Allocates Dilithium context on heap.

static void	lc_dilithium_ctx_zero_free (struct lc_dilithium_ctx *ctx)
	Zeroizes and frees Dilithium context on heap.

static void	lc_dilithium_ctx_zero (struct lc_dilithium_ctx *ctx)
	Zeroizes Dilithium context either on heap or on stack.

static enum lc_dilithium_type	lc_dilithium_sk_type (const struct lc_dilithium_sk *sk)
	Obtain Dilithium type from secret key.

static enum lc_dilithium_type	lc_dilithium_pk_type (const struct lc_dilithium_pk *pk)
	Obtain Dilithium type from public key.

static enum lc_dilithium_type	lc_dilithium_sig_type (const struct lc_dilithium_sig *sig)
	Obtain Dilithium type from signature.

static LC_PURE unsigned int	lc_dilithium_sk_size (enum lc_dilithium_type dilithium_type)
	Return the size of the Dilithium secret key.

static LC_PURE unsigned int	lc_dilithium_pk_size (enum lc_dilithium_type dilithium_type)
	Return the size of the Dilithium public key.

static LC_PURE unsigned int	lc_dilithium_sig_size (enum lc_dilithium_type dilithium_type)
	Return the size of the Dilithium signature.

static int	lc_dilithium_sk_load (struct lc_dilithium_sk sk, const uint8_t src_key, size_t src_key_len)
	Load a Dilithium secret key provided with a buffer into the leancrypto data structure.

static int	lc_dilithium_pk_load (struct lc_dilithium_pk pk, const uint8_t src_key, size_t src_key_len)
	Load a Dilithium public key provided with a buffer into the leancrypto data structure.

static int	lc_dilithium_sig_load (struct lc_dilithium_sig sig, const uint8_t src_sig, size_t src_sig_len)
	Load a Dilithium signature provided with a buffer into the leancrypto data structure.

static int	lc_dilithium_sk_ptr (uint8_t *dilithium_key, size_t dilithium_key_len, struct lc_dilithium_sk *sk)
	Obtain the reference to the Dilithium key and its length.

static int	lc_dilithium_pk_ptr (uint8_t *dilithium_key, size_t dilithium_key_len, struct lc_dilithium_pk *pk)
	Obtain the reference to the Dilithium key and its length.

static int	lc_dilithium_sig_ptr (uint8_t *dilithium_sig, size_t dilithium_sig_len, struct lc_dilithium_sig *sig)
	Obtain the reference to the Dilithium signature and its length.

static int	lc_dilithium_keypair (struct lc_dilithium_pk pk, struct lc_dilithium_sk sk, struct lc_rng_ctx *rng_ctx, enum lc_dilithium_type dilithium_type)
	Generates Dilithium public and private key.

static int	lc_dilithium_keypair_from_seed (struct lc_dilithium_pk pk, struct lc_dilithium_sk sk, const uint8_t *seed, size_t seedlen, enum lc_dilithium_type dilithium_type)
	Generates Dilithium public and private key from a given seed.

static int	lc_dilithium_sign (struct lc_dilithium_sig sig, const uint8_t m, size_t mlen, const struct lc_dilithium_sk sk, struct lc_rng_ctx rng_ctx)
	Computes signature in one shot.

static int	lc_dilithium_sign_init (struct lc_dilithium_ctx ctx, const struct lc_dilithium_sk sk)
	Initializes a signature operation.

static int	lc_dilithium_sign_update (struct lc_dilithium_ctx ctx, const uint8_t m, size_t mlen)
	Add more data to an already initialized signature state.

static int	lc_dilithium_sign_final (struct lc_dilithium_sig sig, struct lc_dilithium_ctx ctx, const struct lc_dilithium_sk sk, struct lc_rng_ctx rng_ctx)
	Computes signature.

static int	lc_dilithium_verify (const struct lc_dilithium_sig sig, const uint8_t m, size_t mlen, const struct lc_dilithium_pk *pk)
	Verifies signature in one shot.

static int	lc_dilithium_verify_init (struct lc_dilithium_ctx ctx, const struct lc_dilithium_pk pk)
	Initializes a signature verification operation.

static int	lc_dilithium_verify_update (struct lc_dilithium_ctx ctx, const uint8_t m, size_t mlen)
	Add more data to an already initialized signature state.

static int	lc_dilithium_verify_final (const struct lc_dilithium_sig sig, struct lc_dilithium_ctx ctx, const struct lc_dilithium_pk *pk)
	Verifies signature.

Detailed Description

Dilithium API concept

The Dilithium API is accessible via the following header files with the mentioned purpose.

lc_dilithium.h: This API is the generic API allowing the caller to select which Dilithium type (Dilithium 87, 65 or 44) are to be used. The selection is made either with the flag specified during key generation or by matching the size of the imported data with the different lc_dilithium_*_load API calls. All remaining APIs take the information about the Dilithium type from the provided input data.

This header file only provides inline functions which selectively call the API provided with the header files below.
lc_dilithium_87.h: Direct access to Dilithium 87.
lc_dilithium_65.h: Direct access to Dilithium 65.
lc_dilithium_44.h: Direct access to Dilithium 44.

To support the stream mode of the Dilithium signature operation, a context structure is required. This context structure can be allocated either on the stack or heap with LC_DILITHIUM_CTX_ON_STACK or lc_dilithium_ctx_alloc. The context should be zeroized and freed (only for heap) with lc_dilithium_ctx_zero or lc_dilithium_ctx_zero_free.

Function Documentation

◆ lc_dilithium_ctx_alloc()

static int lc_dilithium_ctx_alloc ( struct lc_dilithium_ctx ** ctx )

inlinestatic

Allocates Dilithium context on heap.

Parameters

[out] ctx Dilithium context pointer

Returns: 0 (success) or < 0 on error

Definition at line 158 of file lc_dilithium.h.

◆ lc_dilithium_ctx_zero()

static void lc_dilithium_ctx_zero ( struct lc_dilithium_ctx * ctx )

inlinestatic

Zeroizes Dilithium context either on heap or on stack.

Parameters

[out] ctx Dilithium context pointer

Definition at line 200 of file lc_dilithium.h.

◆ lc_dilithium_ctx_zero_free()

static void lc_dilithium_ctx_zero_free ( struct lc_dilithium_ctx * ctx )

inlinestatic

Zeroizes and frees Dilithium context on heap.

Parameters

[out] ctx Dilithium context pointer

Definition at line 180 of file lc_dilithium.h.

◆ lc_dilithium_keypair()

static int lc_dilithium_keypair	(	struct lc_dilithium_pk *	pk,
		struct lc_dilithium_sk *	sk,
		struct lc_rng_ctx *	rng_ctx,
		enum lc_dilithium_type	dilithium_type )

inlinestatic

Generates Dilithium 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
[in]	dilithium_type	type of the Dilithium key to generate

Returns: 0 (success) or < 0 on error

Definition at line 667 of file lc_dilithium.h.

◆ lc_dilithium_keypair_from_seed()

static int lc_dilithium_keypair_from_seed	(	struct lc_dilithium_pk *	pk,
		struct lc_dilithium_sk *	sk,
		const uint8_t *	seed,
		size_t	seedlen,
		enum lc_dilithium_type	dilithium_type )

inlinestatic

Generates Dilithium public and private key from a given seed.

The idea of the function is the allowance of FIPS 204 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
[in]	dilithium_type	type of the Dilithium key to generate

Returns: 0 (success) or < 0 on error

Definition at line 731 of file lc_dilithium.h.

◆ lc_dilithium_pk_load()

static int lc_dilithium_pk_load	(	struct lc_dilithium_pk *	pk,
		const uint8_t *	src_key,
		size_t	src_key_len )

inlinestatic

Load a Dilithium public key provided with a buffer into the leancrypto data structure.

Parameters

[out]	pk	Secret key to be filled (the caller must have it allocated)
[in]	src_key	Buffer that holds the key to be imported
[in]	src_key_len	Buffer length that holds the key to be imported

Returns: 0 on success or < 0 on error

Definition at line 430 of file lc_dilithium.h.

◆ lc_dilithium_pk_ptr()

static int lc_dilithium_pk_ptr	(	uint8_t **	dilithium_key,
		size_t *	dilithium_key_len,
		struct lc_dilithium_pk *	pk )

inlinestatic

Obtain the reference to the Dilithium key and its length.

NOTE: Only pointer references into the leancrypto data structure are returned which implies that any modification will modify the leancrypto key, too.

Parameters

[out]	dilithium_key	Dilithium key pointer
[out]	dilithium_key_len	Length of the key buffer
[in]	pk	Dilithium publi key from which the references are obtained

Returns: 0 on success, != 0 on error

Definition at line 572 of file lc_dilithium.h.

◆ lc_dilithium_pk_size()

static LC_PURE unsigned int lc_dilithium_pk_size ( enum lc_dilithium_type dilithium_type )

inlinestatic

Return the size of the Dilithium public key.

Parameters

[in] dilithium_type Dilithium type for which the size is requested

Returns: requested size

Definition at line 309 of file lc_dilithium.h.

◆ lc_dilithium_pk_type()

static enum lc_dilithium_type lc_dilithium_pk_type ( const struct lc_dilithium_pk * pk )

inlinestatic

Obtain Dilithium type from public key.

Parameters

[in] pk Public key from which the type is to be obtained

Returns: key type

Definition at line 239 of file lc_dilithium.h.

◆ lc_dilithium_sig_load()

static int lc_dilithium_sig_load	(	struct lc_dilithium_sig *	sig,
		const uint8_t *	src_sig,
		size_t	src_sig_len )

inlinestatic

Load a Dilithium signature provided with a buffer into the leancrypto data structure.

Parameters

[out]	sig	Secret key to be filled (the caller must have it allocated)
[in]	src_sig	Buffer that holds the signature to be imported
[in]	src_sig_len	Buffer length that holds the signature to be imported

Returns: 0 on success or < 0 on error

Definition at line 476 of file lc_dilithium.h.

◆ lc_dilithium_sig_ptr()

static int lc_dilithium_sig_ptr	(	uint8_t **	dilithium_sig,
		size_t *	dilithium_sig_len,
		struct lc_dilithium_sig *	sig )

inlinestatic

Obtain the reference to the Dilithium signature and its length.

NOTE: Only pointer references into the leancrypto data structure are returned which implies that any modification will modify the leancrypto signature, too.

Parameters

[out]	dilithium_sig	Dilithium signature pointer
[out]	dilithium_sig_len	Length of the signature buffer
[in]	sig	Dilithium signature from which the references are obtained

Returns: 0 on success, != 0 on error

Definition at line 621 of file lc_dilithium.h.

◆ lc_dilithium_sig_size()

static LC_PURE unsigned int lc_dilithium_sig_size ( enum lc_dilithium_type dilithium_type )

inlinestatic

Return the size of the Dilithium signature.

Parameters

[in] dilithium_type Dilithium type for which the size is requested

Returns: requested size

Definition at line 346 of file lc_dilithium.h.

◆ lc_dilithium_sig_type()

static enum lc_dilithium_type lc_dilithium_sig_type ( const struct lc_dilithium_sig * sig )

inlinestatic

Obtain Dilithium type from signature.

Parameters

[in] sig Signature from which the type is to be obtained

Returns: key type

Definition at line 255 of file lc_dilithium.h.

◆ lc_dilithium_sign()

static int lc_dilithium_sign	(	struct lc_dilithium_sig *	sig,
		const uint8_t *	m,
		size_t	mlen,
		const struct lc_dilithium_sk *	sk,
		struct lc_rng_ctx *	rng_ctx )

inlinestatic

Computes 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

Definition at line 787 of file lc_dilithium.h.

◆ lc_dilithium_sign_final()

static int lc_dilithium_sign_final	(	struct lc_dilithium_sig *	sig,
		struct lc_dilithium_ctx *	ctx,
		const struct lc_dilithium_sk *	sk,
		struct lc_rng_ctx *	rng_ctx )

inlinestatic

Computes signature.

Parameters

[out]	sig	pointer to output signature
[in]	ctx	pointer to Dilithium context that was initialized with lc_dilithium_sign_init and filled with lc_dilithium_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

Definition at line 921 of file lc_dilithium.h.

◆ lc_dilithium_sign_init()

static int lc_dilithium_sign_init	(	struct lc_dilithium_ctx *	ctx,
		const struct lc_dilithium_sk *	sk )

inlinestatic

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_dilithium_sign_update and lc_dilithium_sign_final.

Parameters

[in,out]	ctx	pointer Dilithium context
[in]	sk	pointer to bit-packed secret key

NOTE: This API call is NOT yet stable and thus will not cause a the libraries major version to change. An update request is filed with the FIPS 204 authors to change the cause for providing the sk parameter in the init call. Once that change is applied, the sk parameter is removed for good.

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

Definition at line 846 of file lc_dilithium.h.

◆ lc_dilithium_sign_update()

static int lc_dilithium_sign_update	(	struct lc_dilithium_ctx *	ctx,
		const uint8_t *	m,
		size_t	mlen )

inlinestatic

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_dilithium_sign_init and lc_dilithium_sign_final.

Parameters

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

Returns: 0 (success) or < 0 on error

Definition at line 892 of file lc_dilithium.h.

◆ lc_dilithium_sk_load()

static int lc_dilithium_sk_load	(	struct lc_dilithium_sk *	sk,
		const uint8_t *	src_key,
		size_t	src_key_len )

inlinestatic

Load a Dilithium secret key provided with a buffer into the leancrypto data structure.

Parameters

[out]	sk	Secret key to be filled (the caller must have it allocated)
[in]	src_key	Buffer that holds the key to be imported
[in]	src_key_len	Buffer length that holds the key to be imported

Returns: 0 on success or < 0 on error

Definition at line 384 of file lc_dilithium.h.

◆ lc_dilithium_sk_ptr()

static int lc_dilithium_sk_ptr	(	uint8_t **	dilithium_key,
		size_t *	dilithium_key_len,
		struct lc_dilithium_sk *	sk )

inlinestatic

Obtain the reference to the Dilithium key and its length.

NOTE: Only pointer references into the leancrypto data structure are returned which implies that any modification will modify the leancrypto key, too.

Parameters

[out]	dilithium_key	Dilithium key pointer
[out]	dilithium_key_len	Length of the key buffer
[in]	sk	Dilithium secret key from which the references are obtained

Returns: 0 on success, != 0 on error

Definition at line 524 of file lc_dilithium.h.

◆ lc_dilithium_sk_size()

static LC_PURE unsigned int lc_dilithium_sk_size ( enum lc_dilithium_type dilithium_type )

inlinestatic

Return the size of the Dilithium secret key.

Parameters

[in] dilithium_type Dilithium type for which the size is requested

Returns: requested size

Definition at line 272 of file lc_dilithium.h.

◆ lc_dilithium_sk_type()

static enum lc_dilithium_type lc_dilithium_sk_type ( const struct lc_dilithium_sk * sk )

inlinestatic

Obtain Dilithium type from secret key.

Parameters

[in] sk Secret key from which the type is to be obtained

Returns: key type

Definition at line 223 of file lc_dilithium.h.

◆ lc_dilithium_verify()

static int lc_dilithium_verify	(	const struct lc_dilithium_sig *	sig,
		const uint8_t *	m,
		size_t	mlen,
		const struct lc_dilithium_pk *	pk )

inlinestatic

Verifies 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

Definition at line 972 of file lc_dilithium.h.

◆ lc_dilithium_verify_final()

static int lc_dilithium_verify_final	(	const struct lc_dilithium_sig *	sig,
		struct lc_dilithium_ctx *	ctx,
		const struct lc_dilithium_pk *	pk )

inlinestatic

Verifies signature.

Parameters

[in]	sig	pointer to output signature
[in]	ctx	pointer to Dilithium context that was initialized with lc_dilithium_sign_init and filled with lc_dilithium_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

Definition at line 1102 of file lc_dilithium.h.

◆ lc_dilithium_verify_init()

static int lc_dilithium_verify_init	(	struct lc_dilithium_ctx *	ctx,
		const struct lc_dilithium_pk *	pk )

inlinestatic

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_dilithium_verify_update and lc_dilithium_verify_final.

Parameters

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

NOTE: This API call is NOT yet stable and thus will not cause a the libraries major version to change. An update request is filed with the FIPS 204 authors to change the cause for providing the pk parameter in the init call. Once that change is applied, the pk parameter is removed for good.

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

Definition at line 1028 of file lc_dilithium.h.

◆ lc_dilithium_verify_update()

static int lc_dilithium_verify_update	(	struct lc_dilithium_ctx *	ctx,
		const uint8_t *	m,
		size_t	mlen )

inlinestatic

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_dilithium_verify_init and lc_dilithium_verify_final.

Parameters

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

Returns: 0 (success) or < 0 on error

Definition at line 1075 of file lc_dilithium.h.

Functions

Detailed Description

Function Documentation

◆ lc_dilithium_ctx_alloc()

◆ lc_dilithium_ctx_zero()

◆ lc_dilithium_ctx_zero_free()

◆ lc_dilithium_keypair()

◆ lc_dilithium_keypair_from_seed()

◆ lc_dilithium_pk_load()

◆ lc_dilithium_pk_ptr()

◆ lc_dilithium_pk_size()

◆ lc_dilithium_pk_type()

◆ lc_dilithium_sig_load()

◆ lc_dilithium_sig_ptr()

◆ lc_dilithium_sig_size()

◆ lc_dilithium_sig_type()

◆ lc_dilithium_sign()

◆ lc_dilithium_sign_final()

◆ lc_dilithium_sign_init()

◆ lc_dilithium_sign_update()

◆ lc_dilithium_sk_load()

◆ lc_dilithium_sk_ptr()

◆ lc_dilithium_sk_size()

◆ lc_dilithium_sk_type()

◆ lc_dilithium_verify()

◆ lc_dilithium_verify_final()

◆ lc_dilithium_verify_init()

◆ lc_dilithium_verify_update()