iqr_sike.h File Reference

ISARA Radiate Security Solution Suite's Supersingular Isogeny Key Encapsulation (SIKE). More...

Typedefs
typedef struct iqr_SIKEParams_struct	iqr_SIKEParams
typedef struct iqr_SIKEPublicKey_struct	iqr_SIKEPublicKey
typedef struct iqr_SIKEPrivateKey_struct	iqr_SIKEPrivateKey
typedef struct iqr_SIKEVariant_struct	iqr_SIKEVariant

Functions
IQR_API iqr_retval	iqr_SIKECreateParams (const iqr_Context *ctx, const iqr_SIKEVariant *variant, iqr_SIKEParams **params)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_SIKEDestroyParams (iqr_SIKEParams **params)
IQR_API iqr_retval	iqr_SIKECreateKeyPair (const iqr_SIKEParams *params, const iqr_RNG *rng, iqr_SIKEPublicKey **public_key, iqr_SIKEPrivateKey **private_key)
IQR_API iqr_retval	iqr_SIKEImportPublicKey (const iqr_SIKEParams *params, const uint8_t *buf, size_t buf_size, iqr_SIKEPublicKey **public_key)
IQR_API iqr_retval	iqr_SIKEImportPrivateKey (const iqr_SIKEParams *params, const uint8_t *buf, size_t buf_size, iqr_SIKEPrivateKey **private_key)
IQR_API iqr_retval	iqr_SIKEExportPublicKey (const iqr_SIKEPublicKey *public_key, uint8_t *buf, size_t buf_size)
IQR_API iqr_retval	iqr_SIKEExportPrivateKey (const iqr_SIKEPrivateKey *private_key, uint8_t *buf, size_t buf_size)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_SIKEDestroyPublicKey (iqr_SIKEPublicKey **public_key)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_SIKEDestroyPrivateKey (iqr_SIKEPrivateKey **private_key)
IQR_API iqr_retval	iqr_SIKEGetPublicKeySize (const iqr_SIKEParams *params, size_t *public_key_size)
IQR_API iqr_retval	iqr_SIKEGetPrivateKeySize (const iqr_SIKEParams *params, size_t *private_key_size)
IQR_API iqr_retval	iqr_SIKEGetCiphertextSize (const iqr_SIKEParams *params, size_t *ciphertext_size)
IQR_API iqr_retval	iqr_SIKEGetSharedKeySize (const iqr_SIKEParams *params, size_t *shared_key_size)
IQR_API iqr_retval	iqr_SIKEEncapsulate (const iqr_SIKEPublicKey *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_SIKEDecapsulate (const iqr_SIKEPrivateKey *private_key, const uint8_t *ciphertext, size_t ciphertext_size, uint8_t *shared_key, size_t shared_key_size)

Variables
IQR_EXTERN const iqr_SIKEVariant	IQR_SIKE_P503
IQR_EXTERN const iqr_SIKEVariant	IQR_SIKE_P751

Typedef Documentation

iqr_SIKEParams

typedef struct iqr_SIKEParams_struct iqr_SIKEParams

The algorithm's domain parameters.

iqr_SIKEPrivateKey

typedef struct iqr_SIKEPrivateKey_struct iqr_SIKEPrivateKey

The SIKE private key.

iqr_SIKEPublicKey

typedef struct iqr_SIKEPublicKey_struct iqr_SIKEPublicKey

The SIKE public key.

iqr_SIKEVariant

typedef struct iqr_SIKEVariant_struct iqr_SIKEVariant

The SIKE variant. This controls the amount of security.

Function Documentation

iqr_SIKECreateKeyPair()

IQR_API iqr_retval iqr_SIKECreateKeyPair	(	const iqr_SIKEParams *	params,
		const iqr_RNG *	rng,
		iqr_SIKEPublicKey **	public_key,
		iqr_SIKEPrivateKey **	private_key
	)

Generate a SIKE private/public key pair.

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

*public_key and *private_key must be set to NULL before calling iqr_SIKECreateKeyPair().

Parameters

[in]	params	The SIKE parameters.
[in]	rng	A seeded random number generator.
[out]	public_key	The resulting iqr_SIKEPublicKey object.
[out]	private_key	The resulting iqr_SIKEPrivateKey object.

Returns

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

iqr_SIKECreateParams()

IQR_API iqr_retval iqr_SIKECreateParams	(	const iqr_Context *	ctx,
		const iqr_SIKEVariant *	variant,
		iqr_SIKEParams **	params
	)

Create a parameter object for the SIKE cryptographic system.

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

Parameters

[in]	ctx	A Context object.
[in]	variant	The iqr_SIKEVariant to use.
[out]	params	The SIKE parameter object.

Returns

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

iqr_SIKEDecapsulate()

IQR_API iqr_retval iqr_SIKEDecapsulate	(	const iqr_SIKEPrivateKey *	private_key,
		const uint8_t *	ciphertext,
		size_t	ciphertext_size,
		uint8_t *	shared_key,
		size_t	shared_key_size
	)

SIKE decapsulation.

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

All internal buffers are cleared and deallocated before the call to iqr_SIKEDecapsulate() 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 the size returned by iqr_SIKEGetCiphertextSize().
[out]	shared_key	The resulting shared key.
[in]	shared_key_size	The size of shared_key in bytes. Must be exactly the size returned by iqr_SIKEGetSharedKeySize().

Returns

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

iqr_SIKEDestroyParams()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_SIKEDestroyParams

(

iqr_SIKEParams **

params

)

Clear and deallocate a SIKE parameter object.

params will be set to NULL prior to returning.

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

Parameters

[in,out]

params

The SIKE parameter object to destroy.

Returns

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

iqr_SIKEDestroyPrivateKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_SIKEDestroyPrivateKey

(

iqr_SIKEPrivateKey **

private_key

)

Clear and deallocate a SIKE 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_SIKEPrivateKey object to destroy.

Returns

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

iqr_SIKEDestroyPublicKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_SIKEDestroyPublicKey

(

iqr_SIKEPublicKey **

public_key

)

Clear and deallocate a SIKE public key.

public_key will be set to NULL prior to returning.

Parameters

[in,out]

public_key

The iqr_SIKEPublicKey object to destroy.

Returns

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

iqr_SIKEEncapsulate()

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

SIKE encapsulation.

Creates a shared key and a ciphertext. When iqr_SIKEDecapsulate() 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_SIKEEncapsulate().

All internal buffers are cleared and deallocated before the call to iqr_SIKEEncapsulate() 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 the size returned by iqr_SIKEGetCiphertextSize()
[out]	shared_key	The resulting shared key.
[in]	shared_key_size	The size of shared_key in bytes. Must be exactly the size returned by iqr_SIKEGetSharedKeySize().

Returns

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

iqr_SIKEExportPrivateKey()

IQR_API iqr_retval iqr_SIKEExportPrivateKey	(	const iqr_SIKEPrivateKey *	private_key,
		uint8_t *	buf,
		size_t	buf_size
	)

Export the SIKE 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 the size returned by iqr_SIKEGetPrivateKeySize().

Returns

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

iqr_SIKEExportPublicKey()

IQR_API iqr_retval iqr_SIKEExportPublicKey	(	const iqr_SIKEPublicKey *	public_key,
		uint8_t *	buf,
		size_t	buf_size
	)

Export the SIKE 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 the size returned by iqr_SIKEGetPublicKeySize().

Returns

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

iqr_SIKEGetCiphertextSize()

IQR_API iqr_retval iqr_SIKEGetCiphertextSize	(	const iqr_SIKEParams *	params,
		size_t *	ciphertext_size
	)

Get the size of the ciphertext.

Parameters

[in]	params	The iqr_SIKEParams to use.
[out]	ciphertext_size	The size of the ciphertext in bytes.

Returns

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

iqr_SIKEGetPrivateKeySize()

IQR_API iqr_retval iqr_SIKEGetPrivateKeySize	(	const iqr_SIKEParams *	params,
		size_t *	private_key_size
	)

Get the size of the private key.

Parameters

[in]	params	The iqr_SIKEParams to use.
[out]	private_key_size	The size of the private key in bytes.

Returns

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

iqr_SIKEGetPublicKeySize()

IQR_API iqr_retval iqr_SIKEGetPublicKeySize	(	const iqr_SIKEParams *	params,
		size_t *	public_key_size
	)

Get the size of the public key.

Parameters

[in]	params	The iqr_SIKEParams to use.
[out]	public_key_size	The size of the public key in bytes.

Returns

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

iqr_SIKEGetSharedKeySize()

IQR_API iqr_retval iqr_SIKEGetSharedKeySize	(	const iqr_SIKEParams *	params,
		size_t *	shared_key_size
	)

Get the size of the shared key.

Parameters

[in]	params	The iqr_SIKEParams to use.
[out]	shared_key_size	The size of the shared key in bytes.

Returns

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

iqr_SIKEImportPrivateKey()

IQR_API iqr_retval iqr_SIKEImportPrivateKey	(	const iqr_SIKEParams *	params,
		const uint8_t *	buf,
		size_t	buf_size,
		iqr_SIKEPrivateKey **	private_key
	)

Import a SIKE private key object from a buffer.

Note

This function only accepts data that has been generated by iqr_SIKEExportPrivateKey().

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

Parameters

[in]	params	The SIKE parameters.
[in]	buf	A buffer that contains a private key.
[in]	buf_size	The size of buf in bytes. Must be exactly the size returned by iqr_SIKEGetPrivateKeySize().
[out]	private_key	The resulting iqr_SIKEPrivateKey object.

Returns

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

iqr_SIKEImportPublicKey()

IQR_API iqr_retval iqr_SIKEImportPublicKey	(	const iqr_SIKEParams *	params,
		const uint8_t *	buf,
		size_t	buf_size,
		iqr_SIKEPublicKey **	public_key
	)

Import a SIKE public key object from a buffer.

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

Parameters

[in]	params	The SIKE parameters.
[in]	buf	A buffer that contains a public key.
[in]	buf_size	The size of buf in bytes. Must be exactly the size returned by iqr_SIKEGetPublicKeySize().
[out]	public_key	The resulting iqr_SIKEPublicKey object.

Returns

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

Variable Documentation

IQR_SIKE_P503

IQR_EXTERN const iqr_SIKEVariant IQR_SIKE_P503

SIKEp503 scheme parameter set.

IQR_SIKE_P751

IQR_EXTERN const iqr_SIKEVariant IQR_SIKE_P751

SIKEp751 scheme parameter set.

Detailed Description

ISARA Radiate Security Solution Suite's Supersingular Isogeny Key Encapsulation (SIKE).

An implementation of SIKE as defined in SIKE.

Copyright

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