iqr_mceliece.h File Reference

Typedefs
typedef struct iqr_McElieceParams_struct	iqr_McElieceParams
typedef struct iqr_McEliecePublicKey_struct	iqr_McEliecePublicKey
typedef struct iqr_McEliecePrivateKey_struct	iqr_McEliecePrivateKey

Enumerations
enum	iqr_McElieceKeySize {   IQR_MCELIECE_PUBKEY9857 = 0,   IQR_MCELIECE_PUBKEY14866 = 1,   IQR_MCELIECE_PUBKEY20409 = 2,   IQR_MCELIECE_PUBKEY32771 = 3,   IQR_MCELIECE_PUBKEY45062 = 4,   IQR_MCELIECE_PUBKEY61449 = 5 }

Functions
IQR_API iqr_retval	iqr_McElieceCreateParams (const iqr_Context *ctx, iqr_HashAlgorithmType hash_algo, iqr_McElieceKeySize public_key_size, 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 **pub_key, iqr_McEliecePrivateKey **priv_key)
IQR_API iqr_retval	iqr_McElieceGetPublicKeySize (const iqr_McEliecePublicKey *pub_key, size_t *size)
IQR_API iqr_retval	iqr_McElieceGetPrivateKeySize (const iqr_McEliecePrivateKey *priv_key, size_t *size)
IQR_API iqr_retval	iqr_McElieceGetPublicKeyParams (const iqr_McEliecePublicKey *pub_key, iqr_McElieceParams **params)
IQR_API iqr_retval	iqr_McElieceGetPrivateKeyParams (const iqr_McEliecePrivateKey *priv_key, iqr_McElieceParams **params)
IQR_API iqr_retval	iqr_McElieceImportPublicKey (const iqr_McElieceParams *params, const uint8_t *data, size_t size, iqr_McEliecePublicKey **pub_key)
IQR_API iqr_retval	iqr_McElieceImportPrivateKey (const iqr_McElieceParams *params, const uint8_t *data, size_t size, iqr_McEliecePrivateKey **priv_key)
IQR_API iqr_retval	iqr_McElieceExportPublicKey (const iqr_McEliecePublicKey *pub_key, uint8_t *buf, size_t buf_size)
IQR_API iqr_retval	iqr_McElieceExportPrivateKey (const iqr_McEliecePrivateKey *priv_key, uint8_t *buf, size_t buf_size)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_McElieceDestroyPublicKey (iqr_McEliecePublicKey **pub_key)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_McElieceDestroyPrivateKey (iqr_McEliecePrivateKey **priv_key)
IQR_API iqr_retval	iqr_McElieceGetCiphertextSize (const iqr_McElieceParams *params, size_t plaintext_size, size_t *ciphertext_size)
IQR_API iqr_retval	iqr_McElieceGetPlaintextSize (const iqr_McElieceParams *params, size_t ciphertext_size, size_t *plaintext_size)
IQR_API iqr_retval	iqr_McElieceEncrypt (const iqr_McEliecePublicKey *pub_key, const iqr_RNG *rng, const uint8_t *plaintext, size_t plaintext_size, uint8_t *ciphertext, size_t ciphertext_size)
IQR_API iqr_retval	iqr_McElieceDecrypt (const iqr_McEliecePrivateKey *priv_key, const uint8_t *ciphertext, size_t ciphertext_size, uint8_t *plaintext, size_t *plaintext_size)

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.

Enumeration Type Documentation

iqr_McElieceKeySize

enum iqr_McElieceKeySize

Supported public key sizes.

These are all of the supported public key sizes in bits for security level 128 bits and 256 bits, as documented in the paper mentioned above. Each key size corresponds uniquely to a set of QC-MDPC parameters.

Enumerator
IQR_MCELIECE_PUBKEY9857	128 bits of security.
IQR_MCELIECE_PUBKEY14866	128 bits of security.
IQR_MCELIECE_PUBKEY20409	128 bits of security.
IQR_MCELIECE_PUBKEY32771	256 bits of security.
IQR_MCELIECE_PUBKEY45062	256 bits of security.
IQR_MCELIECE_PUBKEY61449	256 bits of security.

Function Documentation

iqr_McElieceCreateKeyPair()

IQR_API iqr_retval iqr_McElieceCreateKeyPair	(	const iqr_McElieceParams *	params,
		const iqr_RNG *	rng,
		iqr_McEliecePublicKey **	pub_key,
		iqr_McEliecePrivateKey **	priv_key
	)

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

If IQR_EBADVALUE is encountered, you may consider trying this function again with a different rng, or reseeding the current rng.

Parameters

[in]	params	The McEliece QC-MDPC parameters.
[in]	rng	A seeded random number generator object.
[out]	pub_key	The resulting iqr_McEliecePublicKey object.
[out]	priv_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_McElieceKeySize	public_key_size,
		iqr_McElieceParams **	params
	)

Create a parameter object for the McEliece QC-MDPC cryptographic system.

As per the paper, this set of parameters includes n_0, n, r, w, and t.

Since each public key size uniquely maps to a set of QC-MDPC parameters, a set of parameters is chosen by specifying a public key size. See Table 2 in the paper for this mapping.

It's up to the user to manage domain parameters; the parameter data is not exposed in stored keys or encrypted data.

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

Parameters

[in]	ctx	A Context object.
[in]	hash_algo	The Hash algorithm to use for the CCA2 conversion.
[in]	public_key_size	The size of the public key. If the key size is not supported, then error value IQR_EOUTOFRANGE is returned.
[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_McElieceDecrypt()

IQR_API iqr_retval iqr_McElieceDecrypt	(	const iqr_McEliecePrivateKey *	priv_key,
		const uint8_t *	ciphertext,
		size_t	ciphertext_size,
		uint8_t *	plaintext,
		size_t *	plaintext_size
	)

Decrypt the ciphertext using a McEliece QC-MDPC private key.

The McEliece cryptosystem's decryption algorithm is probabilistic; there is a chance for the decryption to randomly fail. If failure happens, IQR_EDECRYPTIONFAILED is returned.

Code using this cryptosystem must consider the probabilistic factor and decide how to process this failure. For instance, the decryption entity may ask the encryption entity to re-encrypt the plaintext and resend it. Since the new ciphertext is different from the old one (due to the randomization process in the CCA2 conversion layer used in our McEliece implementation), the decryption process would likely succeed.

Parameters

[in]	priv_key	The private key object.
[in]	ciphertext	Ciphertext to be encrypted.
[in]	ciphertext_size	Size of the ciphertext in bytes. Cannot be 0.
[out]	plaintext	The resulting plaintext.
[in,out]	plaintext_size	As input, the size of plaintext buffer. This can be the value returned by iqr_McElieceGetPlaintextSize(), which, as per note on iqr_McElieceGetPlaintextSize(), could be larger than the size of the original plaintext. Cannot be 0. As output, the size, in bytes, of the actual message contained in plaintext buffer.

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.

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 **

priv_key

)

Clear and deallocate a McEliece QC-MDPC private key.

priv_key will be set to NULL prior to returning.

Parameters

[in,out]

priv_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 **

pub_key

)

Clear and deallocate a McEliece QC-MDPC public key.

pub_key will be set to NULL prior to returning.

Parameters

[in,out]

pub_key

The iqr_McEliecePublicKey object to destroy.

Returns

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

iqr_McElieceEncrypt()

IQR_API iqr_retval iqr_McElieceEncrypt	(	const iqr_McEliecePublicKey *	pub_key,
		const iqr_RNG *	rng,
		const uint8_t *	plaintext,
		size_t	plaintext_size,
		uint8_t *	ciphertext,
		size_t	ciphertext_size
	)

Encrypt the plaintext using a McEliece QC-MDPC public key.

Note

This cryptosystem implements a security feature which encrypts all plaintexts with sizes smaller than a threshold (which depends on the keysize and the hash digest size) to ciphertexts of the same size. This many-to-one mapping provides the benefit that given the size of a ciphertext, an attacker cannot learn the size of the corresponding plaintext as long as the size of the plaintext is smaller than the threshold.

This cryptosystem also implements a feature that enables it to encrypt plaintexts of arbitrary sizes (except 0 bytes).

Parameters

[in]	pub_key	The public key object.
[in]	rng	A seeded random number generator object.
[in]	plaintext	The plaintext to encrypt.
[in]	plaintext_size	Size of the plaintext in bytes. Cannot be 0.
[out]	ciphertext	The resulting ciphertext.
[in]	ciphertext_size	The size of ciphertext buffer. This must be the value returned by iqr_McElieceGetCiphertextSize().

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 *	priv_key,
		uint8_t *	buf,
		size_t	buf_size
	)

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

Parameters

[in]	priv_key	The private key object.
[out]	buf	The destination buffer.
[in]	buf_size	The size of buf in bytes. This must be the value returned by iqr_McElieceGetPrivateKeySize().

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 *	pub_key,
		uint8_t *	buf,
		size_t	buf_size
	)

Copy a McEliece QC-MDPC public key's data into a buffer.

Parameters

[in]	pub_key	The public key object.
[out]	buf	The destination buffer.
[in]	buf_size	The size of buf in bytes. This must be the value returned by iqr_McElieceGetPublicKeySize().

Returns

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

iqr_McElieceGetCiphertextSize()

IQR_API iqr_retval iqr_McElieceGetCiphertextSize	(	const iqr_McElieceParams *	params,
		size_t	plaintext_size,
		size_t *	ciphertext_size
	)

Get the size of the resulting ciphertext given the size of a plaintext.

Call this function before using iqr_McElieceEncrypt() to get the size of the ciphertext, so you can allocate a buffer large enough to hold the resulting ciphertext.

This step is needed because ciphertext size is not equal to the corresponding plaintext size, and the rate of change of ciphertext size may be different from that of plaintext size due to the underlying CCA2 conversion layer.

Parameters

[in]	params	The McEliece QC-MDPC parameters.
[in]	plaintext_size	Size of the plaintext in bytes. Cannot be 0.
[out]	ciphertext_size	Size of the resulting ciphertext in bytes.

Returns

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

iqr_McElieceGetPlaintextSize()

IQR_API iqr_retval iqr_McElieceGetPlaintextSize	(	const iqr_McElieceParams *	params,
		size_t	ciphertext_size,
		size_t *	plaintext_size
	)

Get the size of the resulting plaintext given the size of a ciphertext.

Call this function before using iqr_McElieceDecrypt() to get the size of the plaintext, so you can allocate a buffer large enough to hold the resulting plaintext.

This step is needed because ciphertext size is not equal to the corresponding plaintext size, and the rate of change of ciphertext size may be different from that of plaintext size due to the underlying CCA2 conversion layer.

Note

The plaintext size returned by this function may be larger than the size of the original plaintext thanks to the fact that this cryptosystem encrypts all messages with size smaller than a threshold to ciphertexts of the same size. See note on iqr_McElieceEncrypt(). In the case that the plaintext size is smaller than the threshold, the only time one can get the exact size is after ciphertext decryption.

Parameters

[in]	params	The McEliece QC-MDPC parameters.
[in]	ciphertext_size	Size of the ciphertext in bytes. Cannot be 0.
[out]	plaintext_size	Maximum possible size of the plaintext in bytes.

Returns

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

iqr_McElieceGetPrivateKeyParams()

IQR_API iqr_retval iqr_McElieceGetPrivateKeyParams	(	const iqr_McEliecePrivateKey *	priv_key,
		iqr_McElieceParams **	params
	)

Retrieve the McEliece QC-MDPC parameters from a private key.

Parameters

[in]	priv_key	The private key.
[out]	params	The resulting iqr_McElieceParams object.

Returns

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

iqr_McElieceGetPrivateKeySize()

IQR_API iqr_retval iqr_McElieceGetPrivateKeySize	(	const iqr_McEliecePrivateKey *	priv_key,
		size_t *	size
	)

Retrieve the size, in bytes, of a McEliece QC-MDPC private key.

Parameters

[in]	priv_key	The private key object.
[out]	size	The resulting size of the priv_key in bytes.

Returns

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

iqr_McElieceGetPublicKeyParams()

IQR_API iqr_retval iqr_McElieceGetPublicKeyParams	(	const iqr_McEliecePublicKey *	pub_key,
		iqr_McElieceParams **	params
	)

Retrieve the McEliece QC-MDPC parameters from a public key.

Parameters

[in]	pub_key	The public key.
[out]	params	The resulting iqr_McElieceParams object.

Returns

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

iqr_McElieceGetPublicKeySize()

IQR_API iqr_retval iqr_McElieceGetPublicKeySize	(	const iqr_McEliecePublicKey *	pub_key,
		size_t *	size
	)

Retrieve the size, in bytes, of a McEliece QC-MDPC public key.

Parameters

[in]	pub_key	The public key object.
[out]	size	The resulting size of the public key in 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 *	data,
		size_t	size,
		iqr_McEliecePrivateKey **	priv_key
	)

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

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.

Parameters

[in]	params	The McEliece QC-MDPC parameters. Must be the same as when the keys were created.
[in]	data	A buffer that contains a private key.
[in]	size	Size, in bytes, of the private key buffer. See iqr_McElieceGetPrivateKeySize(). Cannot be 0.
[out]	priv_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 *	data,
		size_t	size,
		iqr_McEliecePublicKey **	pub_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.

Parameters

[in]	params	The McEliece QC-MDPC parameters. Must be the same as when the keys were created.
[in]	data	A buffer that contains a public key.
[in]	size	Size, in bytes, of the data buffer. See iqr_McElieceGetPublicKeySize(). Cannot be 0.
[out]	pub_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 Toolkit's McEliece QC-MDPC cryptographic system.

The McEliece QC-MDPC (Quasi-Cyclic Moderate Density Parity-Check) cryptographic system is defined by the paper MDPC-McEliece: New McEliece Variants from Moderate Density Parity-Check Codes (Misoczki et al.).

This header contains the functions and parameters necessary to encrypt and decrypt messages using McEliece QC-MDPC. The two main functions are iqr_McElieceEncrypt() and iqr_McElieceDecrypt(). The rest of the functions let you create and manipulate McEliece QC-MDPC parameters and keys.

As part of the McEliece QC-MDPC encryption API, the toolkit uses CCA2 Conversion Gamma on the encrypted message to make McEliece QC-MDPC secure against CCA2 (Adaptive Chosen-Ciphertext Attack). CCA2 Conversion Gamma is defined in Semantically Secure McEliece Public-Key Cryptosystems - Conversions for McEliece PKC (Kobara and Imai).

For the PRNG in CCA2 Conversion Gamma, the toolkit uses HMAC-DRBG with the hash algorithm specified by calling iqr_McElieceCreateParams().

Copyright

Copyright 2015-2016, ISARA Corporation, All Rights Reserved.

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.