lms.h
stdint.h
stddef.h
mbedtls/private_access.h
mbedtls/build_info.h
mbedtls/build_info.h
mbedtls/check_config.h
mbedtls/config_adjust_legacy_crypto.h
mbedtls/config_adjust_psa_from_legacy.h
mbedtls/config_adjust_psa_superset_legacy.h
mbedtls/config_adjust_ssl.h
mbedtls/config_adjust_x509.h
mbedtls/config_psa.h
lms.h
mbedtls/mbedtls_config.h
mbedtls/private_access.h
psa/crypto_adjust_auto_enabled.h
psa/crypto_adjust_config_dependencies.h
psa/crypto_adjust_config_key_pair_types.h
psa/crypto_adjust_config_synonyms.h
psa/crypto_legacy.h
limits.h
stddef.h
stdint.h
mbedtls_lmots_parameters_t
mbedtls_lmots_public_t
mbedtls_lms_parameters_t
mbedtls_lms_public_t
MBEDTLS_ERR_LMS_BAD_INPUT_DATA
-0x0011

Bad data has been input to an LMS function

MBEDTLS_ERR_LMS_OUT_OF_PRIVATE_KEYS
-0x0013

Specified LMS key has utilised all of its private keys

MBEDTLS_ERR_LMS_VERIFY_FAILED
-0x0015

LMS signature verification failed

MBEDTLS_ERR_LMS_ALLOC_FAILED
-0x0017

LMS failed to allocate space for a private key

MBEDTLS_ERR_LMS_BUFFER_TOO_SMALL
-0x0019

Input/output buffer is too small to contain requited data

MBEDTLS_LMOTS_N_HASH_LEN_MAX
(32u)
MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT_MAX
(34u)
MBEDTLS_LMOTS_N_HASH_LEN
type
((type) == MBEDTLS_LMOTS_SHA256_N32_W8 ? 32u : 0)
MBEDTLS_LMOTS_I_KEY_ID_LEN
(16u)
MBEDTLS_LMOTS_Q_LEAF_ID_LEN
(4u)
MBEDTLS_LMOTS_TYPE_LEN
(4u)
MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT
type
((type) == MBEDTLS_LMOTS_SHA256_N32_W8 ? 34u : 0)
MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN
type
(MBEDTLS_LMOTS_N_HASH_LEN(type))
MBEDTLS_LMOTS_SIG_LEN
type
(MBEDTLS_LMOTS_TYPE_LEN + \ MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN(type) + \ (MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT(type) * \ MBEDTLS_LMOTS_N_HASH_LEN(type)))
MBEDTLS_LMS_TYPE_LEN
(4)
MBEDTLS_LMS_H_TREE_HEIGHT
type
((type) == MBEDTLS_LMS_SHA256_M32_H10 ? 10u : 0)
MBEDTLS_LMS_M_NODE_BYTES
type
((type) == MBEDTLS_LMS_SHA256_M32_H10 ? 32 : 0)
MBEDTLS_LMS_M_NODE_BYTES_MAX
32
MBEDTLS_LMS_SIG_LEN
type
otstype
(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)))
MBEDTLS_LMS_PUBLIC_KEY_LEN
type
(MBEDTLS_LMS_TYPE_LEN + \ MBEDTLS_LMOTS_TYPE_LEN + \ MBEDTLS_LMOTS_I_KEY_ID_LEN + \ MBEDTLS_LMS_M_NODE_BYTES(type))
mbedtls_lms_algorithm_type_t
MBEDTLS_LMS_SHA256_M32_H10
= 0x6

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.

mbedtls_lmots_algorithm_type_t
MBEDTLS_LMOTS_SHA256_N32_W8
= 4

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.

void void mbedtls_lms_public_init (mbedtls_lms_public_t *ctx) mbedtls_lms_public_init mbedtls_lms_public_t * ctx

This function initializes an LMS public context.

ctx

The uninitialized LMS context that will then be initialized.

void void mbedtls_lms_public_free (mbedtls_lms_public_t *ctx) mbedtls_lms_public_free mbedtls_lms_public_t * ctx

This function uninitializes an LMS public context.

ctx

The initialized LMS context that will then be uninitialized.

int int mbedtls_lms_import_public_key (mbedtls_lms_public_t *ctx, const unsigned char *key, size_t key_size) 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.

Before this function is called, the context must have been initialized.

See IETF RFC8554 for details of the encoding of this public key.

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.

`0` on success.

A non-zero error code on failure.

int int mbedtls_lms_export_public_key (const mbedtls_lms_public_t *ctx, unsigned char *key, size_t key_size, size_t *key_len) 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.

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.

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.

`0` on success.

A non-zero error code on failure.

int 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) 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.

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

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.

`0` on successful verification.

A non-zero error code on failure.

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

    /*
    *CopyrightTheMbedTLSContributors
    *SPDX-License-Identifier:Apache-2.0ORGPL-2.0-or-later
    */
    #ifndefMBEDTLS_LMS_H
    #defineMBEDTLS_LMS_H

    #include<stdint.h>
    #include<stddef.h>

    #include"mbedtls/private_access.h"
    #include"mbedtls/build_info.h"

    #defineMBEDTLS_ERR_LMS_BAD_INPUT_DATA-0x0011
    #defineMBEDTLS_ERR_LMS_OUT_OF_PRIVATE_KEYS-0x0013
    #defineMBEDTLS_ERR_LMS_VERIFY_FAILED-0x0015
    #defineMBEDTLS_ERR_LMS_ALLOC_FAILED-0x0017
    #defineMBEDTLS_ERR_LMS_BUFFER_TOO_SMALL-0x0019
    /*CurrentlyonlydefinedforSHA256,32isthemaxhashoutputsize*/
    #defineMBEDTLS_LMOTS_N_HASH_LEN_MAX(32u)
    #defineMBEDTLS_LMOTS_P_SIG_DIGIT_COUNT_MAX(34u)
    #defineMBEDTLS_LMOTS_N_HASH_LEN(type)((type)==MBEDTLS_LMOTS_SHA256_N32_W8?32u:0)
    #defineMBEDTLS_LMOTS_I_KEY_ID_LEN(16u)
    #defineMBEDTLS_LMOTS_Q_LEAF_ID_LEN(4u)
    #defineMBEDTLS_LMOTS_TYPE_LEN(4u)
    #defineMBEDTLS_LMOTS_P_SIG_DIGIT_COUNT(type)((type)==MBEDTLS_LMOTS_SHA256_N32_W8?34u:0)
    #defineMBEDTLS_LMOTS_C_RANDOM_VALUE_LEN(type)(MBEDTLS_LMOTS_N_HASH_LEN(type))

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

    #defineMBEDTLS_LMS_TYPE_LEN(4)
    #defineMBEDTLS_LMS_H_TREE_HEIGHT(type)((type)==MBEDTLS_LMS_SHA256_M32_H10?10u:0)

    /*Thelengthofahashoutput,CurrentlyonlyimplementedforSHA256.
    *Maxis32bytes.
    */
    #defineMBEDTLS_LMS_M_NODE_BYTES(type)((type)==MBEDTLS_LMS_SHA256_M32_H10?32:0)
    #defineMBEDTLS_LMS_M_NODE_BYTES_MAX32

    #defineMBEDTLS_LMS_SIG_LEN(type,otstype)(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)))

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

    #ifdef__cplusplus
    extern"C"{
    #endif

    typedefenum{
    MBEDTLS_LMS_SHA256_M32_H10=0x6,
    }mbedtls_lms_algorithm_type_t;

    typedefenum{
    MBEDTLS_LMOTS_SHA256_N32_W8=4
    }mbedtls_lmots_algorithm_type_t;

    typedefstruct{
    unsignedcharMBEDTLS_PRIVATE(I_key_identifier[MBEDTLS_LMOTS_I_KEY_ID_LEN]);
    unsignedcharMBEDTLS_PRIVATE(q_leaf_identifier[MBEDTLS_LMOTS_Q_LEAF_ID_LEN]);
    mbedtls_lmots_algorithm_type_tMBEDTLS_PRIVATE(type);
    }mbedtls_lmots_parameters_t;

    typedefstruct{
    mbedtls_lmots_parameters_tMBEDTLS_PRIVATE(params);
    unsignedcharMBEDTLS_PRIVATE(public_key)[MBEDTLS_LMOTS_N_HASH_LEN_MAX];
    unsignedcharMBEDTLS_PRIVATE(have_public_key);
    }mbedtls_lmots_public_t;

    #ifdefined(MBEDTLS_LMS_PRIVATE)
    typedefstruct{
    mbedtls_lmots_parameters_tMBEDTLS_PRIVATE(params);
    unsignedcharMBEDTLS_PRIVATE(private_key)[MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT_MAX][
    MBEDTLS_LMOTS_N_HASH_LEN_MAX];
    unsignedcharMBEDTLS_PRIVATE(have_private_key);
    }mbedtls_lmots_private_t;
    #endif/*defined(MBEDTLS_LMS_PRIVATE)*/

    typedefstruct{
    unsignedcharMBEDTLS_PRIVATE(I_key_identifier[MBEDTLS_LMOTS_I_KEY_ID_LEN]);
    mbedtls_lmots_algorithm_type_tMBEDTLS_PRIVATE(otstype);
    mbedtls_lms_algorithm_type_tMBEDTLS_PRIVATE(type);
    }mbedtls_lms_parameters_t;

    typedefstruct{
    mbedtls_lms_parameters_tMBEDTLS_PRIVATE(params);
    unsignedcharMBEDTLS_PRIVATE(T_1_pub_key)[MBEDTLS_LMS_M_NODE_BYTES_MAX];
    unsignedcharMBEDTLS_PRIVATE(have_public_key);
    }mbedtls_lms_public_t;

    #ifdefined(MBEDTLS_LMS_PRIVATE)
    typedefstruct{
    mbedtls_lms_parameters_tMBEDTLS_PRIVATE(params);
    uint32_tMBEDTLS_PRIVATE(q_next_usable_key);
    mbedtls_lmots_private_t*MBEDTLS_PRIVATE(ots_private_keys);
    mbedtls_lmots_public_t*MBEDTLS_PRIVATE(ots_public_keys);
    unsignedcharMBEDTLS_PRIVATE(have_private_key);
    }mbedtls_lms_private_t;
    #endif/*defined(MBEDTLS_LMS_PRIVATE)*/

    voidmbedtls_lms_public_init(mbedtls_lms_public_t*ctx);

    voidmbedtls_lms_public_free(mbedtls_lms_public_t*ctx);

    intmbedtls_lms_import_public_key(mbedtls_lms_public_t*ctx,
    constunsignedchar*key,size_tkey_size);

    intmbedtls_lms_export_public_key(constmbedtls_lms_public_t*ctx,
    unsignedchar*key,size_tkey_size,
    size_t*key_len);

    intmbedtls_lms_verify(constmbedtls_lms_public_t*ctx,
    constunsignedchar*msg,size_tmsg_size,
    constunsignedchar*sig,size_tsig_size);

    #ifdefined(MBEDTLS_LMS_PRIVATE)
    voidmbedtls_lms_private_init(mbedtls_lms_private_t*ctx);

    voidmbedtls_lms_private_free(mbedtls_lms_private_t*ctx);

    intmbedtls_lms_generate_private_key(mbedtls_lms_private_t*ctx,
    mbedtls_lms_algorithm_type_ttype,
    mbedtls_lmots_algorithm_type_totstype,
    int(*f_rng)(void*,unsignedchar*,size_t),
    void*p_rng,constunsignedchar*seed,
    size_tseed_size);

    intmbedtls_lms_calculate_public_key(mbedtls_lms_public_t*ctx,
    constmbedtls_lms_private_t*priv_ctx);

    intmbedtls_lms_sign(mbedtls_lms_private_t*ctx,
    int(*f_rng)(void*,unsignedchar*,size_t),
    void*p_rng,constunsignedchar*msg,
    unsignedintmsg_size,unsignedchar*sig,size_tsig_size,
    size_t*sig_len);
    #endif/*defined(MBEDTLS_LMS_PRIVATE)*/

    #ifdef__cplusplus
    }
    #endif

    #endif/*MBEDTLS_LMS_H*/