Mbed TLS v3.6.0
lms.h
Go to the documentation of this file.
1 
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
25 #define MBEDTLS_ERR_LMS_OUT_OF_PRIVATE_KEYS -0x0013
26 #define MBEDTLS_ERR_LMS_VERIFY_FAILED -0x0015
27 #define MBEDTLS_ERR_LMS_ALLOC_FAILED -0x0017
28 #define MBEDTLS_ERR_LMS_BUFFER_TOO_SMALL -0x0019
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 
75 typedef enum {
78 
83 typedef enum {
86 
93 typedef struct {
94  unsigned char MBEDTLS_PRIVATE(I_key_identifier[MBEDTLS_LMOTS_I_KEY_ID_LEN]);
96  unsigned char MBEDTLS_PRIVATE(q_leaf_identifier[MBEDTLS_LMOTS_Q_LEAF_ID_LEN]);
103 
121 typedef struct {
123  unsigned char MBEDTLS_PRIVATE(public_key)[MBEDTLS_LMOTS_N_HASH_LEN_MAX];
124  unsigned char MBEDTLS_PRIVATE(have_public_key);
127 
128 #if defined(MBEDTLS_LMS_PRIVATE)
146 typedef struct {
148  unsigned char MBEDTLS_PRIVATE(private_key)[MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT_MAX][
150  unsigned char MBEDTLS_PRIVATE(have_private_key);
152 } mbedtls_lmots_private_t;
153 #endif /* defined(MBEDTLS_LMS_PRIVATE) */
154 
155 
161 typedef struct {
162  unsigned char MBEDTLS_PRIVATE(I_key_identifier[MBEDTLS_LMOTS_I_KEY_ID_LEN]);
171 
190 typedef struct {
192  unsigned char MBEDTLS_PRIVATE(T_1_pub_key)[MBEDTLS_LMS_M_NODE_BYTES_MAX];
194  unsigned char MBEDTLS_PRIVATE(have_public_key);
197 
198 
199 #if defined(MBEDTLS_LMS_PRIVATE)
216 typedef struct {
218  uint32_t MBEDTLS_PRIVATE(q_next_usable_key);
220  mbedtls_lmots_private_t *MBEDTLS_PRIVATE(ots_private_keys);
224  mbedtls_lmots_public_t *MBEDTLS_PRIVATE(ots_public_keys);
230  unsigned char MBEDTLS_PRIVATE(have_private_key);
232 } mbedtls_lms_private_t;
233 #endif /* defined(MBEDTLS_LMS_PRIVATE) */
234 
242 
250 
271  const unsigned char *key, size_t key_size);
272 
297  unsigned char *key, size_t key_size,
298  size_t *key_len);
299 
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)
330 void mbedtls_lms_private_init(mbedtls_lms_private_t *ctx);
331 
338 void mbedtls_lms_private_free(mbedtls_lms_private_t *ctx);
339 
364 int mbedtls_lms_generate_private_key(mbedtls_lms_private_t *ctx,
367  int (*f_rng)(void *, unsigned char *, size_t),
368  void *p_rng, const unsigned char *seed,
369  size_t seed_size);
370 
389 int mbedtls_lms_calculate_public_key(mbedtls_lms_public_t *ctx,
390  const mbedtls_lms_private_t *priv_ctx);
391 
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 */
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.
#define MBEDTLS_LMOTS_I_KEY_ID_LEN
Definition: lms.h:34
#define MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT_MAX
Definition: lms.h:32
mbedtls_lmots_algorithm_type_t
Definition: lms.h:83
@ MBEDTLS_LMOTS_SHA256_N32_W8
Definition: lms.h:84
void mbedtls_lms_public_free(mbedtls_lms_public_t *ctx)
This function uninitializes an LMS public context.
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.
void mbedtls_lms_public_init(mbedtls_lms_public_t *ctx)
This function initializes an LMS public context.
#define MBEDTLS_LMOTS_N_HASH_LEN_MAX
Definition: lms.h:31
mbedtls_lms_algorithm_type_t
Definition: lms.h:75
@ MBEDTLS_LMS_SHA256_M32_H10
Definition: lms.h:76
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.
#define MBEDTLS_LMS_M_NODE_BYTES_MAX
Definition: lms.h:53
#define MBEDTLS_LMOTS_Q_LEAF_ID_LEN
Definition: lms.h:35
Build-time configuration info.
Macro wrapper for struct's members.
#define MBEDTLS_PRIVATE(member)