dilithium.h File Reference

Contains the primary public API for the Dilithium asymmetric signature scheme implementation. More...

#include "qsccommon.h"

Go to the source code of this file.

Macros
#define	QSC_DILITHIUM_GENERATE_SEED_SIZE   32
	The byte size of the seeded generator seed array.
#define	QSC_DILITHIUM_PRIVATEKEY_SIZE   4896
	The byte size of the secret private-key array.
#define	QSC_DILITHIUM_PUBLICKEY_SIZE   2592
	The byte size of the public-key array.
#define	QSC_DILITHIUM_SIGNATURE_SIZE   4627
	The byte size of the signature array.
#define	QSC_DILITHIUM_ALGNAME   "DILITHIUM"
	The formal algorithm name.

Functions
QSC_EXPORT_API bool	qsc_dilithium_generate_keypair (uint8_t *publickey, uint8_t *privatekey, bool(*rng_generate)(uint8_t *, size_t))
	Generates a Dilithium public/private key-pair.
QSC_EXPORT_API void	qsc_dilithium_seeded_generate_keypair (uint8_t *publickey, uint8_t *privatekey, const uint8_t *seed)
	Generates a Dilithium public/private key-pair using a random input seed.
QSC_EXPORT_API bool	qsc_dilithium_sign (uint8_t *signedmsg, size_t *smsglen, const uint8_t *message, size_t msglen, const uint8_t *privatekey, bool(*rng_generate)(uint8_t *, size_t))
	Takes the message as input and returns an array containing the signature followed by the message.
QSC_EXPORT_API bool	qsc_dilithium_sign_ex (uint8_t *signedmsg, size_t *smsglen, const uint8_t *message, size_t msglen, const uint8_t *context, size_t ctxlen, const uint8_t *privatekey, bool(*rng_generate)(uint8_t *, size_t))
	Takes the message as input with the additional context parameter, and returns an array containing the signature followed by the message.
QSC_EXPORT_API bool	qsc_dilithium_verify (uint8_t *message, size_t *msglen, const uint8_t *signedmsg, size_t smsglen, const uint8_t *publickey)
	Verifies a signature-message pair with the public key.
QSC_EXPORT_API bool	qsc_dilithium_verify_ex (uint8_t *message, size_t *msglen, const uint8_t *context, size_t ctxlen, const uint8_t *signedmsg, size_t smsglen, const uint8_t *publickey)
	Verifies a signature-message pair and context parameter with the public key.

Detailed Description

Contains the primary public API for the Dilithium asymmetric signature scheme implementation.

This header provides the interface for the FIPS 204 version of the Dilithium asymmetric signature scheme. It includes functions for key-pair generation, signing messages, and verifying signatures. The implementation is based entirely on the C reference branch of Dilithium from the FIPS 204 implementation. Dilithium is a lattice-based, CCA-secure digital signature scheme designed for post-quantum security.

Example:

// An example of key-pair creation, signing, and verification
#define MSGLEN 32
uint8_t pk[QSC_DILITHIUM_PUBLICKEY_SIZE];
uint8_t sk[QSC_DILITHIUM_PRIVATEKEY_SIZE];
uint8_t msg[32];
uint8_t smsg[QSC_DILITHIUM_SIGNATURE_SIZE + MSGLEN];
uint8_t rmsg[32];
 
uint32_t rmsglen = 0U;
uint32_t smsglen = 0U;
 
// Create the public and secret keys.
qsc_dilithium_generate_keypair(pk, sk, rng_generate);
// Sign the message; the signature is prepended to the message.
qsc_dilithium_sign(smsg, &smsglen, msg, MSGLEN, sk, rng_generate);
// Verify the signature and retrieve the message bytes.
if (qsc_dilithium_verify(rmsg, &rmsglen, smsg, smsglen, pk) != true)
{
    // Authentication failed; handle error.
}

Reference Links:

• Official Dilithium Specification (FIPS 204)
• FIPS 202: SHA-3 Standard

Function Documentation

qsc_dilithium_generate_keypair()

QSC_EXPORT_API bool qsc_dilithium_generate_keypair	(	uint8_t *	publickey,
		uint8_t *	privatekey,
		bool(*	rng_generate )(uint8_t *, size_t) )

Generates a Dilithium public/private key-pair.

Warning

Arrays must be sized to QSC_DILITHIUM_PUBLICKEY_SIZE and QSC_DILITHIUM_PRIVATEKEY_SIZE.

Parameters

publickey	[uint8_t*] Pointer to the public verification-key array.
privatekey	[uint8_t*] Pointer to the private signature-key array.
rng_generate	[bool (*)(uint8_t*, size_t)] Pointer to the random generator.

Returns

[bool] Returns true if the key pair was generated successfully.

qsc_dilithium_seeded_generate_keypair()

QSC_EXPORT_API void qsc_dilithium_seeded_generate_keypair	(	uint8_t *	publickey,
		uint8_t *	privatekey,
		const uint8_t *	seed )

Generates a Dilithium public/private key-pair using a random input seed.

Note

Used exclusively for the NIST ACVP KAT tests, use the other call to generate the key-pair.

Warning

Arrays must be sized to QSC_DILITHIUM_PUBLICKEY_SIZE, QSC_DILITHIUM_PRIVATEKEY_SIZE, and the seed to DILITHIUM_SEEDBYTES.

Parameters

publickey	[uint8_t*] Pointer to the public verification-key array.
privatekey	[uint8_t*] Pointer to the private signature-key array.
seed	[const uint8_t*] Pointer to the random seed.

qsc_dilithium_sign()

QSC_EXPORT_API bool qsc_dilithium_sign	(	uint8_t *	signedmsg,
		size_t *	smsglen,
		const uint8_t *	message,
		size_t	msglen,
		const uint8_t *	privatekey,
		bool(*	rng_generate )(uint8_t *, size_t) )

Takes the message as input and returns an array containing the signature followed by the message.

Warning

The signed-message array must be sized to the size of the message plus QSC_DILITHIUM_SIGNATURE_SIZE.

Parameters

signedmsg	[uint8_t*] Pointer to the signed-message array.
smsglen	[size_t*] Pointer to the signed message length.
message	[const uint8_t*] Pointer to the message array.
msglen	[size_t] The message array length.
privatekey	[const uint8_t*] Pointer to the private signature-key.
rng_generate	[bool (*)(uint8_t*, size_t)] Pointer to the random generator.

Returns

[bool] Returns true if the message was signed successfully.

qsc_dilithium_sign_ex()

QSC_EXPORT_API bool qsc_dilithium_sign_ex	(	uint8_t *	signedmsg,
		size_t *	smsglen,
		const uint8_t *	message,
		size_t	msglen,
		const uint8_t *	context,
		size_t	ctxlen,
		const uint8_t *	privatekey,
		bool(*	rng_generate )(uint8_t *, size_t) )

Takes the message as input with the additional context parameter, and returns an array containing the signature followed by the message.

Warning

The signed-message array must be sized to the size of the message plus QSC_DILITHIUM_SIGNATURE_SIZE.

Parameters

signedmsg	[uint8_t*] Pointer to the signed-message array.
smsglen	[size_t*] Pointer to the signed message length.
message	[const uint8_t*] Pointer to the message array.
msglen	[size_t] The message array length.
context	[const uint8_t*] Pointer to the context array.
ctxlen	[size_t] The context array length.
privatekey	[const uint8_t*] Pointer to the private signature-key.
rng_generate	[bool (*)(uint8_t*, size_t)] Pointer to the random generator.

Returns

[bool] Returns true if the message was signed successfully.

qsc_dilithium_verify()

QSC_EXPORT_API bool qsc_dilithium_verify	(	uint8_t *	message,
		size_t *	msglen,
		const uint8_t *	signedmsg,
		size_t	smsglen,
		const uint8_t *	publickey )

Verifies a signature-message pair with the public key.

Parameters

message	[uint8_t*] Pointer to the message output array.
msglen	[size_t*] Pointer to the length of the message array.
signedmsg	[const uint8_t*] Pointer to the signed message array.
smsglen	[size_t] The signed message length.
publickey	[const uint8_t*] Pointer to the public verification-key array.

Returns

[bool] Returns true if the signature is valid.

qsc_dilithium_verify_ex()

QSC_EXPORT_API bool qsc_dilithium_verify_ex	(	uint8_t *	message,
		size_t *	msglen,
		const uint8_t *	context,
		size_t	ctxlen,
		const uint8_t *	signedmsg,
		size_t	smsglen,
		const uint8_t *	publickey )

Verifies a signature-message pair and context parameter with the public key.

Parameters

message	[uint8_t*] Pointer to the message output array.
msglen	[size_t*] Pointer to the length of the message array.
context	[const uint8_t*] Pointer to the context array.
ctxlen	[size_t] The context array length.
signedmsg	[const uint8_t*] Pointer to the signed message array.
smsglen	[size_t] The signed message length.
publickey	[const uint8_t*] Pointer to the public verification-key array.

Returns

[bool] Returns true if the signature is valid.