This file provides an API for the LMS post-quantum-safe stateful-hash public-key signature scheme as defined in RFC8554 and NIST.SP.200-208. This implementation currently only supports a single parameter set MBEDTLS_LMS_SHA256_M32_H10 in order to reduce complexity. This is one of the signature schemes recommended by the IETF draft SUIT standard for IOT firmware upgrades (RFC9019). More...

#include <stdint.h>
#include <stddef.h>
#include "mbedtls/private_access.h"
#include "tf-psa-crypto/build_info.h"
#include "mbedtls/compat-3-crypto.h"

Include dependency graph for lms.h:

Go to the source code of this file.

Data Structures
struct	mbedtls_lmots_parameters_t

struct	mbedtls_lmots_public_t

struct	mbedtls_lmots_private_t

struct	mbedtls_lms_parameters_t

struct	mbedtls_lms_public_t

struct	mbedtls_lms_private_t

Macros
#define	MBEDTLS_ERR_LMS_OUT_OF_PRIVATE_KEYS -0x0013

#define	MBEDTLS_ERR_LMS_VERIFY_FAILED -0x0015

#define	MBEDTLS_LMOTS_N_HASH_LEN_MAX (32u)

#define	MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT_MAX (34u)

#define	MBEDTLS_LMOTS_N_HASH_LEN(type) ((type) == MBEDTLS_LMOTS_SHA256_N32_W8 ? 32u : 0)

#define	MBEDTLS_LMOTS_I_KEY_ID_LEN (16u)

#define	MBEDTLS_LMOTS_Q_LEAF_ID_LEN (4u)

#define	MBEDTLS_LMOTS_TYPE_LEN (4u)

#define	MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT(type) ((type) == MBEDTLS_LMOTS_SHA256_N32_W8 ? 34u : 0)

#define	MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN(type) (MBEDTLS_LMOTS_N_HASH_LEN(type))

#define	MBEDTLS_LMOTS_SIG_LEN(type)

#define	MBEDTLS_LMS_TYPE_LEN (4)

#define	MBEDTLS_LMS_H_TREE_HEIGHT(type) ((type) == MBEDTLS_LMS_SHA256_M32_H10 ? 10u : 0)

#define	MBEDTLS_LMS_M_NODE_BYTES(type) ((type) == MBEDTLS_LMS_SHA256_M32_H10 ? 32 : 0)

#define	MBEDTLS_LMS_M_NODE_BYTES_MAX 32

#define	MBEDTLS_LMS_SIG_LEN(type, otstype)

#define	MBEDTLS_LMS_PUBLIC_KEY_LEN(type)

Enumerations
enum	mbedtls_lms_algorithm_type_t { MBEDTLS_LMS_SHA256_M32_H10 = 0x6 }

enum	mbedtls_lmots_algorithm_type_t { MBEDTLS_LMOTS_SHA256_N32_W8 = 4 }

Functions
void	mbedtls_lms_public_init (mbedtls_lms_public_t *ctx)
	This function initializes an LMS public context. More...

void	mbedtls_lms_public_free (mbedtls_lms_public_t *ctx)
	This function uninitializes an LMS public context. More...

int	mbedtls_lms_import_public_key (mbedtls_lms_public_t ctx, const unsigned char key, size_t key_size)
	This function imports an LMS public key into a public LMS context. More...

int	mbedtls_lms_export_public_key (const mbedtls_lms_public_t ctx, unsigned char key, size_t key_size, size_t *key_len)
	This function exports an LMS public key from a LMS public context that already contains a public key. More...

int	mbedtls_lms_verify (const mbedtls_lms_public_t ctx, const unsigned char msg, size_t msg_size, const unsigned char *sig, size_t sig_size)
	This function verifies a LMS signature, using a LMS context that contains a public key. More...

void	mbedtls_lms_private_init (mbedtls_lms_private_t *ctx)
	This function initializes an LMS private context. More...

void	mbedtls_lms_private_free (mbedtls_lms_private_t *ctx)
	This function uninitializes an LMS private context. More...

int	mbedtls_lms_generate_private_key (mbedtls_lms_private_t ctx, mbedtls_lms_algorithm_type_t type, mbedtls_lmots_algorithm_type_t otstype, const unsigned char seed, size_t seed_size)
	This function generates an LMS private key, and stores in into an LMS private context. More...

int	mbedtls_lms_calculate_public_key (mbedtls_lms_public_t ctx, const mbedtls_lms_private_t priv_ctx)
	This function calculates an LMS public key from a LMS context that already contains a private key. More...

int	mbedtls_lms_sign (mbedtls_lms_private_t ctx, const unsigned char msg, unsigned int msg_size, unsigned char sig, size_t sig_size, size_t sig_len)
	This function creates a LMS signature, using a LMS context that contains unused private keys. More...

Detailed Description

This file provides an API for the LMS post-quantum-safe stateful-hash public-key signature scheme as defined in RFC8554 and NIST.SP.200-208. This implementation currently only supports a single parameter set MBEDTLS_LMS_SHA256_M32_H10 in order to reduce complexity. This is one of the signature schemes recommended by the IETF draft SUIT standard for IOT firmware upgrades (RFC9019).

Definition in file lms.h.

Macro Definition Documentation

#define MBEDTLS_ERR_LMS_OUT_OF_PRIVATE_KEYS -0x0013

Specified LMS key has utilised all of its private keys

Definition at line 25 of file lms.h.

#define MBEDTLS_ERR_LMS_VERIFY_FAILED -0x0015

LMS signature verification failed

Definition at line 26 of file lms.h.

#define MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN ( type ) (MBEDTLS_LMOTS_N_HASH_LEN(type))

Definition at line 36 of file lms.h.

#define MBEDTLS_LMOTS_I_KEY_ID_LEN (16u)

Definition at line 32 of file lms.h.

#define MBEDTLS_LMOTS_N_HASH_LEN ( type ) ((type) == MBEDTLS_LMOTS_SHA256_N32_W8 ? 32u : 0)

Definition at line 31 of file lms.h.

#define MBEDTLS_LMOTS_N_HASH_LEN_MAX (32u)

Definition at line 29 of file lms.h.

#define MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT ( type ) ((type) == MBEDTLS_LMOTS_SHA256_N32_W8 ? 34u : 0)

Definition at line 35 of file lms.h.

#define MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT_MAX (34u)

Definition at line 30 of file lms.h.

#define MBEDTLS_LMOTS_Q_LEAF_ID_LEN (4u)

Definition at line 33 of file lms.h.

#define MBEDTLS_LMOTS_SIG_LEN ( type )

Value:

(MBEDTLS_LMOTS_TYPE_LEN + \
                                     MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN(type) + \
                                     (MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT(type) * \
                                      MBEDTLS_LMOTS_N_HASH_LEN(type)))

Definition at line 38 of file lms.h.

#define MBEDTLS_LMOTS_TYPE_LEN (4u)

Definition at line 34 of file lms.h.

#define MBEDTLS_LMS_H_TREE_HEIGHT ( type ) ((type) == MBEDTLS_LMS_SHA256_M32_H10 ? 10u : 0)

Definition at line 45 of file lms.h.

#define MBEDTLS_LMS_M_NODE_BYTES ( type ) ((type) == MBEDTLS_LMS_SHA256_M32_H10 ? 32 : 0)

Definition at line 50 of file lms.h.

#define MBEDTLS_LMS_M_NODE_BYTES_MAX 32

Definition at line 51 of file lms.h.

#define MBEDTLS_LMS_PUBLIC_KEY_LEN ( type )

Value:

(MBEDTLS_LMS_TYPE_LEN + \
                                          MBEDTLS_LMOTS_TYPE_LEN + \
                                          MBEDTLS_LMOTS_I_KEY_ID_LEN + \
                                          MBEDTLS_LMS_M_NODE_BYTES(type))

Definition at line 59 of file lms.h.

#define MBEDTLS_LMS_SIG_LEN	(	type,
		otstype
	)

Value:

(MBEDTLS_LMOTS_Q_LEAF_ID_LEN + \
                                            MBEDTLS_LMOTS_SIG_LEN(otstype) + \
                                            MBEDTLS_LMS_TYPE_LEN + \
                                            (MBEDTLS_LMS_H_TREE_HEIGHT(type) * \
                                             MBEDTLS_LMS_M_NODE_BYTES(type)))

Definition at line 53 of file lms.h.

#define MBEDTLS_LMS_TYPE_LEN (4)

Definition at line 44 of file lms.h.

Enumeration Type Documentation

enum mbedtls_lmots_algorithm_type_t

The Identifier of the LMOTS parameter set, as per https://www.iana.org/assignments/leighton-micali-signatures/leighton-micali-signatures.xhtml. We are only implementing a subset of the types, particularly N32_W8, for the sake of simplicity.

Enumerator
MBEDTLS_LMOTS_SHA256_N32_W8

Definition at line 81 of file lms.h.

enum mbedtls_lms_algorithm_type_t

The Identifier of the LMS parameter set, as per https://www.iana.org/assignments/leighton-micali-signatures/leighton-micali-signatures.xhtml We are only implementing a subset of the types, particularly H10, for the sake of simplicity.

Enumerator
MBEDTLS_LMS_SHA256_M32_H10

Definition at line 73 of file lms.h.

Function Documentation

int mbedtls_lms_calculate_public_key	(	mbedtls_lms_public_t *	ctx,
		const mbedtls_lms_private_t *	priv_ctx
	)

This function calculates an LMS public key from a LMS context that already contains a private key.

Note: Before this function is called, the context must have been initialized and the context must contain a private key.

Parameters

ctx	The initialized LMS public context to calculate the key from and store it into.
priv_ctx	The LMS private context to read the private key from. This must have been initialized and contain a private key.

Returns: 0 on success.; A non-zero error code on failure.

int mbedtls_lms_export_public_key	(	const mbedtls_lms_public_t *	ctx,
		unsigned char *	key,
		size_t	key_size,
		size_t *	key_len
	)

This function exports an LMS public key from a LMS public context that already contains a public key.

Note: Before this function is called, the context must have been initialized and the context must contain a public key.; See IETF RFC8554 for details of the encoding of this public key.

Parameters

ctx	The initialized LMS public context that contains the public key.
key	The buffer into which the key will be output. Must be at least MBEDTLS_LMS_PUBLIC_KEY_LEN in size.
key_size	The size of the key buffer.
key_len	If not NULL, will be written with the size of the key.

Returns: 0 on success.; A non-zero error code on failure.

int mbedtls_lms_generate_private_key	(	mbedtls_lms_private_t *	ctx,
		mbedtls_lms_algorithm_type_t	type,
		mbedtls_lmots_algorithm_type_t	otstype,
		const unsigned char *	seed,
		size_t	seed_size
	)

This function generates an LMS private key, and stores in into an LMS private context.

Warning: This function is not intended for use in production, due to as-yet unsolved problems with handling stateful keys. The API for this function may change considerably in future versions.

Note: The seed must have at least 256 bits of entropy.

Parameters

ctx	The initialized LMOTS context to generate the key into.
type	The LMS parameter set identifier.
otstype	The LMOTS parameter set identifier.
seed	The seed used to deterministically generate the key.
seed_size	The length of the seed.

Returns: 0 on success.; A non-zero error code on failure.

int mbedtls_lms_import_public_key	(	mbedtls_lms_public_t *	ctx,
		const unsigned char *	key,
		size_t	key_size
	)

This function imports an LMS public key into a public LMS context.

Note: Before this function is called, the context must have been initialized.; See IETF RFC8554 for details of the encoding of this public key.

Parameters

ctx	The initialized LMS context store the key in.
key	The buffer from which the key will be read. MBEDTLS_LMS_PUBLIC_KEY_LEN bytes will be read from this.
key_size	The size of the key being imported.

Returns: 0 on success.; A non-zero error code on failure.

void mbedtls_lms_private_free ( mbedtls_lms_private_t * ctx )

This function uninitializes an LMS private context.

Parameters

ctx	The initialized LMS private context that will then be uninitialized.

void mbedtls_lms_private_init ( mbedtls_lms_private_t * ctx )

This function initializes an LMS private context.

Parameters

ctx	The uninitialized LMS private context that will then be initialized.

void mbedtls_lms_public_free ( mbedtls_lms_public_t * ctx )

This function uninitializes an LMS public context.

Parameters

ctx	The initialized LMS context that will then be uninitialized.

void mbedtls_lms_public_init ( mbedtls_lms_public_t * ctx )

This function initializes an LMS public context.

Parameters

ctx	The uninitialized LMS context that will then be initialized.

int mbedtls_lms_sign	(	mbedtls_lms_private_t *	ctx,
		const unsigned char *	msg,
		unsigned int	msg_size,
		unsigned char *	sig,
		size_t	sig_size,
		size_t *	sig_len
	)

This function creates a LMS signature, using a LMS context that contains unused private keys.

Warning: This function is not intended for use in production, due to as-yet unsolved problems with handling stateful keys. The API for this function may change considerably in future versions.

Note: Before this function is called, the context must have been initialized and must contain a private key.; Each of the LMOTS private keys inside a LMS private key can only be used once. If they are reused, then attackers may be able to forge signatures with that key. This is all handled transparently, but it is important to not perform copy operations on LMS contexts that contain private key material.

Parameters

ctx	The initialized LMS private context from which the private key will be read.
msg	The buffer from which the message will be read.
msg_size	The size of the message that will be read.
sig	The buf into which the signature will be stored. Must be at least MBEDTLS_LMS_SIG_LEN in size.
sig_size	The size of the buffer the signature will be written into.
sig_len	If not NULL, will be written with the size of the signature.

Returns: 0 on success.; A non-zero error code on failure.

int mbedtls_lms_verify	(	const mbedtls_lms_public_t *	ctx,
		const unsigned char *	msg,
		size_t	msg_size,
		const unsigned char *	sig,
		size_t	sig_size
	)

This function verifies a LMS signature, using a LMS context that contains a public key.

Note: Before this function is called, the context must have been initialized and must contain a public key (either by import or generation).

Parameters

ctx	The initialized LMS public context from which the public key will be read.
msg	The buffer from which the message will be read.
msg_size	The size of the message that will be read.
sig	The buf from which the signature will be read. MBEDTLS_LMS_SIG_LEN bytes will be read from this.
sig_size	The size of the signature to be verified.

Returns: 0 on successful verification.; A non-zero error code on failure.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation