iqr_hss.h File Reference

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

Macros
#define	IQR_HSS_PUBLIC_KEY_SIZE   60

Typedefs
typedef struct iqr_HSSPrivateKeyState_struct	iqr_HSSPrivateKeyState
typedef struct iqr_HSSParams_struct	iqr_HSSParams
typedef struct iqr_HSSPublicKey_struct	iqr_HSSPublicKey
typedef struct iqr_HSSPrivateKey_struct	iqr_HSSPrivateKey
typedef struct iqr_HSSTreeStrategy_struct	iqr_HSSTreeStrategy
typedef struct iqr_HSSVariant_struct	iqr_HSSVariant

Functions
IQR_API iqr_retval	iqr_HSSCreateParams (const iqr_Context *ctx, const iqr_HSSTreeStrategy *strategy, const iqr_HSSVariant *variant, iqr_HSSParams **params)
IQR_API iqr_retval	iqr_HSSCreateParamsFromSignature (const iqr_Context *ctx, const uint8_t *sig, size_t sig_size, iqr_HSSParams **params)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_HSSDestroyParams (iqr_HSSParams **params)
IQR_API iqr_retval	iqr_HSSCreateKeyPair (const iqr_HSSParams *params, const iqr_RNG *rng, iqr_HSSPublicKey **public_key, iqr_HSSPrivateKey **private_key, iqr_HSSPrivateKeyState **state)
IQR_API iqr_retval	iqr_HSSImportPrivateKey (const iqr_HSSParams *params, const uint8_t *buf, size_t buf_size, iqr_HSSPrivateKey **private_key)
IQR_API iqr_retval	iqr_HSSExportPrivateKey (const iqr_HSSPrivateKey *private_key, uint8_t *buf, size_t buf_size)
IQR_API iqr_retval	iqr_HSSImportPublicKey (const iqr_HSSParams *params, const uint8_t *buf, size_t buf_size, iqr_HSSPublicKey **public_key)
IQR_API iqr_retval	iqr_HSSExportPublicKey (const iqr_HSSPublicKey *public_key, uint8_t *buf, size_t buf_size)
IQR_API iqr_retval	iqr_HSSImportState (const iqr_HSSParams *params, const uint8_t *buf, size_t buf_size, iqr_HSSPrivateKeyState **state)
IQR_API iqr_retval	iqr_HSSExportState (const iqr_HSSPrivateKeyState *state, uint8_t *buf, size_t buf_size)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_HSSDestroyPrivateKey (iqr_HSSPrivateKey **private_key)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_HSSDestroyPublicKey (iqr_HSSPublicKey **public_key)
IQR_API_UNENFORCED_RETURN iqr_retval	iqr_HSSDestroyState (iqr_HSSPrivateKeyState **state)
IQR_API iqr_retval	iqr_HSSDetachState (const iqr_HSSPrivateKey *private_key, iqr_HSSPrivateKeyState *state, uint32_t num_sigs, iqr_HSSPrivateKeyState **detached_state)
IQR_API iqr_retval	iqr_HSSGetPrivateKeySize (const iqr_HSSParams *params, size_t *private_key_size)
IQR_API iqr_retval	iqr_HSSGetPublicKeySize (const iqr_HSSParams *params, size_t *public_key_size)
IQR_API iqr_retval	iqr_HSSGetStateSize (const iqr_HSSParams *params, size_t *state_size)
IQR_API iqr_retval	iqr_HSSGetSignatureSize (const iqr_HSSParams *params, size_t *sig_size)
IQR_API iqr_retval	iqr_HSSGetSignatureCount (const iqr_HSSPrivateKeyState *state, uint32_t *remaining_sigs)
IQR_API iqr_retval	iqr_HSSSign (const iqr_HSSPrivateKey *private_key, const uint8_t *message, size_t message_size, iqr_HSSPrivateKeyState *state, uint8_t *sig, size_t sig_size)
IQR_API iqr_retval	iqr_HSSVerify (const iqr_HSSPublicKey *public_key, const uint8_t *message, size_t message_size, const uint8_t *sig, size_t sig_size)

Variables
const IQR_EXTERN iqr_HSSTreeStrategy	IQR_HSS_MEMORY_CONSTRAINED_STRATEGY
	Strategy for memory-constrained systems. More...
const IQR_EXTERN iqr_HSSTreeStrategy	IQR_HSS_FULL_TREE_STRATEGY
	Strategy for systems with unlimited memory. More...
const IQR_EXTERN iqr_HSSTreeStrategy	IQR_HSS_VERIFY_ONLY_STRATEGY
	Strategy for systems that only need to verify signatures. More...
const IQR_EXTERN iqr_HSSVariant	IQR_HSS_2E15_FAST
	Provide 215 (32,768) signatures in a single tree, Fast variant. More...
const IQR_EXTERN iqr_HSSVariant	IQR_HSS_2E15_SMALL
	Provide 215 (32,768) signatures in a single tree, Small variant. More...

Macro Definition Documentation

IQR_HSS_PUBLIC_KEY_SIZE

#define IQR_HSS_PUBLIC_KEY_SIZE   60

The size of the HSS public key in bytes.

Typedef Documentation

iqr_HSSParams

typedef struct iqr_HSSParams_struct iqr_HSSParams

The HSS algorithm's domain parameters.

iqr_HSSPrivateKey

typedef struct iqr_HSSPrivateKey_struct iqr_HSSPrivateKey

The HSS private key.

iqr_HSSPrivateKeyState

typedef struct iqr_HSSPrivateKeyState_struct iqr_HSSPrivateKeyState

The HSS algorithm's state.

iqr_HSSPublicKey

typedef struct iqr_HSSPublicKey_struct iqr_HSSPublicKey

The HSS public key.

iqr_HSSTreeStrategy

typedef struct iqr_HSSTreeStrategy_struct iqr_HSSTreeStrategy

The HSS tree strategy.

iqr_HSSVariant

typedef struct iqr_HSSVariant_struct iqr_HSSVariant

The HSS variant.

Function Documentation

iqr_HSSCreateKeyPair()

IQR_API iqr_retval iqr_HSSCreateKeyPair	(	const iqr_HSSParams *	params,
		const iqr_RNG *	rng,
		iqr_HSSPublicKey **	public_key,
		iqr_HSSPrivateKey **	private_key,
		iqr_HSSPrivateKeyState **	state
	)

Generate an HSS private/public key pair.

This can take a significant amount of time for large single-tree keys or when using larger Winternitz values (as found in the Small variants).

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

Warning

You must pass in a NIST-approved rng to be fully compliant with NIST SP 800-208. The HMAC-DRBG RNG implemented by this toolkit is approved in NIST FIPS-198-1.

Note

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

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

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

Parameters

[in]	params	The key parameters to use.
[in]	rng	A seeded random number generator.
[out]	public_key	The resulting iqr_HSSPublicKey object.
[out]	private_key	The resulting iqr_HSSPrivateKey object.
[out]	state	The resulting iqr_HSSPrivateKeyState object.

Returns

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

iqr_HSSCreateParams()

IQR_API iqr_retval iqr_HSSCreateParams	(	const iqr_Context *	ctx,
		const iqr_HSSTreeStrategy *	strategy,
		const iqr_HSSVariant *	variant,
		iqr_HSSParams **	params
	)

Create an HSS Parameters object that encapsulates the domain parameters for the Hierarchical Signature Scheme.

It's up to the user to manage domain parameters; the parameter data is not exposed in stored keys. Parameters can be recovered from a signature using iqr_HSSCreateParamsFromSignature().

Note

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

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

Parameters

[in]	ctx	A Context object.
[in]	strategy	An HSS tree strategy.
[in]	variant	The iqr_HSSVariant.
[out]	params	The iqr_HSSParams output.

Returns

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

iqr_HSSCreateParamsFromSignature()

IQR_API iqr_retval iqr_HSSCreateParamsFromSignature	(	const iqr_Context *	ctx,
		const uint8_t *	sig,
		size_t	sig_size,
		iqr_HSSParams **	params
	)

Create an HSS Parameters object using a signature.

This object will have the same parameter values as the key used to create the signature.

The params object will use IQR_HSS_VERIFY_ONLY_STRATEGY. This can be used to verify any valid HSS signature, even those created using parameter combinations not supported by the toolkit.

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

Parameters

[in]	ctx	A Context object.
[in]	sig	Signature buffer.
[in]	sig_size	The size of sig in bytes.
[out]	params	The iqr_HSSParams output.

Returns

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

iqr_HSSDestroyParams()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_HSSDestroyParams

(

iqr_HSSParams **

params

)

Clear and deallocate an HSS parameters object.

params is set to NULL before returning.

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

Parameters

[in,out]

params

The iqr_HSSParams instance to destroy.

Returns

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

iqr_HSSDestroyPrivateKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_HSSDestroyPrivateKey

(

iqr_HSSPrivateKey **

private_key

)

Clear and deallocate an HSS 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_HSSPrivateKey object to destroy.

Returns

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

iqr_HSSDestroyPublicKey()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_HSSDestroyPublicKey

(

iqr_HSSPublicKey **

public_key

)

Clear and deallocate an HSS public key.

*public_key is set to NULL prior to returning.

Parameters

[in,out]

public_key

The iqr_HSSPublicKey object to destroy.

Returns

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

iqr_HSSDestroyState()

IQR_API_UNENFORCED_RETURN iqr_retval iqr_HSSDestroyState

(

iqr_HSSPrivateKeyState **

state

)

Clear and deallocate an HSS state.

*state is set to NULL prior to returning.

Parameters

[in,out]

state

The iqr_HSSPrivateKeyState object to destroy.

Returns

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

iqr_HSSDetachState()

IQR_API iqr_retval iqr_HSSDetachState	(	const iqr_HSSPrivateKey *	private_key,
		iqr_HSSPrivateKeyState *	state,
		uint32_t	num_sigs,
		iqr_HSSPrivateKeyState **	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_HSSDetachState().

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_HSSGetSignatureCount().
[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_HSSExportPrivateKey()

IQR_API iqr_retval iqr_HSSExportPrivateKey	(	const iqr_HSSPrivateKey *	private_key,
		uint8_t *	buf,
		size_t	buf_size
	)

Export the HSS 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_HSSGetPrivateKeySize().

Returns

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

iqr_HSSExportPublicKey()

IQR_API iqr_retval iqr_HSSExportPublicKey	(	const iqr_HSSPublicKey *	public_key,
		uint8_t *	buf,
		size_t	buf_size
	)

Export the HSS 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_HSSGetPublicKeySize().

Returns

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

iqr_HSSExportState()

IQR_API iqr_retval iqr_HSSExportState	(	const iqr_HSSPrivateKeyState *	state,
		uint8_t *	buf,
		size_t	buf_size
	)

Export the HSS 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_HSSGetStateSize().

Returns

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

iqr_HSSGetPrivateKeySize()

IQR_API iqr_retval iqr_HSSGetPrivateKeySize	(	const iqr_HSSParams *	params,
		size_t *	private_key_size
	)

Retrieve the size of the HSS private key in bytes.

Parameters

[in]	params	HSS 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_HSSGetPublicKeySize()

IQR_API iqr_retval iqr_HSSGetPublicKeySize	(	const iqr_HSSParams *	params,
		size_t *	public_key_size
	)

Retrieve the size of the HSS public key in bytes.

Parameters

[in]	params	HSS 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_HSSGetSignatureCount()

IQR_API iqr_retval iqr_HSSGetSignatureCount	(	const iqr_HSSPrivateKeyState *	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_HSSVariant domain parameter).

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_HSSGetSignatureSize()

IQR_API iqr_retval iqr_HSSGetSignatureSize	(	const iqr_HSSParams *	params,
		size_t *	sig_size
	)

Get the size of the signature.

Parameters

[in]	params	HSS domain parameters.
[out]	sig_size	The size of the HSS 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_HSSGetStateSize()

IQR_API iqr_retval iqr_HSSGetStateSize	(	const iqr_HSSParams *	params,
		size_t *	state_size
	)

Retrieve the size of the HSS state in bytes.

The params object must not have been created with IQR_HSS_VERIFY_ONLY_STRATEGY.

Parameters

[in]	params	HSS 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_HSSImportPrivateKey()

IQR_API iqr_retval iqr_HSSImportPrivateKey	(	const iqr_HSSParams *	params,
		const uint8_t *	buf,
		size_t	buf_size,
		iqr_HSSPrivateKey **	private_key
	)

Import an HSS private key object from a buffer.

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

Note

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

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

Parameters

[in]	params	HSS Key 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_HSSGetPrivateKeySize().
[out]	private_key	The resulting iqr_HSSPrivateKey object.

Returns

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

iqr_HSSImportPublicKey()

IQR_API iqr_retval iqr_HSSImportPublicKey	(	const iqr_HSSParams *	params,
		const uint8_t *	buf,
		size_t	buf_size,
		iqr_HSSPublicKey **	public_key
	)

Import an HSS public key object from a buffer.

Note

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

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

Parameters

[in]	params	HSS Key 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_HSSGetPublicKeySize().
[out]	public_key	The resulting iqr_HSSPublicKey object.

Returns

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

iqr_HSSImportState()

IQR_API iqr_retval iqr_HSSImportState	(	const iqr_HSSParams *	params,
		const uint8_t *	buf,
		size_t	buf_size,
		iqr_HSSPrivateKeyState **	state
	)

Import an HSS State object from a buffer.

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

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

Parameters

[in]	params	HSS Key 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_HSSGetStateSize().
[out]	state	The resulting iqr_HSSPrivateKeyState object.

Returns

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

iqr_HSSSign()

IQR_API iqr_retval iqr_HSSSign	(	const iqr_HSSPrivateKey *	private_key,
		const uint8_t *	message,
		size_t	message_size,
		iqr_HSSPrivateKeyState *	state,
		uint8_t *	sig,
		size_t	sig_size
	)

Sign a message using an HSS private key.

As signatures are generated, the state can run out of signing keys. In that case, IQR_ESTATEDEPLETED will be returned and the state can no longer be used for signing. Use iqr_HSSGetSignatureCount() 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 HSS insecure.

Note

You must register a SHA2-256 implementation by calling iqr_HashRegisterCallbacks() before using the HSS 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_HSSSign() 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 used to sign the message.
[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_HSSGetSignatureSize().

Returns

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

iqr_HSSVerify()

IQR_API iqr_retval iqr_HSSVerify	(	const iqr_HSSPublicKey *	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 HSS public key.

Note

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

All internal buffers are cleared and deallocated before the call to iqr_HSSVerify() 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_HSSGetSignatureSize().

Returns

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

Detailed Description

ISARA Radiate Quantum-Safe Library's Hierarchical Signature Scheme.

The Hierarchical Signature scheme is defined by NIST SP 800-208.

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

The HSS 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_HSSSign() carefully. For more details, refer to the Developer's Guide (online).

Note

Due to ongoing changes in the IETF specification, keys and signatures created with this version of HSS are not compatible with earlier versions or our past HSS implementations.

Copyright

Copyright (C) 2015-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.