Add devCtx, PRIVATE_KEY_ID, and label support to LMS and XMSS keys

claude · claude · commit b019052ba650 · 2026-04-27T18:37:23.000Z
Mirrors the convention used by RSA, ECC, and Dilithium so a CryptoCb callback can locate a device-resident LMS / XMSS key by either an opaque byte identifier or a textual label, and stash device-specific state on the key without going through the public API. LmsKey / XmssKey gain (under WOLF_CRYPTO_CB): void* devCtx; and (under WOLF_PRIVATE_KEY_ID): byte id[LMS_MAX_ID_LEN]; int idLen; char label[LMS_MAX_LABEL_LEN]; int labelLen; (with XMSS_MAX_* equivalents on XmssKey). The MAX_* constants default to 32 bytes and can be overridden by predefining the macro. Public init helpers, gated on WOLF_PRIVATE_KEY_ID, follow the wc_InitRsaKey_Id / wc_InitRsaKey_Label pattern: wc_LmsKey_InitId(key, id, len, heap, devId) wc_LmsKey_InitLabel(key, label, heap, devId) wc_XmssKey_InitId(key, id, len, heap, devId) wc_XmssKey_InitLabel(key, label, heap, devId) Both validate length bounds, delegate the rest of init to wc_LmsKey_Init / wc_XmssKey_Init, then copy id/label into the key. Verified to build and pass testwolfcrypt under: --enable-lms --enable-xmss --enable-cryptocb (default and with CPPFLAGS=-DWOLF_PRIVATE_KEY_ID) --enable-lms --enable-xmss --enable-cryptocb https://claude.ai/code/session_01MixzJP9kPWkS8bhfDDDBnX
diff --git a/wolfcrypt/src/wc_lms.c b/wolfcrypt/src/wc_lms.c
@@ -715,6 +715,72 @@ int wc_LmsKey_Init(LmsKey* key, void* heap, int devId)
     return ret;
 }
 
+#ifdef WOLF_PRIVATE_KEY_ID
+/* Initialize an LmsKey and bind it to a device-side key identifier.
+ *
+ * @param [in,out] key    LmsKey to initialize.
+ * @param [in]     id     Identifier bytes (may be NULL when len is 0).
+ * @param [in]     len    Length of id; must be in [0, LMS_MAX_ID_LEN].
+ * @param [in]     heap   Heap hint forwarded to wc_LmsKey_Init.
+ * @param [in]     devId  Device identifier.
+ *
+ * @return  0 on success.
+ * @return  BAD_FUNC_ARG when key is NULL.
+ * @return  BUFFER_E when len is negative or exceeds LMS_MAX_ID_LEN.
+ */
+int wc_LmsKey_InitId(LmsKey* key, const unsigned char* id, int len, void* heap,
+    int devId)
+{
+    int ret = 0;
+
+    if (key == NULL)
+        ret = BAD_FUNC_ARG;
+    if (ret == 0 && (len < 0 || len > LMS_MAX_ID_LEN))
+        ret = BUFFER_E;
+    if (ret == 0)
+        ret = wc_LmsKey_Init(key, heap, devId);
+    if (ret == 0 && id != NULL && len != 0) {
+        XMEMCPY(key->id, id, (size_t)len);
+        key->idLen = len;
+    }
+
+    return ret;
+}
+
+/* Initialize an LmsKey and bind it to a device-side key label.
+ *
+ * @param [in,out] key    LmsKey to initialize.
+ * @param [in]     label  NUL-terminated label string (must be non-empty).
+ * @param [in]     heap   Heap hint forwarded to wc_LmsKey_Init.
+ * @param [in]     devId  Device identifier.
+ *
+ * @return  0 on success.
+ * @return  BAD_FUNC_ARG when key or label is NULL.
+ * @return  BUFFER_E when label is empty or longer than LMS_MAX_LABEL_LEN.
+ */
+int wc_LmsKey_InitLabel(LmsKey* key, const char* label, void* heap, int devId)
+{
+    int ret = 0;
+    int labelLen = 0;
+
+    if (key == NULL || label == NULL)
+        ret = BAD_FUNC_ARG;
+    if (ret == 0) {
+        labelLen = (int)XSTRLEN(label);
+        if (labelLen == 0 || labelLen > LMS_MAX_LABEL_LEN)
+            ret = BUFFER_E;
+    }
+    if (ret == 0)
+        ret = wc_LmsKey_Init(key, heap, devId);
+    if (ret == 0) {
+        XMEMCPY(key->label, label, (size_t)labelLen);
+        key->labelLen = labelLen;
+    }
+
+    return ret;
+}
+#endif /* WOLF_PRIVATE_KEY_ID */
+
 /* Get the string representation of the LMS parameter set.
  *
  * @param [in] lmsParm  LMS parameter set identifier.
diff --git a/wolfcrypt/src/wc_xmss.c b/wolfcrypt/src/wc_xmss.c
@@ -927,6 +927,73 @@ int wc_XmssKey_Init(XmssKey* key, void* heap, int devId)
     return ret;
 }
 
+#ifdef WOLF_PRIVATE_KEY_ID
+/* Initialize an XmssKey and bind it to a device-side key identifier.
+ *
+ * @param [in,out] key    XmssKey to initialize.
+ * @param [in]     id     Identifier bytes (may be NULL when len is 0).
+ * @param [in]     len    Length of id; must be in [0, XMSS_MAX_ID_LEN].
+ * @param [in]     heap   Heap hint forwarded to wc_XmssKey_Init.
+ * @param [in]     devId  Device identifier.
+ *
+ * @return  0 on success.
+ * @return  BAD_FUNC_ARG when key is NULL.
+ * @return  BUFFER_E when len is negative or exceeds XMSS_MAX_ID_LEN.
+ */
+int wc_XmssKey_InitId(XmssKey* key, const unsigned char* id, int len,
+    void* heap, int devId)
+{
+    int ret = 0;
+
+    if (key == NULL)
+        ret = BAD_FUNC_ARG;
+    if (ret == 0 && (len < 0 || len > XMSS_MAX_ID_LEN))
+        ret = BUFFER_E;
+    if (ret == 0)
+        ret = wc_XmssKey_Init(key, heap, devId);
+    if (ret == 0 && id != NULL && len != 0) {
+        XMEMCPY(key->id, id, (size_t)len);
+        key->idLen = len;
+    }
+
+    return ret;
+}
+
+/* Initialize an XmssKey and bind it to a device-side key label.
+ *
+ * @param [in,out] key    XmssKey to initialize.
+ * @param [in]     label  NUL-terminated label string (must be non-empty).
+ * @param [in]     heap   Heap hint forwarded to wc_XmssKey_Init.
+ * @param [in]     devId  Device identifier.
+ *
+ * @return  0 on success.
+ * @return  BAD_FUNC_ARG when key or label is NULL.
+ * @return  BUFFER_E when label is empty or longer than XMSS_MAX_LABEL_LEN.
+ */
+int wc_XmssKey_InitLabel(XmssKey* key, const char* label, void* heap,
+    int devId)
+{
+    int ret = 0;
+    int labelLen = 0;
+
+    if (key == NULL || label == NULL)
+        ret = BAD_FUNC_ARG;
+    if (ret == 0) {
+        labelLen = (int)XSTRLEN(label);
+        if (labelLen == 0 || labelLen > XMSS_MAX_LABEL_LEN)
+            ret = BUFFER_E;
+    }
+    if (ret == 0)
+        ret = wc_XmssKey_Init(key, heap, devId);
+    if (ret == 0) {
+        XMEMCPY(key->label, label, (size_t)labelLen);
+        key->labelLen = labelLen;
+    }
+
+    return ret;
+}
+#endif /* WOLF_PRIVATE_KEY_ID */
+
 /* Set the XMSS key parameter string.
  *
  * The input string must be one of the supported parm set names in
diff --git a/wolfssl/wolfcrypt/lms.h b/wolfssl/wolfcrypt/lms.h
@@ -223,6 +223,12 @@ enum wc_LmsState {
     extern "C" {
 #endif
 WOLFSSL_API int  wc_LmsKey_Init(LmsKey * key, void * heap, int devId);
+#ifdef WOLF_PRIVATE_KEY_ID
+WOLFSSL_API int  wc_LmsKey_InitId(LmsKey * key, const unsigned char * id,
+    int len, void * heap, int devId);
+WOLFSSL_API int  wc_LmsKey_InitLabel(LmsKey * key, const char * label,
+    void * heap, int devId);
+#endif
 WOLFSSL_API int  wc_LmsKey_SetLmsParm(LmsKey * key, enum wc_LmsParm lmsParm);
 WOLFSSL_API int  wc_LmsKey_SetParameters(LmsKey * key, int levels,
     int height, int winternitz);
diff --git a/wolfssl/wolfcrypt/wc_lms.h b/wolfssl/wolfcrypt/wc_lms.h
@@ -546,6 +546,13 @@ typedef struct HssPrivKey {
 #endif
 } HssPrivKey;
 
+#ifndef LMS_MAX_ID_LEN
+#define LMS_MAX_ID_LEN              32
+#endif
+#ifndef LMS_MAX_LABEL_LEN
+#define LMS_MAX_LABEL_LEN           32
+#endif
+
 struct LmsKey {
     /* Public key. */
     ALIGN16 byte pub[HSS_PUBLIC_KEY_LEN(LMS_MAX_NODE_LEN)];
@@ -574,6 +581,16 @@ struct LmsKey {
 #ifdef WOLF_CRYPTO_CB
     /* Device Identifier. */
     int devId;
+    /* Per-device opaque context, populated by the callback. */
+    void* devCtx;
+#endif
+#ifdef WOLF_PRIVATE_KEY_ID
+    /* Optional device-side key identifier. */
+    byte id[LMS_MAX_ID_LEN];
+    int  idLen;
+    /* Optional device-side key label. */
+    char label[LMS_MAX_LABEL_LEN];
+    int  labelLen;
 #endif
 };
 
diff --git a/wolfssl/wolfcrypt/wc_xmss.h b/wolfssl/wolfcrypt/wc_xmss.h
@@ -205,6 +205,13 @@ typedef struct XmssParams {
     word8  bds_k;
 } XmssParams;
 
+#ifndef XMSS_MAX_ID_LEN
+#define XMSS_MAX_ID_LEN              32
+#endif
+#ifndef XMSS_MAX_LABEL_LEN
+#define XMSS_MAX_LABEL_LEN           32
+#endif
+
 struct XmssKey {
     /* Public key. */
     unsigned char        pk[2 * WC_XMSS_MAX_N];
@@ -231,6 +238,16 @@ struct XmssKey {
 #ifdef WOLF_CRYPTO_CB
     /* Device Identifier. */
     int                  devId;
+    /* Per-device opaque context, populated by the callback. */
+    void*                devCtx;
+#endif
+#ifdef WOLF_PRIVATE_KEY_ID
+    /* Optional device-side key identifier. */
+    byte                 id[XMSS_MAX_ID_LEN];
+    int                  idLen;
+    /* Optional device-side key label. */
+    char                 label[XMSS_MAX_LABEL_LEN];
+    int                  labelLen;
 #endif
 };
 
diff --git a/wolfssl/wolfcrypt/xmss.h b/wolfssl/wolfcrypt/xmss.h
@@ -170,6 +170,12 @@ typedef enum wc_XmssRc (*wc_xmss_read_private_key_cb)(byte* priv, word32 privSz,
 #endif
 
 WOLFSSL_API int  wc_XmssKey_Init(XmssKey* key, void* heap, int devId);
+#ifdef WOLF_PRIVATE_KEY_ID
+WOLFSSL_API int  wc_XmssKey_InitId(XmssKey* key, const unsigned char* id,
+    int len, void* heap, int devId);
+WOLFSSL_API int  wc_XmssKey_InitLabel(XmssKey* key, const char* label,
+    void* heap, int devId);
+#endif
 WOLFSSL_API int  wc_XmssKey_SetParamStr(XmssKey* key, const char* str);
 #ifndef WOLFSSL_XMSS_VERIFY_ONLY
 WOLFSSL_API int  wc_XmssKey_SetWriteCb(XmssKey* key,
