1 /** 2 * \file lmots.h 3 * 4 * \brief This file provides an API for the LM-OTS post-quantum-safe one-time 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_LMOTS_SHA256_N32_W8 in order to reduce complexity. 8 */ 9 /* 10 * Copyright The Mbed TLS Contributors 11 * SPDX-License-Identifier: Apache-2.0 12 * 13 * Licensed under the Apache License, Version 2.0 (the "License"); you may 14 * not use this file except in compliance with the License. 15 * You may obtain a copy of the License at 16 * 17 * http://www.apache.org/licenses/LICENSE-2.0 18 * 19 * Unless required by applicable law or agreed to in writing, software 20 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 21 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 22 * See the License for the specific language governing permissions and 23 * limitations under the License. 24 */ 25 26 #ifndef MBEDTLS_LMOTS_H 27 #define MBEDTLS_LMOTS_H 28 29 #include "mbedtls/build_info.h" 30 31 #include "psa/crypto.h" 32 33 #include "mbedtls/lms.h" 34 35 #include <stdint.h> 36 #include <stddef.h> 37 38 39 #define MBEDTLS_LMOTS_PUBLIC_KEY_LEN(type) (MBEDTLS_LMOTS_TYPE_LEN + \ 40 MBEDTLS_LMOTS_I_KEY_ID_LEN + \ 41 MBEDTLS_LMOTS_Q_LEAF_ID_LEN + \ 42 MBEDTLS_LMOTS_N_HASH_LEN(type)) 43 44 #define MBEDTLS_LMOTS_SIG_TYPE_OFFSET (0) 45 #define MBEDTLS_LMOTS_SIG_C_RANDOM_OFFSET (MBEDTLS_LMOTS_SIG_TYPE_OFFSET + \ 46 MBEDTLS_LMOTS_TYPE_LEN) 47 #define MBEDTLS_LMOTS_SIG_SIGNATURE_OFFSET(type) (MBEDTLS_LMOTS_SIG_C_RANDOM_OFFSET + \ 48 MBEDTLS_LMOTS_C_RANDOM_VALUE_LEN(type)) 49 50 #ifdef __cplusplus 51 extern "C" { 52 #endif 53 54 55 #if defined(MBEDTLS_TEST_HOOKS) 56 extern int (*mbedtls_lmots_sign_private_key_invalidated_hook)(unsigned char *); 57 #endif /* defined(MBEDTLS_TEST_HOOKS) */ 58 59 /** 60 * \brief This function converts an unsigned int into a 61 * network-byte-order (big endian) string. 62 * 63 * \param val The unsigned integer value 64 * \param len The length of the string. 65 * \param bytes The string to output into. 66 */ 67 void mbedtls_lms_unsigned_int_to_network_bytes(unsigned int val, size_t len, 68 unsigned char *bytes); 69 70 /** 71 * \brief This function converts a network-byte-order 72 * (big endian) string into an unsigned integer. 73 * 74 * \param len The length of the string. 75 * \param bytes The string. 76 * 77 * \return The corresponding LMS error code. 78 */ 79 unsigned int mbedtls_lms_network_bytes_to_unsigned_int(size_t len, 80 const unsigned char *bytes); 81 82 #if !defined(MBEDTLS_DEPRECATED_REMOVED) 83 /** 84 * \brief This function converts a \ref psa_status_t to a 85 * low-level LMS error code. 86 * 87 * \param status The psa_status_t to convert 88 * 89 * \return The corresponding LMS error code. 90 */ 91 int MBEDTLS_DEPRECATED mbedtls_lms_error_from_psa(psa_status_t status); 92 #endif 93 94 /** 95 * \brief This function initializes a public LMOTS context 96 * 97 * \param ctx The uninitialized LMOTS context that will then be 98 * initialized. 99 */ 100 void mbedtls_lmots_public_init(mbedtls_lmots_public_t *ctx); 101 102 /** 103 * \brief This function uninitializes a public LMOTS context 104 * 105 * \param ctx The initialized LMOTS context that will then be 106 * uninitialized. 107 */ 108 void mbedtls_lmots_public_free(mbedtls_lmots_public_t *ctx); 109 110 /** 111 * \brief This function imports an LMOTS public key into a 112 * LMOTS context. 113 * 114 * \note Before this function is called, the context must 115 * have been initialized. 116 * 117 * \note See IETF RFC8554 for details of the encoding of 118 * this public key. 119 * 120 * \param ctx The initialized LMOTS context store the key in. 121 * \param key The buffer from which the key will be read. 122 * #MBEDTLS_LMOTS_PUBLIC_KEY_LEN bytes will be read 123 * from this. 124 * 125 * \return \c 0 on success. 126 * \return A non-zero error code on failure. 127 */ 128 int mbedtls_lmots_import_public_key(mbedtls_lmots_public_t *ctx, 129 const unsigned char *key, size_t key_size); 130 131 /** 132 * \brief This function exports an LMOTS public key from a 133 * LMOTS context that already contains a public key. 134 * 135 * \note Before this function is called, the context must 136 * have been initialized and the context must contain 137 * a public key. 138 * 139 * \note See IETF RFC8554 for details of the encoding of 140 * this public key. 141 * 142 * \param ctx The initialized LMOTS context that contains the 143 * public key. 144 * \param key The buffer into which the key will be output. Must 145 * be at least #MBEDTLS_LMOTS_PUBLIC_KEY_LEN in size. 146 * 147 * \return \c 0 on success. 148 * \return A non-zero error code on failure. 149 */ 150 int mbedtls_lmots_export_public_key(const mbedtls_lmots_public_t *ctx, 151 unsigned char *key, size_t key_size, 152 size_t *key_len); 153 154 /** 155 * \brief This function creates a candidate public key from 156 * an LMOTS signature. This can then be compared to 157 * the real public key to determine the validity of 158 * the signature. 159 * 160 * \note This function is exposed publicly to be used in LMS 161 * signature verification, it is expected that 162 * mbedtls_lmots_verify will be used for LMOTS 163 * signature verification. 164 * 165 * \param params The LMOTS parameter set, q and I values as an 166 * mbedtls_lmots_parameters_t struct. 167 * \param msg The buffer from which the message will be read. 168 * \param msg_size The size of the message that will be read. 169 * \param sig The buffer from which the signature will be read. 170 * #MBEDTLS_LMOTS_SIG_LEN bytes will be read from 171 * this. 172 * \param out The buffer where the candidate public key will be 173 * stored. Must be at least #MBEDTLS_LMOTS_N_HASH_LEN 174 * bytes in size. 175 * 176 * \return \c 0 on success. 177 * \return A non-zero error code on failure. 178 */ 179 int mbedtls_lmots_calculate_public_key_candidate(const mbedtls_lmots_parameters_t *params, 180 const unsigned char *msg, 181 size_t msg_size, 182 const unsigned char *sig, 183 size_t sig_size, 184 unsigned char *out, 185 size_t out_size, 186 size_t *out_len); 187 188 /** 189 * \brief This function verifies a LMOTS signature, using a 190 * LMOTS context that contains a public key. 191 * 192 * \warning This function is **not intended for use in 193 * production**, due to as-yet unsolved problems with 194 * handling stateful keys. The API for this function 195 * may change considerably in future versions. 196 * 197 * \note Before this function is called, the context must 198 * have been initialized and must contain a public key 199 * (either by import or calculation from a private 200 * key). 201 * 202 * \param ctx The initialized LMOTS context from which the public 203 * key will be read. 204 * \param msg The buffer from which the message will be read. 205 * \param msg_size The size of the message that will be read. 206 * \param sig The buf from which the signature will be read. 207 * #MBEDTLS_LMOTS_SIG_LEN bytes will be read from 208 * this. 209 * 210 * \return \c 0 on successful verification. 211 * \return A non-zero error code on failure. 212 */ 213 int mbedtls_lmots_verify(const mbedtls_lmots_public_t *ctx, 214 const unsigned char *msg, 215 size_t msg_size, const unsigned char *sig, 216 size_t sig_size); 217 218 #if defined(MBEDTLS_LMS_PRIVATE) 219 220 /** 221 * \brief This function initializes a private LMOTS context 222 * 223 * \param ctx The uninitialized LMOTS context that will then be 224 * initialized. 225 */ 226 void mbedtls_lmots_private_init(mbedtls_lmots_private_t *ctx); 227 228 /** 229 * \brief This function uninitializes a private LMOTS context 230 * 231 * \param ctx The initialized LMOTS context that will then be 232 * uninitialized. 233 */ 234 void mbedtls_lmots_private_free(mbedtls_lmots_private_t *ctx); 235 236 /** 237 * \brief This function calculates an LMOTS private key, and 238 * stores in into an LMOTS context. 239 * 240 * \warning This function is **not intended for use in 241 * production**, due to as-yet unsolved problems with 242 * handling stateful keys. The API for this function 243 * may change considerably in future versions. 244 * 245 * \note The seed must have at least 256 bits of entropy. 246 * 247 * \param ctx The initialized LMOTS context to generate the key 248 * into. 249 * \param I_key_identifier The key identifier of the key, as a 16-byte string. 250 * \param q_leaf_identifier The leaf identifier of key. If this LMOTS key is 251 * not being used as part of an LMS key, this should 252 * be set to 0. 253 * \param seed The seed used to deterministically generate the 254 * key. 255 * \param seed_size The length of the seed. 256 * 257 * \return \c 0 on success. 258 * \return A non-zero error code on failure. 259 */ 260 int mbedtls_lmots_generate_private_key(mbedtls_lmots_private_t *ctx, 261 mbedtls_lmots_algorithm_type_t type, 262 const unsigned char I_key_identifier[MBEDTLS_LMOTS_I_KEY_ID_LEN], 263 uint32_t q_leaf_identifier, 264 const unsigned char *seed, 265 size_t seed_size); 266 267 /** 268 * \brief This function generates an LMOTS public key from a 269 * LMOTS context that already contains a private key. 270 * 271 * \note Before this function is called, the context must 272 * have been initialized and the context must contain 273 * a private key. 274 * 275 * \param ctx The initialized LMOTS context to generate the key 276 * from and store it into. 277 * 278 * \return \c 0 on success. 279 * \return A non-zero error code on failure. 280 */ 281 int mbedtls_lmots_calculate_public_key(mbedtls_lmots_public_t *ctx, 282 const mbedtls_lmots_private_t *priv_ctx); 283 284 /** 285 * \brief This function creates a LMOTS signature, using a 286 * LMOTS context that contains a private key. 287 * 288 * \note Before this function is called, the context must 289 * have been initialized and must contain a private 290 * key. 291 * 292 * \note LMOTS private keys can only be used once, otherwise 293 * attackers may be able to create forged signatures. 294 * If the signing operation is successful, the private 295 * key in the context will be erased, and no further 296 * signing will be possible until another private key 297 * is loaded 298 * 299 * \param ctx The initialized LMOTS context from which the 300 * private key will be read. 301 * \param f_rng The RNG function to be used for signature 302 * generation. 303 * \param p_rng The RNG context to be passed to f_rng 304 * \param msg The buffer from which the message will be read. 305 * \param msg_size The size of the message that will be read. 306 * \param sig The buf into which the signature will be stored. 307 * Must be at least #MBEDTLS_LMOTS_SIG_LEN in size. 308 * 309 * \return \c 0 on success. 310 * \return A non-zero error code on failure. 311 */ 312 int mbedtls_lmots_sign(mbedtls_lmots_private_t *ctx, 313 int (*f_rng)(void *, unsigned char *, size_t), 314 void *p_rng, const unsigned char *msg, size_t msg_size, 315 unsigned char *sig, size_t sig_size, size_t *sig_len); 316 317 #endif /* defined(MBEDTLS_LMS_PRIVATE) */ 318 319 #ifdef __cplusplus 320 } 321 #endif 322 323 #endif /* MBEDTLS_LMOTS_H */ 324