iqr_kyber.h File Reference

ISARA Radiate Security Solution Suite's Kyber KEM. More...

Macros
#define	IQR_KYBER_SHARED_KEY_SIZE   32

Typedefs
typedef struct iqr_KyberParams_struct	iqr_KyberParams
typedef struct iqr_KyberPublicKey_struct	iqr_KyberPublicKey
typedef struct iqr_KyberPrivateKey_struct	iqr_KyberPrivateKey
typedef struct iqr_KyberVariant_struct	iqr_KyberVariant

Functions
IQR_API iqr_retval	iqr_KyberCreateParams (const iqr_Context *ctx, const iqr_KyberVariant *variant, iqr_KyberParams **params)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_KyberDestroyParams (iqr_KyberParams **params)
IQR_API iqr_retval	iqr_KyberCreateKeyPair (const iqr_KyberParams *params, const iqr_RNG *rng, iqr_KyberPublicKey **public_key, iqr_KyberPrivateKey **private_key)
IQR_API iqr_retval	iqr_KyberImportPublicKey (const iqr_KyberParams *params, const uint8_t *buf, size_t buf_size, iqr_KyberPublicKey **public_key)
IQR_API iqr_retval	iqr_KyberImportPrivateKey (const iqr_KyberParams *params, const uint8_t *buf, size_t buf_size, iqr_KyberPrivateKey **private_key)
IQR_API iqr_retval	iqr_KyberExportPublicKey (const iqr_KyberPublicKey *public_key, uint8_t *buf, size_t buf_size)
IQR_API iqr_retval	iqr_KyberExportPrivateKey (const iqr_KyberPrivateKey *private_key, uint8_t *buf, size_t buf_size)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_KyberDestroyPublicKey (iqr_KyberPublicKey **public_key)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_KyberDestroyPrivateKey (iqr_KyberPrivateKey **private_key)
IQR_API iqr_retval	iqr_KyberGetPublicKeySize (const iqr_KyberParams *params, size_t *public_key_size)
IQR_API iqr_retval	iqr_KyberGetPrivateKeySize (const iqr_KyberParams *params, size_t *private_key_size)
IQR_API iqr_retval	iqr_KyberGetCiphertextSize (const iqr_KyberParams *params, size_t *ciphertext_size)
IQR_API iqr_retval	iqr_KyberEncapsulate (const iqr_KyberPublicKey *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_KyberDecapsulate (const iqr_KyberPrivateKey *private_key, const uint8_t *ciphertext, size_t ciphertext_size, uint8_t *shared_key, size_t shared_key_size)

Variables
IQR_EXTERN const iqr_KyberVariant	IQR_KYBER_768
IQR_EXTERN const iqr_KyberVariant	IQR_KYBER_1024

Macro Definition Documentation

IQR_KYBER_SHARED_KEY_SIZE

#define IQR_KYBER_SHARED_KEY_SIZE   32

The size of the shared key produced by Kyber in bytes.

Typedef Documentation

iqr_KyberParams

typedef struct iqr_KyberParams_struct iqr_KyberParams

The algorithm's domain parameters.

iqr_KyberPrivateKey

typedef struct iqr_KyberPrivateKey_struct iqr_KyberPrivateKey

The Kyber private key.

iqr_KyberPublicKey

typedef struct iqr_KyberPublicKey_struct iqr_KyberPublicKey

The Kyber public key.

iqr_KyberVariant

typedef struct iqr_KyberVariant_struct iqr_KyberVariant

The Kyber variant. This controls the amount of security.

Function Documentation

iqr_KyberCreateKeyPair()

IQR_API iqr_retval iqr_KyberCreateKeyPair	(	const iqr_KyberParams *	params,
		const iqr_RNG *	rng,
		iqr_KyberPublicKey **	public_key,
		iqr_KyberPrivateKey **	private_key
	)

Generate a Kyber private/public key pair.

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

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

Parameters

[in]	params	The Kyber parameters.
[in]	rng	A seeded random number generator.
[out]	public_key	The resulting iqr_KyberPublicKey object.
[out]	private_key	The resulting iqr_KyberPrivateKey object.

Returns

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

iqr_KyberCreateParams()

IQR_API iqr_retval iqr_KyberCreateParams	(	const iqr_Context *	ctx,
		const iqr_KyberVariant *	variant,
		iqr_KyberParams **	params
	)

Create a parameter object for the Kyber cryptographic system.

Note

You must register SHA3-256 and SHA3-512 implementations by calling iqr_HashRegisterCallbacks() before using the Kyber API.

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

Parameters

[in]	ctx	A Context object.
[in]	variant	iqr_KyberVariant to use.
[out]	params	The Kyber parameter object.

Returns

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

iqr_KyberDecapsulate()

IQR_API iqr_retval iqr_KyberDecapsulate	(	const iqr_KyberPrivateKey *	private_key,
		const uint8_t *	ciphertext,
		size_t	ciphertext_size,
		uint8_t *	shared_key,
		size_t	shared_key_size
	)

Kyber decapsulation.

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

All internal buffers are cleared and deallocated before the call to iqr_KyberDecapsulate() 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 the size returned by iqr_KyberGetCiphertextSize().
[out]	shared_key	The resulting shared key.
[in]	shared_key_size	The size of shared_key in bytes. Must be exactly IQR_KYBER_SHARED_KEY_SIZE bytes.

Returns

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

iqr_KyberDestroyParams()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_KyberDestroyParams

(

iqr_KyberParams **

params

)

Clear and deallocate a Kyber parameter object.

params will be set to NULL prior to returning.

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

Parameters

[in,out]

params

The Kyber parameter object to destroy.

Returns

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

iqr_KyberDestroyPrivateKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_KyberDestroyPrivateKey

(

iqr_KyberPrivateKey **

private_key

)

Clear and deallocate a Kyber 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_KyberPrivateKey object to destroy.

Returns

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

iqr_KyberDestroyPublicKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_KyberDestroyPublicKey

(

iqr_KyberPublicKey **

public_key

)

Clear and deallocate a Kyber public key.

public_key will be set to NULL prior to returning.

Parameters

[in,out]

public_key

The iqr_KyberPublicKey object to destroy.

Returns

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

iqr_KyberEncapsulate()

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

Kyber encapsulation.

Creates a shared key and a ciphertext. When iqr_KyberDecapsulate() 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_KyberEncapsulate().

All internal buffers are cleared and deallocated before the call to iqr_KyberEncapsulate() 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 the size returned by iqr_KyberGetCiphertextSize()
[out]	shared_key	The resulting shared key.
[in]	shared_key_size	The size of shared_key in bytes. Must be exactly IQR_KYBER_SHARED_KEY_SIZE bytes.

Returns

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

iqr_KyberExportPrivateKey()

IQR_API iqr_retval iqr_KyberExportPrivateKey	(	const iqr_KyberPrivateKey *	private_key,
		uint8_t *	buf,
		size_t	buf_size
	)

Export the Kyber 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_KyberGetPrivateKeySize().

Returns

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

iqr_KyberExportPublicKey()

IQR_API iqr_retval iqr_KyberExportPublicKey	(	const iqr_KyberPublicKey *	public_key,
		uint8_t *	buf,
		size_t	buf_size
	)

Export the Kyber 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_KyberGetPublicKeySize().

Returns

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

iqr_KyberGetCiphertextSize()

IQR_API iqr_retval iqr_KyberGetCiphertextSize	(	const iqr_KyberParams *	params,
		size_t *	ciphertext_size
	)

Get the size of the ciphertext.

Parameters

[in]	params	The iqr_KyberParams to use.
[out]	ciphertext_size	The size of the ciphertext in bytes.

Returns

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

iqr_KyberGetPrivateKeySize()

IQR_API iqr_retval iqr_KyberGetPrivateKeySize	(	const iqr_KyberParams *	params,
		size_t *	private_key_size
	)

Get the size of the private key.

Parameters

[in]	params	The iqr_KyberParams 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_KyberGetPublicKeySize()

IQR_API iqr_retval iqr_KyberGetPublicKeySize	(	const iqr_KyberParams *	params,
		size_t *	public_key_size
	)

Get the size of the public key.

Parameters

[in]	params	The iqr_KyberParams 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_KyberImportPrivateKey()

IQR_API iqr_retval iqr_KyberImportPrivateKey	(	const iqr_KyberParams *	params,
		const uint8_t *	buf,
		size_t	buf_size,
		iqr_KyberPrivateKey **	private_key
	)

Import a Kyber private key object from a buffer.

Note

This function only accepts data that has been generated by iqr_KyberExportPrivateKey(). There is currently no standard for saving Kyber private keys.

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

Parameters

[in]	params	The Kyber parameters.
[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_KyberGetPrivateKeySize().
[out]	private_key	The resulting iqr_KyberPrivateKey object.

Returns

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

iqr_KyberImportPublicKey()

IQR_API iqr_retval iqr_KyberImportPublicKey	(	const iqr_KyberParams *	params,
		const uint8_t *	buf,
		size_t	buf_size,
		iqr_KyberPublicKey **	public_key
	)

Import a Kyber public key object from a buffer.

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

Parameters

[in]	params	The Kyber parameters.
[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_KyberGetPublicKeySize().
[out]	public_key	The resulting iqr_KyberPublicKey object.

Returns

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

Variable Documentation

IQR_KYBER_1024

IQR_EXTERN const iqr_KyberVariant IQR_KYBER_1024

224 bit quantum security variant.

IQR_KYBER_768

IQR_EXTERN const iqr_KyberVariant IQR_KYBER_768

160 bit quantum security variant.

Detailed Description

ISARA Radiate Security Solution Suite's Kyber KEM.

An implementation of CRYSTALS Kyber KEM as defined in CRYSTALS - Kyber: a CCA-secure module-lattice-based KEM.

Copyright

Copyright 2017-2018, 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.