iqr_frododh.h File Reference

ISARA Radiate Security Solution Suite's Frodo Diffie-Hellman (FrodoDH) key agreement. More...

Macros
#define	IQR_FRODODH_INITIATOR_PUBLIC_KEY_SIZE   15632
#define	IQR_FRODODH_RESPONDER_PUBLIC_KEY_SIZE   15624
#define	IQR_FRODODH_SECRET_SIZE   32

Typedefs
typedef struct iqr_FrodoDHParams_struct	iqr_FrodoDHParams
typedef struct iqr_FrodoDHInitiatorPrivateKey_struct	iqr_FrodoDHInitiatorPrivateKey
typedef struct iqr_FrodoDHResponderPrivateKey_struct	iqr_FrodoDHResponderPrivateKey
typedef struct iqr_FrodoDHVariant_struct	iqr_FrodoDHVariant

Functions
IQR_API iqr_retval	iqr_FrodoDHCreateParams (const iqr_Context *ctx, const iqr_FrodoDHVariant *variant, iqr_FrodoDHParams **params)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_FrodoDHDestroyParams (iqr_FrodoDHParams **params)
IQR_API iqr_retval	iqr_FrodoDHCreateInitiatorPrivateKey (const iqr_FrodoDHParams *params, const iqr_RNG *rng, iqr_FrodoDHInitiatorPrivateKey **initiator_private_key)
IQR_API iqr_retval	iqr_FrodoDHCreateResponderPrivateKey (const iqr_FrodoDHParams *params, const iqr_RNG *rng, iqr_FrodoDHResponderPrivateKey **responder_private_key)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_FrodoDHDestroyInitiatorPrivateKey (iqr_FrodoDHInitiatorPrivateKey **initiator_private_key)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_FrodoDHDestroyResponderPrivateKey (iqr_FrodoDHResponderPrivateKey **responder_private_key)
IQR_API iqr_retval	iqr_FrodoDHGetInitiatorPublicKey (iqr_FrodoDHInitiatorPrivateKey *initiator_private_key, const iqr_RNG *rng, uint8_t *initiator_public_key, size_t initiator_public_key_size)
IQR_API iqr_retval	iqr_FrodoDHGetResponderPublicKey (iqr_FrodoDHResponderPrivateKey *responder_private_key, const iqr_RNG *rng, const uint8_t *initiator_public_key, size_t initiator_public_key_size, uint8_t *responder_public_key, size_t responder_public_key_size)
IQR_API iqr_retval	iqr_FrodoDHGetInitiatorSecret (const iqr_FrodoDHInitiatorPrivateKey *initiator_private_key, const uint8_t *responder_public_key, size_t responder_public_key_size, uint8_t *secret, size_t secret_size)
IQR_API iqr_retval	iqr_FrodoDHGetResponderSecret (const iqr_FrodoDHResponderPrivateKey *responder_private_key, uint8_t *secret, size_t secret_size)

Variables
IQR_EXTERN const iqr_FrodoDHVariant	IQR_FRODODH_976_AES
IQR_EXTERN const iqr_FrodoDHVariant	IQR_FRODODH_976_CSHAKE

Macro Definition Documentation

IQR_FRODODH_INITIATOR_PUBLIC_KEY_SIZE

#define IQR_FRODODH_INITIATOR_PUBLIC_KEY_SIZE   15632

The size of the initiator public key provided by FrodoDH in bytes.

IQR_FRODODH_RESPONDER_PUBLIC_KEY_SIZE

#define IQR_FRODODH_RESPONDER_PUBLIC_KEY_SIZE   15624

The size of the responder public key provided by FrodoDH in bytes.

IQR_FRODODH_SECRET_SIZE

#define IQR_FRODODH_SECRET_SIZE   32

The size of the shared secret provided by FrodoDH in bytes.

Typedef Documentation

iqr_FrodoDHInitiatorPrivateKey

typedef struct iqr_FrodoDHInitiatorPrivateKey_struct iqr_FrodoDHInitiatorPrivateKey

The initiator private key.

iqr_FrodoDHParams

typedef struct iqr_FrodoDHParams_struct iqr_FrodoDHParams

The FrodoDH domain parameters.

iqr_FrodoDHResponderPrivateKey

typedef struct iqr_FrodoDHResponderPrivateKey_struct iqr_FrodoDHResponderPrivateKey

The responder private key.

iqr_FrodoDHVariant

typedef struct iqr_FrodoDHVariant_struct iqr_FrodoDHVariant

Which variant to use: recommended or paranoid.

Function Documentation

iqr_FrodoDHCreateInitiatorPrivateKey()

IQR_API iqr_retval iqr_FrodoDHCreateInitiatorPrivateKey	(	const iqr_FrodoDHParams *	params,
		const iqr_RNG *	rng,
		iqr_FrodoDHInitiatorPrivateKey **	initiator_private_key
	)

Create a FrodoDH Initiator private key to be used during shared secret generation.

Note

The initiator private key must be created before calling iqr_FrodoDHGetInitiatorPublicKey(). The resulting private key can only be used for generating a single shared secret. Call iqr_FrodoDHDestroyInitiatorPrivateKey() after iqr_FrodoDHGetInitiatorSecret() or when iqr_FrodoDHGetInitiatorPublicKey() fails.

*initiator_private_key must be set to NULL before calling iqr_FrodoDHCreateResponderPrivateKey().

Parameters

[in]	params	The iqr_FrodoDHParams to use.
[in]	rng	A seeded random number generator.
[out]	initiator_private_key	Used to store the initiator's private key.

Returns

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

iqr_FrodoDHCreateParams()

IQR_API iqr_retval iqr_FrodoDHCreateParams	(	const iqr_Context *	ctx,
		const iqr_FrodoDHVariant *	variant,
		iqr_FrodoDHParams **	params
	)

Create a FrodoDH Parameters object that encapsulates the domain parameters.

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

Parameters

[in]	ctx	A Context object.
[in]	variant	The iqr_FrodoDHVariant to use.
[out]	params	The iqr_FrodoDHParams output.

Returns

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

iqr_FrodoDHCreateResponderPrivateKey()

IQR_API iqr_retval iqr_FrodoDHCreateResponderPrivateKey	(	const iqr_FrodoDHParams *	params,
		const iqr_RNG *	rng,
		iqr_FrodoDHResponderPrivateKey **	responder_private_key
	)

Create a FrodoDH Responder private key to be used during shared secret generation.

Note

Create a responder private key before calling iqr_FrodoDHGetResponderPublicKey(). The resulting key can only be used for generating a single shared secret. That means calling iqr_FrodoDHDestroyResponderPrivateKey() after iqr_FrodoDHGetResponderSecret(), or when iqr_FrodoDHGetResponderPublicKey() fails.

*responder_private_key must be set to NULL before calling iqr_FrodoDHCreateResponderPrivateKey().

Parameters

[in]	params	The iqr_FrodoDHParams to use.
[in]	rng	A seeded random number generator.
[out]	responder_private_key	Used to store the responder's private key.

Returns

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

iqr_FrodoDHDestroyInitiatorPrivateKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_FrodoDHDestroyInitiatorPrivateKey

(

iqr_FrodoDHInitiatorPrivateKey **

initiator_private_key

)

Clear and deallocate a FrodoDH initiator private key.

initiator_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]

initiator_private_key

The initiator private key to destroy.

Returns

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

iqr_FrodoDHDestroyParams()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_FrodoDHDestroyParams

(

iqr_FrodoDHParams **

params

)

Clear and deallocate a FrodoDH Parameter object.

params will be set to NULL prior to returning.

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

Parameters

[in,out]

params

The iqr_FrodoDHParams instance to destroy.

Returns

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

iqr_FrodoDHDestroyResponderPrivateKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_FrodoDHDestroyResponderPrivateKey

(

iqr_FrodoDHResponderPrivateKey **

responder_private_key

)

Clear and deallocate a FrodoDH responder private key.

responder_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]

responder_private_key

The responder private key to destroy.

Returns

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

iqr_FrodoDHGetInitiatorPublicKey()

IQR_API iqr_retval iqr_FrodoDHGetInitiatorPublicKey	(	iqr_FrodoDHInitiatorPrivateKey *	initiator_private_key,
		const iqr_RNG *	rng,
		uint8_t *	initiator_public_key,
		size_t	initiator_public_key_size
	)

Create the initiator public key needed for FrodoDH key agreement.

The initiator is responsible for starting the key agreement protocol. Although this can be the server in the client-server model, it is not a requirement.

The initiator generates a public key that must be sent to the responder. The responder then uses this to generate its own public key and the shared secret. The initiator receives the responder's public key which it uses to calculate the shared secret.

Parameters

[in]	initiator_private_key	The initiator's private key.
[in]	rng	A seeded random number generator.
[out]	initiator_public_key	The public key generated by the initiator of FrodoDH.
[in]	initiator_public_key_size	The size of initiator_public_key in bytes. Must be exactly IQR_FRODODH_INITIATOR_PUBLIC_KEY_SIZE bytes.

Returns

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

iqr_FrodoDHGetInitiatorSecret()

IQR_API iqr_retval iqr_FrodoDHGetInitiatorSecret	(	const iqr_FrodoDHInitiatorPrivateKey *	initiator_private_key,
		const uint8_t *	responder_public_key,
		size_t	responder_public_key_size,
		uint8_t *	secret,
		size_t	secret_size
	)

Get the initiator shared secret.

The initiator and responder shared secrets should be the same (although there's a 2^-34 chance of failure) but they are calculated differently. The initiator needs the public key generated from the responder in iqr_FrodoDHGetResponderPublicKey() and the private key from iqr_FrodoDHCreateInitiatorPrivateKey(). This error is inherent to the FrodoDH algorithm. To recover from it you must start over with new keys.

Note

The output secret is a shared secret, not a key. This output must be passed through a KDF or hash function before being used. Do not use this secret directly.

Be sure to safely wipe and discard the secret after it's been used.

Parameters

[in]	initiator_private_key	The initiator's private key.
[in]	responder_public_key	The public key generated by the responder of FrodoDH.
[in]	responder_public_key_size	The size of responder_public_key in bytes. Must be exactly IQR_FRODODH_INITIATOR_PUBLIC_KEY_SIZE bytes.
[out]	secret	The shared secret.
[in]	secret_size	The size of secret in bytes. Must be exactly IQR_FRODODH_SECRET_SIZE bytes.

Returns

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

iqr_FrodoDHGetResponderPublicKey()

IQR_API iqr_retval iqr_FrodoDHGetResponderPublicKey	(	iqr_FrodoDHResponderPrivateKey *	responder_private_key,
		const iqr_RNG *	rng,
		const uint8_t *	initiator_public_key,
		size_t	initiator_public_key_size,
		uint8_t *	responder_public_key,
		size_t	responder_public_key_size
	)

Create the responder public key needed for FrodoDH key agreement.

The public key from the initiator is needed before generating the responder's public key. This is different from traditional Diffie-Hellman where both sides perform the same independent operations.

Parameters

[in]	responder_private_key	The responder's private key.
[in]	rng	A seeded random number generator.
[in]	initiator_public_key	The public key generated by the initiator of FrodoDH.
[in]	initiator_public_key_size	The size of initiator_public_key in bytes. Must be exactly IQR_FRODODH_INITIATOR_PUBLIC_KEY_SIZE bytes.
[out]	responder_public_key	The public key generated by the responder of FrodoDH.
[in]	responder_public_key_size	The size of responder_public_key in bytes. Must be exactly IQR_FRODODH_RESPONDER_PUBLIC_KEY_SIZE bytes.

Returns

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

iqr_FrodoDHGetResponderSecret()

IQR_API iqr_retval iqr_FrodoDHGetResponderSecret	(	const iqr_FrodoDHResponderPrivateKey *	responder_private_key,
		uint8_t *	secret,
		size_t	secret_size
	)

Get the responder shared secret.

The responder and initiator shared secrets should be the same (although there's a 2^-34 chance of failure) but they are calculated differently. This error is inherent to the FrodoDH algorithm. To recover from it you must start over with new keys.

Note

The responder's public key must be created using iqr_FrodoDHGetResponderPublicKey() prior to calling iqr_FrodoDHGetResponderSecret().

The output secret is a shared secret, not a key. This output must be passed through a KDF or hash function before being used. Do not use this secret directly.

Be sure to safely wipe and discard the secret after it's been used.

Parameters

[in]	responder_private_key	The responder's private key.
[out]	secret	The shared secret.
[in]	secret_size	The size of secret in bytes. Must be exactly IQR_FRODODH_SECRET_SIZE bytes.

Returns

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

Variable Documentation

IQR_FRODODH_976_AES

IQR_EXTERN const iqr_FrodoDHVariant IQR_FRODODH_976_AES

AES variant.

IQR_FRODODH_976_CSHAKE

IQR_EXTERN const iqr_FrodoDHVariant IQR_FRODODH_976_CSHAKE

cSHAKE variant.

Detailed Description

ISARA Radiate Security Solution Suite's Frodo Diffie-Hellman (FrodoDH) key agreement.

The IQR Toolkit's implementation of the Frodo LWE secret agreement as defined in Frodo but using the parameter sets from the NIST submission as defined in FrodoKEM.

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.