Typedefs
typedef struct ikm_LMSPrivateKey_struct	ikm_LMSPrivateKey

Functions
IQR_API ikm_retval	ikm_LMSCreateKeyPair (const iqr_LMSParams params, const iqr_RNG rng, iqr_LMSPublicKey pub_key, ikm_LMSPrivateKey priv_key)

IQR_API ikm_retval	ikm_LMSCreateSplitKeyPair (const iqr_LMSParams params, const iqr_RNG rng, iqr_LMSPublicKey *pub_key, ikm_LMSPrivateKey priv_keys[], size_t num_priv_keys)

IQR_API ikm_retval	ikm_LMSLoadPrivateKey (const iqr_Context ctx, const ikm_IO io, uint32_t key_id, ikm_LMSPrivateKey **priv_key)

IQR_API ikm_retval	ikm_LMSStorePrivateKey (ikm_LMSPrivateKey *priv_key, const ikm_IO io, uint32_t key_id)

IQR_API_UNENFORCED_RETURN ikm_retval	ikm_LMSDestroyPrivateKey (ikm_LMSPrivateKey **priv_key)

IQR_API ikm_retval	ikm_LMSGetPrivateKeyParams (const ikm_LMSPrivateKey priv_key, iqr_LMSParams *params)

IQR_API ikm_retval	ikm_LMSSign (ikm_LMSPrivateKey priv_key, const iqr_RNG rng, const uint8_t digest, size_t digest_size, uint8_t sig, size_t sig_size)

IQR_API ikm_retval	ikm_LMSGetRemainingSignatureCount (const ikm_LMSPrivateKey priv_key, uint32_t remaining)

Typedef Documentation

typedef struct ikm_LMSPrivateKey_struct ikm_LMSPrivateKey

The Key State Manager's managed LMS private key.

Function Documentation

IQR_API ikm_retval ikm_LMSCreateKeyPair	(	const iqr_LMSParams *	params,
		const iqr_RNG *	rng,
		iqr_LMSPublicKey **	pub_key,
		ikm_LMSPrivateKey **	priv_key
	)

Generate an LMS private/public key pair for use with the Key State Manager API.

Note: You must register a SHA-256 implementation by calling iqr_HashRegisterCallbacks() before using the LMS API.

Parameters

[in]	params	The key parameters to use.
[in]	rng	A seeded random number generator.
[out]	pub_key	The resulting `iqr_LMSPublicKey` object. Must be initialized to `NULL`.
[out]	priv_key	The resulting `ikm_LMSPrivateKey` object. Must be initialized to `NULL`.

Returns: IKM_OK on success, or a value from ikm_retval.h when an error occurs.

IQR_API ikm_retval ikm_LMSCreateSplitKeyPair	(	const iqr_LMSParams *	params,
		const iqr_RNG *	rng,
		iqr_LMSPublicKey **	pub_key,
		ikm_LMSPrivateKey *	priv_keys[],
		size_t	num_priv_keys
	)

Generate an LMS private/public key pair and split the private key.

LMS private keys can potentially take a relatively large space, which might not be desirable in memory constrained applications. By splitting the private key after creation, the size of the private key at signing time can be controlled. All resulting private keys will be stored in priv_keys array, and num_priv_keys indicates the number of split private keys.

Note: It's up to the user to allocate and free the priv_keys' memory.; You must register a SHA-256 implementation by calling iqr_HashRegisterCallbacks() before using the LMS API.

Parameters

[in]	params	The key parameters to use.
[in]	rng	A seeded random number generator.
[out]	pub_key	The resulting `iqr_LMSPublicKey` object. Must be initialized to `NULL`.
[in,out]	priv_keys	The resulting array of `ikm_LMSPrivateKey` objects. All elements must be initialized to `NULL`.
[in]	num_priv_keys	The number of `ikm_LMSPrivateKey` objects in priv_keys array.

Returns: IKM_OK on success, or a value from ikm_retval.h when an error occurs.

IQR_API_UNENFORCED_RETURN ikm_retval ikm_LMSDestroyPrivateKey ( ikm_LMSPrivateKey ** priv_key )

Clear and deallocate an LMS private key.

priv_key will be set to NULL prior to returning.

Note: If there are unused signing keys in the priv_key, they will be wiped as well. ikm_LMSStorePrivateKey() should be used to backup the priv_key if it is not depleted.

Parameters

[in,out] priv_key The ikm_LMSPrivateKey object to destroy.

Returns: IKM_OK on success, or a value from ikm_retval.h when an error occurs.

IQR_API ikm_retval ikm_LMSGetPrivateKeyParams	(	const ikm_LMSPrivateKey *	priv_key,
		iqr_LMSParams **	params
	)

Retrieve the LMS domain parameters from an LMS private key.

The returned params could be used with helper functions in "iqr_lms.h" header, to retrieve domain parameters as well as the signature size.

Note: iqr_LMSDestroyParams() must be used to destroy the params object after use.

Parameters

[in]	priv_key	The private key.
[out]	params	The resulting `iqr_LMSParams` object.

Returns: IKM_OK on success, or a value from ikm_retval.h when an error occurs.

IQR_API ikm_retval ikm_LMSGetRemainingSignatureCount	(	const ikm_LMSPrivateKey *	priv_key,
		uint32_t *	remaining
	)

Get the number of signatures remaining.

Parameters

[in]	priv_key	An `ikm_LMSPrivateKey` instance.
[out]	remaining	The number of signatures remaining.

Returns: IKM_OK on success, or a value from ikm_retval.h when an error occurs.

IQR_API ikm_retval ikm_LMSLoadPrivateKey	(	const iqr_Context *	ctx,
		const ikm_IO *	io,
		uint32_t	key_id,
		ikm_LMSPrivateKey **	priv_key
	)

Load a private key from storage.

Note: The io interface must be initialized similar to the interface used with ikm_LMSStorePrivateKey in order to retrieve the same private key associated with the key_id.

Parameters

[in]	ctx	A Context object.
[in]	io	An Input/Output interface object.
[in]	key_id	Key object identifier.
[out]	priv_key	The private key.

Returns: IKM_OK on success, or a value from ikm_retval.h when an error occurs.

IQR_API ikm_retval ikm_LMSSign	(	ikm_LMSPrivateKey *	priv_key,
		const iqr_RNG *	rng,
		const uint8_t *	digest,
		size_t	digest_size,
		uint8_t *	sig,
		size_t	sig_size
	)

Sign a message digest using an LMS private key.

This will use the next available signing key to sign the digest. As signatures are generated, the priv_key can run out of signing keys. In that case, IKM_EKEYDEPLETED will be returned and the key can no longer be used for signing. If ikm_LMSCreateSplitKeyPair() was used to create the key pair, and there are other ikm_LMSPrivateKey objects available, they can be used for signing. Otherwise no more signatures can be generated with this key pair.

Note: You must register a SHA-256 implementation by calling iqr_HashRegisterCallbacks() before using the LMS API.

Parameters

[in]	priv_key	The private key.
[in]	rng	A seeded Random Number Generator object.
[in]	digest	The message digest to be signed.
[in]	digest_size	The size of the digest buffer.
[out]	sig	The buffer receiving the resulting signature.
[in]	sig_size	The size of the sig buffer. Use `iqr_LMSGetSignatureSize()` to obtain the required buffer size.

Returns: IKM_OK on success, or a value from ikm_retval.h when an error occurs.

IQR_API ikm_retval ikm_LMSStorePrivateKey	(	ikm_LMSPrivateKey **	priv_key,
		const ikm_IO *	io,
		uint32_t	key_id
	)

Store a private key to storage.

If ikm_LMSCreateSplitKeyPair() is used to create the key pair, a unique key_id should be used for each private key. This key_id is used with the io interface to save the private key to storage.

Note: Same key_id must be used with ikm_LMSLoadPrivateKey() to load the private key from storage.; This will destroy the priv_key after it is successfully stored to storage. ikm_LMSLoadPrivateKey() could be used to reload the key.

Parameters

[in,out]	priv_key	The private key.
[in]	io	An Input/Output interface object.
[in]	key_id	Key object identifier.

Returns: IKM_OK on success, or a value from ikm_retval.h when an error occurs.

Detailed Description

ISARA Radiate Key State Manager's Leighton-Micali One Time Signature scheme's key management.

This header contains the functions necessary to create LMS keys, and facilitates storing and loading them from storage. Also, the provided signing API manages the LMS private key's state.

Typedefs

Functions

Typedef Documentation

Function Documentation

Detailed Description