ISARA Radiate Security Solution Suite's Dilithium Signature scheme. More...

Typedefs
typedef struct iqr_DilithiumParams_struct	iqr_DilithiumParams

typedef struct iqr_DilithiumPublicKey_struct	iqr_DilithiumPublicKey

typedef struct iqr_DilithiumPrivateKey_struct	iqr_DilithiumPrivateKey

typedef struct iqr_DilithiumVariant_struct	iqr_DilithiumVariant

Functions
IQR_API iqr_retval	iqr_DilithiumCreateParams (const iqr_Context ctx, const iqr_DilithiumVariant variant, iqr_DilithiumParams **params)

IQR_API_UNENFORCED_RETURN iqr_retval	iqr_DilithiumDestroyParams (iqr_DilithiumParams **params)

IQR_API iqr_retval	iqr_DilithiumCreateKeyPair (const iqr_DilithiumParams params, const iqr_RNG rng, iqr_DilithiumPublicKey public_key, iqr_DilithiumPrivateKey private_key)

IQR_API iqr_retval	iqr_DilithiumImportPublicKey (const iqr_DilithiumParams params, const uint8_t buf, size_t buf_size, iqr_DilithiumPublicKey **public_key)

IQR_API iqr_retval	iqr_DilithiumImportPrivateKey (const iqr_DilithiumParams params, const uint8_t buf, size_t buf_size, iqr_DilithiumPrivateKey **private_key)

IQR_API iqr_retval	iqr_DilithiumExportPublicKey (const iqr_DilithiumPublicKey public_key, uint8_t buf, size_t buf_size)

IQR_API iqr_retval	iqr_DilithiumExportPrivateKey (const iqr_DilithiumPrivateKey private_key, uint8_t buf, size_t buf_size)

IQR_API_UNENFORCED_RETURN iqr_retval	iqr_DilithiumDestroyPublicKey (iqr_DilithiumPublicKey **public_key)

IQR_API_UNENFORCED_RETURN iqr_retval	iqr_DilithiumDestroyPrivateKey (iqr_DilithiumPrivateKey **private_key)

IQR_API iqr_retval	iqr_DilithiumGetPublicKeySize (const iqr_DilithiumParams params, size_t public_key_size)

IQR_API iqr_retval	iqr_DilithiumGetPrivateKeySize (const iqr_DilithiumParams params, size_t private_key_size)

IQR_API iqr_retval	iqr_DilithiumGetSignatureSize (const iqr_DilithiumParams params, size_t sig_size)

IQR_API iqr_retval	iqr_DilithiumSign (const iqr_DilithiumPrivateKey private_key, const uint8_t message, size_t message_size, uint8_t *sig, size_t sig_size)

IQR_API iqr_retval	iqr_DilithiumVerify (const iqr_DilithiumPublicKey public_key, const uint8_t message, size_t message_size, const uint8_t *sig, size_t sig_size)

Variables
IQR_EXTERN const iqr_DilithiumVariant	IQR_DILITHIUM_128

IQR_EXTERN const iqr_DilithiumVariant	IQR_DILITHIUM_160

Typedef Documentation

◆ iqr_DilithiumParams

typedef struct iqr_DilithiumParams_struct iqr_DilithiumParams

The algorithm's domain parameters.

◆ iqr_DilithiumPrivateKey

typedef struct iqr_DilithiumPrivateKey_struct iqr_DilithiumPrivateKey

The Dilithium private key.

◆ iqr_DilithiumPublicKey

typedef struct iqr_DilithiumPublicKey_struct iqr_DilithiumPublicKey

The Dilithium public key.

◆ iqr_DilithiumVariant

typedef struct iqr_DilithiumVariant_struct iqr_DilithiumVariant

The Dilithium variant. This controls the amount of security.

Function Documentation

◆ iqr_DilithiumCreateKeyPair()

IQR_API iqr_retval iqr_DilithiumCreateKeyPair	(	const iqr_DilithiumParams *	params,
		const iqr_RNG *	rng,
		iqr_DilithiumPublicKey **	public_key,
		iqr_DilithiumPrivateKey **	private_key
	)

Generate a Dilithium private/public key pair.

The rng must be initialized before being passed to iqr_DilithiumCreateKeyPair().

*public_key and *private_key must be set to NULL before calling iqr_DilithiumCreateKeyPair().

Parameters

[in]	params	The Dilithium parameters.
[in]	rng	A seeded random number generator.
[out]	public_key	The resulting `iqr_DilithiumPublicKey` object.
[out]	private_key	The resulting `iqr_DilithiumPrivateKey` object.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_DilithiumCreateParams()

IQR_API iqr_retval iqr_DilithiumCreateParams	(	const iqr_Context *	ctx,
		const iqr_DilithiumVariant *	variant,
		iqr_DilithiumParams **	params
	)

Create a parameter object for the Dilithium signature scheme.

*params must be set to NULL before calling iqr_DilithiumCreateParams().

Parameters

[in]	ctx	A Context object.
[in]	variant	The security variant.
[out]	params	The Dilithium parameter object.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_DilithiumDestroyParams()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_DilithiumDestroyParams ( iqr_DilithiumParams ** params )

Clear and deallocate a Dilithium parameter object.

params will be set to NULL prior to returning.

All internal iqr_DilithiumParams buffers are cleared and deallocated during the call to iqr_DilithiumDestroyParams(). The iqr_DilithiumParams object does not store any cryptographic material.

Parameters

[in,out] params The Dilithium instance to destroy.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_DilithiumDestroyPrivateKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_DilithiumDestroyPrivateKey ( iqr_DilithiumPrivateKey ** private_key )

Clear and deallocate a Dilithium private key.

private_key will be set to NULL prior to returning.

The private key's data is cleared before its internal buffers are deallocated.

Parameters

[in,out] private_key The iqr_DilithiumPrivateKey object to destroy.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_DilithiumDestroyPublicKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_DilithiumDestroyPublicKey ( iqr_DilithiumPublicKey ** public_key )

Clear and deallocate a Dilithium public key.

public_key will be set to NULL prior to returning.

Parameters

[in,out] public_key The iqr_DilithiumPublicKey object to destroy.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_DilithiumExportPrivateKey()

IQR_API iqr_retval iqr_DilithiumExportPrivateKey	(	const iqr_DilithiumPrivateKey *	private_key,
		uint8_t *	buf,
		size_t	buf_size
	)

Export the Dilithium private key's data into a buffer.

Be sure to safely wipe and discard buf when you're done using it.

Parameters

[in]	private_key	The private key object.
[out]	buf	The destination buffer.
[in]	buf_size	The size of buf in bytes. Must be exactly the size returned by `iqr_DilithiumGetPrivateKeySize()`.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_DilithiumExportPublicKey()

IQR_API iqr_retval iqr_DilithiumExportPublicKey	(	const iqr_DilithiumPublicKey *	public_key,
		uint8_t *	buf,
		size_t	buf_size
	)

Export the Dilithium public key's data into a buffer.

Parameters

[in]	public_key	The public key object.
[out]	buf	The destination buffer.
[in]	buf_size	The size of buf in bytes. Must be exactly the size returned by `iqr_DilithiumGetPublicKeySize()`.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_DilithiumGetPrivateKeySize()

IQR_API iqr_retval iqr_DilithiumGetPrivateKeySize	(	const iqr_DilithiumParams *	params,
		size_t *	private_key_size
	)

Get the size of the private key.

Parameters

[in]	params	The `iqr_DilithiumParams` to use.
[out]	private_key_size	The size of the private key in bytes.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_DilithiumGetPublicKeySize()

IQR_API iqr_retval iqr_DilithiumGetPublicKeySize	(	const iqr_DilithiumParams *	params,
		size_t *	public_key_size
	)

Get the size of the public key.

Parameters

[in]	params	The `iqr_DilithiumParams` to use.
[out]	public_key_size	The size of the public key in bytes.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_DilithiumGetSignatureSize()

IQR_API iqr_retval iqr_DilithiumGetSignatureSize	(	const iqr_DilithiumParams *	params,
		size_t *	sig_size
	)

Get the size of the signature.

Parameters

[in]	params	The `iqr_DilithiumParams` to use.
[out]	sig_size	The size of the signature in bytes.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_DilithiumImportPrivateKey()

IQR_API iqr_retval iqr_DilithiumImportPrivateKey	(	const iqr_DilithiumParams *	params,
		const uint8_t *	buf,
		size_t	buf_size,
		iqr_DilithiumPrivateKey **	private_key
	)

Import a Dilithium private key object from a buffer.

Note: This function only accepts data that has been generated by iqr_DilithiumExportPrivateKey(). There is currently no standard for saving Dilithium private keys.

*private_key must be set to NULL before calling iqr_DilithiumImportPrivateKey(). Be sure to safely wipe and discard buf after calling this function.

Parameters

[in]	params	The Dilithium parameters. Must be the same as when the keys were created.
[in]	buf	A buffer that contains a private key.
[in]	buf_size	The size of buf in bytes. Must be exactly the size returned by `iqr_DilithiumGetPrivateKeySize()`.
[out]	private_key	The resulting `iqr_DilithiumPrivateKey` object.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_DilithiumImportPublicKey()

IQR_API iqr_retval iqr_DilithiumImportPublicKey	(	const iqr_DilithiumParams *	params,
		const uint8_t *	buf,
		size_t	buf_size,
		iqr_DilithiumPublicKey **	public_key
	)

Import a Dilithium public key object from a buffer.

Note: This function only accepts data that has been generated by iqr_DilithiumExportPublicKey(). There is currently no standard for saving Dilithium public keys.

*public_key must be set to NULL before calling iqr_DilithiumImportPublicKey().

Parameters

[in]	params	The Dilithium parameters. Must be the same as when the keys were created.
[in]	buf	A buffer that contains a public key.
[in]	buf_size	The size of buf in bytes. Must be exactly the size returned by `iqr_DilithiumGetPublicKeySize()`.
[out]	public_key	The resulting `iqr_DilithiumPublicKey` object.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_DilithiumSign()

IQR_API iqr_retval iqr_DilithiumSign	(	const iqr_DilithiumPrivateKey *	private_key,
		const uint8_t *	message,
		size_t	message_size,
		uint8_t *	sig,
		size_t	sig_size
	)

Sign a message using a Dilithium private key.

Note: If the message is a digest of a hash function it should be 48 bytes or longer to be quantum-safe.; You must register a SHA3-512 implementation by calling iqr_HashRegisterCallbacks() before using the Dilithium API.

All internal buffers are cleared and deallocated before iqr_DilithiumSign() returns.

Parameters

[in]	private_key	The private key.
[in]	message	The message to be signed.
[in]	message_size	The size of message in bytes.
[out]	sig	The buffer receiving the resulting signature.
[in]	sig_size	The size of sig in bytes. Must be exactly the size returned by `iqr_DilithiumGetSignatureSize()`.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

◆ iqr_DilithiumVerify()

IQR_API iqr_retval iqr_DilithiumVerify	(	const iqr_DilithiumPublicKey *	public_key,
		const uint8_t *	message,
		size_t	message_size,
		const uint8_t *	sig,
		size_t	sig_size
	)

Verify the signature of a message using a Dilithium public key.

Note: If the message is a digest of a hash function it should be 48 bytes or longer to be quantum-safe.; You must register a SHA3-512 implementation by calling iqr_HashRegisterCallbacks() before using the Dilithium API.

All internal buffers are cleared and deallocated before iqr_DilithiumVerify() returns.

Parameters

[in]	public_key	The public key.
[in]	message	The message to verify.
[in]	message_size	The size of message in bytes.
[in]	sig	The signature to verify.
[in]	sig_size	The size of sig in bytes. Must be exactly the size returned by `iqr_DilithiumGetSignatureSize`.

Returns: IQR_OK on success, or a value from iqr_retval.h when an error occurs.

Variable Documentation

◆ IQR_DILITHIUM_128

IQR_EXTERN const iqr_DilithiumVariant IQR_DILITHIUM_128

128 bit quantum security (138 bit classical security) variant.

◆ IQR_DILITHIUM_160

IQR_EXTERN const iqr_DilithiumVariant IQR_DILITHIUM_160

160 bit quantum security (176 bit classical security) variant.

Detailed Description

ISARA Radiate Security Solution Suite's Dilithium Signature scheme.

An implementation of CRYSTALS Dilithium signature scheme as defined in CRYSTALS - Dilithium.

License: The code and other content set out herein is not in the public domain, is considered a trade secret and is confidential to ISARA Corporation. Use, reproduction or distribution, in whole or in part, of such code or other content is strictly prohibited except by express written permission of ISARA Corporation. Please contact ISARA Corporation at info@.nosp@m.isar.nosp@m.a.com for more information.

ISARA Radiate Security Solution Suite Toolkit Edition Version 1.5

Typedefs

Functions

Variables

Typedef Documentation

◆ iqr_DilithiumParams

◆ iqr_DilithiumPrivateKey

◆ iqr_DilithiumPublicKey

◆ iqr_DilithiumVariant

Function Documentation

◆ iqr_DilithiumCreateKeyPair()

◆ iqr_DilithiumCreateParams()

◆ iqr_DilithiumDestroyParams()

◆ iqr_DilithiumDestroyPrivateKey()

◆ iqr_DilithiumDestroyPublicKey()

◆ iqr_DilithiumExportPrivateKey()

◆ iqr_DilithiumExportPublicKey()

◆ iqr_DilithiumGetPrivateKeySize()

◆ iqr_DilithiumGetPublicKeySize()

◆ iqr_DilithiumGetSignatureSize()

◆ iqr_DilithiumImportPrivateKey()

◆ iqr_DilithiumImportPublicKey()

◆ iqr_DilithiumSign()

◆ iqr_DilithiumVerify()

Variable Documentation

◆ IQR_DILITHIUM_128

◆ IQR_DILITHIUM_160

Detailed Description