1 /** 2 * \file lms.h 3 * 4 * \brief This file provides an API for the LMS post-quantum-safe stateful-hash 5 public-key signature scheme as defined in RFC8554 and NIST.SP.200-208. 6 * This implementation currently only supports a single parameter set 7 * MBEDTLS_LMS_SHA256_M32_H10 in order to reduce complexity. This is one 8 * of the signature schemes recommended by the IETF draft SUIT standard 9 * for IOT firmware upgrades (RFC9019). 10 */ 11 /* 12 * Copyright The Mbed TLS Contributors 13 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 14 */ 15 #ifndef MBEDTLS_LMS_H 16 #define MBEDTLS_LMS_H 17 18 #include <stdint.h> 19 #include <stddef.h> 20 21 #include "mbedtls/private_access.h" 22 #include "mbedtls/build_info.h" 23 24 #define MBEDTLS_ERR_LMS_BAD_INPUT_DATA -0x0011 /**< Bad data has been input to an LMS function */ 25 #define MBEDTLS_ERR_LMS_OUT_OF_PRIVATE_KEYS -0x0013 /**< Specified LMS key has utilised all of its private keys */ 26 #define MBEDTLS_ERR_LMS_VERIFY_FAILED -0x0015 /**< LMS signature verification failed */ 27 #define MBEDTLS_ERR_LMS_ALLOC_FAILED -0x0017 /**< LMS failed to allocate space for a private key */ 28 #define MBEDTLS_ERR_LMS_BUFFER_TOO_SMALL -0x0019 /**< Input/output buffer is too small to contain requited data */ 29 30 /* Currently only defined for SHA256, 32 is the max hash output size */ 31 #define MBEDTLS_LMOTS_N_HASH_LEN_MAX (32u) 32 #define MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT_MAX (34u) 33 #define MBEDTLS_LMOTS_N_HASH_LEN(type) ((type) == MBEDTLS_LMOTS_SHA256_N32_W8 ? 32u : 0) 34 #define MBEDTLS_LMOTS_I_KEY_ID_LEN (16u) 35 #define MBEDTLS_LMOTS_Q_LEAF_ID_LEN (4u) 36 #define MBEDTLS_LMOTS_TYPE_LEN (4u) 37 #define MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT(type) ((type) == MBEDTLS_LMOTS_SHA256_N32_W8 ? 34u : 0) 38 #define MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN(type) (MBEDTLS_LMOTS_N_HASH_LEN(type)) 39 40 #define MBEDTLS_LMOTS_SIG_LEN(type) (MBEDTLS_LMOTS_TYPE_LEN + \ 41 MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN(type) + \ 42 (MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT(type) * \ 43 MBEDTLS_LMOTS_N_HASH_LEN(type))) 44 45 46 #define MBEDTLS_LMS_TYPE_LEN (4) 47 #define MBEDTLS_LMS_H_TREE_HEIGHT(type) ((type) == MBEDTLS_LMS_SHA256_M32_H10 ? 10u : 0) 48 49 /* The length of a hash output, Currently only implemented for SHA256. 50 * Max is 32 bytes. 51 */ 52 #define MBEDTLS_LMS_M_NODE_BYTES(type) ((type) == MBEDTLS_LMS_SHA256_M32_H10 ? 32 : 0) 53 #define MBEDTLS_LMS_M_NODE_BYTES_MAX 32 54 55 #define MBEDTLS_LMS_SIG_LEN(type, otstype) (MBEDTLS_LMOTS_Q_LEAF_ID_LEN + \ 56 MBEDTLS_LMOTS_SIG_LEN(otstype) + \ 57 MBEDTLS_LMS_TYPE_LEN + \ 58 (MBEDTLS_LMS_H_TREE_HEIGHT(type) * \ 59 MBEDTLS_LMS_M_NODE_BYTES(type))) 60 61 #define MBEDTLS_LMS_PUBLIC_KEY_LEN(type) (MBEDTLS_LMS_TYPE_LEN + \ 62 MBEDTLS_LMOTS_TYPE_LEN + \ 63 MBEDTLS_LMOTS_I_KEY_ID_LEN + \ 64 MBEDTLS_LMS_M_NODE_BYTES(type)) 65 66 67 #ifdef __cplusplus 68 extern "C" { 69 #endif 70 71 /** The Identifier of the LMS parameter set, as per 72 * https://www.iana.org/assignments/leighton-micali-signatures/leighton-micali-signatures.xhtml 73 * We are only implementing a subset of the types, particularly H10, for the sake of simplicity. 74 */ 75 typedef enum { 76 MBEDTLS_LMS_SHA256_M32_H10 = 0x6, 77 } mbedtls_lms_algorithm_type_t; 78 79 /** The Identifier of the LMOTS parameter set, as per 80 * https://www.iana.org/assignments/leighton-micali-signatures/leighton-micali-signatures.xhtml. 81 * We are only implementing a subset of the types, particularly N32_W8, for the sake of simplicity. 82 */ 83 typedef enum { 84 MBEDTLS_LMOTS_SHA256_N32_W8 = 4 85 } mbedtls_lmots_algorithm_type_t; 86 87 /** LMOTS parameters structure. 88 * 89 * This contains the metadata associated with an LMOTS key, detailing the 90 * algorithm type, the key ID, and the leaf identifier should be key be part of 91 * a LMS key. 92 */ 93 typedef struct { 94 unsigned char MBEDTLS_PRIVATE(I_key_identifier[MBEDTLS_LMOTS_I_KEY_ID_LEN]); /*!< The key 95 identifier. */ 96 unsigned char MBEDTLS_PRIVATE(q_leaf_identifier[MBEDTLS_LMOTS_Q_LEAF_ID_LEN]); /*!< Which 97 leaf of the LMS key this is. 98 0 if the key is not part of an LMS key. */ 99 mbedtls_lmots_algorithm_type_t MBEDTLS_PRIVATE(type); /*!< The LM-OTS key type identifier as 100 per IANA. Only SHA256_N32_W8 is 101 currently supported. */ 102 } mbedtls_lmots_parameters_t; 103 104 /** LMOTS public context structure. 105 * 106 * A LMOTS public key is a hash output, and the applicable parameter set. 107 * 108 * The context must be initialized before it is used. A public key must either 109 * be imported or generated from a private context. 110 * 111 * \dot 112 * digraph lmots_public_t { 113 * UNINITIALIZED -> INIT [label="init"]; 114 * HAVE_PUBLIC_KEY -> INIT [label="free"]; 115 * INIT -> HAVE_PUBLIC_KEY [label="import_public_key"]; 116 * INIT -> HAVE_PUBLIC_KEY [label="calculate_public_key from private key"]; 117 * HAVE_PUBLIC_KEY -> HAVE_PUBLIC_KEY [label="export_public_key"]; 118 * } 119 * \enddot 120 */ 121 typedef struct { 122 mbedtls_lmots_parameters_t MBEDTLS_PRIVATE(params); 123 unsigned char MBEDTLS_PRIVATE(public_key)[MBEDTLS_LMOTS_N_HASH_LEN_MAX]; 124 unsigned char MBEDTLS_PRIVATE(have_public_key); /*!< Whether the context contains a public key. 125 Boolean values only. */ 126 } mbedtls_lmots_public_t; 127 128 #if defined(MBEDTLS_LMS_PRIVATE) 129 /** LMOTS private context structure. 130 * 131 * A LMOTS private key is one hash output for each of digit of the digest + 132 * checksum, and the applicable parameter set. 133 * 134 * The context must be initialized before it is used. A public key must either 135 * be imported or generated from a private context. 136 * 137 * \dot 138 * digraph lmots_public_t { 139 * UNINITIALIZED -> INIT [label="init"]; 140 * HAVE_PRIVATE_KEY -> INIT [label="free"]; 141 * INIT -> HAVE_PRIVATE_KEY [label="generate_private_key"]; 142 * HAVE_PRIVATE_KEY -> INIT [label="sign"]; 143 * } 144 * \enddot 145 */ 146 typedef struct { 147 mbedtls_lmots_parameters_t MBEDTLS_PRIVATE(params); 148 unsigned char MBEDTLS_PRIVATE(private_key)[MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT_MAX][ 149 MBEDTLS_LMOTS_N_HASH_LEN_MAX]; 150 unsigned char MBEDTLS_PRIVATE(have_private_key); /*!< Whether the context contains a private key. 151 Boolean values only. */ 152 } mbedtls_lmots_private_t; 153 #endif /* defined(MBEDTLS_LMS_PRIVATE) */ 154 155 156 /** LMS parameters structure. 157 * 158 * This contains the metadata associated with an LMS key, detailing the 159 * algorithm type, the type of the underlying OTS algorithm, and the key ID. 160 */ 161 typedef struct { 162 unsigned char MBEDTLS_PRIVATE(I_key_identifier[MBEDTLS_LMOTS_I_KEY_ID_LEN]); /*!< The key 163 identifier. */ 164 mbedtls_lmots_algorithm_type_t MBEDTLS_PRIVATE(otstype); /*!< The LM-OTS key type identifier as 165 per IANA. Only SHA256_N32_W8 is 166 currently supported. */ 167 mbedtls_lms_algorithm_type_t MBEDTLS_PRIVATE(type); /*!< The LMS key type identifier as per 168 IANA. Only SHA256_M32_H10 is currently 169 supported. */ 170 } mbedtls_lms_parameters_t; 171 172 /** LMS public context structure. 173 * 174 * A LMS public key is the hash output that is the root of the Merkle tree, and 175 * the applicable parameter set 176 * 177 * The context must be initialized before it is used. A public key must either 178 * be imported or generated from a private context. 179 * 180 * \dot 181 * digraph lms_public_t { 182 * UNINITIALIZED -> INIT [label="init"]; 183 * HAVE_PUBLIC_KEY -> INIT [label="free"]; 184 * INIT -> HAVE_PUBLIC_KEY [label="import_public_key"]; 185 * INIT -> HAVE_PUBLIC_KEY [label="calculate_public_key from private key"]; 186 * HAVE_PUBLIC_KEY -> HAVE_PUBLIC_KEY [label="export_public_key"]; 187 * } 188 * \enddot 189 */ 190 typedef struct { 191 mbedtls_lms_parameters_t MBEDTLS_PRIVATE(params); 192 unsigned char MBEDTLS_PRIVATE(T_1_pub_key)[MBEDTLS_LMS_M_NODE_BYTES_MAX]; /*!< The public key, in 193 the form of the Merkle tree root node. */ 194 unsigned char MBEDTLS_PRIVATE(have_public_key); /*!< Whether the context contains a public key. 195 Boolean values only. */ 196 } mbedtls_lms_public_t; 197 198 199 #if defined(MBEDTLS_LMS_PRIVATE) 200 /** LMS private context structure. 201 * 202 * A LMS private key is a set of LMOTS private keys, an index to the next usable 203 * key, and the applicable parameter set. 204 * 205 * The context must be initialized before it is used. A public key must either 206 * be imported or generated from a private context. 207 * 208 * \dot 209 * digraph lms_public_t { 210 * UNINITIALIZED -> INIT [label="init"]; 211 * HAVE_PRIVATE_KEY -> INIT [label="free"]; 212 * INIT -> HAVE_PRIVATE_KEY [label="generate_private_key"]; 213 * } 214 * \enddot 215 */ 216 typedef struct { 217 mbedtls_lms_parameters_t MBEDTLS_PRIVATE(params); 218 uint32_t MBEDTLS_PRIVATE(q_next_usable_key); /*!< The index of the next OTS key that has not 219 been used. */ 220 mbedtls_lmots_private_t *MBEDTLS_PRIVATE(ots_private_keys); /*!< The private key material. One OTS key 221 for each leaf node in the Merkle tree. NULL 222 when have_private_key is 0 and non-NULL otherwise. 223 is 2^MBEDTLS_LMS_H_TREE_HEIGHT(type) in length. */ 224 mbedtls_lmots_public_t *MBEDTLS_PRIVATE(ots_public_keys); /*!< The OTS key public keys, used to 225 build the Merkle tree. NULL 226 when have_private_key is 0 and 227 non-NULL otherwise. 228 Is 2^MBEDTLS_LMS_H_TREE_HEIGHT(type) 229 in length. */ 230 unsigned char MBEDTLS_PRIVATE(have_private_key); /*!< Whether the context contains a private key. 231 Boolean values only. */ 232 } mbedtls_lms_private_t; 233 #endif /* defined(MBEDTLS_LMS_PRIVATE) */ 234 235 /** 236 * \brief This function initializes an LMS public context 237 * 238 * \param ctx The uninitialized LMS context that will then be 239 * initialized. 240 */ 241 void mbedtls_lms_public_init(mbedtls_lms_public_t *ctx); 242 243 /** 244 * \brief This function uninitializes an LMS public context 245 * 246 * \param ctx The initialized LMS context that will then be 247 * uninitialized. 248 */ 249 void mbedtls_lms_public_free(mbedtls_lms_public_t *ctx); 250 251 /** 252 * \brief This function imports an LMS public key into a 253 * public LMS context. 254 * 255 * \note Before this function is called, the context must 256 * have been initialized. 257 * 258 * \note See IETF RFC8554 for details of the encoding of 259 * this public key. 260 * 261 * \param ctx The initialized LMS context store the key in. 262 * \param key The buffer from which the key will be read. 263 * #MBEDTLS_LMS_PUBLIC_KEY_LEN bytes will be read from 264 * this. 265 * \param key_size The size of the key being imported. 266 * 267 * \return \c 0 on success. 268 * \return A non-zero error code on failure. 269 */ 270 int mbedtls_lms_import_public_key(mbedtls_lms_public_t *ctx, 271 const unsigned char *key, size_t key_size); 272 273 /** 274 * \brief This function exports an LMS public key from a 275 * LMS public context that already contains a public 276 * key. 277 * 278 * \note Before this function is called, the context must 279 * have been initialized and the context must contain 280 * a public key. 281 * 282 * \note See IETF RFC8554 for details of the encoding of 283 * this public key. 284 * 285 * \param ctx The initialized LMS public context that contains 286 * the public key. 287 * \param key The buffer into which the key will be output. Must 288 * be at least #MBEDTLS_LMS_PUBLIC_KEY_LEN in size. 289 * \param key_size The size of the key buffer. 290 * \param key_len If not NULL, will be written with the size of the 291 * key. 292 * 293 * \return \c 0 on success. 294 * \return A non-zero error code on failure. 295 */ 296 int mbedtls_lms_export_public_key(const mbedtls_lms_public_t *ctx, 297 unsigned char *key, size_t key_size, 298 size_t *key_len); 299 300 /** 301 * \brief This function verifies a LMS signature, using a 302 * LMS context that contains a public key. 303 * 304 * \note Before this function is called, the context must 305 * have been initialized and must contain a public key 306 * (either by import or generation). 307 * 308 * \param ctx The initialized LMS public context from which the 309 * public key will be read. 310 * \param msg The buffer from which the message will be read. 311 * \param msg_size The size of the message that will be read. 312 * \param sig The buf from which the signature will be read. 313 * #MBEDTLS_LMS_SIG_LEN bytes will be read from 314 * this. 315 * \param sig_size The size of the signature to be verified. 316 * 317 * \return \c 0 on successful verification. 318 * \return A non-zero error code on failure. 319 */ 320 int mbedtls_lms_verify(const mbedtls_lms_public_t *ctx, 321 const unsigned char *msg, size_t msg_size, 322 const unsigned char *sig, size_t sig_size); 323 324 #if defined(MBEDTLS_LMS_PRIVATE) 325 /** 326 * \brief This function initializes an LMS private context 327 * 328 * \param ctx The uninitialized LMS private context that will 329 * then be initialized. */ 330 void mbedtls_lms_private_init(mbedtls_lms_private_t *ctx); 331 332 /** 333 * \brief This function uninitializes an LMS private context 334 * 335 * \param ctx The initialized LMS private context that will then 336 * be uninitialized. 337 */ 338 void mbedtls_lms_private_free(mbedtls_lms_private_t *ctx); 339 340 /** 341 * \brief This function generates an LMS private key, and 342 * stores in into an LMS private context. 343 * 344 * \warning This function is **not intended for use in 345 * production**, due to as-yet unsolved problems with 346 * handling stateful keys. The API for this function 347 * may change considerably in future versions. 348 * 349 * \note The seed must have at least 256 bits of entropy. 350 * 351 * \param ctx The initialized LMOTS context to generate the key 352 * into. 353 * \param type The LMS parameter set identifier. 354 * \param otstype The LMOTS parameter set identifier. 355 * \param f_rng The RNG function to be used to generate the key ID. 356 * \param p_rng The RNG context to be passed to f_rng 357 * \param seed The seed used to deterministically generate the 358 * key. 359 * \param seed_size The length of the seed. 360 * 361 * \return \c 0 on success. 362 * \return A non-zero error code on failure. 363 */ 364 int mbedtls_lms_generate_private_key(mbedtls_lms_private_t *ctx, 365 mbedtls_lms_algorithm_type_t type, 366 mbedtls_lmots_algorithm_type_t otstype, 367 int (*f_rng)(void *, unsigned char *, size_t), 368 void *p_rng, const unsigned char *seed, 369 size_t seed_size); 370 371 /** 372 * \brief This function calculates an LMS public key from a 373 * LMS context that already contains a private key. 374 * 375 * \note Before this function is called, the context must 376 * have been initialized and the context must contain 377 * a private key. 378 * 379 * \param ctx The initialized LMS public context to calculate the key 380 * from and store it into. 381 * 382 * \param priv_ctx The LMS private context to read the private key 383 * from. This must have been initialized and contain a 384 * private key. 385 * 386 * \return \c 0 on success. 387 * \return A non-zero error code on failure. 388 */ 389 int mbedtls_lms_calculate_public_key(mbedtls_lms_public_t *ctx, 390 const mbedtls_lms_private_t *priv_ctx); 391 392 /** 393 * \brief This function creates a LMS signature, using a 394 * LMS context that contains unused private keys. 395 * 396 * \warning This function is **not intended for use in 397 * production**, due to as-yet unsolved problems with 398 * handling stateful keys. The API for this function 399 * may change considerably in future versions. 400 * 401 * \note Before this function is called, the context must 402 * have been initialized and must contain a private 403 * key. 404 * 405 * \note Each of the LMOTS private keys inside a LMS private 406 * key can only be used once. If they are reused, then 407 * attackers may be able to forge signatures with that 408 * key. This is all handled transparently, but it is 409 * important to not perform copy operations on LMS 410 * contexts that contain private key material. 411 * 412 * \param ctx The initialized LMS private context from which the 413 * private key will be read. 414 * \param f_rng The RNG function to be used for signature 415 * generation. 416 * \param p_rng The RNG context to be passed to f_rng 417 * \param msg The buffer from which the message will be read. 418 * \param msg_size The size of the message that will be read. 419 * \param sig The buf into which the signature will be stored. 420 * Must be at least #MBEDTLS_LMS_SIG_LEN in size. 421 * \param sig_size The size of the buffer the signature will be 422 * written into. 423 * \param sig_len If not NULL, will be written with the size of the 424 * signature. 425 * 426 * \return \c 0 on success. 427 * \return A non-zero error code on failure. 428 */ 429 int mbedtls_lms_sign(mbedtls_lms_private_t *ctx, 430 int (*f_rng)(void *, unsigned char *, size_t), 431 void *p_rng, const unsigned char *msg, 432 unsigned int msg_size, unsigned char *sig, size_t sig_size, 433 size_t *sig_len); 434 #endif /* defined(MBEDTLS_LMS_PRIVATE) */ 435 436 #ifdef __cplusplus 437 } 438 #endif 439 440 #endif /* MBEDTLS_LMS_H */ 441
