include/mbedtls/lms.h - mirror/mbed-tls - TrustedFirmware Git Browser

 /**
  * \file lms.h
  *
  * \brief 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).
  */
 /*
  *  Copyright The Mbed TLS Contributors
  *  SPDX-License-Identifier: Apache-2.0
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
  *  not use this file except in compliance with the License.
  *  You may obtain a copy of the License at
  *
  *  http://www.apache.org/licenses/LICENSE-2.0
  *
  *  Unless required by applicable law or agreed to in writing, software
  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  */
 #ifndef MBEDTLS_LMS_H
 #define MBEDTLS_LMS_H

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

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

 #define MBEDTLS_ERR_LMS_BAD_INPUT_DATA   -0x0011 /**< Bad data has been input to an LMS function */
 #define MBEDTLS_ERR_LMS_OUT_OF_PRIVATE_KEYS -0x0013 /**< Specified LMS key has utilised all of its private keys */
 #define MBEDTLS_ERR_LMS_VERIFY_FAILED    -0x0015 /**< LMS signature verification failed */
 #define MBEDTLS_ERR_LMS_ALLOC_FAILED     -0x0017 /**< LMS failed to allocate space for a private key */
 #define MBEDTLS_ERR_LMS_BUFFER_TOO_SMALL -0x0019 /**< Input/output buffer is too small to contain requited data */

 /* Currently only defined for SHA256, 32 is the max hash output size */
 #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) (MBEDTLS_LMOTS_TYPE_LEN + \
                                      MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN(type) + \
                                      (MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT(type) * \
                                       MBEDTLS_LMOTS_N_HASH_LEN(type)))


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

 /* The length of a hash output, Currently only implemented for SHA256.
  * Max is 32 bytes.
  */
 #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) (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)))

 #define 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))


 #ifdef __cplusplus
 extern "C" {
 #endif

 /** 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.
  */
 typedef enum {
     MBEDTLS_LMS_SHA256_M32_H10 = 0x6,
 } mbedtls_lms_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.
  */
 typedef enum {
     MBEDTLS_LMOTS_SHA256_N32_W8 = 4
 } mbedtls_lmots_algorithm_type_t;

 /** LMOTS parameters structure.
  *
  * This contains the metadata associated with an LMOTS key, detailing the
  * algorithm type, the key ID, and the leaf identifier should be key be part of
  * a LMS key.
  */
 typedef struct {
     unsigned char MBEDTLS_PRIVATE(I_key_identifier[MBEDTLS_LMOTS_I_KEY_ID_LEN]); /*!< The key
                                                                                     identifier. */
     unsigned char MBEDTLS_PRIVATE(q_leaf_identifier[MBEDTLS_LMOTS_Q_LEAF_ID_LEN]); /*!< Which
                                                                                       leaf of the LMS key this is.
                                                                                       0 if the key is not part of an LMS key. */
     mbedtls_lmots_algorithm_type_t MBEDTLS_PRIVATE(type); /*!< The LM-OTS key type identifier as
                                                                per IANA. Only SHA256_N32_W8 is
                                                                currently supported. */
 } mbedtls_lmots_parameters_t;

 /** LMOTS public context structure.
  *
  * A LMOTS public key is a hash output, and the applicable parameter set.
  *
  * The context must be initialized before it is used. A public key must either
  * be imported or generated from a private context.
  *
  * \dot
  * digraph lmots_public_t {
  *   UNINITIALIZED -> INIT [label="init"];
  *   HAVE_PUBLIC_KEY -> INIT [label="free"];
  *   INIT -> HAVE_PUBLIC_KEY [label="import_public_key"];
  *   INIT -> HAVE_PUBLIC_KEY [label="calculate_public_key from private key"];
  *   HAVE_PUBLIC_KEY -> HAVE_PUBLIC_KEY [label="export_public_key"];
  * }
  * \enddot
  */
 typedef struct {
     mbedtls_lmots_parameters_t MBEDTLS_PRIVATE(params);
     unsigned char MBEDTLS_PRIVATE(public_key)[MBEDTLS_LMOTS_N_HASH_LEN_MAX];
     unsigned char MBEDTLS_PRIVATE(have_public_key); /*!< Whether the context contains a public key.
                                                        Boolean values only. */
 } mbedtls_lmots_public_t;

 #if defined(MBEDTLS_LMS_PRIVATE)
 /** LMOTS private context structure.
  *
  * A LMOTS private key is one hash output for each of digit of the digest +
  * checksum, and the applicable parameter set.
  *
  * The context must be initialized before it is used. A public key must either
  * be imported or generated from a private context.
  *
  * \dot
  * digraph lmots_public_t {
  *   UNINITIALIZED -> INIT [label="init"];
  *   HAVE_PRIVATE_KEY -> INIT [label="free"];
  *   INIT -> HAVE_PRIVATE_KEY [label="generate_private_key"];
  *   HAVE_PRIVATE_KEY -> INIT [label="sign"];
  * }
  * \enddot
  */
 typedef struct {
     mbedtls_lmots_parameters_t MBEDTLS_PRIVATE(params);
     unsigned char MBEDTLS_PRIVATE(private_key)[MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT_MAX][
         MBEDTLS_LMOTS_N_HASH_LEN_MAX];
     unsigned char MBEDTLS_PRIVATE(have_private_key); /*!< Whether the context contains a private key.
                                                         Boolean values only. */
 } mbedtls_lmots_private_t;
 #endif /* defined(MBEDTLS_LMS_PRIVATE) */


 /** LMS parameters structure.
  *
  * This contains the metadata associated with an LMS key, detailing the
  * algorithm type, the type of the underlying OTS algorithm, and the key ID.
  */
 typedef struct {
     unsigned char MBEDTLS_PRIVATE(I_key_identifier[MBEDTLS_LMOTS_I_KEY_ID_LEN]); /*!< The key
                                                                                     identifier. */
     mbedtls_lmots_algorithm_type_t MBEDTLS_PRIVATE(otstype); /*!< The LM-OTS key type identifier as
                                                                 per IANA. Only SHA256_N32_W8 is
                                                                 currently supported. */
     mbedtls_lms_algorithm_type_t MBEDTLS_PRIVATE(type); /*!< The LMS key type identifier as per
                                                              IANA. Only SHA256_M32_H10 is currently
                                                              supported. */
 } mbedtls_lms_parameters_t;

 /** LMS public context structure.
  *
  * A LMS public key is the hash output that is the root of the Merkle tree, and
  * the applicable parameter set
  *
  * The context must be initialized before it is used. A public key must either
  * be imported or generated from a private context.
  *
  * \dot
  * digraph lms_public_t {
  *   UNINITIALIZED -> INIT [label="init"];
  *   HAVE_PUBLIC_KEY -> INIT [label="free"];
  *   INIT -> HAVE_PUBLIC_KEY [label="import_public_key"];
  *   INIT -> HAVE_PUBLIC_KEY [label="calculate_public_key from private key"];
  *   HAVE_PUBLIC_KEY -> HAVE_PUBLIC_KEY [label="export_public_key"];
  * }
  * \enddot
  */
 typedef struct {
     mbedtls_lms_parameters_t MBEDTLS_PRIVATE(params);
     unsigned char MBEDTLS_PRIVATE(T_1_pub_key)[MBEDTLS_LMS_M_NODE_BYTES_MAX]; /*!< The public key, in
                                                                                  the form of the Merkle tree root node. */
     unsigned char MBEDTLS_PRIVATE(have_public_key); /*!< Whether the context contains a public key.
                                                        Boolean values only. */
 } mbedtls_lms_public_t;


 #if defined(MBEDTLS_LMS_PRIVATE)
 /** LMS private context structure.
  *
  * A LMS private key is a set of LMOTS private keys, an index to the next usable
  * key, and the applicable parameter set.
  *
  * The context must be initialized before it is used. A public key must either
  * be imported or generated from a private context.
  *
  * \dot
  * digraph lms_public_t {
  *   UNINITIALIZED -> INIT [label="init"];
  *   HAVE_PRIVATE_KEY -> INIT [label="free"];
  *   INIT -> HAVE_PRIVATE_KEY [label="generate_private_key"];
  * }
  * \enddot
  */
 typedef struct {
     mbedtls_lms_parameters_t MBEDTLS_PRIVATE(params);
     uint32_t MBEDTLS_PRIVATE(q_next_usable_key); /*!< The index of the next OTS key that has not
                                                       been used. */
     mbedtls_lmots_private_t *MBEDTLS_PRIVATE(ots_private_keys); /*!< The private key material. One OTS key
                                                                    for each leaf node in the Merkle tree. NULL
                                                                    when have_private_key is 0 and non-NULL otherwise.
                                                                    is 2^MBEDTLS_LMS_H_TREE_HEIGHT(type) in length. */
     mbedtls_lmots_public_t *MBEDTLS_PRIVATE(ots_public_keys); /*!< The OTS key public keys, used to
                                                                    build the Merkle tree. NULL
                                                                    when have_private_key is 0 and
                                                                    non-NULL otherwise.
                                                                    Is 2^MBEDTLS_LMS_H_TREE_HEIGHT(type)
                                                                    in length. */
     unsigned char MBEDTLS_PRIVATE(have_private_key); /*!< Whether the context contains a private key.
                                                         Boolean values only. */
 } mbedtls_lms_private_t;
 #endif /* defined(MBEDTLS_LMS_PRIVATE) */

 /**
  * \brief                    This function initializes an LMS public context
  *
  * \param ctx                The uninitialized LMS context that will then be
  *                           initialized.
  */
 void mbedtls_lms_public_init(mbedtls_lms_public_t *ctx);

 /**
  * \brief                    This function uninitializes an LMS public context
  *
  * \param ctx                The initialized LMS context that will then be
  *                           uninitialized.
  */
 void mbedtls_lms_public_free(mbedtls_lms_public_t *ctx);

 /**
  * \brief                    This function imports an LMS public key into a
  *                           public LMS context.
  *
  * \note                     Before this function is called, the context must
  *                           have been initialized.
  *
  * \note                     See IETF RFC8554 for details of the encoding of
  *                           this public key.
  *
  * \param ctx                The initialized LMS context store the key in.
  * \param key                The buffer from which the key will be read.
  *                           #MBEDTLS_LMS_PUBLIC_KEY_LEN bytes will be read from
  *                           this.
  * \param key_size           The size of the key being imported.
  *
  * \return         \c 0 on success.
  * \return         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);

 /**
  * \brief                    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.
  *
  * \note                     See IETF RFC8554 for details of the encoding of
  *                           this public key.
  *
  * \param ctx                The initialized LMS public context that contains
  *                           the public key.
  * \param key                The buffer into which the key will be output. Must
  *                           be at least #MBEDTLS_LMS_PUBLIC_KEY_LEN in size.
  * \param key_size           The size of the key buffer.
  * \param key_len            If not NULL, will be written with the size of the
  *                           key.
  *
  * \return         \c 0 on success.
  * \return         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);

 /**
  * \brief                    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).
  *
  * \param ctx                The initialized LMS public context from which the
  *                           public key will be read.
  * \param msg                The buffer from which the message will be read.
  * \param msg_size           The size of the message that will be read.
  * \param sig                The buf from which the signature will be read.
  *                           #MBEDTLS_LMS_SIG_LEN bytes will be read from
  *                           this.
  * \param sig_size           The size of the signature to be verified.
  *
  * \return         \c 0 on successful verification.
  * \return         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);

 #if defined(MBEDTLS_LMS_PRIVATE)
 /**
  * \brief                    This function initializes an LMS private context
  *
  * \param ctx                The uninitialized LMS private context that will
  *                           then be initialized. */
 void mbedtls_lms_private_init(mbedtls_lms_private_t *ctx);

 /**
  * \brief                    This function uninitializes an LMS private context
  *
  * \param ctx                The initialized LMS private context that will then
  *                           be uninitialized.
  */
 void mbedtls_lms_private_free(mbedtls_lms_private_t *ctx);

 /**
  * \brief                    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.
  *
  * \param ctx                The initialized LMOTS context to generate the key
  *                           into.
  * \param type               The LMS parameter set identifier.
  * \param otstype            The LMOTS parameter set identifier.
  * \param f_rng              The RNG function to be used to generate the key ID.
  * \param p_rng              The RNG context to be passed to f_rng
  * \param seed               The seed used to deterministically generate the
  *                           key.
  * \param seed_size          The length of the seed.
  *
  * \return         \c 0 on success.
  * \return         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,
                                      int (*f_rng)(void *, unsigned char *, size_t),
                                      void *p_rng, const unsigned char *seed,
                                      size_t seed_size);

 /**
  * \brief                    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.
  *
  * \param ctx                The initialized LMS public context to calculate the key
  *                           from and store it into.
  *
  * \param priv_ctx           The LMS private context to read the private key
  *                           from. This must have been initialized and contain a
  *                           private key.
  *
  * \return         \c 0 on success.
  * \return         A non-zero error code on failure.
  */
 int mbedtls_lms_calculate_public_key(mbedtls_lms_public_t *ctx,
                                      const mbedtls_lms_private_t *priv_ctx);

 /**
  * \brief                    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.
  *
  * \note                     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.
  *
  * \param ctx                The initialized LMS private context from which the
  *                           private key will be read.
  * \param f_rng              The RNG function to be used for signature
  *                           generation.
  * \param p_rng              The RNG context to be passed to f_rng
  * \param msg                The buffer from which the message will be read.
  * \param msg_size           The size of the message that will be read.
  * \param sig                The buf into which the signature will be stored.
  *                           Must be at least #MBEDTLS_LMS_SIG_LEN in size.
  * \param sig_size           The size of the buffer the signature will be
  *                           written into.
  * \param sig_len            If not NULL, will be written with the size of the
  *                           signature.
  *
  * \return         \c 0 on success.
  * \return         A non-zero error code on failure.
  */
 int mbedtls_lms_sign(mbedtls_lms_private_t *ctx,
                      int (*f_rng)(void *, unsigned char *, size_t),
                      void *p_rng, const unsigned char *msg,
                      unsigned int msg_size, unsigned char *sig, size_t sig_size,
                      size_t *sig_len);
 #endif /* defined(MBEDTLS_LMS_PRIVATE) */

 #ifdef __cplusplus
 }
 #endif

 #endif /* MBEDTLS_LMS_H */
	/**
	* \file lms.h
	*
	* \brief 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).
	*/
	/*
	* Copyright The Mbed TLS Contributors
	* SPDX-License-Identifier: Apache-2.0
	*
	* Licensed under the Apache License, Version 2.0 (the "License"); you may
	* not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
	* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/
	#ifndef MBEDTLS_LMS_H
	#define MBEDTLS_LMS_H

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

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

	#define MBEDTLS_ERR_LMS_BAD_INPUT_DATA -0x0011 /*< Bad data has been input to an LMS function /
	#define MBEDTLS_ERR_LMS_OUT_OF_PRIVATE_KEYS -0x0013 /*< Specified LMS key has utilised all of its private keys /
	#define MBEDTLS_ERR_LMS_VERIFY_FAILED -0x0015 /*< LMS signature verification failed /
	#define MBEDTLS_ERR_LMS_ALLOC_FAILED -0x0017 /*< LMS failed to allocate space for a private key /
	#define MBEDTLS_ERR_LMS_BUFFER_TOO_SMALL -0x0019 /*< Input/output buffer is too small to contain requited data /

	/* Currently only defined for SHA256, 32 is the max hash output size */
	#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) (MBEDTLS_LMOTS_TYPE_LEN + \
	MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN(type) + \
	(MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT(type) * \
	MBEDTLS_LMOTS_N_HASH_LEN(type)))


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

	/* The length of a hash output, Currently only implemented for SHA256.
	* Max is 32 bytes.
	*/
	#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) (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)))

	#define 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))


	#ifdef __cplusplus
	extern "C" {
	#endif

	/** 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.
	*/
	typedef enum {
	MBEDTLS_LMS_SHA256_M32_H10 = 0x6,
	} mbedtls_lms_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.
	*/
	typedef enum {
	MBEDTLS_LMOTS_SHA256_N32_W8 = 4
	} mbedtls_lmots_algorithm_type_t;

	/** LMOTS parameters structure.
	*
	* This contains the metadata associated with an LMOTS key, detailing the
	* algorithm type, the key ID, and the leaf identifier should be key be part of
	* a LMS key.
	*/
	typedef struct {
	unsigned char MBEDTLS_PRIVATE(I_key_identifier[MBEDTLS_LMOTS_I_KEY_ID_LEN]); /*!< The key
	identifier. */
	unsigned char MBEDTLS_PRIVATE(q_leaf_identifier[MBEDTLS_LMOTS_Q_LEAF_ID_LEN]); /*!< Which
	leaf of the LMS key this is.
	0 if the key is not part of an LMS key. */
	mbedtls_lmots_algorithm_type_t MBEDTLS_PRIVATE(type); /*!< The LM-OTS key type identifier as
	per IANA. Only SHA256_N32_W8 is
	currently supported. */
	} mbedtls_lmots_parameters_t;

	/** LMOTS public context structure.
	*
	* A LMOTS public key is a hash output, and the applicable parameter set.
	*
	* The context must be initialized before it is used. A public key must either
	* be imported or generated from a private context.
	*
	* \dot
	* digraph lmots_public_t {
	* UNINITIALIZED -> INIT [label="init"];
	* HAVE_PUBLIC_KEY -> INIT [label="free"];
	* INIT -> HAVE_PUBLIC_KEY [label="import_public_key"];
	* INIT -> HAVE_PUBLIC_KEY [label="calculate_public_key from private key"];
	* HAVE_PUBLIC_KEY -> HAVE_PUBLIC_KEY [label="export_public_key"];
	* }
	* \enddot
	*/
	typedef struct {
	mbedtls_lmots_parameters_t MBEDTLS_PRIVATE(params);
	unsigned char MBEDTLS_PRIVATE(public_key)[MBEDTLS_LMOTS_N_HASH_LEN_MAX];
	unsigned char MBEDTLS_PRIVATE(have_public_key); /*!< Whether the context contains a public key.
	Boolean values only. */
	} mbedtls_lmots_public_t;

	#if defined(MBEDTLS_LMS_PRIVATE)
	/** LMOTS private context structure.
	*
	* A LMOTS private key is one hash output for each of digit of the digest +
	* checksum, and the applicable parameter set.
	*
	* The context must be initialized before it is used. A public key must either
	* be imported or generated from a private context.
	*
	* \dot
	* digraph lmots_public_t {
	* UNINITIALIZED -> INIT [label="init"];
	* HAVE_PRIVATE_KEY -> INIT [label="free"];
	* INIT -> HAVE_PRIVATE_KEY [label="generate_private_key"];
	* HAVE_PRIVATE_KEY -> INIT [label="sign"];
	* }
	* \enddot
	*/
	typedef struct {
	mbedtls_lmots_parameters_t MBEDTLS_PRIVATE(params);
	unsigned char MBEDTLS_PRIVATE(private_key)[MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT_MAX][
	MBEDTLS_LMOTS_N_HASH_LEN_MAX];
	unsigned char MBEDTLS_PRIVATE(have_private_key); /*!< Whether the context contains a private key.
	Boolean values only. */
	} mbedtls_lmots_private_t;
	#endif /* defined(MBEDTLS_LMS_PRIVATE) */


	/** LMS parameters structure.
	*
	* This contains the metadata associated with an LMS key, detailing the
	* algorithm type, the type of the underlying OTS algorithm, and the key ID.
	*/
	typedef struct {
	unsigned char MBEDTLS_PRIVATE(I_key_identifier[MBEDTLS_LMOTS_I_KEY_ID_LEN]); /*!< The key
	identifier. */
	mbedtls_lmots_algorithm_type_t MBEDTLS_PRIVATE(otstype); /*!< The LM-OTS key type identifier as
	per IANA. Only SHA256_N32_W8 is
	currently supported. */
	mbedtls_lms_algorithm_type_t MBEDTLS_PRIVATE(type); /*!< The LMS key type identifier as per
	IANA. Only SHA256_M32_H10 is currently
	supported. */
	} mbedtls_lms_parameters_t;

	/** LMS public context structure.
	*
	* A LMS public key is the hash output that is the root of the Merkle tree, and
	* the applicable parameter set
	*
	* The context must be initialized before it is used. A public key must either
	* be imported or generated from a private context.
	*
	* \dot
	* digraph lms_public_t {
	* UNINITIALIZED -> INIT [label="init"];
	* HAVE_PUBLIC_KEY -> INIT [label="free"];
	* INIT -> HAVE_PUBLIC_KEY [label="import_public_key"];
	* INIT -> HAVE_PUBLIC_KEY [label="calculate_public_key from private key"];
	* HAVE_PUBLIC_KEY -> HAVE_PUBLIC_KEY [label="export_public_key"];
	* }
	* \enddot
	*/
	typedef struct {
	mbedtls_lms_parameters_t MBEDTLS_PRIVATE(params);
	unsigned char MBEDTLS_PRIVATE(T_1_pub_key)[MBEDTLS_LMS_M_NODE_BYTES_MAX]; /*!< The public key, in
	the form of the Merkle tree root node. */
	unsigned char MBEDTLS_PRIVATE(have_public_key); /*!< Whether the context contains a public key.
	Boolean values only. */
	} mbedtls_lms_public_t;


	#if defined(MBEDTLS_LMS_PRIVATE)
	/** LMS private context structure.
	*
	* A LMS private key is a set of LMOTS private keys, an index to the next usable
	* key, and the applicable parameter set.
	*
	* The context must be initialized before it is used. A public key must either
	* be imported or generated from a private context.
	*
	* \dot
	* digraph lms_public_t {
	* UNINITIALIZED -> INIT [label="init"];
	* HAVE_PRIVATE_KEY -> INIT [label="free"];
	* INIT -> HAVE_PRIVATE_KEY [label="generate_private_key"];
	* }
	* \enddot
	*/
	typedef struct {
	mbedtls_lms_parameters_t MBEDTLS_PRIVATE(params);
	uint32_t MBEDTLS_PRIVATE(q_next_usable_key); /*!< The index of the next OTS key that has not
	been used. */
	mbedtls_lmots_private_t MBEDTLS_PRIVATE(ots_private_keys); /!< The private key material. One OTS key
	for each leaf node in the Merkle tree. NULL
	when have_private_key is 0 and non-NULL otherwise.
	is 2^MBEDTLS_LMS_H_TREE_HEIGHT(type) in length. */
	mbedtls_lmots_public_t MBEDTLS_PRIVATE(ots_public_keys); /!< The OTS key public keys, used to
	build the Merkle tree. NULL
	when have_private_key is 0 and
	non-NULL otherwise.
	Is 2^MBEDTLS_LMS_H_TREE_HEIGHT(type)
	in length. */
	unsigned char MBEDTLS_PRIVATE(have_private_key); /*!< Whether the context contains a private key.
	Boolean values only. */
	} mbedtls_lms_private_t;
	#endif /* defined(MBEDTLS_LMS_PRIVATE) */

	/**
	* \brief This function initializes an LMS public context
	*
	* \param ctx The uninitialized LMS context that will then be
	* initialized.
	*/
	void mbedtls_lms_public_init(mbedtls_lms_public_t *ctx);

	/**
	* \brief This function uninitializes an LMS public context
	*
	* \param ctx The initialized LMS context that will then be
	* uninitialized.
	*/
	void mbedtls_lms_public_free(mbedtls_lms_public_t *ctx);

	/**
	* \brief This function imports an LMS public key into a
	* public LMS context.
	*
	* \note Before this function is called, the context must
	* have been initialized.
	*
	* \note See IETF RFC8554 for details of the encoding of
	* this public key.
	*
	* \param ctx The initialized LMS context store the key in.
	* \param key The buffer from which the key will be read.
	* #MBEDTLS_LMS_PUBLIC_KEY_LEN bytes will be read from
	* this.
	* \param key_size The size of the key being imported.
	*
	* \return \c 0 on success.
	* \return 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);

	/**
	* \brief 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.
	*
	* \note See IETF RFC8554 for details of the encoding of
	* this public key.
	*
	* \param ctx The initialized LMS public context that contains
	* the public key.
	* \param key The buffer into which the key will be output. Must
	* be at least #MBEDTLS_LMS_PUBLIC_KEY_LEN in size.
	* \param key_size The size of the key buffer.
	* \param key_len If not NULL, will be written with the size of the
	* key.
	*
	* \return \c 0 on success.
	* \return 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);

	/**
	* \brief 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).
	*
	* \param ctx The initialized LMS public context from which the
	* public key will be read.
	* \param msg The buffer from which the message will be read.
	* \param msg_size The size of the message that will be read.
	* \param sig The buf from which the signature will be read.
	* #MBEDTLS_LMS_SIG_LEN bytes will be read from
	* this.
	* \param sig_size The size of the signature to be verified.
	*
	* \return \c 0 on successful verification.
	* \return 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);

	#if defined(MBEDTLS_LMS_PRIVATE)
	/**
	* \brief This function initializes an LMS private context
	*
	* \param ctx The uninitialized LMS private context that will
	* then be initialized. */
	void mbedtls_lms_private_init(mbedtls_lms_private_t *ctx);

	/**
	* \brief This function uninitializes an LMS private context
	*
	* \param ctx The initialized LMS private context that will then
	* be uninitialized.
	*/
	void mbedtls_lms_private_free(mbedtls_lms_private_t *ctx);

	/**
	* \brief 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.
	*
	* \param ctx The initialized LMOTS context to generate the key
	* into.
	* \param type The LMS parameter set identifier.
	* \param otstype The LMOTS parameter set identifier.
	* \param f_rng The RNG function to be used to generate the key ID.
	* \param p_rng The RNG context to be passed to f_rng
	* \param seed The seed used to deterministically generate the
	* key.
	* \param seed_size The length of the seed.
	*
	* \return \c 0 on success.
	* \return 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,
	int (f_rng)(void , unsigned char *, size_t),
	void p_rng, const unsigned char seed,
	size_t seed_size);

	/**
	* \brief 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.
	*
	* \param ctx The initialized LMS public context to calculate the key
	* from and store it into.
	*
	* \param priv_ctx The LMS private context to read the private key
	* from. This must have been initialized and contain a
	* private key.
	*
	* \return \c 0 on success.
	* \return A non-zero error code on failure.
	*/
	int mbedtls_lms_calculate_public_key(mbedtls_lms_public_t *ctx,
	const mbedtls_lms_private_t *priv_ctx);

	/**
	* \brief 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.
	*
	* \note 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.
	*
	* \param ctx The initialized LMS private context from which the
	* private key will be read.
	* \param f_rng The RNG function to be used for signature
	* generation.
	* \param p_rng The RNG context to be passed to f_rng
	* \param msg The buffer from which the message will be read.
	* \param msg_size The size of the message that will be read.
	* \param sig The buf into which the signature will be stored.
	* Must be at least #MBEDTLS_LMS_SIG_LEN in size.
	* \param sig_size The size of the buffer the signature will be
	* written into.
	* \param sig_len If not NULL, will be written with the size of the
	* signature.
	*
	* \return \c 0 on success.
	* \return A non-zero error code on failure.
	*/
	int mbedtls_lms_sign(mbedtls_lms_private_t *ctx,
	int (f_rng)(void , unsigned char *, size_t),
	void p_rng, const unsigned char msg,
	unsigned int msg_size, unsigned char *sig, size_t sig_size,
	size_t *sig_len);
	#endif /* defined(MBEDTLS_LMS_PRIVATE) */

	#ifdef __cplusplus
	}
	#endif

	#endif /* MBEDTLS_LMS_H */