iqr_ntruprime.h File Reference

ISARA Radiate Security Solution Suite's NTRUPrime KEM. More...

Macros
#define	IQR_NTRUPRIME_SHARED_KEY_SIZE   32
#define	IQR_NTRUPRIME_CIPHERTEXT_SIZE   1047
#define	IQR_NTRUPRIME_PUBLIC_KEY_SIZE   1218
#define	IQR_NTRUPRIME_PRIVATE_KEY_SIZE   1600

Typedefs
typedef struct iqr_NTRUPrimeParams_struct	iqr_NTRUPrimeParams
typedef struct iqr_NTRUPrimePrivateKey_struct	iqr_NTRUPrimePrivateKey
typedef struct iqr_NTRUPrimePublicKey_struct	iqr_NTRUPrimePublicKey

Functions
IQR_API iqr_retval	iqr_NTRUPrimeCreateParams (const iqr_Context *ctx, iqr_NTRUPrimeParams **params)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_NTRUPrimeDestroyParams (iqr_NTRUPrimeParams **params)
IQR_API iqr_retval	iqr_NTRUPrimeCreateKeyPair (const iqr_NTRUPrimeParams *params, const iqr_RNG *rng, iqr_NTRUPrimePublicKey **public_key, iqr_NTRUPrimePrivateKey **private_key)
IQR_API iqr_retval	iqr_NTRUPrimeImportPublicKey (const iqr_NTRUPrimeParams *params, const uint8_t *buf, size_t buf_size, iqr_NTRUPrimePublicKey **public_key)
IQR_API iqr_retval	iqr_NTRUPrimeImportPrivateKey (const iqr_NTRUPrimeParams *params, const uint8_t *buf, size_t buf_size, iqr_NTRUPrimePrivateKey **private_key)
IQR_API iqr_retval	iqr_NTRUPrimeExportPublicKey (const iqr_NTRUPrimePublicKey *public_key, uint8_t *buf, size_t buf_size)
IQR_API iqr_retval	iqr_NTRUPrimeExportPrivateKey (const iqr_NTRUPrimePrivateKey *private_key, uint8_t *buf, size_t buf_size)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_NTRUPrimeDestroyPublicKey (iqr_NTRUPrimePublicKey **public_key)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_NTRUPrimeDestroyPrivateKey (iqr_NTRUPrimePrivateKey **private_key)
IQR_API iqr_retval	iqr_NTRUPrimeEncapsulate (const iqr_NTRUPrimePublicKey *public_key, const iqr_RNG *rng, uint8_t *ciphertext, size_t ciphertext_size, uint8_t *shared_key, size_t shared_key_size)
IQR_API iqr_retval	iqr_NTRUPrimeDecapsulate (const iqr_NTRUPrimePrivateKey *private_key, const uint8_t *ciphertext, size_t ciphertext_size, uint8_t *shared_key, size_t shared_key_size)

Macro Definition Documentation

IQR_NTRUPRIME_CIPHERTEXT_SIZE

#define IQR_NTRUPRIME_CIPHERTEXT_SIZE   1047

The size of the ciphertext produced by the NTRUPrime KEM in bytes.

IQR_NTRUPRIME_PRIVATE_KEY_SIZE

#define IQR_NTRUPRIME_PRIVATE_KEY_SIZE   1600

The size of the NTRUPrime private key in bytes.

IQR_NTRUPRIME_PUBLIC_KEY_SIZE

#define IQR_NTRUPRIME_PUBLIC_KEY_SIZE   1218

The size of the NTRUPrime public key in bytes.

IQR_NTRUPRIME_SHARED_KEY_SIZE

#define IQR_NTRUPRIME_SHARED_KEY_SIZE   32

The size of the shared key produced by the NTRUPrime KEM in bytes.

Typedef Documentation

iqr_NTRUPrimeParams

typedef struct iqr_NTRUPrimeParams_struct iqr_NTRUPrimeParams

NTRUPrime parameters.

iqr_NTRUPrimePrivateKey

typedef struct iqr_NTRUPrimePrivateKey_struct iqr_NTRUPrimePrivateKey

NTRUPrime private key.

iqr_NTRUPrimePublicKey

typedef struct iqr_NTRUPrimePublicKey_struct iqr_NTRUPrimePublicKey

NTRUPrime public key.

Function Documentation

iqr_NTRUPrimeCreateKeyPair()

IQR_API iqr_retval iqr_NTRUPrimeCreateKeyPair	(	const iqr_NTRUPrimeParams *	params,
		const iqr_RNG *	rng,
		iqr_NTRUPrimePublicKey **	public_key,
		iqr_NTRUPrimePrivateKey **	private_key
	)

Generate an NTRUPrime private/public key pair.

The rng must be initialized before being passed to iqr_NTRUPrimeCreateKeyPair().

Note

If iqr_NTRUPrimeCreateKeyPair() returns IQR_ERESEED, your random number generator isn't producing uniformly random values. Use a cryptographically strong RNG (such as HMAC-DRBG) with sufficient entropy.

Parameters

[in]	params	The NTRUPrime parameters.
[in]	rng	A seeded random number generator.
[out]	public_key	The resulting iqr_NTRUPrimePublicKey object.
[out]	private_key	The resulting iqr_NTRUPrimePrivateKey object.

Returns

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

iqr_NTRUPrimeCreateParams()

IQR_API iqr_retval iqr_NTRUPrimeCreateParams	(	const iqr_Context *	ctx,
		iqr_NTRUPrimeParams **	params
	)

Create an NTRUPrime Parameters object that encapsulates the domain parameters.

We use the hard-coded parameters:

P = 761 Q = 4591 T = 143

This parameter set provides 248 bit classical security and 128 bit quantum security.

The parameter data is not exposed in stored keys or secrets.

You must call iqr_HashRegisterCallbacks() to register the hash implementation. NTRUPrime uses SHA2-512.

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

Parameters

[in]	ctx	A Context object.
[out]	params	The NTRUPrime parameter object.

Returns

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

iqr_NTRUPrimeDecapsulate()

IQR_API iqr_retval iqr_NTRUPrimeDecapsulate	(	const iqr_NTRUPrimePrivateKey *	private_key,
		const uint8_t *	ciphertext,
		size_t	ciphertext_size,
		uint8_t *	shared_key,
		size_t	shared_key_size
	)

NTRUPrime decapsulation.

Creates a shared key from a ciphertext. This will be the same shared key that was generated by iqr_NTRUPrimeEncapsulate() when the ciphertext was created.

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

Parameters

[in]	private_key	Input private key.
[in]	ciphertext	The input ciphertext.
[in]	ciphertext_size	The size of ciphertext in bytes. Must be exactly IQR_NTRUPRIME_CIPHERTEXT_SIZE bytes.
[out]	shared_key	The resulting shared_key.
[in]	shared_key_size	The size of shared_key in bytes. Must be exactly IQR_NTRUPRIME_SHARED_KEY_SIZE bytes.

Returns

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

iqr_NTRUPrimeDestroyParams()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_NTRUPrimeDestroyParams

(

iqr_NTRUPrimeParams **

params

)

Clear and deallocate an NTRUPrime Parameter object.

params will be set to NULL prior to returning.

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

Parameters

[in,out]

params

The NTRUPrime parameter object to destroy.

Returns

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

iqr_NTRUPrimeDestroyPrivateKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_NTRUPrimeDestroyPrivateKey

(

iqr_NTRUPrimePrivateKey **

private_key

)

Clear and deallocate an NTRUPrime private key.

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]

private_key

The iqr_NTRUPrimePrivateKey object to destroy.

Returns

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

iqr_NTRUPrimeDestroyPublicKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_NTRUPrimeDestroyPublicKey

(

iqr_NTRUPrimePublicKey **

public_key

)

Clear and deallocate an NTRUPrime public key.

public_key will be set to NULL prior to returning.

Parameters

[in,out]

public_key

The iqr_NTRUPrimePublicKey object to destroy.

Returns

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

iqr_NTRUPrimeEncapsulate()

IQR_API iqr_retval iqr_NTRUPrimeEncapsulate	(	const iqr_NTRUPrimePublicKey *	public_key,
		const iqr_RNG *	rng,
		uint8_t *	ciphertext,
		size_t	ciphertext_size,
		uint8_t *	shared_key,
		size_t	shared_key_size
	)

NTRUPrime encapsulation.

Creates a shared key and a ciphertext. When iqr_NTRUPrimeDecapsulate() is called on the ciphertext and corresponding private key the same shared key will be generated.

The rng must be initialized before being passed to iqr_NTRUPrimeEncapsulate().

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

Parameters

[in]	public_key	Input public key.
[in]	rng	A seeded random number generator.
[out]	ciphertext	The resulting ciphertext.
[in]	ciphertext_size	The size of ciphertext in bytes. Must be exactly IQR_NTRUPRIME_CIPHERTEXT_SIZE bytes.
[out]	shared_key	The resulting shared_key.
[in]	shared_key_size	The size of shared_key in bytes. Must be exactly IQR_NTRUPRIME_SHARED_KEY_SIZE bytes.

Returns

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

iqr_NTRUPrimeExportPrivateKey()

IQR_API iqr_retval iqr_NTRUPrimeExportPrivateKey	(	const iqr_NTRUPrimePrivateKey *	private_key,
		uint8_t *	buf,
		size_t	buf_size
	)

Export the NTRUPrime private key's data into a buffer.

Be sure to safely wipe and discard buf when you're done using it.

Parameters

[in]	private_key	The private key object.
[out]	buf	The destination buffer.
[in]	buf_size	The size of buf in bytes. Must be exactly IQR_NTRUPRIME_PRIVATE_KEY_SIZE bytes.

Returns

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

iqr_NTRUPrimeExportPublicKey()

IQR_API iqr_retval iqr_NTRUPrimeExportPublicKey	(	const iqr_NTRUPrimePublicKey *	public_key,
		uint8_t *	buf,
		size_t	buf_size
	)

Export the NTRUPrime public key's data into a buffer.

Parameters

[in]	public_key	The public key object.
[out]	buf	The destination buffer.
[in]	buf_size	The size of buf in bytes. Must be exactly IQR_NTRUPRIME_PUBLIC_KEY_SIZE bytes.

Returns

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

iqr_NTRUPrimeImportPrivateKey()

IQR_API iqr_retval iqr_NTRUPrimeImportPrivateKey	(	const iqr_NTRUPrimeParams *	params,
		const uint8_t *	buf,
		size_t	buf_size,
		iqr_NTRUPrimePrivateKey **	private_key
	)

Import an NTRUPrime private key object from a buffer.

Note

This function only accepts data that has been generated by iqr_NTRUPrimeExportPrivateKey(). There is currently no standard for saving NTRUPrime private keys.

*private_key must be set to NULL before calling iqr_NTRUPrimeImportPrivateKey(). Be sure to safely wipe and discard buf after calling this function.

Parameters

[in]	params	The NTRUPrime parameters. Must be the same as when the keys were created.
[in]	buf	A buffer that contains a private key.
[in]	buf_size	The size of buf in bytes. Must be exactly IQR_NTRUPRIME_PRIVATE_KEY_SIZE bytes.
[out]	private_key	The resulting iqr_NTRUPrimePrivateKey object.

Returns

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

iqr_NTRUPrimeImportPublicKey()

IQR_API iqr_retval iqr_NTRUPrimeImportPublicKey	(	const iqr_NTRUPrimeParams *	params,
		const uint8_t *	buf,
		size_t	buf_size,
		iqr_NTRUPrimePublicKey **	public_key
	)

Import an NTRUPrime public key object from a buffer.

Note

This function only accepts data that has been generated by iqr_NTRUPrimeExportPublicKey(). There is currently no standard for saving NTRUPrime public keys.

*public_key must be set to NULL before calling iqr_NTRUPrimeImportPublicKey().

Parameters

[in]	params	The NTRUPrime parameters. same as when the keys were created.
[in]	buf	A buffer that contains a public key.
[in]	buf_size	The size of buf in bytes. Must be exactly IQR_NTRUPRIME_PUBLIC_KEY_SIZE bytes.
[out]	public_key	The resulting iqr_NTRUPrimePublicKey object.

Returns

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

Detailed Description

ISARA Radiate Security Solution Suite's NTRUPrime KEM.

Implementation of Streamlined NTRUPrime with hardcoded parameters Based on NTRU Prime.

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.