iqr_luke.h File Reference

ISARA Radiate Security Solution Suite's Lattice based Unique Key Establishment. More...

Macros
#define	IQR_LUKE_SECRET_SIZE   32
#define	IQR_LUKE_INITIATOR_PUBLIC_KEY_SIZE   1824
#define	IQR_LUKE_RESPONDER_PUBLIC_KEY_SIZE   2048

Typedefs
typedef struct iqr_LUKEParams_struct	iqr_LUKEParams
typedef struct iqr_LUKEInitiatorPrivateKey_struct	iqr_LUKEInitiatorPrivateKey
typedef struct iqr_LUKEResponderPrivateKey_struct	iqr_LUKEResponderPrivateKey

Functions
IQR_API iqr_retval	iqr_LUKECreateParams (const iqr_Context *ctx, iqr_LUKEParams **params)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_LUKEDestroyParams (iqr_LUKEParams **params)
IQR_API iqr_retval	iqr_LUKECreateInitiatorPrivateKey (const iqr_LUKEParams *params, const iqr_RNG *rng, iqr_LUKEInitiatorPrivateKey **initiator_private_key)
IQR_API iqr_retval	iqr_LUKECreateResponderPrivateKey (const iqr_LUKEParams *params, const iqr_RNG *rng, iqr_LUKEResponderPrivateKey **responder_private_key)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_LUKEDestroyInitiatorPrivateKey (iqr_LUKEInitiatorPrivateKey **initiator_private_key)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_LUKEDestroyResponderPrivateKey (iqr_LUKEResponderPrivateKey **responder_private_key)
IQR_API iqr_retval	iqr_LUKEGetInitiatorPublicKey (iqr_LUKEInitiatorPrivateKey *initiator_private_key, const iqr_RNG *rng, uint8_t *initiator_public_key, size_t initiator_public_key_size)
IQR_API iqr_retval	iqr_LUKEGetResponderPublicKey (iqr_LUKEResponderPrivateKey *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_LUKEGetInitiatorSecret (const iqr_LUKEInitiatorPrivateKey *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_LUKEGetResponderSecret (const iqr_LUKEResponderPrivateKey *responder_private_key, uint8_t *secret, size_t secret_size)

Macro Definition Documentation

IQR_LUKE_INITIATOR_PUBLIC_KEY_SIZE

#define IQR_LUKE_INITIATOR_PUBLIC_KEY_SIZE   1824

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

IQR_LUKE_RESPONDER_PUBLIC_KEY_SIZE

#define IQR_LUKE_RESPONDER_PUBLIC_KEY_SIZE   2048

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

IQR_LUKE_SECRET_SIZE

#define IQR_LUKE_SECRET_SIZE   32

The size of the shared secret provided by LUKE in bytes (256 bits).

Typedef Documentation

iqr_LUKEInitiatorPrivateKey

typedef struct iqr_LUKEInitiatorPrivateKey_struct iqr_LUKEInitiatorPrivateKey

The initiator's private key.

iqr_LUKEParams

typedef struct iqr_LUKEParams_struct iqr_LUKEParams

The algorithm's domain parameters.

iqr_LUKEResponderPrivateKey

typedef struct iqr_LUKEResponderPrivateKey_struct iqr_LUKEResponderPrivateKey

The responder's private key.

Function Documentation

iqr_LUKECreateInitiatorPrivateKey()

IQR_API iqr_retval iqr_LUKECreateInitiatorPrivateKey	(	const iqr_LUKEParams *	params,
		const iqr_RNG *	rng,
		iqr_LUKEInitiatorPrivateKey **	initiator_private_key
	)

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

Note

Create an initiator private key before calling iqr_LUKEGetInitiatorPublicKey(). The resulting key can only be used for generating a single shared secret. That means calling iqr_LUKEDestroyInitiatorPrivateKey() after iqr_LUKEGetInitiatorSecret() or a failure of iqr_LUKEGetInitiatorPublicKey().

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

Parameters

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

Returns

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

iqr_LUKECreateParams()

IQR_API iqr_retval iqr_LUKECreateParams	(	const iqr_Context *	ctx,
		iqr_LUKEParams **	params
	)

Create a LUKE 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.

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

Parameters

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

Returns

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

iqr_LUKECreateResponderPrivateKey()

IQR_API iqr_retval iqr_LUKECreateResponderPrivateKey	(	const iqr_LUKEParams *	params,
		const iqr_RNG *	rng,
		iqr_LUKEResponderPrivateKey **	responder_private_key
	)

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

Note

Create a responder private key before calling iqr_LUKEGetResponderPublicKey(). The resulting key can only be used for generating a single shared secret. That means calling iqr_LUKEDestroyResponderPrivateKey() after iqr_LUKEGetResponderSecret() or a failure of iqr_LUKEGetResponderPublicKey().

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

Parameters

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

Returns

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

iqr_LUKEDestroyInitiatorPrivateKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_LUKEDestroyInitiatorPrivateKey

(

iqr_LUKEInitiatorPrivateKey **

initiator_private_key

)

Clear and deallocate a LUKE 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_LUKEDestroyParams()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_LUKEDestroyParams

(

iqr_LUKEParams **

params

)

Clear and deallocate a LUKE Parameter object.

params will be set to NULL prior to returning.

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

Parameters

[in,out]

params

The iqr_LUKEParams instance to destroy.

Returns

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

iqr_LUKEDestroyResponderPrivateKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_LUKEDestroyResponderPrivateKey

(

iqr_LUKEResponderPrivateKey **

responder_private_key

)

Clear and deallocate a LUKE 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_LUKEGetInitiatorPublicKey()

IQR_API iqr_retval iqr_LUKEGetInitiatorPublicKey	(	iqr_LUKEInitiatorPrivateKey *	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 LUKE 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 LUKE.
[in]	initiator_public_key_size	The size of initiator_public_key in bytes Must be exactly IQR_LUKE_INITIATOR_PUBLIC_KEY_SIZE bytes.

Returns

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

iqr_LUKEGetInitiatorSecret()

IQR_API iqr_retval iqr_LUKEGetInitiatorSecret	(	const iqr_LUKEInitiatorPrivateKey *	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_LUKEGetResponderPublicKey() and the private key from iqr_LUKECreateInitiatorPrivateKey(). This error is inherent to the LUKE 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_LUKEGetInitiatorSecret() 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 LUKE.
[in]	responder_public_key_size	The size of responder_public_key in bytes. Must be exactly IQR_LUKE_RESPONDER_PUBLIC_KEY_SIZE bytes.
[out]	secret	The shared secret.
[in]	secret_size	The size of secret in bytes. Must be exactly IQR_LUKE_SECRET_SIZE bytes.

Returns

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

iqr_LUKEGetResponderPublicKey()

IQR_API iqr_retval iqr_LUKEGetResponderPublicKey	(	iqr_LUKEResponderPrivateKey *	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 LUKE 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 from the initiator of LUKE.
[in]	initiator_public_key_size	The size of initiator_public_key in bytes. Must be exactly IQR_LUKE_INITIATOR_PUBLIC_KEY_SIZE bytes.
[out]	responder_public_key	The public key generated by the responder of LUKE.
[in]	responder_public_key_size	The size of responder_public_key in bytes. Must be exactly IQR_LUKE_RESPONDER_PUBLIC_KEY_SIZE bytes.

Returns

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

iqr_LUKEGetResponderSecret()

IQR_API iqr_retval iqr_LUKEGetResponderSecret	(	const iqr_LUKEResponderPrivateKey *	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 LUKE algorithm. To recover from it you must start over with new keys.

Note

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

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_LUKEGetInitiatorSecret() 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_LUKE_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 Lattice based Unique Key Establishment.

Lattice based Unique Key Establishment (LUKE), an optimized variant of 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).

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.