slhdsa: round-3 review fixes

1. wc_SlhDsaKey_Free: make double-free / cryptocb-recursive-free safe.
   - NULL out key->params at the end so a second Free is a no-op.
   - Lift the cryptocb-free dispatch above the SW-cleanup gate and
     re-check params!=NULL before the SHAKE/SHA2 teardown. The test
     pattern in myCryptoDevCb (mirroring dilithium) recursively calls
     wc_SlhDsaKey_Free from the device callback; the inner call now
     does the SW cleanup once and zeroes params, the outer skips, and
     wc_Shake256_Free no longer relies on idempotence to survive a
     re-Free.
2. Drop the stale 'with-digest' doc-block above slhdsakey_signhash_external
   left over from the round-2 helper extraction (the function takes a
   raw msg + hashType, not a precomputed digest).
3. wc_SlhDsaKey_Init_id: document the BAD_FUNC_ARG return for
   (id == NULL, len > 0).
4. wc_SlhDsaKey_Init_label: document the XSTRLEN-based length contract
   and embedded-NUL truncation.
5. wc_SlhDsaKey_MakeKey cryptocb hook: comment the per-algorithm
   meaning of pqc_sig_kg.size. ML-DSA uses NIST level, SLH-DSA uses
   enum SlhDsaParam (a single security level maps to two parameter
   sets, S vs F, that callers must distinguish). Devices keying off
   WC_PQC_SIG_TYPE_SLHDSA must interpret size as enum SlhDsaParam.
6. slhdsa_id_label_test: zero the stack key up-front so rejection-path
   tests don't read uninitialized fields if a future Init refactor
   changes the moment of zeroization.

Author: claude

wolfcrypt/src/wc_slhdsa.c

@@ -6613,7 +6613,7 @@ int wc_SlhDsaKey_Init(SlhDsaKey* key, enum SlhDsaParam param, void* heap,
  * @param [in] heap   Dynamic memory allocation hint.
  * @param [in] devId  Device Id.
  * @return  0 on success.
- * @return  BAD_FUNC_ARG when key is NULL.
+ * @return  BAD_FUNC_ARG when key is NULL or when id is NULL with len > 0.
  * @return  BUFFER_E when len is negative or larger than SLHDSA_MAX_ID_LEN.
  */
 int wc_SlhDsaKey_Init_id(SlhDsaKey* key, enum SlhDsaParam param,
@@ -6647,7 +6647,9 @@ int wc_SlhDsaKey_Init_id(SlhDsaKey* key, enum SlhDsaParam param,
 
 /* Initialize an SLH-DSA key with a device key label.
  *
- * Mirrors wc_dilithium_init_label.
+ * Mirrors wc_dilithium_init_label. Label length is taken via XSTRLEN, so
+ * the label must be NUL-terminated and an embedded NUL terminates the
+ * effective label; bytes past the first NUL are ignored.
  *
  * @param [in] key    SLH-DSA key.
  * @param [in] param  SLH-DSA parameter set to use.
@@ -6700,16 +6702,20 @@ void wc_SlhDsaKey_Free(SlhDsaKey* key)
      * is a reliable signal that devId is meaningful. Releasing the
      * device-side handle on a never-initialized key (devId == garbage from
      * stack) would dispatch to whatever device happens to match. */
-    if (key->params != NULL) {
 #if defined(WOLF_CRYPTO_CB) && defined(WOLF_CRYPTO_CB_FREE)
-        if (key->devId != INVALID_DEVID) {
-            (void)wc_CryptoCb_Free(key->devId, WC_ALGO_TYPE_PK,
-                                   WC_PK_TYPE_PQC_SIG_KEYGEN,
-                                   WC_PQC_SIG_TYPE_SLHDSA,
-                                   (void*)key);
-            /* always continue to software cleanup */
-        }
+    if ((key->params != NULL) && (key->devId != INVALID_DEVID)) {
+        (void)wc_CryptoCb_Free(key->devId, WC_ALGO_TYPE_PK,
+                               WC_PK_TYPE_PQC_SIG_KEYGEN,
+                               WC_PQC_SIG_TYPE_SLHDSA,
+                               (void*)key);
+        /* The device callback may itself recursively call wc_SlhDsaKey_Free
+         * (this is the test pattern in myCryptoDevCb, mirroring dilithium).
+         * The recursive Free runs the SW cleanup once and zeroes params;
+         * checking params!=NULL again below skips a double teardown. */
+    }
 #endif
+
+    if (key->params != NULL) {
         /* Ensure the private key data is zeroized. */
         ForceZero(key->sk, (size_t)key->params->n * 2);
 #ifdef WOLFSSL_SLHDSA_SHA2
@@ -6757,6 +6763,12 @@ void wc_SlhDsaKey_Free(SlhDsaKey* key)
     key->devCtx = NULL;
     key->devId = INVALID_DEVID;
 #endif
+    /* Clearing params last makes a second wc_SlhDsaKey_Free a no-op (the
+     * params!=NULL gate above will skip the SHAKE/SHA2 teardown that has
+     * already run). It also means the cryptocb-driven recursive Free path
+     * does the SW cleanup exactly once: the inner call zeroes params, the
+     * outer call sees params==NULL and skips. */
+    key->params = NULL;
 }
 
 /* Set the HashAddress based on message digest data.
@@ -6875,6 +6887,13 @@ int wc_SlhDsaKey_MakeKey(SlhDsaKey* key, WC_RNG* rng)
         if (key->devId != INVALID_DEVID)
     #endif
         {
+            /* The cryptocb pqc_sig_kg.size field is overloaded per
+             * algorithm: ML-DSA passes the NIST level (2/3/5), SLH-DSA
+             * passes the parameter-set enum (enum SlhDsaParam) since a
+             * single security level (n=16/24/32) corresponds to two
+             * parameter sets ("S" / "F") that callers must distinguish.
+             * Devices keying off WC_PQC_SIG_TYPE_SLHDSA must interpret
+             * size as enum SlhDsaParam, not as an ML-DSA-style level. */
             ret = wc_CryptoCb_MakePqcSignatureKey(rng,
                 WC_PQC_SIG_TYPE_SLHDSA, (int)key->params->param, key);
             if (ret != WC_NO_ERR_TRACE(CRYPTOCB_UNAVAILABLE))
@@ -7979,11 +7998,6 @@ static int slhdsakey_prehash_msg(const byte* msg, word32 msgSz,
  * @return  MEMORY_E on dynamic memory allocation failure.
  * @return  SHAKE-256 error return code on digest failure.
  */
-/* Pre-hash SLH-DSA sign given an already-computed digest+OID.
- *
- * Caller must have validated key/ctx/sig and pre-hashed msg via
- * slhdsakey_prehash_msg.
- */
 static int slhdsakey_signhash_external(SlhDsaKey* key, const byte* ctx,
     byte ctxSz, const byte* msg, word32 msgSz, enum wc_HashType hashType,
     byte* sig, word32* sigSz, byte* addRnd)

wolfcrypt/test/test.c

@@ -54527,6 +54527,11 @@ static wc_test_ret_t slhdsa_id_label_test(void)
         SLHDSA_SHAKE128F;
 #endif
 
+    /* Zero the stack key so rejection-path tests below don't read
+     * uninitialized fields if a future Init refactor inspects key state
+     * before zeroizing it. */
+    XMEMSET(&key, 0, sizeof(key));
+
     /* NULL key rejected. */
     ret = wc_SlhDsaKey_Init_id(NULL, param, id, (int)sizeof(id), HEAP_HINT,
         INVALID_DEVID);