luna - wolfssl/wolfcrypt/src/wc

   1/* wc_lms.c
   2 *
   3 * Copyright (C) 2006-2026 wolfSSL Inc.
   4 *
   5 * This file is part of wolfSSL.
   6 *
   7 * wolfSSL is free software; you can redistribute it and/or modify
   8 * it under the terms of the GNU General Public License as published by
   9 * the Free Software Foundation; either version 3 of the License, or
  10 * (at your option) any later version.
  11 *
  12 * wolfSSL is distributed in the hope that it will be useful,
  13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15 * GNU General Public License for more details.
  16 *
  17 * You should have received a copy of the GNU General Public License
  18 * along with this program; if not, write to the Free Software
  19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA
  20 */
  21
  22#include <wolfssl/wolfcrypt/libwolfssl_sources.h>
  23
  24#if defined(WOLFSSL_HAVE_LMS)
  25
  26#if FIPS_VERSION3_GE(2,0,0)
  27    /* set NO_WRAPPERS before headers, use direct internal f()s not wrappers */
  28    #define FIPS_NO_WRAPPERS
  29#endif
  30#include <wolfssl/wolfcrypt/wc_lms.h>
  31#include <wolfssl/wolfcrypt/hash.h>
  32
  33#ifdef NO_INLINE
  34    #include <wolfssl/wolfcrypt/misc.h>
  35#else
  36    #define WOLFSSL_MISC_INCLUDED
  37    #include <wolfcrypt/src/misc.c>
  38#endif
  39
  40#ifdef WOLF_CRYPTO_CB
  41    #include <wolfssl/wolfcrypt/cryptocb.h>
  42#endif
  43
  44
  45/* Calculate u. Appendix B. Works for w of 1, 2, 4, or 8.
  46 *
  47 * @param [in] w  Winternitz width.
  48 */
  49#define LMS_U(w, hLen)              \
  50    (8 * (hLen) / (w))
  51/* Calculate u. Appendix B. Works for w of 1, 2, 4, or 8.
  52 *
  53 * @param [in] w   Winternitz width.
  54 * @param [in] wb  Winternitz width length in bits.
  55 */
  56#define LMS_V(w, wb)                \
  57    (2 + (8 - (wb)) / (w))
  58/* Calculate ls. Appendix B. Works for w of 1, 2, 4, or 8.
  59 *
  60 * @param [in] w   Winternitz width.
  61 * @param [in] wb  Winternitz width length in bits.
  62 */
  63#define LMS_LS(w, wb)               \
  64    (16 - LMS_V(w, wb) * (w))
  65/* Calculate p. Appendix B. Works for w of 1, 2, 4, or 8.
  66 *
  67 * @param [in] w   Winternitz width.
  68 * @param [in] wb  Winternitz width length in bits.
  69 */
  70#define LMS_P(w, wb, hLen)          \
  71    (LMS_U(w, hLen) + LMS_V(w, wb))
  72/* Calculate signature length.
  73 *
  74 * @param [in] l  Number of levels.
  75 * @param [in] h  Height of the trees.
  76 * @param [in] p  Number of n-byte string elements in signature for a tree.
  77 */
  78#define LMS_PARAMS_SIG_LEN(l, h, p, hLen)               \
  79    (4 + (l) * (4 + 4 + 4 + (hLen) * (1 + (p) + (h))) + \
  80     ((l) - 1) * LMS_PUBKEY_LEN(hLen))
  81
  82#ifndef WOLFSSL_WC_LMS_SMALL
  83    /* Root levels and leaf cache bits. */
  84    #define LMS_PARAMS_CACHE(h)                             \
  85        (((h) < LMS_ROOT_LEVELS) ? (h) : LMS_ROOT_LEVELS),  \
  86        (((h) < LMS_CACHE_BITS ) ? (h) : LMS_CACHE_BITS )
  87#else
  88    /* Root levels and leaf cache bits aren't in structure. */
  89    #define LMS_PARAMS_CACHE(h) /* null expansion */
  90#endif
  91
  92/* Define parameters entry for LMS.
  93 *
  94 * @param [in] l   Number of levels.
  95 * @param [in] h   Height of the trees.
  96 * @param [in] w   Winternitz width.
  97 * @param [in] wb  Winternitz width length in bits.
  98 * @param [in] t   LMS type.
  99 * @param [in] t2  LM-OTS type.
 100 */
 101#define LMS_PARAMS(l, h, w, wb, t, t2, hLen)                        \
 102    { l, h, w, LMS_LS(w, wb), LMS_P(w, wb, hLen), t, t2,            \
 103      (hLen), LMS_PARAMS_SIG_LEN(l, h, LMS_P(w, wb, hLen), hLen),   \
 104      LMS_PARAMS_CACHE(h) }
 105
 106
 107/* Initialize the working state for LMS operations.
 108 *
 109 * @param [in, out] state   LMS state.
 110 * @param [in]      params  LMS parameters.
 111 */
 112static int wc_lmskey_state_init(LmsState* state, const LmsParams* params)
 113{
 114    int ret;
 115
 116    /* Zero out every field. */
 117    XMEMSET(state, 0, sizeof(LmsState));
 118
 119    /* Keep a reference to the parameters for use in operations. */
 120    state->params = params;
 121
 122#ifdef WOLFSSL_LMS_SHAKE256
 123    if (LMS_IS_SHAKE(params->lmOtsType)) {
 124        ret = wc_InitShake256(LMS_STATE_SHAKE(state), NULL, INVALID_DEVID);
 125        if (ret == 0) {
 126            ret = wc_InitShake256(LMS_STATE_SHAKE_K(state), NULL, INVALID_DEVID);
 127            if (ret != 0) {
 128                wc_Shake256_Free(LMS_STATE_SHAKE(state));
 129            }
 130        }
 131        return ret;
 132    }
 133#endif
 134
 135    /* Initialize the two hash algorithms. */
 136    ret = wc_InitSha256(LMS_STATE_HASH(state));
 137    if (ret == 0) {
 138        ret = wc_InitSha256(LMS_STATE_HASH_K(state));
 139        if (ret != 0) {
 140            wc_Sha256Free(LMS_STATE_HASH(state));
 141        }
 142    }
 143
 144    return ret;
 145}
 146
 147/* Free the working state for LMS operations.
 148 *
 149 * @param [in] state  LMS state.
 150 */
 151static void wc_lmskey_state_free(LmsState* state)
 152{
 153#ifdef WOLFSSL_LMS_SHAKE256
 154    if (LMS_IS_SHAKE(state->params->lmOtsType)) {
 155        wc_Shake256_Free(LMS_STATE_SHAKE_K(state));
 156        wc_Shake256_Free(LMS_STATE_SHAKE(state));
 157        return;
 158    }
 159#endif
 160    wc_Sha256Free(LMS_STATE_HASH_K(state));
 161    wc_Sha256Free(LMS_STATE_HASH(state));
 162}
 163
 164/* Supported LMS parameters. */
 165static const wc_LmsParamsMap wc_lms_map[] = {
 166#ifndef WOLFSSL_NO_LMS_SHA256_256
 167#if LMS_MAX_HEIGHT >= 15
 168    { WC_LMS_PARM_L1_H15_W2, "LMS/HSS L1_H15_W2",
 169      LMS_PARAMS(1, 15, 2, 1, LMS_SHA256_M32_H15, LMOTS_SHA256_N32_W2,
 170                 WC_SHA256_DIGEST_SIZE) },
 171    { WC_LMS_PARM_L1_H15_W4, "LMS/HSS L1_H15_W4",
 172      LMS_PARAMS(1, 15, 4, 2, LMS_SHA256_M32_H15, LMOTS_SHA256_N32_W4,
 173                 WC_SHA256_DIGEST_SIZE) },
 174#endif
 175#if LMS_MAX_LEVELS >= 2
 176#if LMS_MAX_HEIGHT >= 10
 177    { WC_LMS_PARM_L2_H10_W2, "LMS/HSS L2_H10_W2",
 178      LMS_PARAMS(2, 10, 2, 1, LMS_SHA256_M32_H10, LMOTS_SHA256_N32_W2,
 179                 WC_SHA256_DIGEST_SIZE) },
 180    { WC_LMS_PARM_L2_H10_W4, "LMS/HSS L2_H10_W4",
 181      LMS_PARAMS(2, 10, 4, 2, LMS_SHA256_M32_H10, LMOTS_SHA256_N32_W4,
 182                 WC_SHA256_DIGEST_SIZE) },
 183    { WC_LMS_PARM_L2_H10_W8, "LMS/HSS L2_H10_W8",
 184      LMS_PARAMS(2, 10, 8, 3, LMS_SHA256_M32_H10, LMOTS_SHA256_N32_W8,
 185                 WC_SHA256_DIGEST_SIZE) },
 186#endif
 187#endif
 188#if LMS_MAX_LEVELS >= 3
 189    { WC_LMS_PARM_L3_H5_W2 , "LMS/HSS L3_H5_W2" ,
 190      LMS_PARAMS(3,  5, 2, 1, LMS_SHA256_M32_H5 , LMOTS_SHA256_N32_W2,
 191                 WC_SHA256_DIGEST_SIZE) },
 192    { WC_LMS_PARM_L3_H5_W4 , "LMS/HSS L3_H5_W4" ,
 193      LMS_PARAMS(3,  5, 4, 2, LMS_SHA256_M32_H5 , LMOTS_SHA256_N32_W4,
 194                 WC_SHA256_DIGEST_SIZE) },
 195    { WC_LMS_PARM_L3_H5_W8 , "LMS/HSS L3_H5_W8" ,
 196      LMS_PARAMS(3,  5, 8, 3, LMS_SHA256_M32_H5 , LMOTS_SHA256_N32_W8,
 197                 WC_SHA256_DIGEST_SIZE) },
 198#if LMS_MAX_HEIGHT >= 10
 199    { WC_LMS_PARM_L3_H10_W4, "LMS/HSS L3_H10_W4",
 200      LMS_PARAMS(3, 10, 4, 2, LMS_SHA256_M32_H10, LMOTS_SHA256_N32_W4,
 201                 WC_SHA256_DIGEST_SIZE) },
 202#endif
 203#endif
 204#if LMS_MAX_LEVELS >= 4
 205    { WC_LMS_PARM_L4_H5_W8 , "LMS/HSS L4_H5_W8" ,
 206      LMS_PARAMS(4,  5, 8, 3, LMS_SHA256_M32_H5 , LMOTS_SHA256_N32_W8,
 207                 WC_SHA256_DIGEST_SIZE) },
 208#endif
 209
 210    /* For when user sets L, H, W explicitly. */
 211    { WC_LMS_PARM_L1_H5_W1 , "LMS/HSS_L1_H5_W1" ,
 212      LMS_PARAMS(1,  5, 1, 1, LMS_SHA256_M32_H5 , LMOTS_SHA256_N32_W1,
 213                 WC_SHA256_DIGEST_SIZE) },
 214    { WC_LMS_PARM_L1_H5_W2 , "LMS/HSS_L1_H5_W2" ,
 215      LMS_PARAMS(1,  5, 2, 1, LMS_SHA256_M32_H5 , LMOTS_SHA256_N32_W2,
 216                 WC_SHA256_DIGEST_SIZE) },
 217    { WC_LMS_PARM_L1_H5_W4 , "LMS/HSS_L1_H5_W4" ,
 218      LMS_PARAMS(1,  5, 4, 2, LMS_SHA256_M32_H5 , LMOTS_SHA256_N32_W4,
 219                 WC_SHA256_DIGEST_SIZE) },
 220    { WC_LMS_PARM_L1_H5_W8 , "LMS/HSS_L1_H5_W8" ,
 221      LMS_PARAMS(1,  5, 8, 3, LMS_SHA256_M32_H5 , LMOTS_SHA256_N32_W8,
 222                 WC_SHA256_DIGEST_SIZE) },
 223#if LMS_MAX_HEIGHT >= 10
 224    { WC_LMS_PARM_L1_H10_W2 , "LMS/HSS_L1_H10_W2",
 225      LMS_PARAMS(1, 10, 2, 1, LMS_SHA256_M32_H10, LMOTS_SHA256_N32_W2,
 226                 WC_SHA256_DIGEST_SIZE) },
 227    { WC_LMS_PARM_L1_H10_W4 , "LMS/HSS_L1_H10_W4",
 228      LMS_PARAMS(1, 10, 4, 2, LMS_SHA256_M32_H10, LMOTS_SHA256_N32_W4,
 229                 WC_SHA256_DIGEST_SIZE) },
 230    { WC_LMS_PARM_L1_H10_W8 , "LMS/HSS_L1_H10_W8",
 231      LMS_PARAMS(1, 10, 8, 3, LMS_SHA256_M32_H10, LMOTS_SHA256_N32_W8,
 232                 WC_SHA256_DIGEST_SIZE) },
 233#endif
 234#if LMS_MAX_HEIGHT >= 15
 235    { WC_LMS_PARM_L1_H15_W8 , "LMS/HSS L1_H15_W8",
 236      LMS_PARAMS(1, 15, 8, 3, LMS_SHA256_M32_H15, LMOTS_SHA256_N32_W8,
 237                 WC_SHA256_DIGEST_SIZE) },
 238#endif
 239#if LMS_MAX_HEIGHT >= 20
 240    { WC_LMS_PARM_L1_H20_W2 , "LMS/HSS_L1_H20_W2",
 241      LMS_PARAMS(1, 20, 2, 1, LMS_SHA256_M32_H20, LMOTS_SHA256_N32_W2,
 242                 WC_SHA256_DIGEST_SIZE) },
 243    { WC_LMS_PARM_L1_H20_W4 , "LMS/HSS_L1_H20_W4",
 244      LMS_PARAMS(1, 20, 4, 2, LMS_SHA256_M32_H20, LMOTS_SHA256_N32_W4,
 245                 WC_SHA256_DIGEST_SIZE) },
 246    { WC_LMS_PARM_L1_H20_W8 , "LMS/HSS_L1_H20_W8",
 247      LMS_PARAMS(1, 20, 8, 3, LMS_SHA256_M32_H20, LMOTS_SHA256_N32_W8,
 248                 WC_SHA256_DIGEST_SIZE) },
 249#endif
 250#if LMS_MAX_LEVELS >= 2
 251    { WC_LMS_PARM_L2_H5_W2 , "LMS/HSS_L2_H5_W2" ,
 252      LMS_PARAMS(2,  5, 2, 1, LMS_SHA256_M32_H5 , LMOTS_SHA256_N32_W2,
 253                 WC_SHA256_DIGEST_SIZE) },
 254    { WC_LMS_PARM_L2_H5_W4 , "LMS/HSS_L2_H5_W4" ,
 255      LMS_PARAMS(2,  5, 4, 2, LMS_SHA256_M32_H5 , LMOTS_SHA256_N32_W4,
 256                 WC_SHA256_DIGEST_SIZE) },
 257    { WC_LMS_PARM_L2_H5_W8 , "LMS/HSS_L2_H5_W8" ,
 258      LMS_PARAMS(2,  5, 8, 3, LMS_SHA256_M32_H5 , LMOTS_SHA256_N32_W8,
 259                 WC_SHA256_DIGEST_SIZE) },
 260#if LMS_MAX_HEIGHT >= 15
 261    { WC_LMS_PARM_L2_H15_W2 , "LMS/HSS_L2_H15_W2",
 262      LMS_PARAMS(2, 15, 2, 1, LMS_SHA256_M32_H15, LMOTS_SHA256_N32_W2,
 263                 WC_SHA256_DIGEST_SIZE) },
 264    { WC_LMS_PARM_L2_H15_W4 , "LMS/HSS_L2_H15_W4",
 265      LMS_PARAMS(2, 15, 4, 2, LMS_SHA256_M32_H15, LMOTS_SHA256_N32_W4,
 266                 WC_SHA256_DIGEST_SIZE) },
 267    { WC_LMS_PARM_L2_H15_W8 , "LMS/HSS_L2_H15_W8",
 268      LMS_PARAMS(2, 15, 8, 3, LMS_SHA256_M32_H15, LMOTS_SHA256_N32_W8,
 269                 WC_SHA256_DIGEST_SIZE) },
 270#endif
 271#if LMS_MAX_HEIGHT >= 20
 272    { WC_LMS_PARM_L2_H20_W2 , "LMS/HSS_L2_H20_W2",
 273      LMS_PARAMS(2, 20, 2, 1, LMS_SHA256_M32_H20, LMOTS_SHA256_N32_W2,
 274                 WC_SHA256_DIGEST_SIZE) },
 275    { WC_LMS_PARM_L2_H20_W4 , "LMS/HSS_L2_H20_W4",
 276      LMS_PARAMS(2, 20, 4, 2, LMS_SHA256_M32_H20, LMOTS_SHA256_N32_W4,
 277                 WC_SHA256_DIGEST_SIZE) },
 278    { WC_LMS_PARM_L2_H20_W8 , "LMS/HSS_L2_H20_W8",
 279      LMS_PARAMS(2, 20, 8, 3, LMS_SHA256_M32_H20, LMOTS_SHA256_N32_W8,
 280                 WC_SHA256_DIGEST_SIZE) },
 281#endif
 282#endif
 283#if LMS_MAX_LEVELS >= 3
 284#if LMS_MAX_HEIGHT >= 10
 285    { WC_LMS_PARM_L3_H10_W8 , "LMS/HSS L3_H10_W8",
 286      LMS_PARAMS(3, 10, 8, 3, LMS_SHA256_M32_H10, LMOTS_SHA256_N32_W8,
 287                 WC_SHA256_DIGEST_SIZE) },
 288#endif
 289#endif
 290#if LMS_MAX_LEVELS >= 4
 291    { WC_LMS_PARM_L4_H5_W2 , "LMS/HSS L4_H5_W2" ,
 292      LMS_PARAMS(4,  5, 2, 1, LMS_SHA256_M32_H5 , LMOTS_SHA256_N32_W2,
 293                 WC_SHA256_DIGEST_SIZE) },
 294    { WC_LMS_PARM_L4_H5_W4 , "LMS/HSS L4_H5_W4" ,
 295      LMS_PARAMS(4,  5, 4, 2, LMS_SHA256_M32_H5 , LMOTS_SHA256_N32_W4,
 296                 WC_SHA256_DIGEST_SIZE) },
 297#if LMS_MAX_HEIGHT >= 10
 298    { WC_LMS_PARM_L4_H10_W4 , "LMS/HSS L4_H10_W4",
 299      LMS_PARAMS(4, 10, 4, 2, LMS_SHA256_M32_H10, LMOTS_SHA256_N32_W4,
 300                 WC_SHA256_DIGEST_SIZE) },
 301    { WC_LMS_PARM_L4_H10_W8 , "LMS/HSS L4_H10_W8",
 302      LMS_PARAMS(4, 10, 8, 3, LMS_SHA256_M32_H10, LMOTS_SHA256_N32_W8,
 303                 WC_SHA256_DIGEST_SIZE) },
 304#endif
 305#endif
 306#if LMS_MAX_HEIGHT >= 25
 307    { WC_LMS_PARM_L1_H25_W1 , "LMS/HSS_L1_H25_W1",
 308      LMS_PARAMS(1, 25, 1, 1, LMS_SHA256_M32_H25, LMOTS_SHA256_N32_W1,
 309                 WC_SHA256_DIGEST_SIZE) },
 310    { WC_LMS_PARM_L1_H25_W2 , "LMS/HSS_L1_H25_W2",
 311      LMS_PARAMS(1, 25, 2, 1, LMS_SHA256_M32_H25, LMOTS_SHA256_N32_W2,
 312                 WC_SHA256_DIGEST_SIZE) },
 313    { WC_LMS_PARM_L1_H25_W4 , "LMS/HSS_L1_H25_W4",
 314      LMS_PARAMS(1, 25, 4, 2, LMS_SHA256_M32_H25, LMOTS_SHA256_N32_W4,
 315                 WC_SHA256_DIGEST_SIZE) },
 316    { WC_LMS_PARM_L1_H25_W8 , "LMS/HSS_L1_H25_W8",
 317      LMS_PARAMS(1, 25, 8, 3, LMS_SHA256_M32_H25, LMOTS_SHA256_N32_W8,
 318                 WC_SHA256_DIGEST_SIZE) },
 319#endif
 320#if LMS_MAX_HEIGHT >= 10
 321    { WC_LMS_PARM_L1_H10_W1 , "LMS/HSS_L1_H10_W1",
 322      LMS_PARAMS(1, 10, 1, 1, LMS_SHA256_M32_H10, LMOTS_SHA256_N32_W1,
 323                 WC_SHA256_DIGEST_SIZE) },
 324#endif
 325#if LMS_MAX_HEIGHT >= 15
 326    { WC_LMS_PARM_L1_H15_W1 , "LMS/HSS_L1_H15_W1",
 327      LMS_PARAMS(1, 15, 1, 1, LMS_SHA256_M32_H15, LMOTS_SHA256_N32_W1,
 328                 WC_SHA256_DIGEST_SIZE) },
 329#endif
 330#if LMS_MAX_HEIGHT >= 20
 331    { WC_LMS_PARM_L1_H20_W1 , "LMS/HSS_L1_H20_W1",
 332      LMS_PARAMS(1, 20, 1, 1, LMS_SHA256_M32_H20, LMOTS_SHA256_N32_W1,
 333                 WC_SHA256_DIGEST_SIZE) },
 334#endif
 335#endif /* !WOLFSSL_NO_LMS_SHA256_256 */
 336
 337#ifdef WOLFSSL_LMS_SHA256_192
 338#if LMS_MAX_HEIGHT >= 15
 339    { WC_LMS_PARM_SHA256_192_L1_H15_W2, "LMS/HSS_SHA256/192 L1_H15_W2",
 340      LMS_PARAMS(1, 15, 2, 2, LMS_SHA256_M24_H15, LMOTS_SHA256_N24_W2,
 341                 WC_SHA256_192_DIGEST_SIZE) },
 342    { WC_LMS_PARM_SHA256_192_L1_H15_W4, "LMS/HSS_SHA256/192 L1_H15_W4",
 343      LMS_PARAMS(1, 15, 4, 3, LMS_SHA256_M24_H15, LMOTS_SHA256_N24_W4,
 344                 WC_SHA256_192_DIGEST_SIZE) },
 345#endif
 346#if LMS_MAX_LEVELS >= 2
 347#if LMS_MAX_HEIGHT >= 10
 348    { WC_LMS_PARM_SHA256_192_L2_H10_W2, "LMS/HSS SHA256/192 L2_H10_W2",
 349      LMS_PARAMS(2, 10, 2, 2, LMS_SHA256_M24_H10, LMOTS_SHA256_N24_W2,
 350                 WC_SHA256_192_DIGEST_SIZE) },
 351    { WC_LMS_PARM_SHA256_192_L2_H10_W4, "LMS/HSS SHA256/192 L2_H10_W4",
 352      LMS_PARAMS(2, 10, 4, 3, LMS_SHA256_M24_H10, LMOTS_SHA256_N24_W4,
 353                 WC_SHA256_192_DIGEST_SIZE) },
 354    { WC_LMS_PARM_SHA256_192_L2_H10_W8, "LMS/HSS SHA256/192 L2_H10_W8",
 355      LMS_PARAMS(2, 10, 8, 4, LMS_SHA256_M24_H10, LMOTS_SHA256_N24_W8,
 356                 WC_SHA256_192_DIGEST_SIZE) },
 357#endif
 358#endif
 359#if LMS_MAX_LEVELS >= 3
 360    { WC_LMS_PARM_SHA256_192_L3_H5_W2 , "LMS/HSS_SHA256/192 L3_H5_W2" ,
 361      LMS_PARAMS(3,  5, 2, 2, LMS_SHA256_M24_H5 , LMOTS_SHA256_N24_W2,
 362                 WC_SHA256_192_DIGEST_SIZE) },
 363    { WC_LMS_PARM_SHA256_192_L3_H5_W4 , "LMS/HSS_SHA256/192 L3_H5_W4" ,
 364      LMS_PARAMS(3,  5, 4, 3, LMS_SHA256_M24_H5 , LMOTS_SHA256_N24_W4,
 365                 WC_SHA256_192_DIGEST_SIZE) },
 366    { WC_LMS_PARM_SHA256_192_L3_H5_W8 , "LMS/HSS_SHA256/192 L3_H5_W8" ,
 367      LMS_PARAMS(3,  5, 8, 4, LMS_SHA256_M24_H5 , LMOTS_SHA256_N24_W8,
 368                 WC_SHA256_192_DIGEST_SIZE) },
 369#if LMS_MAX_HEIGHT >= 10
 370    { WC_LMS_PARM_SHA256_192_L3_H10_W4, "LMS/HSS_SHA256/192 L3_H10_W4",
 371      LMS_PARAMS(3, 10, 4, 3, LMS_SHA256_M24_H10, LMOTS_SHA256_N24_W4,
 372                 WC_SHA256_192_DIGEST_SIZE) },
 373#endif
 374#endif
 375#if LMS_MAX_LEVELS >= 4
 376    { WC_LMS_PARM_SHA256_192_L4_H5_W8 , "LMS/HSS_SHA256/192 L4_H5_W8" ,
 377      LMS_PARAMS(4,  5, 8, 4, LMS_SHA256_M24_H5 , LMOTS_SHA256_N24_W8,
 378                 WC_SHA256_192_DIGEST_SIZE) },
 379#endif
 380
 381    { WC_LMS_PARM_SHA256_192_L1_H5_W1 , "LMS/HSS_SHA256/192_L1_H5_W1" ,
 382      LMS_PARAMS(1,  5, 1, 2, LMS_SHA256_M24_H5 , LMOTS_SHA256_N24_W1,
 383                 WC_SHA256_192_DIGEST_SIZE) },
 384    { WC_LMS_PARM_SHA256_192_L1_H5_W2 , "LMS/HSS_SHA256/192_L1_H5_W2" ,
 385      LMS_PARAMS(1,  5, 2, 2, LMS_SHA256_M24_H5 , LMOTS_SHA256_N24_W2,
 386                 WC_SHA256_192_DIGEST_SIZE) },
 387    { WC_LMS_PARM_SHA256_192_L1_H5_W4 , "LMS/HSS_SHA256/192_L1_H5_W4" ,
 388      LMS_PARAMS(1,  5, 4, 3, LMS_SHA256_M24_H5 , LMOTS_SHA256_N24_W4,
 389                 WC_SHA256_192_DIGEST_SIZE) },
 390    { WC_LMS_PARM_SHA256_192_L1_H5_W8 , "LMS/HSS_SHA256/192_L1_H5_W8" ,
 391      LMS_PARAMS(1,  5, 8, 4, LMS_SHA256_M24_H5 , LMOTS_SHA256_N24_W8,
 392                 WC_SHA256_192_DIGEST_SIZE) },
 393#if LMS_MAX_HEIGHT >= 10
 394    { WC_LMS_PARM_SHA256_192_L1_H10_W2 , "LMS/HSS_SHA256/192_L1_H10_W2",
 395      LMS_PARAMS(1, 10, 2, 2, LMS_SHA256_M24_H10, LMOTS_SHA256_N24_W2,
 396                 WC_SHA256_192_DIGEST_SIZE) },
 397    { WC_LMS_PARM_SHA256_192_L1_H10_W4 , "LMS/HSS_SHA256/192_L1_H10_W4",
 398      LMS_PARAMS(1, 10, 4, 3, LMS_SHA256_M24_H10, LMOTS_SHA256_N24_W4,
 399                 WC_SHA256_192_DIGEST_SIZE) },
 400    { WC_LMS_PARM_SHA256_192_L1_H10_W8 , "LMS/HSS_SHA256/192_L1_H10_W8",
 401      LMS_PARAMS(1, 10, 8, 4, LMS_SHA256_M24_H10, LMOTS_SHA256_N24_W8,
 402                 WC_SHA256_192_DIGEST_SIZE) },
 403#endif
 404#if LMS_MAX_HEIGHT >= 20
 405    { WC_LMS_PARM_SHA256_192_L1_H20_W2 , "LMS/HSS_SHA256/192_L1_H20_W2",
 406      LMS_PARAMS(1, 20, 2, 2, LMS_SHA256_M24_H20, LMOTS_SHA256_N24_W2,
 407                 WC_SHA256_192_DIGEST_SIZE) },
 408    { WC_LMS_PARM_SHA256_192_L1_H20_W4 , "LMS/HSS_SHA256/192_L1_H20_W4",
 409      LMS_PARAMS(1, 20, 4, 3, LMS_SHA256_M24_H20, LMOTS_SHA256_N24_W4,
 410                 WC_SHA256_192_DIGEST_SIZE) },
 411    { WC_LMS_PARM_SHA256_192_L1_H20_W8 , "LMS/HSS_SHA256/192_L1_H20_W8",
 412      LMS_PARAMS(1, 20, 8, 4, LMS_SHA256_M24_H20, LMOTS_SHA256_N24_W8,
 413                 WC_SHA256_192_DIGEST_SIZE) },
 414#endif
 415#if LMS_MAX_HEIGHT >= 25
 416    { WC_LMS_PARM_SHA256_192_L1_H25_W1 , "LMS/HSS_SHA256/192_L1_H25_W1",
 417      LMS_PARAMS(1, 25, 1, 2, LMS_SHA256_M24_H25, LMOTS_SHA256_N24_W1,
 418                 WC_SHA256_192_DIGEST_SIZE) },
 419    { WC_LMS_PARM_SHA256_192_L1_H25_W2 , "LMS/HSS_SHA256/192_L1_H25_W2",
 420      LMS_PARAMS(1, 25, 2, 2, LMS_SHA256_M24_H25, LMOTS_SHA256_N24_W2,
 421                 WC_SHA256_192_DIGEST_SIZE) },
 422    { WC_LMS_PARM_SHA256_192_L1_H25_W4 , "LMS/HSS_SHA256/192_L1_H25_W4",
 423      LMS_PARAMS(1, 25, 4, 3, LMS_SHA256_M24_H25, LMOTS_SHA256_N24_W4,
 424                 WC_SHA256_192_DIGEST_SIZE) },
 425    { WC_LMS_PARM_SHA256_192_L1_H25_W8 , "LMS/HSS_SHA256/192_L1_H25_W8",
 426      LMS_PARAMS(1, 25, 8, 4, LMS_SHA256_M24_H25, LMOTS_SHA256_N24_W8,
 427                 WC_SHA256_192_DIGEST_SIZE) },
 428#endif
 429#if LMS_MAX_HEIGHT >= 10
 430    { WC_LMS_PARM_SHA256_192_L1_H10_W1 , "LMS/HSS_SHA256/192_L1_H10_W1",
 431      LMS_PARAMS(1, 10, 1, 2, LMS_SHA256_M24_H10, LMOTS_SHA256_N24_W1,
 432                 WC_SHA256_192_DIGEST_SIZE) },
 433#endif
 434#if LMS_MAX_HEIGHT >= 15
 435    { WC_LMS_PARM_SHA256_192_L1_H15_W1 , "LMS/HSS_SHA256/192_L1_H15_W1",
 436      LMS_PARAMS(1, 15, 1, 2, LMS_SHA256_M24_H15, LMOTS_SHA256_N24_W1,
 437                 WC_SHA256_192_DIGEST_SIZE) },
 438    { WC_LMS_PARM_SHA256_192_L1_H15_W8 , "LMS/HSS_SHA256/192_L1_H15_W8",
 439      LMS_PARAMS(1, 15, 8, 4, LMS_SHA256_M24_H15, LMOTS_SHA256_N24_W8,
 440                 WC_SHA256_192_DIGEST_SIZE) },
 441#endif
 442#if LMS_MAX_HEIGHT >= 20
 443    { WC_LMS_PARM_SHA256_192_L1_H20_W1 , "LMS/HSS_SHA256/192_L1_H20_W1",
 444      LMS_PARAMS(1, 20, 1, 2, LMS_SHA256_M24_H20, LMOTS_SHA256_N24_W1,
 445                 WC_SHA256_192_DIGEST_SIZE) },
 446#endif
 447#endif /* WOLFSSL_LMS_SHA256_192 */
 448
 449#ifdef WOLFSSL_LMS_SHAKE256
 450#ifndef WOLFSSL_NO_LMS_SHAKE256_256
 451    /* SHAKE256/256 L1 H5 */
 452    { WC_LMS_PARM_SHAKE_L1_H5_W1 , "LMS/HSS_SHAKE256/256_L1_H5_W1",
 453      LMS_PARAMS(1,  5, 1, 1, LMS_SHAKE_M32_H5 , LMOTS_SHAKE_N32_W1,
 454                 WC_SHA256_DIGEST_SIZE) },
 455    { WC_LMS_PARM_SHAKE_L1_H5_W2 , "LMS/HSS_SHAKE256/256_L1_H5_W2",
 456      LMS_PARAMS(1,  5, 2, 1, LMS_SHAKE_M32_H5 , LMOTS_SHAKE_N32_W2,
 457                 WC_SHA256_DIGEST_SIZE) },
 458    { WC_LMS_PARM_SHAKE_L1_H5_W4 , "LMS/HSS_SHAKE256/256_L1_H5_W4",
 459      LMS_PARAMS(1,  5, 4, 2, LMS_SHAKE_M32_H5 , LMOTS_SHAKE_N32_W4,
 460                 WC_SHA256_DIGEST_SIZE) },
 461    { WC_LMS_PARM_SHAKE_L1_H5_W8 , "LMS/HSS_SHAKE256/256_L1_H5_W8",
 462      LMS_PARAMS(1,  5, 8, 3, LMS_SHAKE_M32_H5 , LMOTS_SHAKE_N32_W8,
 463                 WC_SHA256_DIGEST_SIZE) },
 464#if LMS_MAX_HEIGHT >= 10
 465    /* SHAKE256/256 L1 H10 */
 466    { WC_LMS_PARM_SHAKE_L1_H10_W1 , "LMS/HSS_SHAKE256/256_L1_H10_W1",
 467      LMS_PARAMS(1, 10, 1, 1, LMS_SHAKE_M32_H10, LMOTS_SHAKE_N32_W1,
 468                 WC_SHA256_DIGEST_SIZE) },
 469    { WC_LMS_PARM_SHAKE_L1_H10_W2 , "LMS/HSS_SHAKE256/256_L1_H10_W2",
 470      LMS_PARAMS(1, 10, 2, 1, LMS_SHAKE_M32_H10, LMOTS_SHAKE_N32_W2,
 471                 WC_SHA256_DIGEST_SIZE) },
 472    { WC_LMS_PARM_SHAKE_L1_H10_W4 , "LMS/HSS_SHAKE256/256_L1_H10_W4",
 473      LMS_PARAMS(1, 10, 4, 2, LMS_SHAKE_M32_H10, LMOTS_SHAKE_N32_W4,
 474                 WC_SHA256_DIGEST_SIZE) },
 475    { WC_LMS_PARM_SHAKE_L1_H10_W8 , "LMS/HSS_SHAKE256/256_L1_H10_W8",
 476      LMS_PARAMS(1, 10, 8, 3, LMS_SHAKE_M32_H10, LMOTS_SHAKE_N32_W8,
 477                 WC_SHA256_DIGEST_SIZE) },
 478#endif
 479#if LMS_MAX_HEIGHT >= 15
 480    /* SHAKE256/256 L1 H15 */
 481    { WC_LMS_PARM_SHAKE_L1_H15_W1 , "LMS/HSS_SHAKE256/256_L1_H15_W1",
 482      LMS_PARAMS(1, 15, 1, 1, LMS_SHAKE_M32_H15, LMOTS_SHAKE_N32_W1,
 483                 WC_SHA256_DIGEST_SIZE) },
 484    { WC_LMS_PARM_SHAKE_L1_H15_W2 , "LMS/HSS_SHAKE256/256_L1_H15_W2",
 485      LMS_PARAMS(1, 15, 2, 1, LMS_SHAKE_M32_H15, LMOTS_SHAKE_N32_W2,
 486                 WC_SHA256_DIGEST_SIZE) },
 487    { WC_LMS_PARM_SHAKE_L1_H15_W4 , "LMS/HSS_SHAKE256/256_L1_H15_W4",
 488      LMS_PARAMS(1, 15, 4, 2, LMS_SHAKE_M32_H15, LMOTS_SHAKE_N32_W4,
 489                 WC_SHA256_DIGEST_SIZE) },
 490    { WC_LMS_PARM_SHAKE_L1_H15_W8 , "LMS/HSS_SHAKE256/256_L1_H15_W8",
 491      LMS_PARAMS(1, 15, 8, 3, LMS_SHAKE_M32_H15, LMOTS_SHAKE_N32_W8,
 492                 WC_SHA256_DIGEST_SIZE) },
 493#endif
 494#if LMS_MAX_HEIGHT >= 20
 495    /* SHAKE256/256 L1 H20 */
 496    { WC_LMS_PARM_SHAKE_L1_H20_W1 , "LMS/HSS_SHAKE256/256_L1_H20_W1",
 497      LMS_PARAMS(1, 20, 1, 1, LMS_SHAKE_M32_H20, LMOTS_SHAKE_N32_W1,
 498                 WC_SHA256_DIGEST_SIZE) },
 499    { WC_LMS_PARM_SHAKE_L1_H20_W2 , "LMS/HSS_SHAKE256/256_L1_H20_W2",
 500      LMS_PARAMS(1, 20, 2, 1, LMS_SHAKE_M32_H20, LMOTS_SHAKE_N32_W2,
 501                 WC_SHA256_DIGEST_SIZE) },
 502    { WC_LMS_PARM_SHAKE_L1_H20_W4 , "LMS/HSS_SHAKE256/256_L1_H20_W4",
 503      LMS_PARAMS(1, 20, 4, 2, LMS_SHAKE_M32_H20, LMOTS_SHAKE_N32_W4,
 504                 WC_SHA256_DIGEST_SIZE) },
 505    { WC_LMS_PARM_SHAKE_L1_H20_W8 , "LMS/HSS_SHAKE256/256_L1_H20_W8",
 506      LMS_PARAMS(1, 20, 8, 3, LMS_SHAKE_M32_H20, LMOTS_SHAKE_N32_W8,
 507                 WC_SHA256_DIGEST_SIZE) },
 508#endif
 509#if LMS_MAX_HEIGHT >= 25
 510    /* SHAKE256/256 L1 H25 */
 511    { WC_LMS_PARM_SHAKE_L1_H25_W1 , "LMS/HSS_SHAKE256/256_L1_H25_W1",
 512      LMS_PARAMS(1, 25, 1, 1, LMS_SHAKE_M32_H25, LMOTS_SHAKE_N32_W1,
 513                 WC_SHA256_DIGEST_SIZE) },
 514    { WC_LMS_PARM_SHAKE_L1_H25_W2 , "LMS/HSS_SHAKE256/256_L1_H25_W2",
 515      LMS_PARAMS(1, 25, 2, 1, LMS_SHAKE_M32_H25, LMOTS_SHAKE_N32_W2,
 516                 WC_SHA256_DIGEST_SIZE) },
 517    { WC_LMS_PARM_SHAKE_L1_H25_W4 , "LMS/HSS_SHAKE256/256_L1_H25_W4",
 518      LMS_PARAMS(1, 25, 4, 2, LMS_SHAKE_M32_H25, LMOTS_SHAKE_N32_W4,
 519                 WC_SHA256_DIGEST_SIZE) },
 520    { WC_LMS_PARM_SHAKE_L1_H25_W8 , "LMS/HSS_SHAKE256/256_L1_H25_W8",
 521      LMS_PARAMS(1, 25, 8, 3, LMS_SHAKE_M32_H25, LMOTS_SHAKE_N32_W8,
 522                 WC_SHA256_DIGEST_SIZE) },
 523#endif
 524#endif /* !WOLFSSL_NO_LMS_SHAKE256_256 */
 525
 526    /* SHAKE256/192 L1 H5 */
 527    { WC_LMS_PARM_SHAKE192_L1_H5_W1 , "LMS/HSS_SHAKE256/192_L1_H5_W1",
 528      LMS_PARAMS(1,  5, 1, 2, LMS_SHAKE_M24_H5 , LMOTS_SHAKE_N24_W1,
 529                 WC_SHA256_192_DIGEST_SIZE) },
 530    { WC_LMS_PARM_SHAKE192_L1_H5_W2 , "LMS/HSS_SHAKE256/192_L1_H5_W2",
 531      LMS_PARAMS(1,  5, 2, 2, LMS_SHAKE_M24_H5 , LMOTS_SHAKE_N24_W2,
 532                 WC_SHA256_192_DIGEST_SIZE) },
 533    { WC_LMS_PARM_SHAKE192_L1_H5_W4 , "LMS/HSS_SHAKE256/192_L1_H5_W4",
 534      LMS_PARAMS(1,  5, 4, 3, LMS_SHAKE_M24_H5 , LMOTS_SHAKE_N24_W4,
 535                 WC_SHA256_192_DIGEST_SIZE) },
 536    { WC_LMS_PARM_SHAKE192_L1_H5_W8 , "LMS/HSS_SHAKE256/192_L1_H5_W8",
 537      LMS_PARAMS(1,  5, 8, 4, LMS_SHAKE_M24_H5 , LMOTS_SHAKE_N24_W8,
 538                 WC_SHA256_192_DIGEST_SIZE) },
 539#if LMS_MAX_HEIGHT >= 10
 540    /* SHAKE256/192 L1 H10 */
 541    { WC_LMS_PARM_SHAKE192_L1_H10_W1 , "LMS/HSS_SHAKE256/192_L1_H10_W1",
 542      LMS_PARAMS(1, 10, 1, 2, LMS_SHAKE_M24_H10, LMOTS_SHAKE_N24_W1,
 543                 WC_SHA256_192_DIGEST_SIZE) },
 544    { WC_LMS_PARM_SHAKE192_L1_H10_W2 , "LMS/HSS_SHAKE256/192_L1_H10_W2",
 545      LMS_PARAMS(1, 10, 2, 2, LMS_SHAKE_M24_H10, LMOTS_SHAKE_N24_W2,
 546                 WC_SHA256_192_DIGEST_SIZE) },
 547    { WC_LMS_PARM_SHAKE192_L1_H10_W4 , "LMS/HSS_SHAKE256/192_L1_H10_W4",
 548      LMS_PARAMS(1, 10, 4, 3, LMS_SHAKE_M24_H10, LMOTS_SHAKE_N24_W4,
 549                 WC_SHA256_192_DIGEST_SIZE) },
 550    { WC_LMS_PARM_SHAKE192_L1_H10_W8 , "LMS/HSS_SHAKE256/192_L1_H10_W8",
 551      LMS_PARAMS(1, 10, 8, 4, LMS_SHAKE_M24_H10, LMOTS_SHAKE_N24_W8,
 552                 WC_SHA256_192_DIGEST_SIZE) },
 553#endif
 554#if LMS_MAX_HEIGHT >= 15
 555    /* SHAKE256/192 L1 H15 */
 556    { WC_LMS_PARM_SHAKE192_L1_H15_W1 , "LMS/HSS_SHAKE256/192_L1_H15_W1",
 557      LMS_PARAMS(1, 15, 1, 2, LMS_SHAKE_M24_H15, LMOTS_SHAKE_N24_W1,
 558                 WC_SHA256_192_DIGEST_SIZE) },
 559    { WC_LMS_PARM_SHAKE192_L1_H15_W2 , "LMS/HSS_SHAKE256/192_L1_H15_W2",
 560      LMS_PARAMS(1, 15, 2, 2, LMS_SHAKE_M24_H15, LMOTS_SHAKE_N24_W2,
 561                 WC_SHA256_192_DIGEST_SIZE) },
 562    { WC_LMS_PARM_SHAKE192_L1_H15_W4 , "LMS/HSS_SHAKE256/192_L1_H15_W4",
 563      LMS_PARAMS(1, 15, 4, 3, LMS_SHAKE_M24_H15, LMOTS_SHAKE_N24_W4,
 564                 WC_SHA256_192_DIGEST_SIZE) },
 565    { WC_LMS_PARM_SHAKE192_L1_H15_W8 , "LMS/HSS_SHAKE256/192_L1_H15_W8",
 566      LMS_PARAMS(1, 15, 8, 4, LMS_SHAKE_M24_H15, LMOTS_SHAKE_N24_W8,
 567                 WC_SHA256_192_DIGEST_SIZE) },
 568#endif
 569#if LMS_MAX_HEIGHT >= 20
 570    /* SHAKE256/192 L1 H20 */
 571    { WC_LMS_PARM_SHAKE192_L1_H20_W1 , "LMS/HSS_SHAKE256/192_L1_H20_W1",
 572      LMS_PARAMS(1, 20, 1, 2, LMS_SHAKE_M24_H20, LMOTS_SHAKE_N24_W1,
 573                 WC_SHA256_192_DIGEST_SIZE) },
 574    { WC_LMS_PARM_SHAKE192_L1_H20_W2 , "LMS/HSS_SHAKE256/192_L1_H20_W2",
 575      LMS_PARAMS(1, 20, 2, 2, LMS_SHAKE_M24_H20, LMOTS_SHAKE_N24_W2,
 576                 WC_SHA256_192_DIGEST_SIZE) },
 577    { WC_LMS_PARM_SHAKE192_L1_H20_W4 , "LMS/HSS_SHAKE256/192_L1_H20_W4",
 578      LMS_PARAMS(1, 20, 4, 3, LMS_SHAKE_M24_H20, LMOTS_SHAKE_N24_W4,
 579                 WC_SHA256_192_DIGEST_SIZE) },
 580    { WC_LMS_PARM_SHAKE192_L1_H20_W8 , "LMS/HSS_SHAKE256/192_L1_H20_W8",
 581      LMS_PARAMS(1, 20, 8, 4, LMS_SHAKE_M24_H20, LMOTS_SHAKE_N24_W8,
 582                 WC_SHA256_192_DIGEST_SIZE) },
 583#endif
 584#if LMS_MAX_HEIGHT >= 25
 585    /* SHAKE256/192 L1 H25 */
 586    { WC_LMS_PARM_SHAKE192_L1_H25_W1 , "LMS/HSS_SHAKE256/192_L1_H25_W1",
 587      LMS_PARAMS(1, 25, 1, 2, LMS_SHAKE_M24_H25, LMOTS_SHAKE_N24_W1,
 588                 WC_SHA256_192_DIGEST_SIZE) },
 589    { WC_LMS_PARM_SHAKE192_L1_H25_W2 , "LMS/HSS_SHAKE256/192_L1_H25_W2",
 590      LMS_PARAMS(1, 25, 2, 2, LMS_SHAKE_M24_H25, LMOTS_SHAKE_N24_W2,
 591                 WC_SHA256_192_DIGEST_SIZE) },
 592    { WC_LMS_PARM_SHAKE192_L1_H25_W4 , "LMS/HSS_SHAKE256/192_L1_H25_W4",
 593      LMS_PARAMS(1, 25, 4, 3, LMS_SHAKE_M24_H25, LMOTS_SHAKE_N24_W4,
 594                 WC_SHA256_192_DIGEST_SIZE) },
 595    { WC_LMS_PARM_SHAKE192_L1_H25_W8 , "LMS/HSS_SHAKE256/192_L1_H25_W8",
 596      LMS_PARAMS(1, 25, 8, 4, LMS_SHAKE_M24_H25, LMOTS_SHAKE_N24_W8,
 597                 WC_SHA256_192_DIGEST_SIZE) },
 598#endif
 599#endif /* WOLFSSL_LMS_SHAKE256 */
 600};
 601/* Number of parameter sets supported. */
 602#define WC_LMS_MAP_LEN      ((int)(sizeof(wc_lms_map) / sizeof(*wc_lms_map)))
 603
 604/* Initialize LMS key.
 605 *
 606 * Call this before setting the params of an LMS key.
 607 * Must call wc_LmsKey_Free before calling this function again.
 608 *
 609 * @param [out] key    LMS key to initialize.
 610 * @param [in]  heap   Heap hint.
 611 * @param [in]  devId  Device identifier.
 612 *                     Use INVALID_DEVID when not using a device.
 613 * @return  0 on success.
 614 * @return  BAD_FUNC_ARG when key is NULL.
 615 */
 616int wc_LmsKey_Init(LmsKey* key, void* heap, int devId)
 617{
 618    int ret = 0;
 619
 620    (void)heap;
 621    (void)devId;
 622
 623    /* Validate parameters. */
 624    if (key == NULL) {
 625        ret = BAD_FUNC_ARG;
 626    }
 627    if (ret == 0) {
 628        /* Clear the key data. */
 629        XMEMSET(key, 0, sizeof(LmsKey));
 630
 631    #ifndef WOLFSSL_LMS_VERIFY_ONLY
 632        /* Initialize other fields. */
 633        key->heap = heap;
 634    #endif
 635    #ifdef WOLF_CRYPTO_CB
 636        key->devId = devId;
 637    #endif
 638        /* Start in initialized state. */
 639        key->state = WC_LMS_STATE_INITED;
 640    }
 641
 642    return ret;
 643}
 644
 645#ifdef WOLF_PRIVATE_KEY_ID
 646/* Initialize an LmsKey and bind it to a device-side key identifier.
 647 *
 648 * @param [in,out] key    LmsKey to initialize.
 649 * @param [in]     id     Identifier bytes (may be NULL when len is 0).
 650 * @param [in]     len    Length of id; must be in [0, LMS_MAX_ID_LEN].
 651 * @param [in]     heap   Heap hint forwarded to wc_LmsKey_Init.
 652 * @param [in]     devId  Device identifier.
 653 *
 654 * @return  0 on success.
 655 * @return  BAD_FUNC_ARG when key is NULL, or id is NULL and len is not 0.
 656 * @return  BUFFER_E when len is negative or exceeds LMS_MAX_ID_LEN.
 657 */
 658int wc_LmsKey_InitId(LmsKey* key, const unsigned char* id, int len, void* heap,
 659    int devId)
 660{
 661    int ret = 0;
 662
 663    if ((key == NULL) || ((id == NULL) && (len != 0))) {
 664        ret = BAD_FUNC_ARG;
 665    }
 666    if ((ret == 0) && ((len < 0) || (len > LMS_MAX_ID_LEN))) {
 667        ret = BUFFER_E;
 668    }
 669    if (ret == 0) {
 670        ret = wc_LmsKey_Init(key, heap, devId);
 671    }
 672    if ((ret == 0) && (id != NULL) && (len != 0)) {
 673        XMEMCPY(key->id, id, (size_t)len);
 674        key->idLen = len;
 675    }
 676
 677    return ret;
 678}
 679
 680/* Initialize an LmsKey and bind it to a device-side key label.
 681 *
 682 * @param [in,out] key    LmsKey to initialize.
 683 * @param [in]     label  NUL-terminated label string (must be non-empty).
 684 * @param [in]     heap   Heap hint forwarded to wc_LmsKey_Init.
 685 * @param [in]     devId  Device identifier.
 686 *
 687 * @return  0 on success.
 688 * @return  BAD_FUNC_ARG when key or label is NULL.
 689 * @return  BUFFER_E when label is empty or longer than LMS_MAX_LABEL_LEN.
 690 */
 691int wc_LmsKey_InitLabel(LmsKey* key, const char* label, void* heap, int devId)
 692{
 693    int ret = 0;
 694    size_t labelLen = 0;
 695
 696    if ((key == NULL) || (label == NULL)) {
 697        ret = BAD_FUNC_ARG;
 698    }
 699    if (ret == 0) {
 700        labelLen = XSTRLEN(label);
 701        if ((labelLen == 0) || (labelLen > LMS_MAX_LABEL_LEN)) {
 702            ret = BUFFER_E;
 703        }
 704    }
 705    if (ret == 0) {
 706        ret = wc_LmsKey_Init(key, heap, devId);
 707    }
 708    if (ret == 0) {
 709        XMEMCPY(key->label, label, labelLen);
 710        key->labelLen = (int)labelLen;
 711    }
 712
 713    return ret;
 714}
 715#endif /* WOLF_PRIVATE_KEY_ID */
 716
 717/* Get the string representation of the LMS parameter set.
 718 *
 719 * @param [in] lmsParm  LMS parameter set identifier.
 720 * @return  String representing LMS parameter set on success.
 721 * @return  NULL when parameter set not supported.
 722 */
 723const char* wc_LmsKey_ParmToStr(enum wc_LmsParm lmsParm)
 724{
 725    const char* str = NULL;
 726    int i;
 727
 728    /* Search through table for matching numeric identifier. */
 729    for (i = 0; i < WC_LMS_MAP_LEN; i++) {
 730        if (lmsParm == wc_lms_map[i].id) {
 731            /* Get string corresponding to numeric identifier. */
 732            str = wc_lms_map[i].str;
 733            break;
 734        }
 735    }
 736
 737    /* Return the string or NULL. */
 738    return str;
 739}
 740
 741/* Set the wc_LmsParm of an LMS key.
 742 *
 743 * Use this if you wish to set a key with a predefined parameter set,
 744 * such as WC_LMS_PARM_L2_H10_W8.
 745 *
 746 * Key must be inited before calling this.
 747 *
 748 * @param [in, out] key      LMS key to set parameters on.
 749 * @param [in]      lmsParm  Identifier of parameters.
 750 * @return  0 on success.
 751 * @return  BAD_FUNC_ARG when key is NULL.
 752 * @return  BAD_FUNC_ARG when parameters not supported.
 753 */
 754int wc_LmsKey_SetLmsParm(LmsKey* key, enum wc_LmsParm lmsParm)
 755{
 756    int ret = 0;
 757
 758    /* Validate parameters. */
 759    if (key == NULL) {
 760        ret = BAD_FUNC_ARG;
 761    }
 762
 763    /* Check state is valid. */
 764    if ((ret == 0) && (key->state != WC_LMS_STATE_INITED)) {
 765        WOLFSSL_MSG("error: LmsKey needs init");
 766        ret = BAD_STATE_E;
 767    }
 768
 769    if (ret == 0) {
 770        int i;
 771
 772        ret = BAD_FUNC_ARG;
 773        /* Search through table for matching numeric identifier. */
 774        for (i = 0; i < WC_LMS_MAP_LEN; i++) {
 775            if (lmsParm == wc_lms_map[i].id) {
 776                /* Set the parameters into the key. */
 777                key->params = &wc_lms_map[i].params;
 778                ret = 0;
 779                break;
 780            }
 781        }
 782    }
 783
 784    if (ret == 0) {
 785        /* Move the state to params set.
 786         * Key is ready for MakeKey or Reload. */
 787        key->state = WC_LMS_STATE_PARMSET;
 788    }
 789
 790    return ret;
 791}
 792
 793/* Set the parameters of an LMS key.
 794 *
 795 * Key must be inited before calling this.
 796 *
 797 * @param [in, out] key         LMS key to set parameters on.
 798 * @param [in]      levels      Number of tree levels.
 799 * @param [in]      height      Height of each tree.
 800 * @param [in]      winternitz  Width or Winternitz coefficient.
 801 * @return  0 on success.
 802 * @return  BAD_FUNC_ARG when key is NULL.
 803 * @return  BAD_FUNC_ARG when parameters not supported.
 804 * @return  BAD_STATE_E when key state is not initialized.
 805 * */
 806int wc_LmsKey_SetParameters(LmsKey* key, int levels, int height,
 807    int winternitz)
 808{
 809    int ret = 0;
 810
 811    /* Validate parameters. */
 812    if (key == NULL) {
 813        ret = BAD_FUNC_ARG;
 814    }
 815
 816    /* Check state is valid. */
 817    if ((ret == 0) && (key->state != WC_LMS_STATE_INITED)) {
 818        WOLFSSL_MSG("error: LmsKey needs init");
 819        ret = BAD_STATE_E;
 820    }
 821
 822    if (ret == 0) {
 823        int i;
 824
 825        ret = BAD_FUNC_ARG;
 826        /* Search through table for matching levels, height and width. */
 827        for (i = 0; i < WC_LMS_MAP_LEN; i++) {
 828            if ((levels == wc_lms_map[i].params.levels) &&
 829                    (height == wc_lms_map[i].params.height) &&
 830                    (winternitz == wc_lms_map[i].params.width)) {
 831                /* Set the parameters into the key. */
 832                key->params = &wc_lms_map[i].params;
 833                ret = 0;
 834                break;
 835            }
 836        }
 837    }
 838
 839    if (ret == 0) {
 840        /* Move the state to params set.
 841         * Key is ready for MakeKey or Reload. */
 842        key->state = WC_LMS_STATE_PARMSET;
 843    }
 844
 845    return ret;
 846}
 847
 848/* Set the parameters of an LMS key including hash length.
 849 *
 850 * Key must be inited before calling this.
 851 *
 852 * @param [in, out] key         LMS key to set parameters on.
 853 * @param [in]      levels      Number of tree levels.
 854 * @param [in]      height      Height of each tree.
 855 * @param [in]      winternitz  Width or Winternitz coefficient.
 856 * @param [in]      hash        Hash algorithm to use. Valid values:
 857 *                               - LMS_SHA256
 858 *                               - LMS_SHA256_192
 859 *                               - LMS_SHAKE256
 860 *                               - LMS_SHAKE256_192
 861 * @return  0 on success.
 862 * @return  BAD_FUNC_ARG when key is NULL.
 863 * @return  BAD_FUNC_ARG when parameters not supported.
 864 * @return  BAD_STATE_E when key state is not initialized.
 865 * */
 866int wc_LmsKey_SetParameters_ex(LmsKey* key, int levels, int height,
 867    int winternitz, int hash)
 868{
 869    int ret = 0;
 870
 871    /* Validate parameters. */
 872    if (key == NULL) {
 873        ret = BAD_FUNC_ARG;
 874    }
 875
 876    /* Check state is valid. */
 877    if ((ret == 0) && (key->state != WC_LMS_STATE_INITED)) {
 878        WOLFSSL_MSG("error: LmsKey needs init");
 879        ret = BAD_STATE_E;
 880    }
 881
 882    if (ret == 0) {
 883        int i;
 884
 885        ret = BAD_FUNC_ARG;
 886        /* Search through table for matching levels, height and width. */
 887        for (i = 0; i < WC_LMS_MAP_LEN; i++) {
 888            if ((levels == wc_lms_map[i].params.levels) &&
 889                    (height == wc_lms_map[i].params.height) &&
 890                    (winternitz == wc_lms_map[i].params.width) &&
 891                    (hash == (wc_lms_map[i].params.lmsType & LMS_HASH_MASK))) {
 892                /* Set the parameters into the key. */
 893                key->params = &wc_lms_map[i].params;
 894                ret = 0;
 895                break;
 896            }
 897        }
 898    }
 899
 900    if (ret == 0) {
 901        /* Move the state to params set.
 902         * Key is ready for MakeKey or Reload. */
 903        key->state = WC_LMS_STATE_PARMSET;
 904    }
 905
 906    return ret;
 907}
 908
 909/* Get the parameters of an LMS key.
 910 *
 911 * Key must be inited and parameters set before calling this.
 912 *
 913 * @param [in]  key         LMS key.
 914 * @param [out] levels      Number of levels of trees.
 915 * @param [out] height      Height of the trees.
 916 * @param [out] winternitz  Winternitz width.
 917 * @return  0 on success.
 918 * @return  BAD_FUNC_ARG when key, key->params, levels, height or winternitz is
 919 *          NULL.
 920 */
 921int wc_LmsKey_GetParameters(const LmsKey* key, int* levels, int* height,
 922    int* winternitz)
 923{
 924    int ret = 0;
 925
 926    /* Validate parameters. */
 927    if ((key == NULL) || (levels == NULL) || (height == NULL) ||
 928            (winternitz == NULL)) {
 929        ret = BAD_FUNC_ARG;
 930    }
 931
 932    /* Validate the parameters are available. */
 933    if ((ret == 0) && (key->params == NULL)) {
 934        ret = BAD_FUNC_ARG;
 935    }
 936
 937    if (ret == 0) {
 938        /* Set the levels, height and Winternitz width from parameters. */
 939        *levels = key->params->levels;
 940        *height = key->params->height;
 941        *winternitz = key->params->width;
 942    }
 943
 944    return ret;
 945}
 946
 947/* Get the parameters of an LMS key.
 948 *
 949 * Key must be inited and parameters set before calling this.
 950 *
 951 * @param [in]  key         LMS key.
 952 * @param [out] levels      Number of levels of trees.
 953 * @param [out] height      Height of the trees.
 954 * @param [out] winternitz  Winternitz width.
 955 * @param [out] hash        Hash algorithm.
 956 * @return  0 on success.
 957 * @return  BAD_FUNC_ARG when key, key->params, levels, height, winternitz or
 958 *          hash is NULL.
 959 */
 960int wc_LmsKey_GetParameters_ex(const LmsKey* key, int* levels, int* height,
 961    int* winternitz, int* hash)
 962{
 963    int ret = 0;
 964
 965    /* Validate parameters. */
 966    if ((key == NULL) || (levels == NULL) || (height == NULL) ||
 967            (winternitz == NULL) || (hash == NULL)) {
 968        ret = BAD_FUNC_ARG;
 969    }
 970
 971    /* Validate the parameters are available. */
 972    if ((ret == 0) && (key->params == NULL)) {
 973        ret = BAD_FUNC_ARG;
 974    }
 975
 976    if (ret == 0) {
 977        /* Set the levels, height and Winternitz width from parameters. */
 978        *levels = key->params->levels;
 979        *height = key->params->height;
 980        *winternitz = key->params->width;
 981        *hash = key->params->lmsType & LMS_HASH_MASK;
 982    }
 983
 984    return ret;
 985}
 986
 987/* Frees the LMS key from memory.
 988 *
 989 * This does not affect the private key saved to non-volatile storage.
 990 *
 991 * @param [in, out] key  LMS key to free.
 992 */
 993void wc_LmsKey_Free(LmsKey* key)
 994{
 995    if (key != NULL) {
 996    #ifndef WOLFSSL_LMS_VERIFY_ONLY
 997        if (key->priv_data != NULL) {
 998            const LmsParams* params = key->params;
 999            word32 priv_data_len = LMS_PRIV_DATA_LEN(params->levels,
1000                params->height, params->p, params->rootLevels,
1001                params->cacheBits, params->hash_len);
1002
1003        #ifdef WOLFSSL_WC_LMS_SERIALIZE_STATE
1004            priv_data_len += HSS_PRIVATE_KEY_LEN(key->params->hash_len);
1005        #endif
1006            ForceZero(key->priv_data, priv_data_len);
1007            XFREE(key->priv_data, key->heap, DYNAMIC_TYPE_LMS);
1008            key->priv_data = NULL;
1009        }
1010
1011        ForceZero(key->priv_raw, HSS_MAX_PRIVATE_KEY_LEN);
1012        ForceZero(&key->priv, sizeof(HssPrivKey));
1013
1014        key->write_private_key = NULL;
1015        key->read_private_key = NULL;
1016        key->context = NULL;
1017        key->heap = NULL;
1018    #endif
1019        XMEMSET(key->pub, 0, sizeof(key->pub));
1020        key->params = NULL;
1021    #ifdef WOLF_CRYPTO_CB
1022        key->devId = INVALID_DEVID;
1023        key->devCtx = NULL;
1024    #endif
1025    #ifdef WOLF_PRIVATE_KEY_ID
1026        XMEMSET(key->id, 0, sizeof(key->id));
1027        key->idLen = 0;
1028        XMEMSET(key->label, 0, sizeof(key->label));
1029        key->labelLen = 0;
1030    #endif
1031
1032        key->state = WC_LMS_STATE_FREED;
1033    }
1034}
1035
1036#ifndef WOLFSSL_LMS_VERIFY_ONLY
1037/* Set the write private key callback to the LMS key structure.
1038 *
1039 * The callback must be able to write/update the private key to
1040 * non-volatile storage.
1041 *
1042 * @param [in, out] key       LMS key.
1043 * @param [in]      write_cb  Callback function that stores private key.
1044 * @return  0 on success.
1045 * @return  BAD_FUNC_ARG when key or write_cb is NULL.
1046 * @return  BAD_STATE_E when key state is invalid.
1047 */
1048int wc_LmsKey_SetWriteCb(LmsKey* key, wc_lms_write_private_key_cb write_cb)
1049{
1050    int ret = 0;
1051
1052    /* Validate parameters. */
1053    if ((key == NULL) || (write_cb == NULL)) {
1054        ret = BAD_FUNC_ARG;
1055    }
1056    /* Changing the write callback of an already working key is forbidden. */
1057    if ((ret == 0) && (key->state == WC_LMS_STATE_OK)) {
1058        WOLFSSL_MSG("error: wc_LmsKey_SetWriteCb: key in use");
1059        ret = BAD_STATE_E;
1060    }
1061
1062    if (ret == 0) {
1063        /* Set the callback into the key. */
1064        key->write_private_key = write_cb;
1065    }
1066
1067    return ret;
1068}
1069
1070/* Set the read private key callback to the LMS key structure.
1071 *
1072 * The callback must be able to read the private key from
1073 * non-volatile storage.
1074 *
1075 * @param [in, out] key      LMS key.
1076 * @param [in]      read_cb  Callback function that loads private key.
1077 * @return  0 on success.
1078 * @return  BAD_FUNC_ARG when key or read_cb is NULL.
1079 * @return  BAD_STATE_E when key state is invalid.
1080 * */
1081int wc_LmsKey_SetReadCb(LmsKey* key, wc_lms_read_private_key_cb read_cb)
1082{
1083    int ret = 0;
1084
1085    /* Validate parameters. */
1086    if ((key == NULL) || (read_cb == NULL)) {
1087        ret = BAD_FUNC_ARG;
1088    }
1089    /* Changing the read callback of an already working key is forbidden. */
1090    if ((ret == 0) && (key->state == WC_LMS_STATE_OK)) {
1091        WOLFSSL_MSG("error: wc_LmsKey_SetReadCb: key in use");
1092        ret = BAD_STATE_E;
1093    }
1094
1095    if (ret == 0) {
1096        /* Set the callback into the key. */
1097        key->read_private_key = read_cb;
1098    }
1099
1100    return ret;
1101}
1102
1103/* Sets the context to be used by write and read callbacks.
1104 *
1105 * E.g. this could be a filename if the callbacks write/read to file.
1106 *
1107 * @param [in, out] key      LMS key.
1108 * @param [in]      context  Pointer to data for read/write callbacks.
1109 * @return  0 on success.
1110 * @return  BAD_FUNC_ARG when key or context is NULL.
1111 * @return  BAD_STATE_E when key state is invalid.
1112 * */
1113int wc_LmsKey_SetContext(LmsKey* key, void* context)
1114{
1115    int ret = 0;
1116
1117    /* Validate parameters. NULL context is allowed: callers with stub
1118     * read/write callbacks (e.g. HSM-backed keys whose private state lives
1119     * in the device) have no meaningful context to pass. */
1120    if (key == NULL) {
1121        ret = BAD_FUNC_ARG;
1122    }
1123    /* Setting context of an already working key is forbidden. */
1124    if ((ret == 0) && (key->state == WC_LMS_STATE_OK)) {
1125        WOLFSSL_MSG("error: wc_LmsKey_SetContext: key in use");
1126        ret = BAD_STATE_E;
1127    }
1128
1129    if (ret == 0) {
1130        /* Set the callback context into the key. */
1131        key->context = context;
1132    }
1133
1134    return ret;
1135}
1136
1137/* Make the LMS private/public key pair. The key must have its parameters
1138 * set before calling this.
1139 *
1140 * Write/read callbacks, and context data, must be set prior.
1141 * Key must have parameters set.
1142 *
1143 * @param [in, out] key   LMS key.
1144 * @param [in]      rng   Random number generator.
1145 * @return  0 on success.
1146 * @return  BAD_FUNC_ARG when key or rng is NULL.
1147 * @return  BAD_STATE_E when key is in an invalid state.
1148 * @return  BAD_FUNC_ARG when write callback or callback context not set.
1149 * @return  BAD_STATE_E when no more signatures can be created.
1150 */
1151int wc_LmsKey_MakeKey(LmsKey* key, WC_RNG* rng)
1152{
1153    int ret = 0;
1154    word32 priv_data_len = 0;
1155
1156    /* Validate parameters. */
1157    if ((key == NULL) || (rng == NULL)) {
1158        ret = BAD_FUNC_ARG;
1159    }
1160    /* Check state. */
1161    if ((ret == 0) && (key->state != WC_LMS_STATE_PARMSET)) {
1162        WOLFSSL_MSG("error: LmsKey not ready for generation");
1163        ret = BAD_STATE_E;
1164    }
1165
1166#ifdef WOLF_CRYPTO_CB
1167    /* HSM-backed keys skip the software write/context callbacks because the
1168     * device owns the private state. On CRYPTOCB_UNAVAILABLE fall-through the
1169     * software checks below still run. */
1170    if ((ret == 0) && (key->devId != INVALID_DEVID)) {
1171        ret = wc_CryptoCb_PqcStatefulSigKeyGen(WC_PQC_STATEFUL_SIG_TYPE_LMS,
1172            key, rng);
1173        if (ret != WC_NO_ERR_TRACE(CRYPTOCB_UNAVAILABLE)) {
1174            /* This should not happen, but check whether signatures can be
1175             * created. */
1176            if ((ret == 0) && (wc_LmsKey_SigsLeft(key) == 0)) {
1177                WOLFSSL_MSG("error: generated LMS key signatures exhausted");
1178                key->state = WC_LMS_STATE_NOSIGS;
1179                ret = BAD_STATE_E;
1180            }
1181            /* On success, mirror the software path's terminal state so
1182             * subsequent Sign/Verify calls don't fail with BAD_STATE_E. */
1183            if (ret == 0) {
1184                key->state = WC_LMS_STATE_OK;
1185            }
1186            return ret;
1187        }
1188        ret = 0; /* fall through to software path */
1189    }
1190#endif
1191
1192    /* Check write callback set. */
1193    if ((ret == 0) && (key->write_private_key == NULL)) {
1194        WOLFSSL_MSG("error: LmsKey write callback is not set");
1195        ret = BAD_FUNC_ARG;
1196    }
1197    if (ret == 0) {
1198        const LmsParams* params = key->params;
1199        priv_data_len = LMS_PRIV_DATA_LEN(params->levels, params->height,
1200            params->p, params->rootLevels, params->cacheBits, params->hash_len);
1201
1202    #ifdef WOLFSSL_WC_LMS_SERIALIZE_STATE
1203        priv_data_len += HSS_PRIVATE_KEY_LEN(key->params->hash_len);
1204    #endif
1205    }
1206    if ((ret == 0) && (key->priv_data == NULL)) {
1207        /* Allocate memory for the private key data. */
1208        key->priv_data = (byte *)XMALLOC(priv_data_len, key->heap,
1209            DYNAMIC_TYPE_LMS);
1210        /* Check pointer is valid. */
1211        if (key->priv_data == NULL) {
1212            ret = MEMORY_E;
1213        }
1214    #ifdef WOLFSSL_WC_LMS_SERIALIZE_STATE
1215        else {
1216            XMEMSET(key->priv_data, 0, priv_data_len);
1217        }
1218    #endif
1219    }
1220    if (ret == 0) {
1221        WC_DECLARE_VAR(state, LmsState, 1, 0);
1222
1223        /* Allocate memory for working state. */
1224        WC_ALLOC_VAR_EX(state, LmsState, 1, NULL, DYNAMIC_TYPE_TMP_BUFFER,
1225            ret=MEMORY_E);
1226        if (WC_VAR_OK(state))
1227        {
1228            /* Initialize working state for use. */
1229            ret = wc_lmskey_state_init(state, key->params);
1230            if (ret == 0) {
1231                /* Make the HSS key. */
1232                ret = wc_hss_make_key(state, rng, key->priv_raw, &key->priv,
1233                    key->priv_data, key->pub);
1234                wc_lmskey_state_free(state);
1235            }
1236            ForceZero(state, sizeof(LmsState));
1237            WC_FREE_VAR_EX(state, NULL, DYNAMIC_TYPE_TMP_BUFFER);
1238        }
1239    }
1240    if (ret == 0) {
1241        int rv;
1242        /* Write private key to storage. */
1243    #ifdef WOLFSSL_WC_LMS_SERIALIZE_STATE
1244        XMEMCPY(key->priv_data + priv_data_len -
1245            HSS_PRIVATE_KEY_LEN(key->params->hash_len), key->priv_raw,
1246            HSS_PRIVATE_KEY_LEN(key->params->hash_len));
1247        rv = key->write_private_key(key->priv_data, priv_data_len,
1248            key->context);
1249    #else
1250        rv = key->write_private_key(key->priv_raw,
1251            HSS_PRIVATE_KEY_LEN(key->params->hash_len), key->context);
1252    #endif
1253        if (rv != WC_LMS_RC_SAVED_TO_NV_MEMORY) {
1254            ret = IO_FAILED_E;
1255        }
1256    }
1257
1258    /* This should not happen, but check whether signatures can be created. */
1259    if ((ret == 0) && (wc_LmsKey_SigsLeft(key) == 0)) {
1260        WOLFSSL_MSG("error: generated LMS key signatures exhausted");
1261        key->state = WC_LMS_STATE_NOSIGS;
1262        ret = BAD_STATE_E;
1263    }
1264
1265    if (ret == 0) {
1266        /* Update state. */
1267        key->state = WC_LMS_STATE_OK;
1268    }
1269
1270    return ret;
1271}
1272
1273/* Reload a key that has been prepared with the appropriate params and data.
1274 *
1275 * Use this if you wish to resume signing with an existing key.
1276 * Call this function after initializing and setting parameters.
1277 *
1278 * Write/read callbacks, and context data, must be set prior.
1279 * Key must have parameters set.
1280 *
1281 * @param [in, out] key  LMS key.
1282 *
1283 * Returns 0 on success. */
1284int wc_LmsKey_Reload(LmsKey* key)
1285{
1286    int ret = 0;
1287    word32 priv_data_len = 0;
1288
1289    /* Validate parameter. */
1290    if (key == NULL) {
1291        ret = BAD_FUNC_ARG;
1292    }
1293    /* Check state. */
1294    if ((ret == 0) && (key->state != WC_LMS_STATE_PARMSET)) {
1295        WOLFSSL_MSG("error: LmsKey not ready for reload");
1296        ret = BAD_STATE_E;
1297    }
1298
1299#ifdef WOLF_CRYPTO_CB
1300    /* State for HSM-backed keys lives in the device; no software reload. */
1301    if ((ret == 0) && (key->devId != INVALID_DEVID)) {
1302        WOLFSSL_MSG("wc_LmsKey_Reload is a no-op for HSM-backed keys");
1303        key->state = WC_LMS_STATE_OK;
1304        return 0;
1305    }
1306#endif
1307
1308    /* Check read callback present. */
1309    if ((ret == 0) && (key->read_private_key == NULL)) {
1310        WOLFSSL_MSG("error: LmsKey read callback is not set");
1311        ret = BAD_FUNC_ARG;
1312    }
1313
1314    if (ret == 0) {
1315        const LmsParams* params = key->params;
1316        priv_data_len = LMS_PRIV_DATA_LEN(params->levels, params->height,
1317            params->p, params->rootLevels, params->cacheBits, params->hash_len);
1318
1319    #ifdef WOLFSSL_WC_LMS_SERIALIZE_STATE
1320        priv_data_len += HSS_PRIVATE_KEY_LEN(params->hash_len);
1321    #endif
1322    }
1323    if ((ret == 0) && (key->priv_data == NULL)) {
1324        /* Allocate memory for the private key data. */
1325        key->priv_data = (byte *)XMALLOC(priv_data_len, key->heap,
1326            DYNAMIC_TYPE_LMS);
1327        /* Check pointer is valid. */
1328        if (key->priv_data == NULL) {
1329            ret = MEMORY_E;
1330        }
1331    }
1332    if (ret == 0) {
1333        int rv;
1334
1335        /* Load private key. */
1336    #ifdef WOLFSSL_WC_LMS_SERIALIZE_STATE
1337        const LmsParams* params = key->params;
1338
1339        rv = key->read_private_key(key->priv_data, priv_data_len, key->context);
1340    #else
1341        rv = key->read_private_key(key->priv_raw,
1342            HSS_PRIVATE_KEY_LEN(key->params->hash_len), key->context);
1343    #endif
1344        if (rv != WC_LMS_RC_READ_TO_MEMORY) {
1345            ret = IO_FAILED_E;
1346        }
1347    #ifdef WOLFSSL_WC_LMS_SERIALIZE_STATE
1348        if (ret == 0) {
1349            XMEMCPY(key->priv_raw, key->priv_data + priv_data_len -
1350                HSS_PRIVATE_KEY_LEN(params->hash_len),
1351                HSS_PRIVATE_KEY_LEN(params->hash_len));
1352        }
1353    #endif
1354    }
1355
1356    /* Double check the key actually has signatures left. */
1357    if ((ret == 0) && (wc_LmsKey_SigsLeft(key) == 0)) {
1358        WOLFSSL_MSG("error: reloaded LMS key signatures exhausted");
1359        key->state = WC_LMS_STATE_NOSIGS;
1360        ret = BAD_STATE_E;
1361    }
1362
1363    if (ret == 0) {
1364        WC_DECLARE_VAR(state, LmsState, 1, 0);
1365
1366        /* Allocate memory for working state. */
1367        WC_ALLOC_VAR_EX(state, LmsState, 1, NULL, DYNAMIC_TYPE_TMP_BUFFER,
1368            ret=MEMORY_E);
1369        if (WC_VAR_OK(state))
1370        {
1371            /* Initialize working state for use. */
1372            ret = wc_lmskey_state_init(state, key->params);
1373            if (ret == 0) {
1374                /* Reload the key ready for signing. */
1375                ret = wc_hss_reload_key(state, key->priv_raw, &key->priv,
1376                    key->priv_data, NULL);
1377                wc_lmskey_state_free(state);
1378            }
1379            ForceZero(state, sizeof(LmsState));
1380            WC_FREE_VAR_EX(state, NULL, DYNAMIC_TYPE_TMP_BUFFER);
1381        }
1382    }
1383
1384    if (ret == 0) {
1385        /* Update state. */
1386        key->state = WC_LMS_STATE_OK;
1387    }
1388
1389    return ret;
1390}
1391
1392/* Get the raw private key length based on parameter set of key.
1393 *
1394 * @param [in]  key  LMS key.
1395 * @param [out] len  Length of private key.
1396 * @return  0 on success.
1397 * @return  BAD_FUNC_ARG when key or len is NULL or parameters not set.
1398 */
1399int wc_LmsKey_GetPrivLen(const LmsKey* key, word32* len)
1400{
1401    int ret = 0;
1402
1403    /* Validate parameters. */
1404    if ((key == NULL) || (len == NULL) || (key->params == NULL)) {
1405        ret = BAD_FUNC_ARG;
1406    }
1407
1408    if (ret == 0) {
1409        /* Return private key length from parameter set. */
1410        *len = HSS_PRIVATE_KEY_LEN(key->params->hash_len);
1411    }
1412
1413    return ret;
1414}
1415
1416/* Sign a message.
1417 *
1418 * @param [in, out] key    LMS key to sign with.
1419 * @param [out]     sig    Signature data. Buffer must be big enough to hold
1420 *                         signature data.
1421 * @param [out]     sigSz  Length of signature data.
1422 * @param [in]      msg    Message to sign.
1423 * @param [in]      msgSz  Length of message in bytes.
1424 * @return  0 on success.
1425 * @return  BAD_FUNC_ARG when key, sig, sigSz or msg is NULL.
1426 * @return  BAD_FUNC_ARG when msgSz is less than 0.
1427 * @return  BAD_FUNC_ARG when a write private key is not set.
1428 * @return  BAD_FUNC_ARG when a read/write private key context is not set.
1429 * @return  BUFFER_E when sigSz is too small.
1430 * @return  BAD_STATE_E when wrong state for operation.
1431 * @return  IO_FAILED_E when reading or writing private key failed.
1432 */
1433int wc_LmsKey_Sign(LmsKey* key, byte* sig, word32* sigSz, const byte* msg,
1434    int msgSz)
1435{
1436    int ret = 0;
1437
1438    /* Validate parameters. */
1439    if ((key == NULL) || (key->params == NULL) || (sig == NULL) ||
1440            (sigSz == NULL) || (msg == NULL)) {
1441        ret = BAD_FUNC_ARG;
1442    }
1443    if ((ret == 0) && (msgSz < 0)) {
1444        ret = BAD_FUNC_ARG;
1445    }
1446    /* Check state. */
1447    if ((ret == 0) && (key->state != WC_LMS_STATE_OK)) {
1448        if (key->state == WC_LMS_STATE_NOSIGS) {
1449            WOLFSSL_MSG("error: LMS signatures exhausted");
1450        }
1451        else {
1452            /* The key state is not ready for signing. */
1453            WOLFSSL_MSG("error: can't sign, LMS key not in good state");
1454        }
1455        ret = BAD_STATE_E;
1456    }
1457    /* Check signature buffer size. */
1458    if ((ret == 0) && (*sigSz < key->params->sig_len)) {
1459        /* Signature buffer too small. */
1460        WOLFSSL_MSG("error: LMS sig buffer too small");
1461        ret = BUFFER_E;
1462    }
1463
1464#ifdef WOLF_CRYPTO_CB
1465    /* HSM-backed keys skip the software write/context callbacks because the
1466     * device owns the private state. On CRYPTOCB_UNAVAILABLE fall-through the
1467     * software checks below still run. */
1468    if ((ret == 0) && (key->devId != INVALID_DEVID)) {
1469        ret = wc_CryptoCb_PqcStatefulSigSign(msg, (word32)msgSz, sig, sigSz,
1470            WC_PQC_STATEFUL_SIG_TYPE_LMS, key);
1471        if (ret != WC_NO_ERR_TRACE(CRYPTOCB_UNAVAILABLE)) {
1472            return ret;
1473        }
1474        ret = 0; /* fall through to software path */
1475    }
1476#endif
1477
1478    /* Check read and write callbacks available. */
1479    if ((ret == 0) && (key->write_private_key == NULL)) {
1480        WOLFSSL_MSG("error: LmsKey write/read callbacks are not set");
1481        ret = BAD_FUNC_ARG;
1482    }
1483
1484    if (ret == 0) {
1485        WC_DECLARE_VAR(state, LmsState, 1, 0);
1486
1487        /* Allocate memory for working state. */
1488        WC_ALLOC_VAR_EX(state, LmsState, 1, NULL, DYNAMIC_TYPE_TMP_BUFFER,
1489            ret=MEMORY_E);
1490        if (WC_VAR_OK(state))
1491        {
1492            /* Initialize working state for use. */
1493            ret = wc_lmskey_state_init(state, key->params);
1494            if (ret == 0) {
1495                /* Sign message. */
1496                ret = wc_hss_sign(state, key->priv_raw, &key->priv,
1497                    key->priv_data, msg, (word32)msgSz, sig);
1498                wc_lmskey_state_free(state);
1499            }
1500            ForceZero(state, sizeof(LmsState));
1501            WC_FREE_VAR_EX(state, NULL, DYNAMIC_TYPE_TMP_BUFFER);
1502        }
1503    }
1504    if (ret == 0) {
1505        *sigSz = (word32)key->params->sig_len;
1506    }
1507    if (ret == 0) {
1508        int rv;
1509
1510        /* Write private key to storage. */
1511    #ifdef WOLFSSL_WC_LMS_SERIALIZE_STATE
1512        const LmsParams* params = key->params;
1513        word32 priv_data_len = LMS_PRIV_DATA_LEN(params->levels, params->height,
1514            params->p, params->rootLevels, params->cacheBits,
1515            params->hash_len) + HSS_PRIVATE_KEY_LEN(key->params->hash_len);
1516
1517        XMEMCPY(key->priv_data + priv_data_len -
1518            HSS_PRIVATE_KEY_LEN(params->hash_len), key->priv_raw,
1519            HSS_PRIVATE_KEY_LEN(params->hash_len));
1520        rv = key->write_private_key(key->priv_data, priv_data_len,
1521            key->context);
1522    #else
1523        rv = key->write_private_key(key->priv_raw,
1524            HSS_PRIVATE_KEY_LEN(key->params->hash_len), key->context);
1525    #endif
1526        if (rv != WC_LMS_RC_SAVED_TO_NV_MEMORY) {
1527            /* Write to NV storage failed. Erase the signature from
1528             * memory to prevent OTS key reuse if state is rolled back. */
1529            ForceZero(sig, key->params->sig_len);
1530            ret = IO_FAILED_E;
1531        }
1532    }
1533
1534    return ret;
1535}
1536
1537/* Returns whether signatures can be created with key.
1538 *
1539 * @param [in]  key  LMS key.
1540 *
1541 * @return  1 if there are signatures remaining.
1542 * @return  0 if available signatures are exhausted.
1543 */
1544int wc_LmsKey_SigsLeft(LmsKey* key)
1545{
1546    int ret = 0;
1547
1548    /* NULL keys have no signatures remaining. */
1549    if (key != NULL) {
1550    #ifdef WOLF_CRYPTO_CB
1551        if (key->devId != INVALID_DEVID) {
1552            word32 sigsLeft = 0;
1553            int cbRet = wc_CryptoCb_PqcStatefulSigSigsLeft(
1554                WC_PQC_STATEFUL_SIG_TYPE_LMS, key, &sigsLeft);
1555            if (cbRet == 0) {
1556                return (sigsLeft != 0) ? 1 : 0;
1557            }
1558            if (cbRet != WC_NO_ERR_TRACE(CRYPTOCB_UNAVAILABLE)) {
1559                /* Device returned an actual error; the device owns the
1560                 * private state so no safe software fallback exists. */
1561                WOLFSSL_MSG("PqcStatefulSigSigsLeft returned an error");
1562                return 0;
1563            }
1564            /* Cryptocb declined. priv_raw reflects software state from the
1565             * CRYPTOCB_UNAVAILABLE fall-through in MakeKey/Reload, so the
1566             * software check below is valid. */
1567            WOLFSSL_MSG("LMS SigsLeft not supported by device, using software");
1568        }
1569    #endif
1570        ret = wc_hss_sigsleft(key->params, key->priv_raw);
1571    }
1572
1573    return ret;
1574}
1575
1576#endif /* ifndef WOLFSSL_LMS_VERIFY_ONLY*/
1577
1578/* Get the public key length based on parameter set of key.
1579 *
1580 * @param [in]  key  LMS key.
1581 * @param [out] len  Length of public key.
1582 * @return  0 on success.
1583 * @return  BAD_FUNC_ARG when key or len is NULL or parameters not set.
1584 */
1585int wc_LmsKey_GetPubLen(const LmsKey* key, word32* len)
1586{
1587    int ret = 0;
1588
1589    /* Validate parameters */
1590    if ((key == NULL) || (len == NULL) || (key->params == NULL)) {
1591        ret = BAD_FUNC_ARG;
1592    }
1593
1594    if (ret == 0) {
1595        *len = HSS_PUBLIC_KEY_LEN(key->params->hash_len);
1596    }
1597
1598    return ret;
1599}
1600
1601/* Export a generated public key and parameter set from one LmsKey
1602 * to another, with explicit heap and device bindings.
1603 *
1604 * The destination key must be unused or have been freed.
1605 * The destination is fully initialized as a verify-only key.
1606 *
1607 * @param [out] keyDst  LMS key to copy into.
1608 * @param [in]  keySrc  LMS key to copy.
1609 * @param [in]  heap    Heap hint for keyDst.
1610 * @param [in]  devId   Device identifier for keyDst.
1611 *                      Use INVALID_DEVID when not using a device.
1612 * @return  0 on success.
1613 * @return  BAD_FUNC_ARG when keyDst or keySrc is NULL.
1614 * @return  BAD_STATE_E when in the wrong state for the operation.
1615 */
1616int wc_LmsKey_ExportPub_ex(LmsKey* keyDst, const LmsKey* keySrc,
1617                           void* heap, int devId)
1618{
1619    int ret = 0;
1620
1621    if ((keyDst == NULL) || (keySrc == NULL)) {
1622        ret = BAD_FUNC_ARG;
1623    }
1624    if ((ret == 0) && (keySrc->state != WC_LMS_STATE_OK) &&
1625            (keySrc->state != WC_LMS_STATE_VERIFYONLY) &&
1626            (keySrc->state != WC_LMS_STATE_NOSIGS)) {
1627        ret = BAD_STATE_E;
1628    }
1629
1630    if (ret == 0) {
1631        ret = wc_LmsKey_Init(keyDst, heap, devId);
1632    }
1633    if (ret == 0) {
1634        keyDst->params = keySrc->params;
1635        XMEMCPY(keyDst->pub, keySrc->pub, sizeof(keySrc->pub));
1636
1637        /* Mark this key as verify only, to prevent misuse. */
1638        keyDst->state = WC_LMS_STATE_VERIFYONLY;
1639    }
1640
1641    return ret;
1642}
1643
1644/* Export a generated public key and parameter set from one LmsKey
1645 * to another. Use this to prepare a signature verification LmsKey
1646 * that is pub only.
1647 *
1648 * Though the public key is all that is used to verify signatures,
1649 * the parameter set is needed to calculate the signature length
1650 * before hand.
1651 *
1652 * The destination key is left with no heap hint and no device
1653 * binding. Callers that need either should use
1654 * wc_LmsKey_ExportPub_ex.
1655 *
1656 * @param [out] keyDst  LMS key to copy into.
1657 * @param [in]  keySrc  LMS key to copy.
1658 * @return  0 on success.
1659 * @return  BAD_FUNC_ARG when keyDst or keySrc is NULL.
1660 */
1661int wc_LmsKey_ExportPub(LmsKey* keyDst, const LmsKey* keySrc)
1662{
1663    return wc_LmsKey_ExportPub_ex(keyDst, keySrc,
1664    #ifndef WOLFSSL_LMS_VERIFY_ONLY
1665        (keySrc != NULL) ? keySrc->heap : NULL,
1666    #else
1667        NULL,
1668    #endif
1669        INVALID_DEVID);
1670}
1671
1672/* Exports the raw LMS public key buffer from key to out buffer.
1673 * The out buffer should be large enough to hold the public key, and
1674 * outLen should indicate the size of the buffer.
1675 *
1676 * Call wc_LmsKey_GetPubLen beforehand to determine pubLen.
1677 *
1678 * @param [in]      key     LMS key.
1679 * @param [out]     out     Buffer to hold encoded public key.
1680 * @param [in, out] outLen  On in, length of out in bytes.
1681 *                          On out, the length of the public key in bytes.
1682 * @return  0 on success.
1683 * @return  BAD_FUNC_ARG when key, out or outLen is NULL.
1684 * @return  BUFFER_E when outLen is too small to hold encoded public key.
1685 */
1686int wc_LmsKey_ExportPubRaw(const LmsKey* key, byte* out, word32* outLen)
1687{
1688    int ret = 0;
1689
1690    /* Validate parameters. */
1691    if ((key == NULL) || (out == NULL) || (outLen == NULL) ||
1692            (key->params == NULL)) {
1693        ret = BAD_FUNC_ARG;
1694    }
1695    /* Check size of out is sufficient. */
1696    if ((ret == 0) &&
1697            (*outLen < (word32)HSS_PUBLIC_KEY_LEN(key->params->hash_len))) {
1698        ret = BUFFER_E;
1699    }
1700
1701    if (ret == 0) {
1702        /* Return encoded public key. */
1703        XMEMCPY(out, key->pub, HSS_PUBLIC_KEY_LEN(key->params->hash_len));
1704        *outLen = HSS_PUBLIC_KEY_LEN(key->params->hash_len);
1705    }
1706
1707    return ret;
1708}
1709
1710/* Imports a raw public key buffer from in array to LmsKey key.
1711 *
1712 * If the LMS parameters have already been configured (via
1713 * wc_LmsKey_SetLmsParm or wc_LmsKey_SetParameters), the levels /
1714 * lms_algorithm_type / lmots_algorithm_type encoded in the raw key are
1715 * checked for consistency and inLen must match wc_LmsKey_GetPubLen.
1716 *
1717 * If the parameters have not yet been set (key->params == NULL), they
1718 * are derived from the raw public key prefix (RFC 8554 sec 3.3 / sec
1719 * 6.1: u32str(L) || lms_algorithm_type || lmots_algorithm_type) and
1720 * matched against the static parameter map. The candidate is held in
1721 * a local until the length check passes, so a length mismatch leaves
1722 * key->params NULL.
1723 *
1724 * Accepts a key in INITED, PARMSET or VERIFYONLY state. WC_LMS_STATE_OK
1725 * is rejected because the key already has private material loaded and
1726 * silently overwriting key->pub would create an inconsistent priv/pub
1727 * pair.
1728 *
1729 * @param [in, out] key    LMS key to put public key in.
1730 * @param [in]      in     Buffer holding encoded public key.
1731 * @param [in]      inLen  Length of encoded public key in bytes.
1732 * @return  0 on success.
1733 * @return  BAD_FUNC_ARG when key or in is NULL, or when the raw key's
1734 *          levels / lmsType / lmOtsType disagree with pre-set params.
1735 * @return  BAD_STATE_E when wrong state for operation.
1736 * @return  BUFFER_E when inLen is too small to contain the LMS type
1737 *          fields, or doesn't match the public key length determined
1738 *          by parameters.
1739 * @return  NOT_COMPILED_IN when the derived parameter set isn't built in.
1740 */
1741int wc_LmsKey_ImportPubRaw(LmsKey* key, const byte* in, word32 inLen)
1742{
1743    int              ret = 0;
1744    const LmsParams* matched = NULL;
1745
1746    /* Validate parameters. */
1747    if ((key == NULL) || (in == NULL)) {
1748        ret = BAD_FUNC_ARG;
1749    }
1750    /* Reject states where re-importing the public bytes would desync
1751     * the key. INITED (params unset, will derive), PARMSET (params set
1752     * but no private material) and VERIFYONLY (already a pub-only key)
1753     * are all safe. OK means a private key is loaded; silently
1754     * overwriting key->pub would create a priv/pub mismatch. Mirrors
1755     * the wc_XmssKey_ImportPubRaw_ex post-condition added in the same
1756     * RFC 9802 series. */
1757    if ((ret == 0) &&
1758            (key->state != WC_LMS_STATE_INITED) &&
1759            (key->state != WC_LMS_STATE_PARMSET) &&
1760            (key->state != WC_LMS_STATE_VERIFYONLY)) {
1761        WOLFSSL_MSG("error: LMS key not ready for import");
1762        ret = BAD_STATE_E;
1763    }
1764    /* Need at least L || lmsType || lmOtsType to derive or validate. */
1765    if ((ret == 0) && (inLen < (word32)(LMS_L_LEN + 2 * LMS_TYPE_LEN))) {
1766        ret = BUFFER_E;
1767    }
1768
1769    if (ret == 0) {
1770        word32 levels = 0;
1771        word32 lmsType = 0;
1772        word32 lmOtsType = 0;
1773
1774        /* RFC 8554 sec 3.3 / sec 6.1: HSS public key = u32str(L) || pub[0],
1775         * where pub[0] starts with lms_algorithm_type || lmots_algorithm_type.
1776         */
1777        ato32(in + 0,                   &levels);
1778        ato32(in + LMS_L_LEN,           &lmsType);
1779        ato32(in + LMS_L_LEN + LMS_TYPE_LEN, &lmOtsType);
1780
1781        /* The wire format carries only the RFC type code (low 12 bits);
1782         * params->lmsType / lmOtsType also pack a wolfSSL-internal hash
1783         * family flag in the high 4 bits (LMS_HASH_MASK). Compare on the
1784         * RFC code only -- safe as long as low-12-bit codes stay globally
1785         * distinct across hash families (see wc_lms_impl.c step 3.d-e
1786         * note). */
1787        if (key->params == NULL) {
1788            /* Auto-derive: find matching entry in the static map. Hold
1789             * the candidate in a local until the length check passes to
1790             * avoid leaving key->params half-set on failure. */
1791            int i;
1792            ret = WC_NO_ERR_TRACE(NOT_COMPILED_IN);
1793            for (i = 0; i < WC_LMS_MAP_LEN; i++) {
1794                if (((word32)wc_lms_map[i].params.levels == levels) &&
1795                    ((word32)(wc_lms_map[i].params.lmsType & LMS_H_W_MASK) ==
1796                                                                     lmsType) &&
1797                    ((word32)(wc_lms_map[i].params.lmOtsType& LMS_H_W_MASK) ==
1798                                                                   lmOtsType)) {
1799                    matched = &wc_lms_map[i].params;
1800                    ret = 0;
1801                    break;
1802                }
1803            }
1804            if (ret != 0) {
1805                WOLFSSL_MSG("error: LMS params from pub key not supported");
1806            }
1807        }
1808        else {
1809            /* Validate against pre-set params. */
1810            if (((word32)key->params->levels != levels) ||
1811                ((word32)(key->params->lmsType & LMS_H_W_MASK) != lmsType) ||
1812                ((word32)(key->params->lmOtsType & LMS_H_W_MASK) != lmOtsType)){
1813                WOLFSSL_MSG("error: LMS pub key doesn't match set params");
1814                ret = BAD_FUNC_ARG;
1815            }
1816            else {
1817                matched = key->params;
1818            }
1819        }
1820    }
1821    if ((ret == 0) &&
1822            (inLen != (word32)HSS_PUBLIC_KEY_LEN(matched->hash_len))) {
1823        ret = BUFFER_E;
1824    }
1825
1826    if (ret == 0) {
1827        /* Commit params (no-op when already set) and copy the key.
1828         * State is INITED/PARMSET/VERIFYONLY here (OK is rejected
1829         * above), so promoting to VERIFYONLY is always correct. */
1830        key->params = matched;
1831        XMEMCPY(key->pub, in, inLen);
1832        key->state = WC_LMS_STATE_VERIFYONLY;
1833    }
1834
1835    return ret;
1836}
1837
1838/* Given a levels, height, winternitz parameter set, determine
1839 * the signature length.
1840 *
1841 * Call this before wc_LmsKey_Sign so you know the length of
1842 * the required signature buffer.
1843 *
1844 * @param [in]  key  LMS key.
1845 * @param [out] len  Length of a signature in bytes.
1846 * @return  0 on success.
1847 * @return  BAD_FUNC_ARG when key or len is NULL, or when the LMS
1848 *          parameters have not been configured on the key.
1849 */
1850int wc_LmsKey_GetSigLen(const LmsKey* key, word32* len)
1851{
1852    int ret = 0;
1853
1854    /* Validate parameters. */
1855    if ((key == NULL) || (len == NULL) || (key->params == NULL)) {
1856        ret = BAD_FUNC_ARG;
1857    }
1858
1859    if (ret == 0) {
1860        *len = key->params->sig_len;
1861    }
1862
1863    return ret;
1864}
1865
1866/* Verify the signature of the message with public key.
1867 *
1868 * @param [in] key    LMS key.
1869 * @param [in] sig    Signature to verify.
1870 * @param [in] sigSz  Size of signature in bytes.
1871 * @param [in] msg    Message to verify.
1872 * @param [in] msgSz  Length of the message in bytes.
1873 * @return  0 on success.
1874 * @return  BAD_FUNC_ARG when a key, sig or msg is NULL.
1875 * @return  BAD_FUNC_ARG when msgSz is negative.
1876 * @return  SIG_VERIFY_E when signature did not verify message.
1877 * @return  BAD_STATE_E when wrong state for operation.
1878 * @return  BUFFER_E when sigSz is invalid for parameters.
1879 */
1880int wc_LmsKey_Verify(LmsKey* key, const byte* sig, word32 sigSz,
1881    const byte* msg, int msgSz)
1882{
1883    int ret = 0;
1884
1885    /* Validate parameters. */
1886    if ((key == NULL) || (key->params == NULL) || (sig == NULL) ||
1887            (msg == NULL)) {
1888        ret = BAD_FUNC_ARG;
1889    }
1890    if ((ret == 0) && (msgSz < 0)) {
1891        ret = BAD_FUNC_ARG;
1892    }
1893    /* Check state. */
1894    if ((ret == 0) && (key->state != WC_LMS_STATE_OK) &&
1895            (key->state != WC_LMS_STATE_VERIFYONLY)) {
1896        /* LMS key not ready for verification. Param str must be
1897         * set first, and Reload() called. */
1898        WOLFSSL_MSG("error: LMS key not ready for verification");
1899        ret = BAD_STATE_E;
1900    }
1901    /* Check signature length. */
1902    if ((ret == 0) && (sigSz != key->params->sig_len)) {
1903        ret = BUFFER_E;
1904    }
1905
1906#ifdef WOLF_CRYPTO_CB
1907    if ((ret == 0) && (key->devId != INVALID_DEVID)) {
1908        int res = 0;
1909        ret = wc_CryptoCb_PqcStatefulSigVerify(sig, sigSz, msg, (word32)msgSz,
1910            &res, WC_PQC_STATEFUL_SIG_TYPE_LMS, key);
1911        if (ret != WC_NO_ERR_TRACE(CRYPTOCB_UNAVAILABLE)) {
1912            if (ret == 0 && res != 1)
1913                ret = SIG_VERIFY_E;
1914            return ret;
1915        }
1916        ret = 0; /* fall through to software path */
1917    }
1918#endif
1919
1920    if (ret == 0) {
1921        WC_DECLARE_VAR(state, LmsState, 1, 0);
1922
1923        /* Allocate memory for working state. */
1924        WC_ALLOC_VAR_EX(state, LmsState, 1, NULL, DYNAMIC_TYPE_TMP_BUFFER,
1925            ret=MEMORY_E);
1926        if (WC_VAR_OK(state))
1927        {
1928            /* Initialize working state for use. */
1929            ret = wc_lmskey_state_init(state, key->params);
1930            if (ret == 0) {
1931                /* Verify signature of message with public key. */
1932                ret = wc_hss_verify(state, key->pub, msg, (word32)msgSz, sig,
1933                    sigSz);
1934                wc_lmskey_state_free(state);
1935            }
1936            ForceZero(state, sizeof(LmsState));
1937            WC_FREE_VAR_EX(state, NULL, DYNAMIC_TYPE_TMP_BUFFER);
1938        }
1939    }
1940
1941    return ret;
1942}
1943
1944#ifndef WOLFSSL_LMS_VERIFY_ONLY
1945
1946/* Get the Key ID from the LMS key.
1947 *
1948 * PRIV = Q | PARAMS | SEED | I
1949 * where I is the Key ID.
1950 *
1951 * @param [in]  key    LMS key.
1952 * @param [out] kid    Key ID data.
1953 * @param [out] kidSz  Size of key ID.
1954 * @return  0 on success.
1955 * @return  BAD_FUNC_ARG when a key, kid or kidSz is NULL.
1956 * @return  NOT_COMPILED_IN when key is on a device.
1957 */
1958int wc_LmsKey_GetKid(LmsKey* key, const byte** kid, word32* kidSz)
1959{
1960    int ret = 0;
1961    word32 offset;
1962
1963    if ((key == NULL) || (key->params == NULL) || (kid == NULL) ||
1964            (kidSz == NULL)) {
1965        ret = BAD_FUNC_ARG;
1966    }
1967
1968#ifdef WOLF_CRYPTO_CB
1969    /* priv_raw is not populated for HSM-backed keys where the device owns
1970     * the private state. Extend the CryptoCb surface if device-side KID
1971     * retrieval becomes a requirement.
1972     */
1973    if ((ret == 0) && (key->devId != INVALID_DEVID)) {
1974        WOLFSSL_MSG(
1975                "wc_LmsKey_GetKid: priv_raw may be uninitialised for HSM keys");
1976    }
1977#endif
1978    if (ret == 0) {
1979        /* SEED length is hash length. */
1980        offset = HSS_Q_LEN + HSS_PRIV_KEY_PARAM_SET_LEN + key->params->hash_len;
1981        *kid = key->priv_raw + offset;
1982        *kidSz = HSS_PRIVATE_KEY_LEN(key->params->hash_len) - offset;
1983    }
1984
1985    return ret;
1986}
1987
1988
1989/* Get the Key ID from the raw private key data.
1990 *
1991 * PRIV = Q | PARAMS | SEED | I
1992 * where I is the Key ID.
1993 *
1994 * @param [in] priv    Private key data.
1995 * @param [in] privSz  Size of private key data.
1996 * @param  Pointer to 16 byte Key ID in the private key.
1997 * @return  NULL on failure.
1998 */
1999const byte* wc_LmsKey_GetKidFromPrivRaw(const byte* priv, word32 privSz)
2000{
2001    const byte* ret;
2002
2003    if ((priv == NULL) ||
2004            (privSz < HSS_Q_LEN + HSS_PRIV_KEY_PARAM_SET_LEN + LMS_I_LEN)) {
2005        ret = NULL;
2006    }
2007    else {
2008        word32 seedSz = privSz - HSS_Q_LEN - HSS_PRIV_KEY_PARAM_SET_LEN -
2009                        LMS_I_LEN;
2010        if ((seedSz != WC_SHA256_192_DIGEST_SIZE) &&
2011                (seedSz != WC_SHA256_DIGEST_SIZE)) {
2012            ret = NULL;
2013        }
2014        else {
2015            ret = priv + privSz - LMS_I_LEN;
2016        }
2017    }
2018
2019    return ret;
2020}
2021
2022#endif
2023
2024#endif /* WOLFSSL_HAVE_LMS */