ISARA Quantum Resistant Toolkit  Version 1.1
Quantum resistant cryptographic primitives and algorithms.
Macros | Typedefs | Functions
iqr_luke.h File Reference

Macros

#define IQR_LUKE_SECRET_SIZE   32
 
#define IQR_LUKE_INITIATOR_KEY_SIZE   1824
 
#define IQR_LUKE_RESPONDER_KEY_SIZE   2048
 

Typedefs

typedef struct iqr_LUKEParams_struct iqr_LUKEParams
 
typedef struct iqr_LUKEPrivateKey_struct iqr_LUKEPrivateKey
 

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_LUKECreatePrivateKey (const iqr_LUKEParams *params, iqr_LUKEPrivateKey **private_key)
 
IQR_API_UNENFORCED_RETURN iqr_retval iqr_LUKEDestroyPrivateKey (iqr_LUKEPrivateKey **private_key)
 
IQR_API iqr_retval iqr_LUKEGetInitiatorPublicKey (iqr_LUKEPrivateKey *private_key, const iqr_RNG *rng, uint8_t *initiator_public_key, size_t initiator_public_key_size)
 
IQR_API iqr_retval iqr_LUKEGetInitiatorSecret (const iqr_LUKEPrivateKey *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_LUKEGetResponderPublicKeyandSecret (const iqr_LUKEParams *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)
 

Macro Definition Documentation

§ IQR_LUKE_INITIATOR_KEY_SIZE

#define IQR_LUKE_INITIATOR_KEY_SIZE   1824

The size of the initiator and responder public keys in bytes.

§ IQR_LUKE_RESPONDER_KEY_SIZE

#define IQR_LUKE_RESPONDER_KEY_SIZE   2048

§ 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_LUKEParams

typedef struct iqr_LUKEParams_struct iqr_LUKEParams

The algorithm's domain parameters.

§ iqr_LUKEPrivateKey

typedef struct iqr_LUKEPrivateKey_struct iqr_LUKEPrivateKey

The initiator's private key.

Function Documentation

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

Parameters
[in]ctxA Context object.
[out]paramsThe iqr_LUKEParams output.
Returns
IQR_OK on success, or a value from iqr_retval.h when an error occurs.

§ iqr_LUKECreatePrivateKey()

IQR_API iqr_retval iqr_LUKECreatePrivateKey ( const iqr_LUKEParams *  params,
iqr_LUKEPrivateKey **  private_key 
)

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

Note
Create private key before calling iqr_LUKEGetInitiatorPublicKey. The resulting key should only be used for generating a single shared secret. That means calling iqr_LUKEDestroyPrivateKey after iqr_LUKEGetInitiatorSecret or on iqr_LUKEGetInitiatorPublicKey failure.
Parameters
[in]paramsThe iqr_LUKEParams to use.
[out]private_keyUsed to store the initiator's private data.
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.

Parameters
[in,out]paramsThe iqr_LUKEParams instance to destroy.
Returns
IQR_OK on success, or a value from iqr_retval.h when an error occurs.

§ iqr_LUKEDestroyPrivateKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_LUKEDestroyPrivateKey ( iqr_LUKEPrivateKey **  private_key)

Clear and deallocate a LUKE initiator private key.

private_key will be set to NULL prior to returning.

Parameters
[in,out]private_keyThe initiator 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_LUKEPrivateKey *  private_key,
const iqr_RNG *  rng,
uint8_t *  initiator_public_key,
size_t  initiator_public_key_size 
)

Create 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,out]private_keyThe initiator's private key.
[in]rngThe iqr_RNG to use.
[out]initiator_public_keyThe public key generated by the initiator of LUKE. Must be IQR_LUKE_INITIATOR_KEY_SIZE bytes.
[in]initiator_public_key_sizeSize of initiator_public_key in 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_LUKEPrivateKey *  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_LUKECreateResponderPublicKey() and the private key from iqr_LUKEGetInitiatorPublicKey().

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_keyThe initiator's private key.
[in]responder_public_keyThe public key generated by the responder of LUKE.
[in]responder_public_key_sizeSize in bytes of responder_public_key. Must be exactly IQR_LUKE_RESPONDER_KEY_SIZE bytes.
[out]secretThe shared secret. Must be IQR_LUKE_SECRET_SIZE bytes.
[in]secret_sizeSize in bytes of secret.
Returns
IQR_OK on success, or a value from iqr_retval.h when an error occurs.

§ iqr_LUKEGetResponderPublicKeyandSecret()

IQR_API iqr_retval iqr_LUKEGetResponderPublicKeyandSecret ( const iqr_LUKEParams *  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]paramsThe iqr_LUKEParams to use.
[in]rngThe iqr_RNG to use.
[in]initiator_public_keyThe public key from the initiator of LUKE. Must be IQR_LUKE_INITIATOR_KEY_SIZE bytes.
[in]initiator_public_key_sizeSize in bytes of initiator_public_key.
[out]responder_public_keyThe public key generated by the responder of LUKE. Must be IQR_LUKE_RESPONDER_KEY_SIZE bytes.
[in]responder_public_key_sizeSize in bytes of responder_public_key.
[out]secretThe shared secret. Must be IQR_LUKE_SECRET_SIZE bytes.
[in]secret_sizeSize in bytes of secret.
Returns
IQR_OK on success, or a value from iqr_retval.h when an error occurs.

Detailed Description

ISARA'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, 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.