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 /** 83 * \brief This function converts a \ref psa_status_t to a 84 * low-level LMS error code. 85 * 86 * \param status The psa_status_t to convert 87 * 88 * \return The corresponding LMS error code. 89 */ 90 int mbedtls_lms_error_from_psa( psa_status_t status ); 91 92 93 /** 94 * \brief This function initializes a public LMOTS context 95 * 96 * \param ctx The uninitialized LMOTS context that will then be 97 * initialized. 98 */ 99 void mbedtls_lmots_public_init( mbedtls_lmots_public_t *ctx ); 100 101 /** 102 * \brief This function uninitializes a public LMOTS context 103 * 104 * \param ctx The initialized LMOTS context that will then be 105 * uninitialized. 106 */ 107 void mbedtls_lmots_public_free( mbedtls_lmots_public_t *ctx ); 108 109 /** 110 * \brief This function imports an LMOTS public key into a 111 * LMOTS context. 112 * 113 * \note Before this function is called, the context must 114 * have been initialized. 115 * 116 * \note See IETF RFC8554 for details of the encoding of 117 * this public key. 118 * 119 * \param ctx The initialized LMOTS context store the key in. 120 * \param key The buffer from which the key will be read. 121 * #MBEDTLS_LMOTS_PUBLIC_KEY_LEN bytes will be read 122 * from this. 123 * 124 * \return \c 0 on success. 125 * \return A non-zero error code on failure. 126 */ 127 int mbedtls_lmots_import_public_key( mbedtls_lmots_public_t *ctx, 128 const unsigned char *key, size_t key_size ); 129 130 /** 131 * \brief This function exports an LMOTS public key from a 132 * LMOTS context that already contains a public key. 133 * 134 * \note Before this function is called, the context must 135 * have been initialized and the context must contain 136 * a public key. 137 * 138 * \note See IETF RFC8554 for details of the encoding of 139 * this public key. 140 * 141 * \param ctx The initialized LMOTS context that contains the 142 * public key. 143 * \param key The buffer into which the key will be output. Must 144 * be at least #MBEDTLS_LMOTS_PUBLIC_KEY_LEN in size. 145 * 146 * \return \c 0 on success. 147 * \return A non-zero error code on failure. 148 */ 149 int mbedtls_lmots_export_public_key( const mbedtls_lmots_public_t *ctx, 150 unsigned char *key, size_t key_size, 151 size_t *key_len ); 152 153 /** 154 * \brief This function creates a candidate public key from 155 * an LMOTS signature. This can then be compared to 156 * the real public key to determine the validity of 157 * the signature. 158 * 159 * \note This function is exposed publicly to be used in LMS 160 * signature verification, it is expected that 161 * mbedtls_lmots_verify will be used for LMOTS 162 * signature verification. 163 * 164 * \param params The LMOTS parameter set, q and I values as an 165 * mbedtls_lmots_parameters_t struct. 166 * \param msg The buffer from which the message will be read. 167 * \param msg_size The size of the message that will be read. 168 * \param sig The buffer from which the signature will be read. 169 * #MBEDTLS_LMOTS_SIG_LEN bytes will be read from 170 * this. 171 * \param out The buffer where the candidate public key will be 172 * stored. Must be at least #MBEDTLS_LMOTS_N_HASH_LEN 173 * bytes in size. 174 * 175 * \return \c 0 on success. 176 * \return A non-zero error code on failure. 177 */ 178 int mbedtls_lmots_calculate_public_key_candidate( const mbedtls_lmots_parameters_t *params, 179 const unsigned char *msg, 180 size_t msg_size, 181 const unsigned char *sig, 182 size_t sig_size, 183 unsigned char *out, 184 size_t out_size, 185 size_t *out_len ); 186 187 /** 188 * \brief This function verifies a LMOTS signature, using a 189 * LMOTS context that contains a public key. 190 * 191 * \warning This function is **not intended for use in 192 * production**, due to as-yet unsolved problems with 193 * handling stateful keys. The API for this function 194 * may change considerably in future versions. 195 * 196 * \note Before this function is called, the context must 197 * have been initialized and must contain a public key 198 * (either by import or calculation from a private 199 * key). 200 * 201 * \param ctx The initialized LMOTS context from which the public 202 * key will be read. 203 * \param msg The buffer from which the message will be read. 204 * \param msg_size The size of the message that will be read. 205 * \param sig The buf from which the signature will be read. 206 * #MBEDTLS_LMOTS_SIG_LEN bytes will be read from 207 * this. 208 * 209 * \return \c 0 on successful verification. 210 * \return A non-zero error code on failure. 211 */ 212 int mbedtls_lmots_verify( const mbedtls_lmots_public_t *ctx, 213 const unsigned char *msg, 214 size_t msg_size, const unsigned char *sig, 215 size_t sig_size ); 216 217 #if defined(MBEDTLS_LMS_PRIVATE) 218 219 /** 220 * \brief This function initializes a private LMOTS context 221 * 222 * \param ctx The uninitialized LMOTS context that will then be 223 * initialized. 224 */ 225 void mbedtls_lmots_private_init( mbedtls_lmots_private_t *ctx ); 226 227 /** 228 * \brief This function uninitializes a private LMOTS context 229 * 230 * \param ctx The initialized LMOTS context that will then be 231 * uninitialized. 232 */ 233 void mbedtls_lmots_private_free( mbedtls_lmots_private_t *ctx ); 234 235 /** 236 * \brief This function calculates an LMOTS private key, and 237 * stores in into an LMOTS context. 238 * 239 * \warning This function is **not intended for use in 240 * production**, due to as-yet unsolved problems with 241 * handling stateful keys. The API for this function 242 * may change considerably in future versions. 243 * 244 * \note The seed must have at least 256 bits of entropy. 245 * 246 * \param ctx The initialized LMOTS context to generate the key 247 * into. 248 * \param I_key_identifier The key identifier of the key, as a 16-byte string. 249 * \param q_leaf_identifier The leaf identifier of key. If this LMOTS key is 250 * not being used as part of an LMS key, this should 251 * be set to 0. 252 * \param seed The seed used to deterministically generate the 253 * key. 254 * \param seed_size The length of the seed. 255 * 256 * \return \c 0 on success. 257 * \return A non-zero error code on failure. 258 */ 259 int mbedtls_lmots_generate_private_key( mbedtls_lmots_private_t *ctx, 260 mbedtls_lmots_algorithm_type_t type, 261 const unsigned char I_key_identifier[MBEDTLS_LMOTS_I_KEY_ID_LEN], 262 uint32_t q_leaf_identifier, 263 const unsigned char *seed, 264 size_t seed_size ); 265 266 /** 267 * \brief This function generates an LMOTS public key from a 268 * LMOTS context that already contains a private key. 269 * 270 * \note Before this function is called, the context must 271 * have been initialized and the context must contain 272 * a private key. 273 * 274 * \param ctx The initialized LMOTS context to generate the key 275 * from and store it into. 276 * 277 * \return \c 0 on success. 278 * \return A non-zero error code on failure. 279 */ 280 int mbedtls_lmots_calculate_public_key( mbedtls_lmots_public_t *ctx, 281 const mbedtls_lmots_private_t *priv_ctx ); 282 283 /** 284 * \brief This function creates a LMOTS signature, using a 285 * LMOTS context that contains a private key. 286 * 287 * \note Before this function is called, the context must 288 * have been initialized and must contain a private 289 * key. 290 * 291 * \note LMOTS private keys can only be used once, otherwise 292 * attackers may be able to create forged signatures. 293 * If the signing operation is successful, the private 294 * key in the context will be erased, and no further 295 * signing will be possible until another private key 296 * is loaded 297 * 298 * \param ctx The initialized LMOTS context from which the 299 * private key will be read. 300 * \param f_rng The RNG function to be used for signature 301 * generation. 302 * \param p_rng The RNG context to be passed to f_rng 303 * \param msg The buffer from which the message will be read. 304 * \param msg_size The size of the message that will be read. 305 * \param sig The buf into which the signature will be stored. 306 * Must be at least #MBEDTLS_LMOTS_SIG_LEN in size. 307 * 308 * \return \c 0 on success. 309 * \return A non-zero error code on failure. 310 */ 311 int mbedtls_lmots_sign( mbedtls_lmots_private_t *ctx, 312 int (*f_rng)(void *, unsigned char *, size_t), 313 void *p_rng, const unsigned char *msg, size_t msg_size, 314 unsigned char *sig, size_t sig_size, size_t* sig_len ); 315 316 #endif /* defined(MBEDTLS_LMS_PRIVATE) */ 317 318 #ifdef __cplusplus 319 } 320 #endif 321 322 #endif /* MBEDTLS_LMOTS_H */ 323