Mbed TLS v3.6.2
Loading...
Searching...
No Matches
lms.h File Reference

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 "mbedtls/build_info.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_lms_parameters_t
 
struct  mbedtls_lms_public_t
 

Macros

#define MBEDTLS_ERR_LMS_BAD_INPUT_DATA   -0x0011
 
#define MBEDTLS_ERR_LMS_OUT_OF_PRIVATE_KEYS   -0x0013
 
#define MBEDTLS_ERR_LMS_VERIFY_FAILED   -0x0015
 
#define MBEDTLS_ERR_LMS_ALLOC_FAILED   -0x0017
 
#define MBEDTLS_ERR_LMS_BUFFER_TOO_SMALL   -0x0019
 
#define MBEDTLS_LMOTS_N_HASH_LEN_MAX   (32u)
 
#define MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT_MAX   (34u)
 
#define MBEDTLS_LMOTS_N_HASH_LEN(type)
 
#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)
 
#define MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN(type)
 
#define MBEDTLS_LMOTS_SIG_LEN(type)
 
#define MBEDTLS_LMS_TYPE_LEN   (4)
 
#define MBEDTLS_LMS_H_TREE_HEIGHT(type)
 
#define MBEDTLS_LMS_M_NODE_BYTES(type)
 
#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.
 
void mbedtls_lms_public_free (mbedtls_lms_public_t *ctx)
 This function uninitializes an LMS public context.
 
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.
 
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.
 
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.
 

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

◆ MBEDTLS_ERR_LMS_ALLOC_FAILED

#define MBEDTLS_ERR_LMS_ALLOC_FAILED   -0x0017

LMS failed to allocate space for a private key

Definition at line 27 of file lms.h.

◆ MBEDTLS_ERR_LMS_BAD_INPUT_DATA

#define MBEDTLS_ERR_LMS_BAD_INPUT_DATA   -0x0011

Bad data has been input to an LMS function

Definition at line 24 of file lms.h.

◆ MBEDTLS_ERR_LMS_BUFFER_TOO_SMALL

#define MBEDTLS_ERR_LMS_BUFFER_TOO_SMALL   -0x0019

Input/output buffer is too small to contain requited data

Definition at line 28 of file lms.h.

◆ MBEDTLS_ERR_LMS_OUT_OF_PRIVATE_KEYS

#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.

◆ MBEDTLS_ERR_LMS_VERIFY_FAILED

#define MBEDTLS_ERR_LMS_VERIFY_FAILED   -0x0015

LMS signature verification failed

Definition at line 26 of file lms.h.

◆ MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN

#define MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN ( type)
Value:
#define MBEDTLS_LMOTS_N_HASH_LEN(type)
Definition lms.h:33

Definition at line 38 of file lms.h.

◆ MBEDTLS_LMOTS_I_KEY_ID_LEN

#define MBEDTLS_LMOTS_I_KEY_ID_LEN   (16u)

Definition at line 34 of file lms.h.

◆ MBEDTLS_LMOTS_N_HASH_LEN

#define MBEDTLS_LMOTS_N_HASH_LEN ( type)
Value:
((type) == MBEDTLS_LMOTS_SHA256_N32_W8 ? 32u : 0)
@ MBEDTLS_LMOTS_SHA256_N32_W8
Definition lms.h:84

Definition at line 33 of file lms.h.

◆ MBEDTLS_LMOTS_N_HASH_LEN_MAX

#define MBEDTLS_LMOTS_N_HASH_LEN_MAX   (32u)

Definition at line 31 of file lms.h.

◆ MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT

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

Definition at line 37 of file lms.h.

◆ MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT_MAX

#define MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT_MAX   (34u)

Definition at line 32 of file lms.h.

◆ MBEDTLS_LMOTS_Q_LEAF_ID_LEN

#define MBEDTLS_LMOTS_Q_LEAF_ID_LEN   (4u)

Definition at line 35 of file lms.h.

◆ MBEDTLS_LMOTS_SIG_LEN

#define MBEDTLS_LMOTS_SIG_LEN ( type)
Value:
MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN(type) + \
MBEDTLS_LMOTS_N_HASH_LEN(type)))
#define MBEDTLS_LMOTS_TYPE_LEN
Definition lms.h:36
#define MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT(type)
Definition lms.h:37

Definition at line 40 of file lms.h.

◆ MBEDTLS_LMOTS_TYPE_LEN

#define MBEDTLS_LMOTS_TYPE_LEN   (4u)

Definition at line 36 of file lms.h.

◆ MBEDTLS_LMS_H_TREE_HEIGHT

#define MBEDTLS_LMS_H_TREE_HEIGHT ( type)
Value:
((type) == MBEDTLS_LMS_SHA256_M32_H10 ? 10u : 0)
@ MBEDTLS_LMS_SHA256_M32_H10
Definition lms.h:76

Definition at line 47 of file lms.h.

◆ MBEDTLS_LMS_M_NODE_BYTES

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

Definition at line 52 of file lms.h.

◆ MBEDTLS_LMS_M_NODE_BYTES_MAX

#define MBEDTLS_LMS_M_NODE_BYTES_MAX   32

Definition at line 53 of file lms.h.

◆ MBEDTLS_LMS_PUBLIC_KEY_LEN

#define MBEDTLS_LMS_PUBLIC_KEY_LEN ( type)
Value:
MBEDTLS_LMS_M_NODE_BYTES(type))
#define MBEDTLS_LMOTS_I_KEY_ID_LEN
Definition lms.h:34
#define MBEDTLS_LMS_TYPE_LEN
Definition lms.h:46

Definition at line 61 of file lms.h.

◆ MBEDTLS_LMS_SIG_LEN

#define MBEDTLS_LMS_SIG_LEN ( type,
otstype )
Value:
MBEDTLS_LMOTS_SIG_LEN(otstype) + \
MBEDTLS_LMS_M_NODE_BYTES(type)))
#define MBEDTLS_LMS_H_TREE_HEIGHT(type)
Definition lms.h:47
#define MBEDTLS_LMOTS_Q_LEAF_ID_LEN
Definition lms.h:35

Definition at line 55 of file lms.h.

◆ MBEDTLS_LMS_TYPE_LEN

#define MBEDTLS_LMS_TYPE_LEN   (4)

Definition at line 46 of file lms.h.

Enumeration Type Documentation

◆ 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 83 of file lms.h.

◆ 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 75 of file lms.h.

Function Documentation

◆ mbedtls_lms_export_public_key()

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
ctxThe initialized LMS public context that contains the public key.
keyThe buffer into which the key will be output. Must be at least MBEDTLS_LMS_PUBLIC_KEY_LEN in size.
key_sizeThe size of the key buffer.
key_lenIf not NULL, will be written with the size of the key.
Returns
0 on success.
A non-zero error code on failure.

◆ mbedtls_lms_import_public_key()

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
ctxThe initialized LMS context store the key in.
keyThe buffer from which the key will be read. MBEDTLS_LMS_PUBLIC_KEY_LEN bytes will be read from this.
key_sizeThe size of the key being imported.
Returns
0 on success.
A non-zero error code on failure.

◆ mbedtls_lms_public_free()

void mbedtls_lms_public_free ( mbedtls_lms_public_t * ctx)

This function uninitializes an LMS public context.

Parameters
ctxThe initialized LMS context that will then be uninitialized.

◆ mbedtls_lms_public_init()

void mbedtls_lms_public_init ( mbedtls_lms_public_t * ctx)

This function initializes an LMS public context.

Parameters
ctxThe uninitialized LMS context that will then be initialized.

◆ mbedtls_lms_verify()

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
ctxThe initialized LMS public context from which the public key will be read.
msgThe buffer from which the message will be read.
msg_sizeThe size of the message that will be read.
sigThe buf from which the signature will be read. MBEDTLS_LMS_SIG_LEN bytes will be read from this.
sig_sizeThe size of the signature to be verified.
Returns
0 on successful verification.
A non-zero error code on failure.