iqr_newhopedh.h File Reference

ISARA Radiate Security Solution Suite's NewHopeDH key agreement. More...

Macros
#define	IQR_NEWHOPEDH_SECRET_SIZE   32
#define	IQR_NEWHOPEDH_INITIATOR_PUBLIC_KEY_SIZE   1824
#define	IQR_NEWHOPEDH_RESPONDER_PUBLIC_KEY_SIZE   2048

Typedefs
typedef struct iqr_NewHopeDHParams_struct	iqr_NewHopeDHParams
typedef struct iqr_NewHopeDHInitiatorPrivateKey_struct	iqr_NewHopeDHInitiatorPrivateKey
typedef struct iqr_NewHopeDHResponderPrivateKey_struct	iqr_NewHopeDHResponderPrivateKey

Functions
IQR_API iqr_retval	iqr_NewHopeDHCreateParams (const iqr_Context *ctx, iqr_NewHopeDHParams **params)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_NewHopeDHDestroyParams (iqr_NewHopeDHParams **params)
IQR_API iqr_retval	iqr_NewHopeDHCreateInitiatorPrivateKey (const iqr_NewHopeDHParams *params, const iqr_RNG *rng, iqr_NewHopeDHInitiatorPrivateKey **initiator_private_key)
IQR_API iqr_retval	iqr_NewHopeDHCreateResponderPrivateKey (const iqr_NewHopeDHParams *params, const iqr_RNG *rng, iqr_NewHopeDHResponderPrivateKey **responder_private_key)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_NewHopeDHDestroyInitiatorPrivateKey (iqr_NewHopeDHInitiatorPrivateKey **initiator_private_key)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_NewHopeDHDestroyResponderPrivateKey (iqr_NewHopeDHResponderPrivateKey **responder_private_key)
IQR_API iqr_retval	iqr_NewHopeDHGetInitiatorPublicKey (iqr_NewHopeDHInitiatorPrivateKey *initiator_private_key, const iqr_RNG *rng, uint8_t *initiator_public_key, size_t initiator_public_key_size)
IQR_API iqr_retval	iqr_NewHopeDHGetResponderPublicKey (iqr_NewHopeDHResponderPrivateKey *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_NewHopeDHGetInitiatorSecret (const iqr_NewHopeDHInitiatorPrivateKey *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_NewHopeDHGetResponderSecret (const iqr_NewHopeDHResponderPrivateKey *responder_private_key, uint8_t *secret, size_t secret_size)

Macro Definition Documentation

IQR_NEWHOPEDH_INITIATOR_PUBLIC_KEY_SIZE

#define IQR_NEWHOPEDH_INITIATOR_PUBLIC_KEY_SIZE   1824

The size of the initiator's public key in bytes.

IQR_NEWHOPEDH_RESPONDER_PUBLIC_KEY_SIZE

#define IQR_NEWHOPEDH_RESPONDER_PUBLIC_KEY_SIZE   2048

The size of the responder's public key in bytes.

IQR_NEWHOPEDH_SECRET_SIZE

#define IQR_NEWHOPEDH_SECRET_SIZE   32

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

Typedef Documentation

iqr_NewHopeDHInitiatorPrivateKey

typedef struct iqr_NewHopeDHInitiatorPrivateKey_struct iqr_NewHopeDHInitiatorPrivateKey

The initiator's private key.

iqr_NewHopeDHParams

typedef struct iqr_NewHopeDHParams_struct iqr_NewHopeDHParams

The NewHopeDH domain parameters.

iqr_NewHopeDHResponderPrivateKey

typedef struct iqr_NewHopeDHResponderPrivateKey_struct iqr_NewHopeDHResponderPrivateKey

The responder's private key.

Function Documentation

iqr_NewHopeDHCreateInitiatorPrivateKey()

IQR_API iqr_retval iqr_NewHopeDHCreateInitiatorPrivateKey	(	const iqr_NewHopeDHParams *	params,
		const iqr_RNG *	rng,
		iqr_NewHopeDHInitiatorPrivateKey **	initiator_private_key
	)

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

Note

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

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

Parameters

[in]	params	The iqr_NewHopeDHParams 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_NewHopeDHCreateParams()

IQR_API iqr_retval iqr_NewHopeDHCreateParams	(	const iqr_Context *	ctx,
		iqr_NewHopeDHParams **	params
	)

Create a NewHopeDH Parameters object that encapsulates the domain parameters.

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

Note

Be sure that the hash IQR_HASHALGO_SHA3_256 callbacks have been registered via iqr_HashRegisterCallbacks() before calling this function.

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

Parameters

[in]	ctx	A Context object.
[out]	params	The iqr_NewHopeDHParams output.

Returns

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

iqr_NewHopeDHCreateResponderPrivateKey()

IQR_API iqr_retval iqr_NewHopeDHCreateResponderPrivateKey	(	const iqr_NewHopeDHParams *	params,
		const iqr_RNG *	rng,
		iqr_NewHopeDHResponderPrivateKey **	responder_private_key
	)

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

Note

The responder private key must be created before calling iqr_NewHopeDHGetResponderPublicKey(). The resulting private key can only be used for generating a single shared secret. Call iqr_NewHopeDHDestroyResponderPrivateKey() after iqr_NewHopeDHGetResponderSecret() or when iqr_NewHopeDHGetResponderPublicKey() fails.

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

Parameters

[in]	params	The iqr_NewHopeDHParams 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_NewHopeDHDestroyInitiatorPrivateKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_NewHopeDHDestroyInitiatorPrivateKey

(

iqr_NewHopeDHInitiatorPrivateKey **

initiator_private_key

)

Clear and deallocate a NewHopeDH 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_NewHopeDHDestroyParams()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_NewHopeDHDestroyParams

(

iqr_NewHopeDHParams **

params

)

Clear and deallocate a NewHopeDH Parameter object.

params will be set to NULL prior to returning.

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

Parameters

[in,out]

params

The iqr_NewHopeDHParams instance to destroy.

Returns

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

iqr_NewHopeDHDestroyResponderPrivateKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_NewHopeDHDestroyResponderPrivateKey

(

iqr_NewHopeDHResponderPrivateKey **

responder_private_key

)

Clear and deallocate a NewHopeDH 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_NewHopeDHGetInitiatorPublicKey()

IQR_API iqr_retval iqr_NewHopeDHGetInitiatorPublicKey	(	iqr_NewHopeDHInitiatorPrivateKey *	initiator_private_key,
		const iqr_RNG *	rng,
		uint8_t *	initiator_public_key,
		size_t	initiator_public_key_size
	)

Get the initiator public key needed for NewHopeDH key agreement.

The initiator is responsible for starting the key agreement protocol. Although this can be the server in the client-server model it does not have to be.

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 as well.

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 NewHopeDH.
[in]	initiator_public_key_size	The size of initiator_public_key in bytes. Must be exactly IQR_NEWHOPEDH_INITIATOR_PUBLIC_KEY_SIZE bytes.

Returns

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

iqr_NewHopeDHGetInitiatorSecret()

IQR_API iqr_retval iqr_NewHopeDHGetInitiatorSecret	(	const iqr_NewHopeDHInitiatorPrivateKey *	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^-60 chance of failure) but they are calculated differently. The initiator needs the public key generated from the responder in iqr_NewHopeDHGetResponderPublicKey() and the private key from iqr_NewHopeDHCreateInitiatorPrivateKey(). This error is inherent to the NewHopeDH 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.

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

Parameters

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

Returns

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

iqr_NewHopeDHGetResponderPublicKey()

IQR_API iqr_retval iqr_NewHopeDHGetResponderPublicKey	(	iqr_NewHopeDHResponderPrivateKey *	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
	)

Get the responder public key needed for NewHopeDH 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.
[out]	initiator_public_key	The public key generated by the initiator of NewHopeDH.
[in]	initiator_public_key_size	The size of initiator_public_key in bytes. Must be exactly IQR_NEWHOPEDH_INITIATOR_PUBLIC_KEY_SIZE bytes.
[out]	responder_public_key	The public key generated by the responder of NewHopeDH.
[in]	responder_public_key_size	The size of responder_public_key in bytes. Must be exactly IQR_NEWHOPEDH_RESPONDER_PUBLIC_KEY_SIZE bytes.

Returns

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

iqr_NewHopeDHGetResponderSecret()

IQR_API iqr_retval iqr_NewHopeDHGetResponderSecret	(	const iqr_NewHopeDHResponderPrivateKey *	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^-60 chance of failure) but they are calculated differently. This error is inherent to the NewHopeDH 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.

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

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_NEWHOPEDH_SECRET_SIZE bytes.

Returns

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

Detailed Description

ISARA Radiate Security Solution Suite's NewHopeDH key agreement.

The toolkit's implementation of the NewHope Ring-LWE secret agreement as defined in A NewHope. This paper does not allow for specific parameter choices. The modulus (q) is chosen to be 12289, the dimension (n) to be 1024 and the binomial distribution has a standard deviation of sqrt(16/2).

Note

This is not the same as the NIST NewHope submission.

Copyright

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