ISARA Radiate Security Solution Suite's McEliece QC-MDPC KEM. More...

Macros
#define	IQR_MCELIECE_SHARED_KEY_SIZE 32

#define	IQR_MCELIECE_CIPHERTEXT_SIZE 8225

#define	IQR_MCELIECE_PUBLIC_KEY_SIZE 4097

#define	IQR_MCELIECE_PRIVATE_KEY_SIZE 548

Typedefs
typedef struct iqr_McElieceParams_struct	iqr_McElieceParams

typedef struct iqr_McEliecePublicKey_struct	iqr_McEliecePublicKey

typedef struct iqr_McEliecePrivateKey_struct	iqr_McEliecePrivateKey

Functions
IQR_API iqr_retval	iqr_McElieceCreateParams (const iqr_Context ctx, iqr_HashAlgorithmType hash_algo, iqr_McElieceParams *params)

IQR_API_UNENFORCED_RETURN iqr_retval	iqr_McElieceDestroyParams (iqr_McElieceParams **params)

IQR_API iqr_retval	iqr_McElieceCreateKeyPair (const iqr_McElieceParams params, const iqr_RNG rng, iqr_McEliecePublicKey public_key, iqr_McEliecePrivateKey private_key)

IQR_API iqr_retval	iqr_McElieceImportPublicKey (const iqr_McElieceParams params, const uint8_t buf, size_t buf_size, iqr_McEliecePublicKey **public_key)

IQR_API iqr_retval	iqr_McElieceImportPrivateKey (const iqr_McElieceParams params, const uint8_t buf, size_t buf_size, iqr_McEliecePrivateKey **private_key)

IQR_API iqr_retval	iqr_McElieceExportPublicKey (const iqr_McEliecePublicKey public_key, uint8_t buf, size_t buf_size)

IQR_API iqr_retval	iqr_McElieceExportPrivateKey (const iqr_McEliecePrivateKey private_key, uint8_t buf, size_t buf_size)

IQR_API_UNENFORCED_RETURN iqr_retval	iqr_McElieceDestroyPublicKey (iqr_McEliecePublicKey **public_key)

IQR_API_UNENFORCED_RETURN iqr_retval	iqr_McElieceDestroyPrivateKey (iqr_McEliecePrivateKey **private_key)

IQR_API iqr_retval	iqr_McElieceEncapsulate (const iqr_McEliecePublicKey public_key, const iqr_RNG rng, uint8_t ciphertext, size_t ciphertext_size, uint8_t shared_key, size_t shared_key_size)

IQR_API iqr_retval	iqr_McElieceDecapsulate (const iqr_McEliecePrivateKey private_key, const uint8_t ciphertext, size_t ciphertext_size, uint8_t *shared_key, size_t shared_key_size)

Macro Definition Documentation

◆ IQR_MCELIECE_CIPHERTEXT_SIZE

#define IQR_MCELIECE_CIPHERTEXT_SIZE 8225

The size of the ciphertext produced by the McEliece KEM in bytes.

◆ IQR_MCELIECE_PRIVATE_KEY_SIZE

#define IQR_MCELIECE_PRIVATE_KEY_SIZE 548

The size of the McEliece private key in bytes.

◆ IQR_MCELIECE_PUBLIC_KEY_SIZE

#define IQR_MCELIECE_PUBLIC_KEY_SIZE 4097

The size of the McEliece public key in bytes (32771 bits).

◆ IQR_MCELIECE_SHARED_KEY_SIZE

#define IQR_MCELIECE_SHARED_KEY_SIZE 32

The size of the shared key produced by the McEliece KEM in bytes.

Typedef Documentation

◆ iqr_McElieceParams

typedef struct iqr_McElieceParams_struct iqr_McElieceParams

McEliece QC-MDPC parameters.

◆ iqr_McEliecePrivateKey

typedef struct iqr_McEliecePrivateKey_struct iqr_McEliecePrivateKey

McEliece QC-MDPC private key.

◆ iqr_McEliecePublicKey

typedef struct iqr_McEliecePublicKey_struct iqr_McEliecePublicKey

McEliece QC-MDPC public key.

Function Documentation

◆ iqr_McElieceCreateKeyPair()

IQR_API iqr_retval iqr_McElieceCreateKeyPair	(	const iqr_McElieceParams *	params,
		const iqr_RNG *	rng,
		iqr_McEliecePublicKey **	public_key,
		iqr_McEliecePrivateKey **	private_key
	)

Generate a McEliece QC-MDPC private/public key pair.

Note: If iqr_McElieceCreateKeyPair() returns IQR_ERESEED, your random number generator isn't producing uniformly random values. Use a cryptographically strong RNG (such as HMAC-DRBG) with sufficient entropy.

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

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

Parameters

[in]	params	The McEliece QC-MDPC parameters.
[in]	rng	A seeded random number generator.
[out]	public_key	The resulting `iqr_McEliecePublicKey` object.
[out]	private_key	The resulting `iqr_McEliecePrivateKey` object.

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

◆ iqr_McElieceCreateParams()

IQR_API iqr_retval iqr_McElieceCreateParams	(	const iqr_Context *	ctx,
		iqr_HashAlgorithmType	hash_algo,
		iqr_McElieceParams **	params
	)

Create a parameter object for the McEliece QC-MDPC KEM.

As per the paper mentioned above (Misoczki et al.), this set of parameters includes n_0, n, r, w, t, and the public key size. The parameter set that is used by the toolkit is: n_0 = 2, n = 65542, r = 32771, w = 274, t = 264, and public key size = 32771 (bits). Note that the value for n is also the size of the private key in bits.

This parameter set provides 256 bit classical security and 128 bit quantum security.

You must call iqr_HashRegisterCallbacks() to set the Hash implementation for hash_algo before calling this function.

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

Parameters

[in]	ctx	A Context object.
[in]	hash_algo	The Hash algorithm to use for the KEM.
[out]	params	The McEliece QC-MDPC parameter object.

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

◆ iqr_McElieceDecapsulate()

IQR_API iqr_retval iqr_McElieceDecapsulate	(	const iqr_McEliecePrivateKey *	private_key,
		const uint8_t *	ciphertext,
		size_t	ciphertext_size,
		uint8_t *	shared_key,
		size_t	shared_key_size
	)

McEliece decapsulation.

Creates a shared key from a ciphertext. This will be the same shared key that was generated by iqr_McElieceEncapsulate() when the ciphertext was created.

The McEliece QC-MDPC KEM is CPA secure, but not CCA2 secure. Re-using the private key is insecure.

All internal buffers are cleared and deallocated before the call to iqr_McElieceDecapsulate() returns. Be sure to safely wipe and deallocate the shared_key when you're done with it.

Parameters

[in]	private_key	Input private key.
[in]	ciphertext	The input ciphertext.
[in]	ciphertext_size	The size of ciphertext in bytes. Must be exactly `IQR_MCELIECE_CIPHERTEXT_SIZE` bytes.
[out]	shared_key	The resulting shared key.
[in]	shared_key_size	The size of shared_key in bytes. Must be exactly `IQR_MCELIECE_SHARED_KEY_SIZE` bytes.

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

◆ iqr_McElieceDestroyParams()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_McElieceDestroyParams ( iqr_McElieceParams ** params )

Clear and deallocate a McEliece QC-MDPC parameter object.

params will be set to NULL prior to returning.

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

Parameters

[in,out] params The McEliece QC-MDPC parameter object to destroy.

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

◆ iqr_McElieceDestroyPrivateKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_McElieceDestroyPrivateKey ( iqr_McEliecePrivateKey ** private_key )

Clear and deallocate a McEliece QC-MDPC 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_McEliecePrivateKey object to destroy.

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

◆ iqr_McElieceDestroyPublicKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_McElieceDestroyPublicKey ( iqr_McEliecePublicKey ** public_key )

Clear and deallocate a McEliece QC-MDPC public key.

public_key will be set to NULL prior to returning.

Parameters

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

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

◆ iqr_McElieceEncapsulate()

IQR_API iqr_retval iqr_McElieceEncapsulate	(	const iqr_McEliecePublicKey *	public_key,
		const iqr_RNG *	rng,
		uint8_t *	ciphertext,
		size_t	ciphertext_size,
		uint8_t *	shared_key,
		size_t	shared_key_size
	)

McEliece encapsulation.

Creates a shared key and a ciphertext. When iqr_McElieceDecapsulate() is called on the ciphertext and corresponding private key the same shared key will be generated.

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

All internal buffers are cleared and deallocated before the call to iqr_McElieceEncapsulate() returns. Be sure to safely wipe and deallocate the shared_key when you're done with it.

Parameters

[in]	public_key	Input public key.
[in]	rng	A seeded random number generator.
[out]	ciphertext	The resulting ciphertext.
[in]	ciphertext_size	The size of ciphertext in bytes. Must be exactly `IQR_MCELIECE_CIPHERTEXT_SIZE` bytes.
[out]	shared_key	The resulting shared key.
[in]	shared_key_size	The size of shared_key in bytes. Must be exactly `IQR_MCELIECE_SHARED_KEY_SIZE` bytes.

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

◆ iqr_McElieceExportPrivateKey()

IQR_API iqr_retval iqr_McElieceExportPrivateKey	(	const iqr_McEliecePrivateKey *	private_key,
		uint8_t *	buf,
		size_t	buf_size
	)

Export the McEliece QC-MDPC private key's data into a buffer.

The McEliece QC-MDPC KEM is CPA secure, but not CCA2 secure. Re-using the private key is insecure.

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 `IQR_MCELIECE_PRIVATE_KEY_SIZE` bytes.

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

◆ iqr_McElieceExportPublicKey()

IQR_API iqr_retval iqr_McElieceExportPublicKey	(	const iqr_McEliecePublicKey *	public_key,
		uint8_t *	buf,
		size_t	buf_size
	)

Export the McEliece QC-MDPC 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 `IQR_MCELIECE_PUBLIC_KEY_SIZE` bytes.

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

◆ iqr_McElieceImportPrivateKey()

IQR_API iqr_retval iqr_McElieceImportPrivateKey	(	const iqr_McElieceParams *	params,
		const uint8_t *	buf,
		size_t	buf_size,
		iqr_McEliecePrivateKey **	private_key
	)

Import a McEliece QC-MDPC private key object from a buffer.

The McEliece QC-MDPC KEM is CPA secure, but not CCA2 secure. Re-using the private key is insecure.

Note: This function only accepts data that has been generated by iqr_McElieceExportPrivateKey(). There is currently no standard for saving McEliece QC-MDPC private keys.

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

Parameters

[in]	params	The McEliece QC-MDPC parameters. Must be created with the same hash algorithm 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 `IQR_MCELIECE_PRIVATE_KEY_SIZE` bytes.
[out]	private_key	The resulting `iqr_McEliecePrivateKey` object.

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

◆ iqr_McElieceImportPublicKey()

IQR_API iqr_retval iqr_McElieceImportPublicKey	(	const iqr_McElieceParams *	params,
		const uint8_t *	buf,
		size_t	buf_size,
		iqr_McEliecePublicKey **	public_key
	)

Import a McEliece QC-MDPC public key object from a buffer.

Note: This function only accepts data that has been generated by iqr_McElieceExportPublicKey(). There is currently no standard for saving McEliece QC-MDPC public keys.

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

Parameters

[in]	params	The McEliece QC-MDPC parameters. Must be created with the same hash algorithm 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 `IQR_MCELIECE_PUBLIC_KEY_SIZE` bytes.
[out]	public_key	The resulting `iqr_McEliecePublicKey` object.

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

Detailed Description

ISARA Radiate Security Solution Suite's McEliece QC-MDPC KEM.

The McEliece QC-MDPC (Quasi-Cyclic Moderate Density Parity-Check) cryptographic system and the KEM implementation are described in the NIST PQC submission "QC-MDPC KEM".

This header contains the functions and parameters necessary to do key encapsulation and decapsulation using McEliece QC-MDPC. The two main functions are iqr_McElieceEncapsulate() and iqr_McElieceDecapsulate(). The rest of the functions let you create and manipulate McEliece QC-MDPC parameters and keys.

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

Macros

Typedefs

Functions

Macro Definition Documentation

◆ IQR_MCELIECE_CIPHERTEXT_SIZE

◆ IQR_MCELIECE_PRIVATE_KEY_SIZE

◆ IQR_MCELIECE_PUBLIC_KEY_SIZE

◆ IQR_MCELIECE_SHARED_KEY_SIZE

Typedef Documentation

◆ iqr_McElieceParams

◆ iqr_McEliecePrivateKey

◆ iqr_McEliecePublicKey

Function Documentation

◆ iqr_McElieceCreateKeyPair()

◆ iqr_McElieceCreateParams()

◆ iqr_McElieceDecapsulate()

◆ iqr_McElieceDestroyParams()

◆ iqr_McElieceDestroyPrivateKey()

◆ iqr_McElieceDestroyPublicKey()

◆ iqr_McElieceEncapsulate()

◆ iqr_McElieceExportPrivateKey()

◆ iqr_McElieceExportPublicKey()

◆ iqr_McElieceImportPrivateKey()

◆ iqr_McElieceImportPublicKey()

Detailed Description