iqr_frodokem.h File Reference

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

Macros
#define	IQR_FRODOKEM_PUBLIC_KEY_SIZE   15632
#define	IQR_FRODOKEM_PRIVATE_KEY_SIZE   31280
#define	IQR_FRODOKEM_CIPHERTEXT_SIZE   15768
#define	IQR_FRODOKEM_SHARED_KEY_SIZE   24

Typedefs
typedef struct iqr_FrodoKEMParams_struct	iqr_FrodoKEMParams
typedef struct iqr_FrodoKEMPublicKey_struct	iqr_FrodoKEMPublicKey
typedef struct iqr_FrodoKEMPrivateKey_struct	iqr_FrodoKEMPrivateKey
typedef struct iqr_FrodoKEMVariant_struct	iqr_FrodoKEMVariant

Functions
IQR_API iqr_retval	iqr_FrodoKEMCreateParams (const iqr_Context *ctx, const iqr_FrodoKEMVariant *variant, iqr_FrodoKEMParams **params)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_FrodoKEMDestroyParams (iqr_FrodoKEMParams **params)
IQR_API iqr_retval	iqr_FrodoKEMCreateKeyPair (const iqr_FrodoKEMParams *params, const iqr_RNG *rng, iqr_FrodoKEMPublicKey **public_key, iqr_FrodoKEMPrivateKey **private_key)
IQR_API iqr_retval	iqr_FrodoKEMImportPublicKey (const iqr_FrodoKEMParams *params, const uint8_t *buf, size_t buf_size, iqr_FrodoKEMPublicKey **public_key)
IQR_API iqr_retval	iqr_FrodoKEMImportPrivateKey (const iqr_FrodoKEMParams *params, const uint8_t *buf, size_t buf_size, iqr_FrodoKEMPrivateKey **private_key)
IQR_API iqr_retval	iqr_FrodoKEMExportPublicKey (const iqr_FrodoKEMPublicKey *public_key, uint8_t *buf, size_t buf_size)
IQR_API iqr_retval	iqr_FrodoKEMExportPrivateKey (const iqr_FrodoKEMPrivateKey *private_key, uint8_t *buf, size_t buf_size)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_FrodoKEMDestroyPublicKey (iqr_FrodoKEMPublicKey **public_key)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_FrodoKEMDestroyPrivateKey (iqr_FrodoKEMPrivateKey **private_key)
IQR_API iqr_retval	iqr_FrodoKEMEncapsulate (const iqr_FrodoKEMPublicKey *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_FrodoKEMDecapsulate (const iqr_FrodoKEMPrivateKey *private_key, const uint8_t *ciphertext, size_t ciphertext_size, uint8_t *shared_key, size_t shared_key_size)

Variables
IQR_EXTERN const iqr_FrodoKEMVariant	IQR_FRODOKEM_976_AES
IQR_EXTERN const iqr_FrodoKEMVariant	IQR_FRODOKEM_976_CSHAKE

Macro Definition Documentation

IQR_FRODOKEM_CIPHERTEXT_SIZE

#define IQR_FRODOKEM_CIPHERTEXT_SIZE   15768

The size of the ciphertext produced by FrodoKEM in bytes.

IQR_FRODOKEM_PRIVATE_KEY_SIZE

#define IQR_FRODOKEM_PRIVATE_KEY_SIZE   31280

The size of the private key produced by FrodoKEM in bytes.

IQR_FRODOKEM_PUBLIC_KEY_SIZE

#define IQR_FRODOKEM_PUBLIC_KEY_SIZE   15632

The size of the public key produced by FrodoKEM in bytes.

IQR_FRODOKEM_SHARED_KEY_SIZE

#define IQR_FRODOKEM_SHARED_KEY_SIZE   24

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

Typedef Documentation

iqr_FrodoKEMParams

typedef struct iqr_FrodoKEMParams_struct iqr_FrodoKEMParams

The algorithm's domain parameters.

iqr_FrodoKEMPrivateKey

typedef struct iqr_FrodoKEMPrivateKey_struct iqr_FrodoKEMPrivateKey

The FrodoKEM private key.

iqr_FrodoKEMPublicKey

typedef struct iqr_FrodoKEMPublicKey_struct iqr_FrodoKEMPublicKey

The FrodoKEM public key.

iqr_FrodoKEMVariant

typedef struct iqr_FrodoKEMVariant_struct iqr_FrodoKEMVariant

The FrodoKEM variant.

Function Documentation

iqr_FrodoKEMCreateKeyPair()

IQR_API iqr_retval iqr_FrodoKEMCreateKeyPair	(	const iqr_FrodoKEMParams *	params,
		const iqr_RNG *	rng,
		iqr_FrodoKEMPublicKey **	public_key,
		iqr_FrodoKEMPrivateKey **	private_key
	)

Generate a FrodoKEM private/public key pair.

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

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

Parameters

[in]	params	The FrodoKEM parameters.
[in]	rng	A seeded random number generator.
[out]	public_key	The resulting iqr_FrodoKEMPublicKey object.
[out]	private_key	The resulting iqr_FrodoKEMPrivateKey object.

Returns

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

iqr_FrodoKEMCreateParams()

IQR_API iqr_retval iqr_FrodoKEMCreateParams	(	const iqr_Context *	ctx,
		const iqr_FrodoKEMVariant *	variant,
		iqr_FrodoKEMParams **	params
	)

Create a parameter object for the FrodoKEM cryptographic system.

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

Parameters

[in]	ctx	A Context object.
[in]	variant	iqr_FrodoKEMVariant to use.
[out]	params	The FrodoKEM parameter object.

Returns

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

iqr_FrodoKEMDecapsulate()

IQR_API iqr_retval iqr_FrodoKEMDecapsulate	(	const iqr_FrodoKEMPrivateKey *	private_key,
		const uint8_t *	ciphertext,
		size_t	ciphertext_size,
		uint8_t *	shared_key,
		size_t	shared_key_size
	)

FrodoKEM decapsulation.

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

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

Returns

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

iqr_FrodoKEMDestroyParams()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_FrodoKEMDestroyParams

(

iqr_FrodoKEMParams **

params

)

Clear and deallocate a FrodoKEM parameter object.

params will be set to NULL prior to returning.

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

Parameters

[in,out]

params

The FrodoKEM parameter object to destroy.

Returns

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

iqr_FrodoKEMDestroyPrivateKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_FrodoKEMDestroyPrivateKey

(

iqr_FrodoKEMPrivateKey **

private_key

)

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

Returns

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

iqr_FrodoKEMDestroyPublicKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_FrodoKEMDestroyPublicKey

(

iqr_FrodoKEMPublicKey **

public_key

)

Clear and deallocate a FrodoKEM public key.

public_key will be set to NULL prior to returning.

Parameters

[in,out]

public_key

The iqr_FrodoKEMPublicKey object to destroy.

Returns

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

iqr_FrodoKEMEncapsulate()

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

FrodoKEM encapsulation.

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

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

Returns

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

iqr_FrodoKEMExportPrivateKey()

IQR_API iqr_retval iqr_FrodoKEMExportPrivateKey	(	const iqr_FrodoKEMPrivateKey *	private_key,
		uint8_t *	buf,
		size_t	buf_size
	)

Export the FrodoKEM 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 IQR_FRODOKEM_PRIVATE_KEY_SIZE.

Returns

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

iqr_FrodoKEMExportPublicKey()

IQR_API iqr_retval iqr_FrodoKEMExportPublicKey	(	const iqr_FrodoKEMPublicKey *	public_key,
		uint8_t *	buf,
		size_t	buf_size
	)

Export the FrodoKEM 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_FRODOKEM_PUBLIC_KEY_SIZE.

Returns

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

iqr_FrodoKEMImportPrivateKey()

IQR_API iqr_retval iqr_FrodoKEMImportPrivateKey	(	const iqr_FrodoKEMParams *	params,
		const uint8_t *	buf,
		size_t	buf_size,
		iqr_FrodoKEMPrivateKey **	private_key
	)

Import a FrodoKEM private key object from a buffer.

Note

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

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

Parameters

[in]	params	The FrodoKEM parameters.
[in]	buf	A buffer that contains a private key.
[in]	buf_size	The size of buf in bytes. Must be exactly IQR_FRODOKEM_PRIVATE_KEY_SIZE.
[out]	private_key	The resulting iqr_FrodoKEMPrivateKey object.

Returns

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

iqr_FrodoKEMImportPublicKey()

IQR_API iqr_retval iqr_FrodoKEMImportPublicKey	(	const iqr_FrodoKEMParams *	params,
		const uint8_t *	buf,
		size_t	buf_size,
		iqr_FrodoKEMPublicKey **	public_key
	)

Import a FrodoKEM public key object from a buffer.

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

Parameters

[in]	params	The FrodoKEM parameters.
[in]	buf	A buffer that contains a public key.
[in]	buf_size	The size of buf in bytes. Must be exactly IQR_FRODOKEM_PUBLIC_KEY_SIZE.
[out]	public_key	The resulting iqr_FrodoKEMPublicKey object.

Returns

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

Variable Documentation

IQR_FRODOKEM_976_AES

IQR_EXTERN const iqr_FrodoKEMVariant IQR_FRODOKEM_976_AES

AES variant.

IQR_FRODOKEM_976_CSHAKE

IQR_EXTERN const iqr_FrodoKEMVariant IQR_FRODOKEM_976_CSHAKE

cSHAKE variant.

Detailed Description

ISARA Radiate Security Solution Suite's FrodoKEM KEM.

An implementation of FrodoKEM as defined in FrodoKEM.

Copyright

Copyright 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.