blob: cf92d326c987b5abe869176d8923f50b74683f4f [file] [log] [blame]
Raef Coles8ff6df52021-07-21 12:42:15 +01001/**
2 * \file lmots.h
3 *
4 * \brief This file provides an API for the LM-OTS post-quantum-safe one-time
Raef Coles2ad6e612022-08-24 13:33:35 +01005 * 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_LMOTS_SHA256_N32_W8 in order to reduce complexity.
Raef Coles8ff6df52021-07-21 12:42:15 +01008 */
9/*
10 * Copyright The Mbed TLS Contributors
Dave Rodgman16799db2023-11-02 19:47:20 +000011 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
Raef Coles8ff6df52021-07-21 12:42:15 +010012 */
13
14#ifndef MBEDTLS_LMOTS_H
15#define MBEDTLS_LMOTS_H
16
Raef Coles01c71a12022-08-31 15:55:00 +010017#include "mbedtls/build_info.h"
Raef Coles8ff6df52021-07-21 12:42:15 +010018
Raef Colesc8f96042022-08-25 13:49:54 +010019#include "psa/crypto.h"
20
Raef Colesab300f12022-09-28 17:12:41 +010021#include "mbedtls/lms.h"
22
Raef Coles8ff6df52021-07-21 12:42:15 +010023#include <stdint.h>
24#include <stddef.h>
25
Raef Coles8ff6df52021-07-21 12:42:15 +010026
Raef Colese9479a02022-09-01 16:06:35 +010027#define MBEDTLS_LMOTS_PUBLIC_KEY_LEN(type) (MBEDTLS_LMOTS_TYPE_LEN + \
28 MBEDTLS_LMOTS_I_KEY_ID_LEN + \
29 MBEDTLS_LMOTS_Q_LEAF_ID_LEN + \
30 MBEDTLS_LMOTS_N_HASH_LEN(type))
Raef Coles8ff6df52021-07-21 12:42:15 +010031
Raef Coles01c71a12022-08-31 15:55:00 +010032#define MBEDTLS_LMOTS_SIG_TYPE_OFFSET (0)
Raef Coles9c9027b2022-09-02 18:26:31 +010033#define MBEDTLS_LMOTS_SIG_C_RANDOM_OFFSET (MBEDTLS_LMOTS_SIG_TYPE_OFFSET + \
34 MBEDTLS_LMOTS_TYPE_LEN)
35#define MBEDTLS_LMOTS_SIG_SIGNATURE_OFFSET(type) (MBEDTLS_LMOTS_SIG_C_RANDOM_OFFSET + \
36 MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN(type))
Raef Coles8ff6df52021-07-21 12:42:15 +010037
38#ifdef __cplusplus
39extern "C" {
40#endif
41
Raef Coles01c71a12022-08-31 15:55:00 +010042
Raef Coles40158e12022-09-27 10:23:53 +010043#if defined(MBEDTLS_TEST_HOOKS)
Gilles Peskine449bd832023-01-11 14:50:10 +010044extern int (*mbedtls_lmots_sign_private_key_invalidated_hook)(unsigned char *);
Raef Coles40158e12022-09-27 10:23:53 +010045#endif /* defined(MBEDTLS_TEST_HOOKS) */
46
Andrzej Kurek8a045ce2022-12-23 11:00:06 -050047#if !defined(MBEDTLS_DEPRECATED_REMOVED)
Raef Colesc8f96042022-08-25 13:49:54 +010048/**
49 * \brief This function converts a \ref psa_status_t to a
50 * low-level LMS error code.
51 *
52 * \param status The psa_status_t to convert
53 *
54 * \return The corresponding LMS error code.
55 */
Andrzej Kurek8a045ce2022-12-23 11:00:06 -050056int MBEDTLS_DEPRECATED mbedtls_lms_error_from_psa(psa_status_t status);
57#endif
Raef Coles8ff6df52021-07-21 12:42:15 +010058
59/**
Raef Coles01c71a12022-08-31 15:55:00 +010060 * \brief This function initializes a public LMOTS context
Raef Coles8ff6df52021-07-21 12:42:15 +010061 *
62 * \param ctx The uninitialized LMOTS context that will then be
63 * initialized.
64 */
Gilles Peskine449bd832023-01-11 14:50:10 +010065void mbedtls_lmots_public_init(mbedtls_lmots_public_t *ctx);
Raef Coles8ff6df52021-07-21 12:42:15 +010066
67/**
Raef Coles01c71a12022-08-31 15:55:00 +010068 * \brief This function uninitializes a public LMOTS context
Raef Coles8ff6df52021-07-21 12:42:15 +010069 *
70 * \param ctx The initialized LMOTS context that will then be
71 * uninitialized.
72 */
Gilles Peskine449bd832023-01-11 14:50:10 +010073void mbedtls_lmots_public_free(mbedtls_lmots_public_t *ctx);
Raef Coles8ff6df52021-07-21 12:42:15 +010074
75/**
Raef Coles01c71a12022-08-31 15:55:00 +010076 * \brief This function imports an LMOTS public key into a
77 * LMOTS context.
Raef Coles8ff6df52021-07-21 12:42:15 +010078 *
Raef Coles01c71a12022-08-31 15:55:00 +010079 * \note Before this function is called, the context must
80 * have been initialized.
Raef Coles8ff6df52021-07-21 12:42:15 +010081 *
Raef Coles01c71a12022-08-31 15:55:00 +010082 * \note See IETF RFC8554 for details of the encoding of
83 * this public key.
84 *
85 * \param ctx The initialized LMOTS context store the key in.
86 * \param key The buffer from which the key will be read.
Raef Coles366d67d2022-09-01 17:23:12 +010087 * #MBEDTLS_LMOTS_PUBLIC_KEY_LEN bytes will be read
88 * from this.
Raef Colesc8f96042022-08-25 13:49:54 +010089 *
90 * \return \c 0 on success.
91 * \return A non-zero error code on failure.
Raef Coles8ff6df52021-07-21 12:42:15 +010092 */
Gilles Peskine449bd832023-01-11 14:50:10 +010093int mbedtls_lmots_import_public_key(mbedtls_lmots_public_t *ctx,
94 const unsigned char *key, size_t key_size);
Raef Coles8ff6df52021-07-21 12:42:15 +010095
96/**
Raef Coles370cc432022-10-07 16:07:33 +010097 * \brief This function exports an LMOTS public key from a
98 * LMOTS context that already contains a public key.
99 *
100 * \note Before this function is called, the context must
101 * have been initialized and the context must contain
102 * a public key.
103 *
104 * \note See IETF RFC8554 for details of the encoding of
105 * this public key.
106 *
107 * \param ctx The initialized LMOTS context that contains the
Tom Cosgrove1797b052022-12-04 17:19:59 +0000108 * public key.
Raef Coles370cc432022-10-07 16:07:33 +0100109 * \param key The buffer into which the key will be output. Must
110 * be at least #MBEDTLS_LMOTS_PUBLIC_KEY_LEN in size.
111 *
112 * \return \c 0 on success.
113 * \return A non-zero error code on failure.
114 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100115int mbedtls_lmots_export_public_key(const mbedtls_lmots_public_t *ctx,
116 unsigned char *key, size_t key_size,
117 size_t *key_len);
Raef Coles370cc432022-10-07 16:07:33 +0100118
119/**
Raef Coles8ff6df52021-07-21 12:42:15 +0100120 * \brief This function creates a candidate public key from
121 * an LMOTS signature. This can then be compared to
122 * the real public key to determine the validity of
123 * the signature.
124 *
125 * \note This function is exposed publicly to be used in LMS
126 * signature verification, it is expected that
127 * mbedtls_lmots_verify will be used for LMOTS
128 * signature verification.
129 *
Raef Coles01c71a12022-08-31 15:55:00 +0100130 * \param params The LMOTS parameter set, q and I values as an
131 * mbedtls_lmots_parameters_t struct.
Raef Coles8ff6df52021-07-21 12:42:15 +0100132 * \param msg The buffer from which the message will be read.
Raef Coles01c71a12022-08-31 15:55:00 +0100133 * \param msg_size The size of the message that will be read.
Raef Coles2ad6e612022-08-24 13:33:35 +0100134 * \param sig The buffer from which the signature will be read.
Raef Coles366d67d2022-09-01 17:23:12 +0100135 * #MBEDTLS_LMOTS_SIG_LEN bytes will be read from
136 * this.
Raef Coles8ff6df52021-07-21 12:42:15 +0100137 * \param out The buffer where the candidate public key will be
138 * stored. Must be at least #MBEDTLS_LMOTS_N_HASH_LEN
139 * bytes in size.
140 *
141 * \return \c 0 on success.
142 * \return A non-zero error code on failure.
143 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100144int mbedtls_lmots_calculate_public_key_candidate(const mbedtls_lmots_parameters_t *params,
145 const unsigned char *msg,
146 size_t msg_size,
147 const unsigned char *sig,
148 size_t sig_size,
149 unsigned char *out,
150 size_t out_size,
151 size_t *out_len);
Raef Coles8ff6df52021-07-21 12:42:15 +0100152
153/**
Raef Coles01c71a12022-08-31 15:55:00 +0100154 * \brief This function verifies a LMOTS signature, using a
155 * LMOTS context that contains a public key.
156 *
157 * \warning This function is **not intended for use in
158 * production**, due to as-yet unsolved problems with
Raef Coles9b0daf62022-10-10 14:25:39 +0100159 * handling stateful keys. The API for this function
160 * may change considerably in future versions.
Raef Coles01c71a12022-08-31 15:55:00 +0100161 *
162 * \note Before this function is called, the context must
163 * have been initialized and must contain a public key
Raef Coles366d67d2022-09-01 17:23:12 +0100164 * (either by import or calculation from a private
165 * key).
Raef Coles01c71a12022-08-31 15:55:00 +0100166 *
167 * \param ctx The initialized LMOTS context from which the public
168 * key will be read.
169 * \param msg The buffer from which the message will be read.
170 * \param msg_size The size of the message that will be read.
171 * \param sig The buf from which the signature will be read.
172 * #MBEDTLS_LMOTS_SIG_LEN bytes will be read from
173 * this.
174 *
175 * \return \c 0 on successful verification.
176 * \return A non-zero error code on failure.
177 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100178int mbedtls_lmots_verify(const mbedtls_lmots_public_t *ctx,
179 const unsigned char *msg,
180 size_t msg_size, const unsigned char *sig,
181 size_t sig_size);
Raef Coles01c71a12022-08-31 15:55:00 +0100182
Raef Coles5127e852022-10-07 10:35:56 +0100183#if defined(MBEDTLS_LMS_PRIVATE)
Raef Colesab4f8742022-09-01 12:24:31 +0100184
Raef Coles01c71a12022-08-31 15:55:00 +0100185/**
186 * \brief This function initializes a private LMOTS context
187 *
188 * \param ctx The uninitialized LMOTS context that will then be
189 * initialized.
190 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100191void mbedtls_lmots_private_init(mbedtls_lmots_private_t *ctx);
Raef Coles01c71a12022-08-31 15:55:00 +0100192
193/**
194 * \brief This function uninitializes a private LMOTS context
195 *
196 * \param ctx The initialized LMOTS context that will then be
197 * uninitialized.
198 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100199void mbedtls_lmots_private_free(mbedtls_lmots_private_t *ctx);
Raef Coles01c71a12022-08-31 15:55:00 +0100200
201/**
Raef Coles2ac352a2022-10-07 11:12:27 +0100202 * \brief This function calculates an LMOTS private key, and
Raef Coles01c71a12022-08-31 15:55:00 +0100203 * stores in into an LMOTS context.
204 *
205 * \warning This function is **not intended for use in
206 * production**, due to as-yet unsolved problems with
Raef Coles9b0daf62022-10-10 14:25:39 +0100207 * handling stateful keys. The API for this function
208 * may change considerably in future versions.
Raef Coles01c71a12022-08-31 15:55:00 +0100209 *
210 * \note The seed must have at least 256 bits of entropy.
211 *
212 * \param ctx The initialized LMOTS context to generate the key
213 * into.
214 * \param I_key_identifier The key identifier of the key, as a 16-byte string.
215 * \param q_leaf_identifier The leaf identifier of key. If this LMOTS key is
216 * not being used as part of an LMS key, this should
217 * be set to 0.
218 * \param seed The seed used to deterministically generate the
219 * key.
220 * \param seed_size The length of the seed.
221 *
222 * \return \c 0 on success.
223 * \return A non-zero error code on failure.
224 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100225int mbedtls_lmots_generate_private_key(mbedtls_lmots_private_t *ctx,
226 mbedtls_lmots_algorithm_type_t type,
227 const unsigned char I_key_identifier[MBEDTLS_LMOTS_I_KEY_ID_LEN],
228 uint32_t q_leaf_identifier,
229 const unsigned char *seed,
230 size_t seed_size);
Raef Coles01c71a12022-08-31 15:55:00 +0100231
232/**
233 * \brief This function generates an LMOTS public key from a
234 * LMOTS context that already contains a private key.
235 *
236 * \note Before this function is called, the context must
237 * have been initialized and the context must contain
238 * a private key.
239 *
240 * \param ctx The initialized LMOTS context to generate the key
241 * from and store it into.
242 *
243 * \return \c 0 on success.
244 * \return A non-zero error code on failure.
245 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100246int mbedtls_lmots_calculate_public_key(mbedtls_lmots_public_t *ctx,
247 const mbedtls_lmots_private_t *priv_ctx);
Raef Coles01c71a12022-08-31 15:55:00 +0100248
Raef Coles01c71a12022-08-31 15:55:00 +0100249/**
Raef Coles8ff6df52021-07-21 12:42:15 +0100250 * \brief This function creates a LMOTS signature, using a
251 * LMOTS context that contains a private key.
252 *
253 * \note Before this function is called, the context must
254 * have been initialized and must contain a private
255 * key.
256 *
257 * \note LMOTS private keys can only be used once, otherwise
258 * attackers may be able to create forged signatures.
259 * If the signing operation is successful, the private
260 * key in the context will be erased, and no further
261 * signing will be possible until another private key
262 * is loaded
263 *
264 * \param ctx The initialized LMOTS context from which the
265 * private key will be read.
266 * \param f_rng The RNG function to be used for signature
267 * generation.
268 * \param p_rng The RNG context to be passed to f_rng
269 * \param msg The buffer from which the message will be read.
Raef Coles01c71a12022-08-31 15:55:00 +0100270 * \param msg_size The size of the message that will be read.
Raef Coles8ff6df52021-07-21 12:42:15 +0100271 * \param sig The buf into which the signature will be stored.
272 * Must be at least #MBEDTLS_LMOTS_SIG_LEN in size.
273 *
274 * \return \c 0 on success.
275 * \return A non-zero error code on failure.
276 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100277int mbedtls_lmots_sign(mbedtls_lmots_private_t *ctx,
278 int (*f_rng)(void *, unsigned char *, size_t),
279 void *p_rng, const unsigned char *msg, size_t msg_size,
280 unsigned char *sig, size_t sig_size, size_t *sig_len);
Raef Coles8ff6df52021-07-21 12:42:15 +0100281
Raef Coles5127e852022-10-07 10:35:56 +0100282#endif /* defined(MBEDTLS_LMS_PRIVATE) */
Raef Coles8ff6df52021-07-21 12:42:15 +0100283
284#ifdef __cplusplus
285}
286#endif
287
288#endif /* MBEDTLS_LMOTS_H */