iqr_newhope.h File Reference

Macros
#define	IQR_NEWHOPE_SECRET_SIZE   32
#define	IQR_NEWHOPE_INITIATOR_KEY_SIZE   1824
#define	IQR_NEWHOPE_RESPONDER_KEY_SIZE   2048

Typedefs
typedef struct iqr_NewHopeParams_struct	iqr_NewHopeParams
typedef struct iqr_NewHopePrivateKey_struct	iqr_NewHopePrivateKey
typedef struct iqr_NewHopeVariant_struct	iqr_NewHopeVariant

Functions
IQR_API iqr_retval	iqr_NewHopeCreateParams (const iqr_Context *ctx, const iqr_NewHopeVariant *variant, iqr_NewHopeParams **params)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_NewHopeDestroyParams (iqr_NewHopeParams **params)
IQR_API iqr_retval	iqr_NewHopeCreatePrivateKey (const iqr_NewHopeParams *params, iqr_NewHopePrivateKey **private_key)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_NewHopeDestroyPrivateKey (iqr_NewHopePrivateKey **private_key)
IQR_API iqr_retval	iqr_NewHopeGetInitiatorPublicKey (iqr_NewHopePrivateKey *private_key, const iqr_RNG *rng, uint8_t *initiator_public_key, size_t initiator_public_key_size)
IQR_API iqr_retval	iqr_NewHopeGetInitiatorSecret (const iqr_NewHopePrivateKey *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_NewHopeGetResponderPublicKeyandSecret (const iqr_NewHopeParams *params, 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, uint8_t *secret, size_t secret_size)

Variables
IQR_EXTERN const iqr_NewHopeVariant	IQR_NEWHOPE_REFERENCE
IQR_EXTERN const iqr_NewHopeVariant	IQR_NEWHOPE_BORINGSSL

Macro Definition Documentation

IQR_NEWHOPE_INITIATOR_KEY_SIZE

#define IQR_NEWHOPE_INITIATOR_KEY_SIZE   1824

The size of the initiator and responder public keys in bytes

IQR_NEWHOPE_RESPONDER_KEY_SIZE

#define IQR_NEWHOPE_RESPONDER_KEY_SIZE   2048

IQR_NEWHOPE_SECRET_SIZE

#define IQR_NEWHOPE_SECRET_SIZE   32

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

Typedef Documentation

iqr_NewHopeParams

typedef struct iqr_NewHopeParams_struct iqr_NewHopeParams

The NewHope domain parameters.

iqr_NewHopePrivateKey

typedef struct iqr_NewHopePrivateKey_struct iqr_NewHopePrivateKey

The initiator's private key.

iqr_NewHopeVariant

typedef struct iqr_NewHopeVariant_struct iqr_NewHopeVariant

Which variant to use: reference or BoringSSL.

Function Documentation

iqr_NewHopeCreateParams()

IQR_API iqr_retval iqr_NewHopeCreateParams	(	const iqr_Context *	ctx,
		const iqr_NewHopeVariant *	variant,
		iqr_NewHopeParams **	params
	)

Create a NewHope 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

When using either of the NewHope variants be sure that the hash callbacks have been registered via iqr_HashRegisterCallbacks() before calling this function. IQR_NEWHOPE_REFERENCE uses SHA3-256 (IQR_HASHALGO_SHA3_256). IQR_NEWHOPE_BORINGSSL uses SHA-256 (IQR_HASHALGO_SHA2_256).

Parameters

[in]	ctx	A Context object.
[in]	variant	iqr_NewHopeVariant to use.
[out]	params	The iqr_NewHopeParams output.

Returns

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

iqr_NewHopeCreatePrivateKey()

IQR_API iqr_retval iqr_NewHopeCreatePrivateKey	(	const iqr_NewHopeParams *	params,
		iqr_NewHopePrivateKey **	private_key
	)

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

Note

The initiator private key must be created before calling iqr_NewHopeGetInitiatorPublicKey(). The resulting private key should only be used for generating a single shared secret. Call iqr_NewHopeDestroyPrivateKey() after iqr_NewHopeGetInitiatorSecret() or when iqr_NewHopeGetInitiatorPublicKey() fails.

Parameters

[in]	params	The iqr_NewHopeParams to use.
[out]	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_NewHopeDestroyParams()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_NewHopeDestroyParams

(

iqr_NewHopeParams **

params

)

Clear and deallocate a NewHope Parameter object.

params will be set to NULL prior to returning.

Parameters

[in,out]

params

The iqr_NewHopeParams instance to destroy.

Returns

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

iqr_NewHopeDestroyPrivateKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_NewHopeDestroyPrivateKey

(

iqr_NewHopePrivateKey **

private_key

)

Zero and deallocate NewHope initiator private key.

private_key will be set to NULL prior to returning.

Parameters

[in,out]

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_NewHopeGetInitiatorPublicKey()

IQR_API iqr_retval iqr_NewHopeGetInitiatorPublicKey	(	iqr_NewHopePrivateKey *	private_key,
		const iqr_RNG *	rng,
		uint8_t *	initiator_public_key,
		size_t	initiator_public_key_size
	)

Create the initiator public key needed for NewHope 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,out]	private_key	The initiator's private key.
[in]	rng	The iqr_RNG to use.
[out]	initiator_public_key	The public key generated by the initiator of NewHope. Must be IQR_NEWHOPE_INITIATOR_KEY_SIZE bytes.
[in]	initiator_public_key_size	Size of initiator_public_key in bytes.

Returns

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

iqr_NewHopeGetInitiatorSecret()

IQR_API iqr_retval iqr_NewHopeGetInitiatorSecret	(	const iqr_NewHopePrivateKey *	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_NewHopeGetResponderPublicKeyandSecret() and the private key from iqr_NewHopeGetInitiatorPublicKey().

Note

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

Parameters

[in]	private_key	The initiator's private key.
[in]	responder_public_key	The public key generated by the responder of NewHope.
[in]	responder_public_key_size	Size in bytes of responder_public_key. Must be exactly IQR_NEWHOPE_RESPONDER_KEY_SIZE bytes.
[out]	secret	The shared secret. Must be IQR_NEWHOPE_SECRET_SIZE bytes.
[in]	secret_size	Size secret in bytes.

Returns

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

iqr_NewHopeGetResponderPublicKeyandSecret()

IQR_API iqr_retval iqr_NewHopeGetResponderPublicKeyandSecret	(	const iqr_NewHopeParams *	params,
		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,
		uint8_t *	secret,
		size_t	secret_size
	)

Get the responder public key and 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.

Note

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

Parameters

[in]	params	The iqr_NewHopeParams to use.
[in]	rng	The iqr_RNG to use.
[in]	initiator_public_key	The public key from the initiator of NewHope. Must be IQR_NEWHOPE_INITIATOR_KEY_SIZE bytes.
[in]	initiator_public_key_size	Size in bytes of initiator_public_key.
[out]	responder_public_key	The public key generated by the responder of NewHope. Must be IQR_NEWHOPE_RESPONDER_KEY_SIZE bytes.
[in]	responder_public_key_size	Size in bytes of responder_public_key.
[out]	secret	The shared secret. Must be IQR_NEWHOPE_SECRET_SIZE bytes.
[in]	secret_size	Size in bytes of secret.

Returns

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

Variable Documentation

IQR_NEWHOPE_BORINGSSL

IQR_EXTERN const iqr_NewHopeVariant IQR_NEWHOPE_BORINGSSL

The BoringSSL compatible variant.

IQR_NEWHOPE_REFERENCE

IQR_EXTERN const iqr_NewHopeVariant IQR_NEWHOPE_REFERENCE

The NewHope reference compatible variant.

Detailed Description

ISARA's NewHope key agreement.

The IQR 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).

There are two different variants that are implemented. One that is compatible with the reference NewHope implementation and the other is compatible with the BoringSSL implementation.

Copyright

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