HashSLH-DSA APIs now take the pre-hashed digest, not the raw message

wc_SlhDsaKey_{Sign,Verify}Hash* previously accepted the raw message and
performed the pre-hash internally. They now require the caller to hash the
message first and pass the resulting digest -- the functions no longer call
wc_*Hash() themselves and feed the supplied digest directly into the M'
construction. Parameters are renamed from msg/msgSz to hash/hashSz to reflect
this, and hashSz is validated against wc_HashGetDigestSize(hashType) per
FIPS 205 Section 10.2.2 (32 for SHAKE128, 64 for SHAKE256), returning
BAD_LENGTH_E on mismatch.

This matches ML-DSA's wc_dilithium_{sign,verify}_ctx_hash, NIST ACVP
signatureInterface=external / preHash=preHash vectors, and other libraries
(OpenSSL HASH-ML-DSA, leancrypto, mldsa-native). It also enables distributed
signers and HSM-style flows where the digest is computed separately from the
signing operation.

Migration: callers must now hash the message before invoking these APIs;
passing the raw message will either fail length validation or produce
signatures over the wrong input. The M'-supplied wc_SlhDsaKey_SignMsg* /
VerifyMsg family (FIPS 205 internal interface, Algorithms 19/20) is
unchanged but gains stricter input validation and doxygen coverage.

Author: Frauschi

ChangeLog.md

@@ -2,6 +2,22 @@
 
 ## Enhancements
 
+* **BREAKING (FIPS 205 SLH-DSA)**: `wc_SlhDsaKey_SignHash`,
+  `wc_SlhDsaKey_SignHashDeterministic`, `wc_SlhDsaKey_SignHashWithRandom`, and
+  `wc_SlhDsaKey_VerifyHash` now take the **caller-pre-hashed message digest**
+  via `hash`/`hashSz` parameters (renamed from `msg`/`msgSz`), aligned with
+  ML-DSA's `wc_dilithium_sign_ctx_hash` / `wc_dilithium_verify_ctx_hash`
+  semantics, and NIST ACVP `signatureInterface=external` / `preHash=preHash`
+  test vectors. `hashSz` must equal `wc_HashGetDigestSize(hashType)` (32 bytes
+  for SHAKE128, 64 bytes for SHAKE256 per FIPS 205 Section 10.2.2); otherwise
+  `BAD_LENGTH_E` is returned. Migration: hash the message yourself before the
+  call (callers using positional arguments are source-compatible; only the
+  parameter names changed). The pre-existing `wc_SlhDsaKey_SignMsgDeterministic`
+  and `wc_SlhDsaKey_SignMsgWithRandom` (FIPS 205 internal interface, M'
+  supplied directly) are unaffected and gain stricter input validation
+  matching the `*Hash*` family. `wc_SlhDsaKey_VerifyMsg` is unchanged. All
+  three gain doxygen coverage.
+
 * TLS 1.3: zero traffic key staging buffers in `SetKeysSide()` once a
   CryptoCB callback has imported the AES key into a Secure Element
   (`aes->devCtx != NULL`).  Clears `keys->{client,server}_write_key`

doc/dox_comments/header_files/wc_slhdsa.h

@@ -302,15 +302,19 @@ int wc_SlhDsaKey_Verify(SlhDsaKey* key, const byte* ctx,
 
     \brief Signs using the SLH-DSA internal interface with deterministic
     randomness. Unlike the external interface, M' is provided directly by
-    the caller — no 0x00||len(ctx)||ctx||M wrapping is performed. This
-    corresponds to FIPS 205 Algorithm 19 (slh_sign_internal) with opt_rand
-    set to PK.seed.
+    the caller — no wrapping is performed. This corresponds to FIPS 205
+    Algorithm 19 (slh_sign_internal) with opt_rand set to PK.seed.
 
-    Use this when the CAVP test framework or protocol layer has already
-    constructed M'.
+    Use this when the ACVP signatureInterface=internal test framework or a
+    protocol layer has already constructed M'. For HashSLH-DSA the caller
+    builds M' as 0x01 || ctxSz || ctx || OID(hashType) || PHM and passes it
+    in here, where PHM is the hash of the application message under hashType.
 
     \return 0 on success.
     \return BAD_FUNC_ARG if key, mprime, sig, or sigSz is NULL.
+    \return BAD_LENGTH_E if sigSz is less than the parameter set's signature
+    length.
+    \return MISSING_KEY if the private key has not been set.
 
     \param [in] key Pointer to a private SlhDsaKey.
     \param [in] mprime Pointer to the pre-constructed M' message.
@@ -334,6 +338,7 @@ int wc_SlhDsaKey_Verify(SlhDsaKey* key, const byte* ctx,
     \sa wc_SlhDsaKey_SignMsgWithRandom
     \sa wc_SlhDsaKey_VerifyMsg
     \sa wc_SlhDsaKey_SignDeterministic
+    \sa wc_SlhDsaKey_SignHashDeterministic
 */
 int wc_SlhDsaKey_SignMsgDeterministic(SlhDsaKey* key,
     const byte* mprime, word32 mprimeSz, byte* sig, word32* sigSz);
@@ -344,10 +349,14 @@ int wc_SlhDsaKey_SignMsgDeterministic(SlhDsaKey* key,
     \brief Signs using the SLH-DSA internal interface with caller-provided
     additional randomness. M' is provided directly — no wrapping is performed.
     This corresponds to FIPS 205 Algorithm 19 (slh_sign_internal) with an
-    explicit opt_rand value.
+    explicit opt_rand value. See wc_SlhDsaKey_SignMsgDeterministic for the M'
+    layout used by HashSLH-DSA.
 
     \return 0 on success.
     \return BAD_FUNC_ARG if key, mprime, sig, sigSz, or addRnd is NULL.
+    \return BAD_LENGTH_E if sigSz is less than the parameter set's signature
+    length.
+    \return MISSING_KEY if the private key has not been set.
 
     \param [in] key Pointer to a private SlhDsaKey.
     \param [in] mprime Pointer to the pre-constructed M' message.
@@ -373,6 +382,7 @@ int wc_SlhDsaKey_SignMsgDeterministic(SlhDsaKey* key,
 
     \sa wc_SlhDsaKey_SignMsgDeterministic
     \sa wc_SlhDsaKey_VerifyMsg
+    \sa wc_SlhDsaKey_SignHashWithRandom
 */
 int wc_SlhDsaKey_SignMsgWithRandom(SlhDsaKey* key,
     const byte* mprime, word32 mprimeSz, byte* sig, word32* sigSz,
@@ -412,29 +422,36 @@ int wc_SlhDsaKey_SignMsgWithRandom(SlhDsaKey* key,
 
     \sa wc_SlhDsaKey_SignMsgDeterministic
     \sa wc_SlhDsaKey_Verify
+    \sa wc_SlhDsaKey_VerifyHash
 */
 int wc_SlhDsaKey_VerifyMsg(SlhDsaKey* key, const byte* mprime,
     word32 mprimeSz, const byte* sig, word32 sigSz);
 
 /*!
     \ingroup SLH_DSA
 
-    \brief Signs a pre-hashed message using the SLH-DSA external (HashSLH-DSA)
-    interface with deterministic randomness. The message is hashed with the
-    specified hash algorithm, then signed per FIPS 205 Algorithm 22 with the
-    pre-hash domain separator (0x01).
+    \brief Signs a caller-pre-hashed message digest using the SLH-DSA external
+    (HashSLH-DSA) interface with deterministic randomness, per FIPS 205
+    Algorithm 23 with the pre-hash domain separator (0x01). The caller must
+    hash the application message with hashType first and pass the digest as
+    hash; this function does NOT hash its input.
 
     \return 0 on success.
-    \return BAD_FUNC_ARG if key, msg, sig, or sigSz is NULL, or hashType
-    is unsupported.
+    \return BAD_FUNC_ARG if key, hash, sig, or sigSz is NULL.
+    \return BAD_LENGTH_E if hashSz does not equal the digest size for hashType
+    (32 for SHAKE128, 64 for SHAKE256 per FIPS 205 Section 10.2.2).
+    \return NOT_COMPILED_IN if hashType is not supported in this build.
+    \return MISSING_KEY if the private key has not been set.
 
     \param [in] key Pointer to a private SlhDsaKey.
     \param [in] ctx Context string. May be NULL if ctxSz is 0.
     \param [in] ctxSz Length of the context string (0-255).
-    \param [in] msg Pointer to the message to hash and sign.
-    \param [in] msgSz Length of the message.
-    \param [in] hashType Hash algorithm to use for pre-hashing. Supported:
-    WC_HASH_TYPE_SHA256, WC_HASH_TYPE_SHA384, WC_HASH_TYPE_SHA512,
+    \param [in] hash Pointer to the pre-hashed message digest. hashSz must
+    equal the digest size for hashType.
+    \param [in] hashSz Length of the digest in bytes.
+    \param [in] hashType Hash algorithm used for pre-hashing (selects OID).
+    Supported: WC_HASH_TYPE_SHA224, WC_HASH_TYPE_SHA256, WC_HASH_TYPE_SHA384,
+    WC_HASH_TYPE_SHA512, WC_HASH_TYPE_SHA512_224, WC_HASH_TYPE_SHA512_256,
     WC_HASH_TYPE_SHAKE128, WC_HASH_TYPE_SHAKE256, WC_HASH_TYPE_SHA3_224,
     WC_HASH_TYPE_SHA3_256, WC_HASH_TYPE_SHA3_384, WC_HASH_TYPE_SHA3_512.
     \param [out] sig Buffer to receive the signature.
@@ -447,92 +464,116 @@ int wc_SlhDsaKey_VerifyMsg(SlhDsaKey* key, const byte* mprime,
     byte sig[WC_SLHDSA_MAX_SIG_LEN];
     word32 sigSz = sizeof(sig);
     byte msg[] = "Hello World!";
+    byte digest[WC_SHA256_DIGEST_SIZE];
     int ret;
 
+    wc_Sha256Hash(msg, sizeof(msg), digest);
     ret = wc_SlhDsaKey_SignHashDeterministic(&key, NULL, 0,
-        msg, sizeof(msg), WC_HASH_TYPE_SHA256, sig, &sigSz);
+        digest, sizeof(digest), WC_HASH_TYPE_SHA256, sig, &sigSz);
     \endcode
 
     \sa wc_SlhDsaKey_SignHashWithRandom
     \sa wc_SlhDsaKey_SignHash
     \sa wc_SlhDsaKey_VerifyHash
+    \sa wc_SlhDsaKey_SignMsgDeterministic
 */
 int wc_SlhDsaKey_SignHashDeterministic(SlhDsaKey* key,
-    const byte* ctx, byte ctxSz, const byte* msg, word32 msgSz,
+    const byte* ctx, byte ctxSz, const byte* hash, word32 hashSz,
     enum wc_HashType hashType, byte* sig, word32* sigSz);
 
 /*!
     \ingroup SLH_DSA
 
-    \brief Signs a pre-hashed message using the SLH-DSA external (HashSLH-DSA)
-    interface with caller-provided additional randomness.
+    \brief Signs a caller-pre-hashed message digest using the SLH-DSA external
+    (HashSLH-DSA) interface with caller-provided additional randomness. The
+    caller must hash the application message with hashType first and pass the
+    digest as hash; this function does NOT hash its input.
 
     \return 0 on success.
-    \return BAD_FUNC_ARG if key, msg, sig, sigSz, or addRnd is NULL.
+    \return BAD_FUNC_ARG if key, hash, sig, sigSz, or addRnd is NULL.
+    \return BAD_LENGTH_E if hashSz does not equal the digest size for hashType
+    (32 for SHAKE128, 64 for SHAKE256 per FIPS 205 Section 10.2.2).
+    \return NOT_COMPILED_IN if hashType is not supported in this build.
 
     \param [in] key Pointer to a private SlhDsaKey.
     \param [in] ctx Context string. May be NULL if ctxSz is 0.
     \param [in] ctxSz Length of the context string (0-255).
-    \param [in] msg Pointer to the message to hash and sign.
-    \param [in] msgSz Length of the message.
-    \param [in] hashType Hash algorithm to use for pre-hashing.
+    \param [in] hash Pointer to the pre-hashed message digest. hashSz must
+    equal the digest size for hashType.
+    \param [in] hashSz Length of the digest in bytes.
+    \param [in] hashType Hash algorithm used for pre-hashing (selects OID).
     \param [out] sig Buffer to receive the signature.
     \param [in,out] sigSz On input, size of sig buffer. On output, actual
     signature length.
     \param [in] addRnd Additional randomness (n bytes).
 
     \sa wc_SlhDsaKey_SignHashDeterministic
     \sa wc_SlhDsaKey_VerifyHash
+    \sa wc_SlhDsaKey_SignMsgWithRandom
 */
 int wc_SlhDsaKey_SignHashWithRandom(SlhDsaKey* key,
-    const byte* ctx, byte ctxSz, const byte* msg, word32 msgSz,
+    const byte* ctx, byte ctxSz, const byte* hash, word32 hashSz,
     enum wc_HashType hashType, byte* sig, word32* sigSz, byte* addRnd);
 
 /*!
     \ingroup SLH_DSA
 
-    \brief Signs a pre-hashed message using the SLH-DSA external (HashSLH-DSA)
-    interface with RNG-provided randomness.
+    \brief Signs a caller-pre-hashed message digest using the SLH-DSA external
+    (HashSLH-DSA) interface with RNG-provided randomness. The caller must
+    hash the application message with hashType first and pass the digest as
+    hash; this function does NOT hash its input.
 
     \return 0 on success.
-    \return BAD_FUNC_ARG if key, msg, sig, sigSz, or rng is NULL.
+    \return BAD_FUNC_ARG if key, hash, sig, sigSz, or rng is NULL.
+    \return BAD_LENGTH_E if hashSz does not equal the digest size for hashType
+    (32 for SHAKE128, 64 for SHAKE256 per FIPS 205 Section 10.2.2).
+    \return NOT_COMPILED_IN if hashType is not supported in this build.
 
     \param [in] key Pointer to a private SlhDsaKey.
     \param [in] ctx Context string. May be NULL if ctxSz is 0.
     \param [in] ctxSz Length of the context string (0-255).
-    \param [in] msg Pointer to the message to hash and sign.
-    \param [in] msgSz Length of the message.
-    \param [in] hashType Hash algorithm to use for pre-hashing.
+    \param [in] hash Pointer to the pre-hashed message digest. hashSz must
+    equal the digest size for hashType.
+    \param [in] hashSz Length of the digest in bytes.
+    \param [in] hashType Hash algorithm used for pre-hashing (selects OID).
     \param [out] sig Buffer to receive the signature.
     \param [in,out] sigSz On input, size of sig buffer. On output, actual
     signature length.
     \param [in] rng Pointer to an initialized WC_RNG.
 
     \sa wc_SlhDsaKey_SignHashDeterministic
     \sa wc_SlhDsaKey_VerifyHash
+    \sa wc_SlhDsaKey_SignMsgDeterministic
 */
 int wc_SlhDsaKey_SignHash(SlhDsaKey* key, const byte* ctx,
-    byte ctxSz, const byte* msg, word32 msgSz, enum wc_HashType hashType,
+    byte ctxSz, const byte* hash, word32 hashSz, enum wc_HashType hashType,
     byte* sig, word32* sigSz, WC_RNG* rng);
 
 /*!
     \ingroup SLH_DSA
 
-    \brief Verifies an SLH-DSA signature over a pre-hashed message
-    (HashSLH-DSA). The message is hashed with the specified hash algorithm
-    before verification.
+    \brief Verifies an SLH-DSA signature using the external HashSLH-DSA
+    interface (FIPS 205 Algorithm 24). The caller must hash the application
+    message with hashType first and pass the digest as hash; this function
+    does NOT hash its input.
 
     \return 0 on success (signature valid).
-    \return BAD_FUNC_ARG if key, msg, or sig is NULL.
+    \return BAD_FUNC_ARG if key, hash, or sig is NULL.
+    \return BAD_LENGTH_E if sigSz does not match the parameter set, or if
+    hashSz does not equal the digest size for hashType (32 for SHAKE128, 64
+    for SHAKE256 per FIPS 205 Section 10.2.2).
+    \return NOT_COMPILED_IN if hashType is not supported in this build.
+    \return MISSING_KEY if the public key has not been set.
     \return SIG_VERIFY_E if the signature is invalid.
 
     \param [in] key Pointer to a public SlhDsaKey.
     \param [in] ctx Context string. May be NULL if ctxSz is 0.
     \param [in] ctxSz Length of the context string (0-255).
-    \param [in] msg Pointer to the message to hash and verify.
-    \param [in] msgSz Length of the message.
-    \param [in] hashType Hash algorithm used for pre-hashing. Must match the
-    hash used during signing.
+    \param [in] hash Pointer to the pre-hashed message digest. hashSz must
+    equal the digest size for hashType.
+    \param [in] hashSz Length of the digest in bytes.
+    \param [in] hashType Hash algorithm used for pre-hashing (selects OID).
+    Must match the hash used during signing.
     \param [in] sig Pointer to the signature to verify.
     \param [in] sigSz Length of the signature.
 
@@ -542,20 +583,23 @@ int wc_SlhDsaKey_SignHash(SlhDsaKey* key, const byte* ctx,
     byte sig[...];
     word32 sigSz;
     byte msg[] = "Hello World!";
+    byte digest[WC_SHA256_DIGEST_SIZE];
     int ret;
 
+    wc_Sha256Hash(msg, sizeof(msg), digest);
     ret = wc_SlhDsaKey_VerifyHash(&key, NULL, 0,
-        msg, sizeof(msg), WC_HASH_TYPE_SHA256, sig, sigSz);
+        digest, sizeof(digest), WC_HASH_TYPE_SHA256, sig, sigSz);
     if (ret == 0) {
         // signature is valid
     }
     \endcode
 
     \sa wc_SlhDsaKey_SignHashDeterministic
     \sa wc_SlhDsaKey_Verify
+    \sa wc_SlhDsaKey_VerifyMsg
 */
 int wc_SlhDsaKey_VerifyHash(SlhDsaKey* key, const byte* ctx,
-    byte ctxSz, const byte* msg, word32 msgSz, enum wc_HashType hashType,
+    byte ctxSz, const byte* hash, word32 hashSz, enum wc_HashType hashType,
     const byte* sig, word32 sigSz);
 
 /*!