Mbed TLS v3.5.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
14  *
15  * Licensed under the Apache License, Version 2.0 (the "License"); you may
16  * not use this file except in compliance with the License.
17  * You may obtain a copy of the License at
18  *
19  * http://www.apache.org/licenses/LICENSE-2.0
20  *
21  * Unless required by applicable law or agreed to in writing, software
22  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
23  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
24  * See the License for the specific language governing permissions and
25  * limitations under the License.
26  */
27 #ifndef MBEDTLS_LMS_H
28 #define MBEDTLS_LMS_H
29 
30 #include <stdint.h>
31 #include <stddef.h>
32 
33 #include "mbedtls/private_access.h"
34 #include "mbedtls/build_info.h"
35 
36 #define MBEDTLS_ERR_LMS_BAD_INPUT_DATA -0x0011
37 #define MBEDTLS_ERR_LMS_OUT_OF_PRIVATE_KEYS -0x0013
38 #define MBEDTLS_ERR_LMS_VERIFY_FAILED -0x0015
39 #define MBEDTLS_ERR_LMS_ALLOC_FAILED -0x0017
40 #define MBEDTLS_ERR_LMS_BUFFER_TOO_SMALL -0x0019
42 /* Currently only defined for SHA256, 32 is the max hash output size */
43 #define MBEDTLS_LMOTS_N_HASH_LEN_MAX (32u)
44 #define MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT_MAX (34u)
45 #define MBEDTLS_LMOTS_N_HASH_LEN(type) ((type) == MBEDTLS_LMOTS_SHA256_N32_W8 ? 32u : 0)
46 #define MBEDTLS_LMOTS_I_KEY_ID_LEN (16u)
47 #define MBEDTLS_LMOTS_Q_LEAF_ID_LEN (4u)
48 #define MBEDTLS_LMOTS_TYPE_LEN (4u)
49 #define MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT(type) ((type) == MBEDTLS_LMOTS_SHA256_N32_W8 ? 34u : 0)
50 #define MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN(type) (MBEDTLS_LMOTS_N_HASH_LEN(type))
51 
52 #define MBEDTLS_LMOTS_SIG_LEN(type) (MBEDTLS_LMOTS_TYPE_LEN + \
53  MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN(type) + \
54  (MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT(type) * \
55  MBEDTLS_LMOTS_N_HASH_LEN(type)))
56 
57 
58 #define MBEDTLS_LMS_TYPE_LEN (4)
59 #define MBEDTLS_LMS_H_TREE_HEIGHT(type) ((type) == MBEDTLS_LMS_SHA256_M32_H10 ? 10u : 0)
60 
61 /* The length of a hash output, Currently only implemented for SHA256.
62  * Max is 32 bytes.
63  */
64 #define MBEDTLS_LMS_M_NODE_BYTES(type) ((type) == MBEDTLS_LMS_SHA256_M32_H10 ? 32 : 0)
65 #define MBEDTLS_LMS_M_NODE_BYTES_MAX 32
66 
67 #define MBEDTLS_LMS_SIG_LEN(type, otstype) (MBEDTLS_LMOTS_Q_LEAF_ID_LEN + \
68  MBEDTLS_LMOTS_SIG_LEN(otstype) + \
69  MBEDTLS_LMS_TYPE_LEN + \
70  (MBEDTLS_LMS_H_TREE_HEIGHT(type) * \
71  MBEDTLS_LMS_M_NODE_BYTES(type)))
72 
73 #define MBEDTLS_LMS_PUBLIC_KEY_LEN(type) (MBEDTLS_LMS_TYPE_LEN + \
74  MBEDTLS_LMOTS_TYPE_LEN + \
75  MBEDTLS_LMOTS_I_KEY_ID_LEN + \
76  MBEDTLS_LMS_M_NODE_BYTES(type))
77 
78 
79 #ifdef __cplusplus
80 extern "C" {
81 #endif
82 
87 typedef enum {
90 
95 typedef enum {
98 
105 typedef struct {
106  unsigned char MBEDTLS_PRIVATE(I_key_identifier[MBEDTLS_LMOTS_I_KEY_ID_LEN]);
108  unsigned char MBEDTLS_PRIVATE(q_leaf_identifier[MBEDTLS_LMOTS_Q_LEAF_ID_LEN]);
115 
133 typedef struct {
135  unsigned char MBEDTLS_PRIVATE(public_key)[MBEDTLS_LMOTS_N_HASH_LEN_MAX];
136  unsigned char MBEDTLS_PRIVATE(have_public_key);
139 
140 #if defined(MBEDTLS_LMS_PRIVATE)
158 typedef struct {
160  unsigned char MBEDTLS_PRIVATE(private_key)[MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT_MAX][
162  unsigned char MBEDTLS_PRIVATE(have_private_key);
164 } mbedtls_lmots_private_t;
165 #endif /* defined(MBEDTLS_LMS_PRIVATE) */
166 
167 
173 typedef struct {
174  unsigned char MBEDTLS_PRIVATE(I_key_identifier[MBEDTLS_LMOTS_I_KEY_ID_LEN]);
183 
202 typedef struct {
204  unsigned char MBEDTLS_PRIVATE(T_1_pub_key)[MBEDTLS_LMS_M_NODE_BYTES_MAX];
206  unsigned char MBEDTLS_PRIVATE(have_public_key);
209 
210 
211 #if defined(MBEDTLS_LMS_PRIVATE)
228 typedef struct {
230  uint32_t MBEDTLS_PRIVATE(q_next_usable_key);
232  mbedtls_lmots_private_t *MBEDTLS_PRIVATE(ots_private_keys);
236  mbedtls_lmots_public_t *MBEDTLS_PRIVATE(ots_public_keys);
242  unsigned char MBEDTLS_PRIVATE(have_private_key);
244 } mbedtls_lms_private_t;
245 #endif /* defined(MBEDTLS_LMS_PRIVATE) */
246 
254 
262 
283  const unsigned char *key, size_t key_size);
284 
309  unsigned char *key, size_t key_size,
310  size_t *key_len);
311 
333  const unsigned char *msg, size_t msg_size,
334  const unsigned char *sig, size_t sig_size);
335 
336 #if defined(MBEDTLS_LMS_PRIVATE)
342 void mbedtls_lms_private_init(mbedtls_lms_private_t *ctx);
343 
350 void mbedtls_lms_private_free(mbedtls_lms_private_t *ctx);
351 
376 int mbedtls_lms_generate_private_key(mbedtls_lms_private_t *ctx,
379  int (*f_rng)(void *, unsigned char *, size_t),
380  void *p_rng, const unsigned char *seed,
381  size_t seed_size);
382 
401 int mbedtls_lms_calculate_public_key(mbedtls_lms_public_t *ctx,
402  const mbedtls_lms_private_t *priv_ctx);
403 
441 int mbedtls_lms_sign(mbedtls_lms_private_t *ctx,
442  int (*f_rng)(void *, unsigned char *, size_t),
443  void *p_rng, const unsigned char *msg,
444  unsigned int msg_size, unsigned char *sig, size_t sig_size,
445  size_t *sig_len);
446 #endif /* defined(MBEDTLS_LMS_PRIVATE) */
447 
448 #ifdef __cplusplus
449 }
450 #endif
451 
452 #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:46
#define MBEDTLS_LMOTS_P_SIG_DIGIT_COUNT_MAX
Definition: lms.h:44
mbedtls_lmots_algorithm_type_t
Definition: lms.h:95
@ MBEDTLS_LMOTS_SHA256_N32_W8
Definition: lms.h:96
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:43
mbedtls_lms_algorithm_type_t
Definition: lms.h:87
@ MBEDTLS_LMS_SHA256_M32_H10
Definition: lms.h:88
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:65
#define MBEDTLS_LMOTS_Q_LEAF_ID_LEN
Definition: lms.h:47
Build-time configuration info.
Macro wrapper for struct's members.
#define MBEDTLS_PRIVATE(member)