iqr_xmss.h File Reference

ISARA Radiate Quantum-Safe Library's eXtended Merkle Signature Scheme. More...

Macros
#define	IQR_XMSS_PUBLIC_KEY_SIZE   68

Typedefs
typedef struct iqr_XMSSPrivateKeyState_struct	iqr_XMSSPrivateKeyState
typedef struct iqr_XMSSParams_struct	iqr_XMSSParams
typedef struct iqr_XMSSPublicKey_struct	iqr_XMSSPublicKey
typedef struct iqr_XMSSPrivateKey_struct	iqr_XMSSPrivateKey
typedef struct iqr_XMSSTreeStrategy_struct	iqr_XMSSTreeStrategy
typedef struct iqr_XMSSVariant_struct	iqr_XMSSVariant

Functions
IQR_API iqr_retval	iqr_XMSSCreateParams (const iqr_Context *ctx, const iqr_XMSSTreeStrategy *strategy, const iqr_XMSSVariant *variant, iqr_XMSSParams **params)
IQR_API iqr_retval	iqr_XMSSCreateParamsFromPublicKeyBuffer (const iqr_Context *ctx, const uint8_t *buf, size_t buf_size, iqr_XMSSParams **params)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_XMSSDestroyParams (iqr_XMSSParams **params)
IQR_API iqr_retval	iqr_XMSSCreateKeyPair (const iqr_XMSSParams *params, const iqr_RNG *rng, iqr_XMSSPublicKey **public_key, iqr_XMSSPrivateKey **private_key, iqr_XMSSPrivateKeyState **state)
IQR_API iqr_retval	iqr_XMSSImportPrivateKey (const iqr_XMSSParams *params, const uint8_t *buf, size_t buf_size, iqr_XMSSPrivateKey **private_key)
IQR_API iqr_retval	iqr_XMSSExportPrivateKey (const iqr_XMSSPrivateKey *private_key, uint8_t *buf, size_t buf_size)
IQR_API iqr_retval	iqr_XMSSImportPublicKey (const iqr_XMSSParams *params, const uint8_t *buf, size_t buf_size, iqr_XMSSPublicKey **public_key)
IQR_API iqr_retval	iqr_XMSSExportPublicKey (const iqr_XMSSPublicKey *public_key, uint8_t *buf, size_t buf_size)
IQR_API iqr_retval	iqr_XMSSImportState (const iqr_XMSSParams *params, const uint8_t *buf, size_t buf_size, iqr_XMSSPrivateKeyState **state)
IQR_API iqr_retval	iqr_XMSSExportState (const iqr_XMSSPrivateKeyState *state, uint8_t *buf, size_t buf_size)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_XMSSDestroyPrivateKey (iqr_XMSSPrivateKey **private_key)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_XMSSDestroyPublicKey (iqr_XMSSPublicKey **public_key)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_XMSSDestroyState (iqr_XMSSPrivateKeyState **state)
IQR_API iqr_retval	iqr_XMSSDetachState (const iqr_XMSSPrivateKey *private_key, iqr_XMSSPrivateKeyState *state, uint32_t num_sigs, iqr_XMSSPrivateKeyState **detached_state)
IQR_API iqr_retval	iqr_XMSSGetPrivateKeySize (const iqr_XMSSParams *params, size_t *private_key_size)
IQR_API iqr_retval	iqr_XMSSGetPublicKeySize (const iqr_XMSSParams *params, size_t *public_key_size)
IQR_API iqr_retval	iqr_XMSSGetStateSize (const iqr_XMSSParams *params, size_t *state_size)
IQR_API iqr_retval	iqr_XMSSGetSignatureSize (const iqr_XMSSParams *params, size_t *sig_size)
IQR_API iqr_retval	iqr_XMSSGetSignatureCount (const iqr_XMSSPrivateKeyState *state, uint32_t *remaining_sigs)
IQR_API iqr_retval	iqr_XMSSSign (const iqr_XMSSPrivateKey *private_key, const uint8_t *message, size_t message_size, iqr_XMSSPrivateKeyState *state, uint8_t *sig, size_t sig_size)
IQR_API iqr_retval	iqr_XMSSVerify (const iqr_XMSSPublicKey *public_key, const uint8_t *message, size_t message_size, const uint8_t *sig, size_t sig_size)

Variables
const IQR_EXTERN iqr_XMSSTreeStrategy	IQR_XMSS_MEMORY_CONSTRAINED_STRATEGY
	Strategy for memory-constrained systems. More...
const IQR_EXTERN iqr_XMSSTreeStrategy	IQR_XMSS_FULL_TREE_STRATEGY
	Strategy for systems with unlimited memory. More...
const IQR_EXTERN iqr_XMSSTreeStrategy	IQR_XMSS_VERIFY_ONLY_STRATEGY
	Strategy for systems that only need to verify signatures. More...
const IQR_EXTERN iqr_XMSSVariant	IQR_XMSS_2E10
	Provide 210 (1,024) one-time signatures in a single tree. More...
const IQR_EXTERN iqr_XMSSVariant	IQR_XMSS_2E16
	Provide 216 (65,536) one-time signatures in a single tree. More...

Macro Definition Documentation

IQR_XMSS_PUBLIC_KEY_SIZE

#define IQR_XMSS_PUBLIC_KEY_SIZE   68

The size of the XMSS public key in bytes.

Typedef Documentation

iqr_XMSSParams

typedef struct iqr_XMSSParams_struct iqr_XMSSParams

The XMSS algorithm's domain parameters.

iqr_XMSSPrivateKey

typedef struct iqr_XMSSPrivateKey_struct iqr_XMSSPrivateKey

The XMSS private key.

iqr_XMSSPrivateKeyState

typedef struct iqr_XMSSPrivateKeyState_struct iqr_XMSSPrivateKeyState

The XMSS private state.

iqr_XMSSPublicKey

typedef struct iqr_XMSSPublicKey_struct iqr_XMSSPublicKey

The XMSS public key.

iqr_XMSSTreeStrategy

typedef struct iqr_XMSSTreeStrategy_struct iqr_XMSSTreeStrategy

The XMSS tree strategy.

iqr_XMSSVariant

typedef struct iqr_XMSSVariant_struct iqr_XMSSVariant

The XMSS variant.

Function Documentation

iqr_XMSSCreateKeyPair()

IQR_API iqr_retval iqr_XMSSCreateKeyPair	(	const iqr_XMSSParams *	params,
		const iqr_RNG *	rng,
		iqr_XMSSPublicKey **	public_key,
		iqr_XMSSPrivateKey **	private_key,
		iqr_XMSSPrivateKeyState **	state
	)

Generate an XMSS private/public key pair.

The iqr_XMSSCreateKeyPair() function calls the watchdog callback (see iqr_watchdog.h).

Note

You must register a SHA2-256 implementation by calling iqr_HashRegisterCallbacks() before using the XMSS API.

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

*public_key, *private_key, and state must be set to NULL before calling iqr_XMSSCreateKeyPair().

params must be created with a tree strategy other than IQR_XMSS_VERIFY_ONLY_STRATEGY.

Parameters

[in]	params	The key parameters to use.
[in]	rng	A seeded random number generator.
[out]	public_key	The resulting iqr_XMSSPublicKey object.
[out]	private_key	The resulting iqr_XMSSPrivateKey object.
[out]	state	The resulting iqr_XMSSPrivateKeyState object.

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_XMSSCreateParams()

IQR_API iqr_retval iqr_XMSSCreateParams	(	const iqr_Context *	ctx,
		const iqr_XMSSTreeStrategy *	strategy,
		const iqr_XMSSVariant *	variant,
		iqr_XMSSParams **	params
	)

Create an XMSS Parameters object that encapsulates domain parameters.

It's up to the user to manage domain parameters; the parameter data is not exposed in stored keys or signatures.

Note

You must register a SHA2-256 implementation by calling iqr_HashRegisterCallbacks() before using the XMSS API.

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

Parameters

[in]	ctx	A Context object.
[in]	strategy	The tree strategy.
[in]	variant	The iqr_XMSSVariant.
[out]	params	The iqr_XMSSParams output.

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_XMSSCreateParamsFromPublicKeyBuffer()

IQR_API iqr_retval iqr_XMSSCreateParamsFromPublicKeyBuffer	(	const iqr_Context *	ctx,
		const uint8_t *	buf,
		size_t	buf_size,
		iqr_XMSSParams **	params
	)

Create an XMSS Parameters object using a public key buffer.

This object will have the same parameter values as the public key.

The params object will use IQR_XMSS_VERIFY_ONLY_STRATEGY.

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

Parameters

[in]	ctx	A Context object.
[in]	buf	Public key buffer.
[in]	buf_size	The size of buf in bytes. Must be exactly IQR_XMSS_PUBLIC_KEY_SIZE.
[out]	params	The iqr_XMSSParams output.

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_XMSSDestroyParams()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_XMSSDestroyParams

(

iqr_XMSSParams **

params

)

Clear and deallocate an XMSS key parameters object.

params is set to NULL before returning.

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

Parameters

[in,out]

params

The iqr_XMSSParams instance to destroy.

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_XMSSDestroyPrivateKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_XMSSDestroyPrivateKey

(

iqr_XMSSPrivateKey **

private_key

)

Clear and deallocate an XMSS private key.

*private_key is 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_XMSSPrivateKey object to destroy.

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_XMSSDestroyPublicKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_XMSSDestroyPublicKey

(

iqr_XMSSPublicKey **

public_key

)

Clear and deallocate an XMSS public key.

*public_key is set to NULL prior to returning.

Parameters

[in,out]

public_key

The iqr_XMSSPublicKey object to destroy.

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_XMSSDestroyState()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_XMSSDestroyState

(

iqr_XMSSPrivateKeyState **

state

)

Clear and deallocate an XMSS state.

*state is set to NULL prior to returning.

Parameters

[in,out]

state

The iqr_XMSSPrivateKeyState object to destroy.

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_XMSSDetachState()

IQR_API iqr_retval iqr_XMSSDetachState	(	const iqr_XMSSPrivateKey *	private_key,
		iqr_XMSSPrivateKeyState *	state,
		uint32_t	num_sigs,
		iqr_XMSSPrivateKeyState **	detached_state
	)

Detaches a subset of signatures from state into a new state object.

This function can be used to split a state into two distinct, non-overlapping state objects. This operation effectively "reserves" a number of signatures from state and places them into a new distinct object, detached_state. Both state objects must be used with the same private key to generate signatures.

Please see the Developer's Guide (online) for details about using detached states.

*detached_state must be set to NULL before calling iqr_XMSSDetachState().

Parameters

[in]	private_key	The private key.
[in,out]	state	The original state to be split.
[in]	num_sigs	The number of signatures to split off. Must not exceed the value returned by iqr_XMSSGetSignatureCount().
[out]	detached_state	A new state object containing num_sigs signatures.

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_XMSSExportPrivateKey()

IQR_API iqr_retval iqr_XMSSExportPrivateKey	(	const iqr_XMSSPrivateKey *	private_key,
		uint8_t *	buf,
		size_t	buf_size
	)

Export the XMSS 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_XMSSGetPrivateKeySize().

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_XMSSExportPublicKey()

IQR_API iqr_retval iqr_XMSSExportPublicKey	(	const iqr_XMSSPublicKey *	public_key,
		uint8_t *	buf,
		size_t	buf_size
	)

Export the XMSS 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_XMSSGetPublicKeySize().

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_XMSSExportState()

IQR_API iqr_retval iqr_XMSSExportState	(	const iqr_XMSSPrivateKeyState *	state,
		uint8_t *	buf,
		size_t	buf_size
	)

Export the XMSS state's data into a buffer.

Parameters

[in]	state	The state object.
[out]	buf	The destination buffer.
[in]	buf_size	The size of buf in bytes. Must be exactly the size returned by iqr_XMSSGetStateSize().

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_XMSSGetPrivateKeySize()

IQR_API iqr_retval iqr_XMSSGetPrivateKeySize	(	const iqr_XMSSParams *	params,
		size_t *	private_key_size
	)

Retrieve the size of the XMSS private key in bytes.

Parameters

[in]	params	XMSS domain parameters.
[out]	private_key_size	The size of the private key in bytes.

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_XMSSGetPublicKeySize()

IQR_API iqr_retval iqr_XMSSGetPublicKeySize	(	const iqr_XMSSParams *	params,
		size_t *	public_key_size
	)

Retrieve the size of the XMSS public key in bytes.

Parameters

[in]	params	XMSS domain parameters.
[out]	public_key_size	The size of the public key in bytes.

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_XMSSGetSignatureCount()

IQR_API iqr_retval iqr_XMSSGetSignatureCount	(	const iqr_XMSSPrivateKeyState *	state,
		uint32_t *	remaining_sigs
	)

Get the number of signatures available with the given state.

The total number of signatures that can be generated is based on the height of the tree (governed by the iqr_XMSSVariant). The number of remaining signatures depends on how many iqr_XMSSSign() operations have been performed.

Parameters

[in]	state	The state.
[out]	remaining_sigs	The remaining number of signatures.

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_XMSSGetSignatureSize()

IQR_API iqr_retval iqr_XMSSGetSignatureSize	(	const iqr_XMSSParams *	params,
		size_t *	sig_size
	)

Get the size of the signature.

Parameters

[in]	params	XMSS domain parameters.
[out]	sig_size	The size of the XMSS signature for the given private key in bytes.

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_XMSSGetStateSize()

IQR_API iqr_retval iqr_XMSSGetStateSize	(	const iqr_XMSSParams *	params,
		size_t *	state_size
	)

Get the size of the XMSS state in bytes.

params must be created with a tree strategy other than IQR_XMSS_VERIFY_ONLY_STRATEGY.

Parameters

[in]	params	XMSS domain parameters.
[out]	state_size	The size of the state in bytes.

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_XMSSImportPrivateKey()

IQR_API iqr_retval iqr_XMSSImportPrivateKey	(	const iqr_XMSSParams *	params,
		const uint8_t *	buf,
		size_t	buf_size,
		iqr_XMSSPrivateKey **	private_key
	)

Import an XMSS private key object from a buffer.

The value of buf_size must be exactly the size given by iqr_XMSSGetPrivateKeySize().

Note

You must register a SHA2-256 implementation by calling iqr_HashRegisterCallbacks() before using the XMSS API.

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

Parameters

[in]	params	XMSS 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 the size returned by iqr_XMSSGetPrivateKeySize().
[out]	private_key	The resulting iqr_XMSSPrivateKey object.

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_XMSSImportPublicKey()

IQR_API iqr_retval iqr_XMSSImportPublicKey	(	const iqr_XMSSParams *	params,
		const uint8_t *	buf,
		size_t	buf_size,
		iqr_XMSSPublicKey **	public_key
	)

Import an XMSS public key object from a buffer.

Note

You must register a SHA2-256 implementation by calling iqr_HashRegisterCallbacks() before using the XMSS API.

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

Parameters

[in]	params	XMSS parameters. Must be the same as when the keys were created.
[in]	buf	A buffer containing the public key.
[in]	buf_size	The size of buf in bytes. Must be exactly the size returned by iqr_XMSSGetPublicKeySize().
[out]	public_key	The resulting iqr_XMSSPublicKey object.

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_XMSSImportState()

IQR_API iqr_retval iqr_XMSSImportState	(	const iqr_XMSSParams *	params,
		const uint8_t *	buf,
		size_t	buf_size,
		iqr_XMSSPrivateKeyState **	state
	)

Import an XMSS State object from a buffer.

The value of buf_size must be exactly the size given by iqr_XMSSGetStateSize().

*state must be set to NULL before calling iqr_XMSSImportState().

params must be created with a tree strategy other than IQR_XMSS_VERIFY_ONLY_STRATEGY for a successful import.

Parameters

[in]	params	XMSS parameters. Must be the same as when the keys were created.
[in]	buf	A buffer that contains a state.
[in]	buf_size	The size of buf in bytes. Must be exactly the size returned by iqr_XMSSGetStateSize().
[out]	state	The resulting iqr_XMSSPrivateKeyState object.

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_XMSSSign()

IQR_API iqr_retval iqr_XMSSSign	(	const iqr_XMSSPrivateKey *	private_key,
		const uint8_t *	message,
		size_t	message_size,
		iqr_XMSSPrivateKeyState *	state,
		uint8_t *	sig,
		size_t	sig_size
	)

Sign a message using an XMSS private key.

As signatures are generated, the state can run out of signing keys. In that case, IQR_ESTATEDEPLETED is returned and the key can no longer be used for signing. Use iqr_XMSSGetSignatureCount() to check the number of signatures remaining.

For more details about signing and the private key state, refer to the Developer's Guide (online).

Warning

Restarting from a previous state makes XMSS insecure.

Note

You must register a SHA2-256 implementation by calling iqr_HashRegisterCallbacks() before using the XMSS API.

If the message is a digest of a hash function it should be 32 bytes or longer to be quantum-safe.

All internal buffers are cleared and deallocated before the call to iqr_XMSSSign() returns.

Parameters

[in]	private_key	The private key.
[in]	message	The message to be signed.
[in]	message_size	The size of message in bytes.
[in,out]	state	The state object.
[out]	sig	The buffer receiving the resulting signature.
[in]	sig_size	The size of sig in bytes. Must be exactly the size returned by iqr_XMSSGetSignatureSize().

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

iqr_XMSSVerify()

IQR_API iqr_retval iqr_XMSSVerify	(	const iqr_XMSSPublicKey *	public_key,
		const uint8_t *	message,
		size_t	message_size,
		const uint8_t *	sig,
		size_t	sig_size
	)

Verify the signature of a message using an XMSS public key.

Note

You must register a SHA2-256 implementation by calling iqr_HashRegisterCallbacks() before using the XMSS API.

All internal buffers are cleared and deallocated before the call to iqr_XMSSVerify() returns.

Parameters

[in]	public_key	The public key.
[in]	message	The message to verify.
[in]	message_size	The size of message in bytes.
[in]	sig	The signature to verify.
[in]	sig_size	The size of sig in bytes. Must be exactly the size returned by iqr_XMSSGetSignatureSize().

Returns

IQR_OK on success, or another value from iqr_retval.h if an error occurs.

Detailed Description

ISARA Radiate Quantum-Safe Library's eXtended Merkle Signature Scheme.

The eXtended Merkle Signature Scheme is defined by NIST SP 800-208.

This header contains the functions and parameters necessary to create and verify an XMSS signature. The two main functions are iqr_XMSSSign() and iqr_XMSSVerify(). The rest of the functions let you create and manipulate XMSS keys.

This scheme has some fundamental differences from traditional signature schemes such as RSA or ECDSA. In particular, you'll need to manage the state used by iqr_XMSSSign() carefully. For more details, refer to the Developer's Guide (online).

Note

As specified above, the state is managed by the user. This differs from the IETF specification, where the state is stored and updated within the private key as an index.

Copyright

Copyright (C) 2017-2023, 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.