lmots.h File Reference

This file provides an API for the LM-OTS post-quantum-safe one-time public-key signature scheme as defined in RFC8554 and NIST.SP.200-208. This implementation currently only supports a single parameter set MBEDTLS_LMOTS_SHA256_N32_W8 in order to reduce complexity. More...

#include "mbedtls/build_info.h"
#include "psa/crypto.h"
#include "mbedtls/lms.h"
#include <stdint.h>
#include <stddef.h>

Include dependency graph for lmots.h:

Go to the source code of this file.

Macros
#define	MBEDTLS_LMOTS_PUBLIC_KEY_LEN(type)
#define	MBEDTLS_LMOTS_SIG_TYPE_OFFSET   (0)
#define	MBEDTLS_LMOTS_SIG_C_RANDOM_OFFSET
#define	MBEDTLS_LMOTS_SIG_SIGNATURE_OFFSET(type)

Functions
int MBEDTLS_DEPRECATED	mbedtls_lms_error_from_psa (psa_status_t status)
	This function converts a psa_status_t to a low-level LMS error code.
void	mbedtls_lmots_public_init (mbedtls_lmots_public_t *ctx)
	This function initializes a public LMOTS context.
void	mbedtls_lmots_public_free (mbedtls_lmots_public_t *ctx)
	This function uninitializes a public LMOTS context.
int	mbedtls_lmots_import_public_key (mbedtls_lmots_public_t *ctx, const unsigned char *key, size_t key_size)
	This function imports an LMOTS public key into a LMOTS context.
int	mbedtls_lmots_export_public_key (const mbedtls_lmots_public_t *ctx, unsigned char *key, size_t key_size, size_t *key_len)
	This function exports an LMOTS public key from a LMOTS context that already contains a public key.
int	mbedtls_lmots_calculate_public_key_candidate (const mbedtls_lmots_parameters_t *params, const unsigned char *msg, size_t msg_size, const unsigned char *sig, size_t sig_size, unsigned char *out, size_t out_size, size_t *out_len)
	This function creates a candidate public key from an LMOTS signature. This can then be compared to the real public key to determine the validity of the signature.
int	mbedtls_lmots_verify (const mbedtls_lmots_public_t *ctx, const unsigned char *msg, size_t msg_size, const unsigned char *sig, size_t sig_size)
	This function verifies a LMOTS signature, using a LMOTS context that contains a public key.

Detailed Description

This file provides an API for the LM-OTS post-quantum-safe one-time public-key signature scheme as defined in RFC8554 and NIST.SP.200-208. This implementation currently only supports a single parameter set MBEDTLS_LMOTS_SHA256_N32_W8 in order to reduce complexity.

Macro Definition Documentation

MBEDTLS_LMOTS_PUBLIC_KEY_LEN

#define MBEDTLS_LMOTS_PUBLIC_KEY_LEN

(

type

)

Value:

                                            (MBEDTLS_LMOTS_TYPE_LEN + \
                                            MBEDTLS_LMOTS_I_KEY_ID_LEN + \
                                            MBEDTLS_LMOTS_Q_LEAF_ID_LEN + \
                                            MBEDTLS_LMOTS_N_HASH_LEN(type))

MBEDTLS_LMOTS_SIG_C_RANDOM_OFFSET

#define MBEDTLS_LMOTS_SIG_C_RANDOM_OFFSET

Value:

                                           (MBEDTLS_LMOTS_SIG_TYPE_OFFSET + \
                                           MBEDTLS_LMOTS_TYPE_LEN)

MBEDTLS_LMOTS_SIG_SIGNATURE_OFFSET

#define MBEDTLS_LMOTS_SIG_SIGNATURE_OFFSET

(

type

)

Value:

                                                  (MBEDTLS_LMOTS_SIG_C_RANDOM_OFFSET + \
                                                  MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN(type))

MBEDTLS_LMOTS_SIG_TYPE_OFFSET

#define MBEDTLS_LMOTS_SIG_TYPE_OFFSET   (0)

Function Documentation

mbedtls_lmots_calculate_public_key_candidate()

int mbedtls_lmots_calculate_public_key_candidate	(	const mbedtls_lmots_parameters_t *	params,
		const unsigned char *	msg,
		size_t	msg_size,
		const unsigned char *	sig,
		size_t	sig_size,
		unsigned char *	out,
		size_t	out_size,
		size_t *	out_len
	)

This function creates a candidate public key from an LMOTS signature. This can then be compared to the real public key to determine the validity of the signature.

Note

This function is exposed publicly to be used in LMS signature verification, it is expected that mbedtls_lmots_verify will be used for LMOTS signature verification.

Parameters

params	The LMOTS parameter set, q and I values as an mbedtls_lmots_parameters_t struct.
msg	The buffer from which the message will be read.
msg_size	The size of the message that will be read.
sig	The buffer from which the signature will be read. MBEDTLS_LMOTS_SIG_LEN bytes will be read from this.
out	The buffer where the candidate public key will be stored. Must be at least MBEDTLS_LMOTS_N_HASH_LEN bytes in size.

Returns

0 on success.

A non-zero error code on failure.

mbedtls_lmots_export_public_key()

int mbedtls_lmots_export_public_key	(	const mbedtls_lmots_public_t *	ctx,
		unsigned char *	key,
		size_t	key_size,
		size_t *	key_len
	)

This function exports an LMOTS public key from a LMOTS 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 LMOTS context that contains the public key.
key	The buffer into which the key will be output. Must be at least MBEDTLS_LMOTS_PUBLIC_KEY_LEN in size.

Returns

0 on success.

A non-zero error code on failure.

mbedtls_lmots_import_public_key()

int mbedtls_lmots_import_public_key	(	mbedtls_lmots_public_t *	ctx,
		const unsigned char *	key,
		size_t	key_size
	)

This function imports an LMOTS public key into a LMOTS 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 LMOTS context store the key in.
key	The buffer from which the key will be read. MBEDTLS_LMOTS_PUBLIC_KEY_LEN bytes will be read from this.

Returns

0 on success.

A non-zero error code on failure.

mbedtls_lmots_public_free()

void mbedtls_lmots_public_free

(

mbedtls_lmots_public_t *

ctx

)

This function uninitializes a public LMOTS context.

Parameters

ctx	The initialized LMOTS context that will then be uninitialized.

mbedtls_lmots_public_init()

void mbedtls_lmots_public_init

(

mbedtls_lmots_public_t *

ctx

)

This function initializes a public LMOTS context.

Parameters

ctx	The uninitialized LMOTS context that will then be initialized.

mbedtls_lmots_verify()

int mbedtls_lmots_verify	(	const mbedtls_lmots_public_t *	ctx,
		const unsigned char *	msg,
		size_t	msg_size,
		const unsigned char *	sig,
		size_t	sig_size
	)

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

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 public key (either by import or calculation from a private key).

Parameters

ctx	The initialized LMOTS 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_LMOTS_SIG_LEN bytes will be read from this.

Returns

0 on successful verification.

A non-zero error code on failure.

mbedtls_lms_error_from_psa()

int MBEDTLS_DEPRECATED mbedtls_lms_error_from_psa

(

psa_status_t

status

)

This function converts a psa_status_t to a low-level LMS error code.

Parameters

status

The psa_status_t to convert

Returns

The corresponding LMS error code.