pq_crypto 0.6.1 → 0.6.2

data/ext/pqcrypto/vendor/mldsa-native/mldsa/mldsa_native.h

@@ -132,6 +132,11 @@
 /* An rng failure occured. Might be due to insufficient entropy or
  * system misconfiguration. */
 #define MLD_ERR_RNG_FAIL -3
+/* The signing rejection-sampling loop exceeded
+ * MLD_CONFIG_MAX_SIGNING_ATTEMPTS iterations without producing a valid
+ * signature. With a FIPS 204 Appendix C compliant bound (>= 814) this
+ * has probability < 2^-256. */
+#define MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED -4
 
 /****************************** Function API **********************************/
 
@@ -205,32 +210,38 @@ extern "C"
 {
 #endif
 
-/*************************************************
- * Name:        crypto_sign_keypair_internal
- *
- * Description: Generates public and private key. Internal API.
- *              When MLD_CONFIG_KEYGEN_PCT is set, performs a Pairwise
- *              Consistency Test (PCT) as required by FIPS 140-3 IG.
- *
- * Arguments:
- *     - uint8_t pk[MLDSA_PUBLICKEYBYTES(MLD_CONFIG_API_PARAMETER_SET)]:
- *           output public key
- *     - uint8_t sk[MLDSA_SECRETKEYBYTES(MLD_CONFIG_API_PARAMETER_SET)]:
- *           output private key
- *     - const uint8_t seed[MLDSA_SEEDBYTES]:
- *           input random seed
- *
- * Returns:
- *     - 0: Success
- *     - MLD_ERR_OUT_OF_MEMORY: If MLD_CONFIG_CUSTOM_ALLOC_FREE is
- *         used and an allocation via MLD_CUSTOM_ALLOC returned NULL.
- *     - MLD_ERR_RNG_FAIL: Random number generation failed.
- *     - MLD_ERR_FAIL: Other kinds of failure, incl. PCT failure
- *         if MLD_CONFIG_KEYGEN_PCT is enabled.
- *
- * Specification: Implements @[FIPS204 Algorithm 6 (ML-DSA.KeyGen_internal)]
- *
- **************************************************/
+#if !defined(MLD_CONFIG_NO_KEYPAIR_API)
+/**
+ * Generate a public-private key pair from a seed.
+ *
+ * When MLD_CONFIG_KEYGEN_PCT is set, performs a Pairwise Consistency Test
+ * (PCT) as required by FIPS 140-3 IG.
+ *
+ * @warning The seed must be generated by a cryptographically secure random
+ *          number generator.
+ *
+ * @spec{Implements @[FIPS204 Algorithm 6 (ML-DSA.KeyGen_internal)].}
+ *
+ * @param[out] pk      Output public key.
+ * @param[out] sk      Output private key.
+ * @param[in]  seed    Input random seed.
+ * @param      context Application context. Only present when
+ *                     MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                     MLD_CONFIG_CONTEXT_PARAMETER_TYPE.
+ *
+ * @retval 0                               Success.
+ * @retval MLD_ERR_OUT_OF_MEMORY           MLD_CONFIG_CUSTOM_ALLOC_FREE was
+ *                                         used and an allocation via
+ *                                         MLD_CUSTOM_ALLOC returned NULL.
+ * @retval MLD_ERR_RNG_FAIL                Random number generation failed.
+ * @retval MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED The PCT's signing step exhausted
+ *                                         MLD_CONFIG_MAX_SIGNING_ATTEMPTS
+ *                                         iterations. Only possible when
+ *                                         MLD_CONFIG_KEYGEN_PCT is enabled.
+ * @retval MLD_ERR_FAIL                    Other kinds of failure, including
+ *                                         PCT failure if
+ *                                         MLD_CONFIG_KEYGEN_PCT is enabled.
+ */
 MLD_API_QUALIFIER
 MLD_API_MUST_CHECK_RETURN_VALUE
 int MLD_API_NAMESPACE(keypair_internal)(
@@ -243,29 +254,33 @@ int MLD_API_NAMESPACE(keypair_internal)(
 #endif
 );
 
-/*************************************************
- * Name:        crypto_sign_keypair
- *
- * Description: Generates public and private key.
- *              When MLD_CONFIG_KEYGEN_PCT is set, performs a Pairwise
- *              Consistency Test (PCT) as required by FIPS 140-3 IG.
- *
- * Arguments:
- *     - uint8_t pk[MLDSA_PUBLICKEYBYTES(MLD_CONFIG_API_PARAMETER_SET)]:
- *           output public key
- *     - uint8_t sk[MLDSA_SECRETKEYBYTES(MLD_CONFIG_API_PARAMETER_SET)]:
- *           output private key
- *
- * Returns: - 0: Success
- *          - MLD_ERR_OUT_OF_MEMORY: If MLD_CONFIG_CUSTOM_ALLOC_FREE is
- *              used and an allocation via MLD_CUSTOM_ALLOC returned NULL.
- *          - MLD_ERR_RNG_FAIL: Random number generation failed.
- *          - MLD_ERR_FAIL: If MLD_CONFIG_KEYGEN_PCT is enabled and the
- *              PCT check failed.
- *
- * Specification: Implements @[FIPS204 Algorithm 1 (ML-DSA.KeyGen)]
- *
- **************************************************/
+#if !defined(MLD_CONFIG_CORE_API_ONLY)
+/**
+ * Generate a public-private key pair.
+ *
+ * When MLD_CONFIG_KEYGEN_PCT is set, performs a Pairwise Consistency Test
+ * (PCT) as required by FIPS 140-3 IG.
+ *
+ * @spec{Implements @[FIPS204 Algorithm 1 (ML-DSA.KeyGen)].}
+ *
+ * @param[out] pk      Output public key.
+ * @param[out] sk      Output private key.
+ * @param      context Application context. Only present when
+ *                     MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                     MLD_CONFIG_CONTEXT_PARAMETER_TYPE.
+ *
+ * @retval 0                               Success.
+ * @retval MLD_ERR_OUT_OF_MEMORY           MLD_CONFIG_CUSTOM_ALLOC_FREE was
+ *                                         used and an allocation via
+ *                                         MLD_CUSTOM_ALLOC returned NULL.
+ * @retval MLD_ERR_RNG_FAIL                Random number generation failed.
+ * @retval MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED The PCT's signing step exhausted
+ *                                         MLD_CONFIG_MAX_SIGNING_ATTEMPTS
+ *                                         iterations. Only possible when
+ *                                         MLD_CONFIG_KEYGEN_PCT is enabled.
+ * @retval MLD_ERR_FAIL                    MLD_CONFIG_KEYGEN_PCT is enabled and
+ *                                         the PCT check failed.
+ */
 MLD_API_QUALIFIER
 MLD_API_MUST_CHECK_RETURN_VALUE
 int MLD_API_NAMESPACE(keypair)(
@@ -276,39 +291,48 @@ int MLD_API_NAMESPACE(keypair)(
     MLD_CONFIG_CONTEXT_PARAMETER_TYPE context
 #endif
 );
-
-/*************************************************
- * Name:        crypto_sign_signature_internal
- *
- * Description: Computes signature. Internal API.
- *
- * Arguments:
- *     - uint8_t sig[MLDSA_BYTES(MLD_CONFIG_API_PARAMETER_SET)]:
- *                           output signature
- *     - size_t *siglen:     pointer to output length of signature
- *     - const uint8_t *m:   pointer to message to be signed
- *     - size_t mlen:        length of message
- *     - const uint8_t *pre: pointer to prefix string
- *     - size_t prelen:      length of prefix string
- *     - const uint8_t rnd[MLDSA_RNDBYTES]:
- *                           random seed
- *     - const uint8_t sk[MLDSA_SECRETKEYBYTES(MLD_CONFIG_API_PARAMETER_SET)]:
- *                           bit-packed secret key
- *     - int externalmu:     indicates input message m is processed as mu
- *
- * Returns:
- *     - 0: Success
- *     - MLD_ERR_OUT_OF_MEMORY: If MLD_CONFIG_CUSTOM_ALLOC_FREE is
- *         used and an allocation via MLD_CUSTOM_ALLOC returned NULL.
- *     - MLD_ERR_FAIL: Other kinds of failure
- *
- * If the returned value is non-zero, then the values of *sig and
- * *siglen should not be referenced.
- *
- * Reference: This code differs from the reference implementation
- *            in that it adds an explicit check for nonce exhaustion
- *            and can return -1 in that case.
- **************************************************/
+#endif /* !MLD_CONFIG_CORE_API_ONLY */
+#endif /* !MLD_CONFIG_NO_KEYPAIR_API */
+
+#if !defined(MLD_CONFIG_NO_SIGN_API)
+/**
+ * Compute signature using a caller-supplied random seed and prefix.
+ *
+ * If the returned value is non-zero, then the values of *sig and *siglen
+ * should not be referenced.
+ *
+ * @spec{Implements @[FIPS204 Algorithm 7 (ML-DSA.Sign_internal)].}
+ *
+ * @param[out] sig        Output signature.
+ * @param[out] siglen     Pointer to output length of signature.
+ * @param[in]  m          Pointer to message to be signed (when
+ *                        externalmu == 0), or to a precomputed
+ *                        message representative mu (when externalmu != 0).
+ * @param      mlen       Length of m. Must equal MLDSA_CRHBYTES when
+ *                        externalmu != 0.
+ * @param[in]  pre        Pointer to prefix string. Ignored when
+ *                        externalmu != 0.
+ * @param      prelen     Length of prefix string. Ignored when
+ *                        externalmu != 0.
+ * @param[in]  rnd        Random seed.
+ * @param[in]  sk         Bit-packed secret key.
+ * @param      externalmu 0: m/mlen is the raw message; mu = H(tr, pre, m) is
+ *                        computed internally.
+ *                        non-zero: m points to a precomputed mu of
+ *                        MLDSA_CRHBYTES bytes; pre/prelen unused.
+ * @param      context    Application context. Only present when
+ *                        MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                        MLD_CONFIG_CONTEXT_PARAMETER_TYPE.
+ *
+ * @retval 0                               Success.
+ * @retval MLD_ERR_OUT_OF_MEMORY           MLD_CONFIG_CUSTOM_ALLOC_FREE was
+ *                                         used and an allocation via
+ *                                         MLD_CUSTOM_ALLOC returned NULL.
+ * @retval MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED The rejection-sampling loop exceeded
+ *                                         MLD_CONFIG_MAX_SIGNING_ATTEMPTS
+ *                                         iterations.
+ * @retval MLD_ERR_FAIL                    Other kinds of failure.
+ */
 MLD_API_QUALIFIER
 MLD_API_MUST_CHECK_RETURN_VALUE
 int MLD_API_NAMESPACE(signature_internal)(
@@ -323,36 +347,35 @@ int MLD_API_NAMESPACE(signature_internal)(
 #endif
 );
 
-/*************************************************
- * Name:        crypto_sign_signature
- *
- * Description: Computes signature. This function implements the randomized
- *              variant of ML-DSA. If you require the deterministic variant,
- *              use crypto_sign_signature_internal directly.
- *
- * Arguments:
- *     - uint8_t sig[MLDSA_BYTES(MLD_CONFIG_API_PARAMETER_SET)]:
- *                           output signature
- *     - size_t *siglen:     pointer to output length of signature
- *     - const uint8_t *m:   pointer to message to be signed
- *     - size_t mlen:        length of message
- *     - const uint8_t *ctx: pointer to context string.
- *                           May be NULL if ctxlen == 0.
- *     - size_t ctxlen:      length of context string.
- *                           Should be <= 255.
- *     - const uint8_t sk[MLDSA_SECRETKEYBYTES(MLD_CONFIG_API_PARAMETER_SET)]:
- *                           bit-packed secret key
- *
- * Returns:
- *     - 0: Success
- *     - MLD_ERR_OUT_OF_MEMORY: If MLD_CONFIG_CUSTOM_ALLOC_FREE is
- *         used and an allocation via MLD_CUSTOM_ALLOC returned NULL.
- *     - MLD_ERR_RNG_FAIL: Random number generation failed.
- *     - MLD_ERR_FAIL: Other kinds of failure.
- *
- * Specification: Implements @[FIPS204 Algorithm 2 (ML-DSA.Sign)]
- *
- **************************************************/
+#if !defined(MLD_CONFIG_CORE_API_ONLY)
+/**
+ * Compute signature. This function implements the randomized variant of
+ * ML-DSA. If you require the deterministic variant, use
+ * crypto_sign_signature_internal directly.
+ *
+ * @spec{Implements @[FIPS204 Algorithm 2 (ML-DSA.Sign)].}
+ *
+ * @param[out] sig     Output signature.
+ * @param[out] siglen  Pointer to output length of signature.
+ * @param[in]  m       Pointer to message to be signed.
+ * @param      mlen    Length of message.
+ * @param[in]  ctx     Pointer to context string. May be NULL if ctxlen == 0.
+ * @param      ctxlen  Length of context string. Should be <= 255.
+ * @param[in]  sk      Bit-packed secret key.
+ * @param      context Application context. Only present when
+ *                     MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                     MLD_CONFIG_CONTEXT_PARAMETER_TYPE.
+ *
+ * @retval 0                               Success.
+ * @retval MLD_ERR_OUT_OF_MEMORY           MLD_CONFIG_CUSTOM_ALLOC_FREE was
+ *                                         used and an allocation via
+ *                                         MLD_CUSTOM_ALLOC returned NULL.
+ * @retval MLD_ERR_RNG_FAIL                Random number generation failed.
+ * @retval MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED The rejection-sampling loop exceeded
+ *                                         MLD_CONFIG_MAX_SIGNING_ATTEMPTS
+ *                                         iterations.
+ * @retval MLD_ERR_FAIL                    Other kinds of failure.
+ */
 MLD_API_QUALIFIER
 MLD_API_MUST_CHECK_RETURN_VALUE
 int MLD_API_NAMESPACE(signature)(
@@ -365,31 +388,33 @@ int MLD_API_NAMESPACE(signature)(
 #endif
 );
 
-/*************************************************
- * Name:        crypto_sign_signature_extmu
- *
- * Description: Computes signature.
- *
- * Arguments:
- *     - uint8_t sig[MLDSA_BYTES(MLD_CONFIG_API_PARAMETER_SET)]:
- *                       output signature
- *     - size_t *siglen: pointer to output length of signature
- *     - const uint8_t mu[MLDSA_CRHBYTES]:
- *                       input mu to be signed
- *     - const uint8_t sk[MLDSA_SECRETKEYBYTES(MLD_CONFIG_API_PARAMETER_SET)]:
- *                       bit-packed secret key
- *
- * Returns:
- *     - 0: Success
- *     - MLD_ERR_OUT_OF_MEMORY: If MLD_CONFIG_CUSTOM_ALLOC_FREE is
- *         used and an allocation via MLD_CUSTOM_ALLOC returned NULL.
- *     - MLD_ERR_RNG_FAIL: Random number generation failed.
- *     - MLD_ERR_FAIL: Other kinds of failure.
- *
- * Specification: Implements @[FIPS204 Algorithm 2 (ML-DSA.Sign external mu
- *                variant)]
- *
- **************************************************/
+/**
+ * Compute signature in "external mu" mode: the caller has already computed
+ * the message representative mu = SHAKE256(tr || M', 64), where
+ * tr = SHAKE256(pk, 64) and M' is the FIPS 204 formatted message (e.g.
+ * 0x00 || ctxlen || ctx || msg for pure ML-DSA). This is useful when the
+ * message is large or streamed and cannot be held in memory.
+ *
+ * @spec{Implements @[FIPS204 Algorithm 2 (ML-DSA.Sign external mu variant)].}
+ *
+ * @param[out] sig     Output signature.
+ * @param[out] siglen  Pointer to output length of signature.
+ * @param[in]  mu      Precomputed message representative.
+ * @param[in]  sk      Bit-packed secret key.
+ * @param      context Application context. Only present when
+ *                     MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                     MLD_CONFIG_CONTEXT_PARAMETER_TYPE.
+ *
+ * @retval 0                               Success.
+ * @retval MLD_ERR_OUT_OF_MEMORY           MLD_CONFIG_CUSTOM_ALLOC_FREE was
+ *                                         used and an allocation via
+ *                                         MLD_CUSTOM_ALLOC returned NULL.
+ * @retval MLD_ERR_RNG_FAIL                Random number generation failed.
+ * @retval MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED The rejection-sampling loop exceeded
+ *                                         MLD_CONFIG_MAX_SIGNING_ATTEMPTS
+ *                                         iterations.
+ * @retval MLD_ERR_FAIL                    Other kinds of failure.
+ */
 MLD_API_QUALIFIER
 MLD_API_MUST_CHECK_RETURN_VALUE
 int MLD_API_NAMESPACE(signature_extmu)(
@@ -402,31 +427,32 @@ int MLD_API_NAMESPACE(signature_extmu)(
 #endif
 );
 
-/*************************************************
- * Name:        crypto_sign
- *
- * Description: Computes signature. This function implements the randomized
- *              variant of ML-DSA. If you require the deterministic variant,
- *              use crypto_sign_signature_internal directly.
- *
- * Arguments:
- *     - uint8_t *sm:        pointer to output signed message (allocated array
- *                           with MLDSA{44,65,87}_BYTES + mlen bytes), can be
- *                           equal to m
- *     - size_t *smlen:      pointer to output length of signed message
- *     - const uint8_t *m:   pointer to message to be signed
- *     - size_t mlen:        length of message
- *     - const uint8_t *ctx: pointer to context string
- *     - size_t ctxlen:      length of context string
- *     - const uint8_t sk[MLDSA_SECRETKEYBYTES(MLD_CONFIG_API_PARAMETER_SET)]:
- *                           bit-packed secret key
- *
- * Returns:
- *     - 0: Success
- *     - MLD_ERR_OUT_OF_MEMORY: If MLD_CONFIG_CUSTOM_ALLOC_FREE is
- *         used and an allocation via MLD_CUSTOM_ALLOC returned NULL.
- *     - MLD_ERR_FAIL: Other kinds of failure
- **************************************************/
+/**
+ * Compute signed message. This function implements the randomized variant of
+ * ML-DSA. If you require the deterministic variant, use
+ * crypto_sign_signature_internal directly.
+ *
+ * @param[out] sm      Pointer to output signed message (allocated array with
+ *                     MLDSA{44,65,87}_BYTES + mlen bytes); can be equal to m.
+ * @param[out] smlen   Pointer to output length of signed message.
+ * @param[in]  m       Pointer to message to be signed.
+ * @param      mlen    Length of message.
+ * @param[in]  ctx     Pointer to context string.
+ * @param      ctxlen  Length of context string.
+ * @param[in]  sk      Bit-packed secret key.
+ * @param      context Application context. Only present when
+ *                     MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                     MLD_CONFIG_CONTEXT_PARAMETER_TYPE.
+ *
+ * @retval 0                               Success.
+ * @retval MLD_ERR_OUT_OF_MEMORY           MLD_CONFIG_CUSTOM_ALLOC_FREE was
+ *                                         used and an allocation via
+ *                                         MLD_CUSTOM_ALLOC returned NULL.
+ * @retval MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED The rejection-sampling loop exceeded
+ *                                         MLD_CONFIG_MAX_SIGNING_ATTEMPTS
+ *                                         iterations.
+ * @retval MLD_ERR_FAIL                    Other kinds of failure.
+ */
 MLD_API_QUALIFIER
 MLD_API_MUST_CHECK_RETURN_VALUE
 int MLD_API_NAMESPACE(sign)(
@@ -438,32 +464,38 @@ int MLD_API_NAMESPACE(sign)(
     MLD_CONFIG_CONTEXT_PARAMETER_TYPE context
 #endif
 );
-
-/*************************************************
- * Name:        crypto_sign_verify_internal
- *
- * Description: Verifies signature. Internal API.
- *
- * Arguments:
- *     - const uint8_t *sig: pointer to input signature
- *     - size_t siglen:      length of signature
- *     - const uint8_t *m:   pointer to message
- *     - size_t mlen:        length of message
- *     - const uint8_t *pre: pointer to prefix string
- *     - size_t prelen:      length of prefix string
- *     - const uint8_t pk[MLDSA_PUBLICKEYBYTES(MLD_CONFIG_API_PARAMETER_SET)]:
- *                           bit-packed public key
- *     - int externalmu:     indicates input message m is processed as mu
- *
- * Returns:
- *     - 0: Success
- *     - MLD_ERR_OUT_OF_MEMORY: If MLD_CONFIG_CUSTOM_ALLOC_FREE is
- *         used and an allocation via MLD_CUSTOM_ALLOC returned NULL.
- *     - MLD_ERR_FAIL: Signature verification failed
- *
- * Specification: Implements @[FIPS204 Algorithm 8 (ML-DSA.Verify_internal)]
- *
- **************************************************/
+#endif /* !MLD_CONFIG_CORE_API_ONLY */
+#endif /* !MLD_CONFIG_NO_SIGN_API */
+
+#if !defined(MLD_CONFIG_NO_VERIFY_API)
+/**
+ * Verify signature. Internal API.
+ *
+ * @spec{Implements @[FIPS204 Algorithm 8 (ML-DSA.Verify_internal)].}
+ *
+ * @param[in] sig        Pointer to input signature.
+ * @param     siglen     Length of signature.
+ * @param[in] m          Pointer to message (when externalmu == 0), or to a
+ *                       precomputed message representative mu (when
+ *                       externalmu != 0).
+ * @param     mlen       Length of m. Must equal MLDSA_CRHBYTES when
+ *                       externalmu != 0.
+ * @param[in] pre        Pointer to prefix string. Ignored when externalmu != 0.
+ * @param     prelen     Length of prefix string. Ignored when externalmu != 0.
+ * @param[in] pk         Bit-packed public key.
+ * @param     externalmu 0: m/mlen is the raw message; mu = H(H(pk), pre, m) is
+ *                       computed internally.
+ *                       non-zero: m points to a precomputed mu of
+ *                       MLDSA_CRHBYTES bytes; pre/prelen unused.
+ * @param     context    Application context. Only present when
+ *                       MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                       MLD_CONFIG_CONTEXT_PARAMETER_TYPE.
+ *
+ * @retval 0                    Success.
+ * @retval MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was used and an
+ *                               allocation via MLD_CUSTOM_ALLOC returned NULL.
+ * @retval MLD_ERR_FAIL          Signature verification failed.
+ */
 MLD_API_QUALIFIER
 MLD_API_MUST_CHECK_RETURN_VALUE
 int MLD_API_NAMESPACE(verify_internal)(
@@ -477,31 +509,28 @@ int MLD_API_NAMESPACE(verify_internal)(
 #endif
 );
 
-/*************************************************
- * Name:        crypto_sign_verify
- *
- * Description: Verifies signature.
- *
- * Arguments:
- *     - const uint8_t *sig: pointer to input signature
- *     - size_t siglen:      length of signature
- *     - const uint8_t *m:   pointer to message
- *     - size_t mlen:        length of message
- *     - const uint8_t *ctx: pointer to context string.
- *                           May be NULL if ctxlen == 0.
- *     - size_t ctxlen:      length of context string
- *     - const uint8_t pk[MLDSA_PUBLICKEYBYTES(MLD_CONFIG_API_PARAMETER_SET)]:
- *                           bit-packed public key
- *
- * Returns:
- *     - 0: Success
- *     - MLD_ERR_OUT_OF_MEMORY: If MLD_CONFIG_CUSTOM_ALLOC_FREE is
- *         used and an allocation via MLD_CUSTOM_ALLOC returned NULL.
- *     - MLD_ERR_FAIL: Signature verification failed
- *
- * Specification: Implements @[FIPS204 Algorithm 3 (ML-DSA.Verify)]
- *
- **************************************************/
+#if !defined(MLD_CONFIG_CORE_API_ONLY)
+/**
+ * Verify signature.
+ *
+ * @spec{Implements @[FIPS204 Algorithm 3 (ML-DSA.Verify)].}
+ *
+ * @param[in] sig     Pointer to input signature.
+ * @param     siglen  Length of signature.
+ * @param[in] m       Pointer to message.
+ * @param     mlen    Length of message.
+ * @param[in] ctx     Pointer to context string. May be NULL if ctxlen == 0.
+ * @param     ctxlen  Length of context string.
+ * @param[in] pk      Bit-packed public key.
+ * @param     context Application context. Only present when
+ *                    MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                    MLD_CONFIG_CONTEXT_PARAMETER_TYPE.
+ *
+ * @retval 0                    Success.
+ * @retval MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was used and an
+ *                               allocation via MLD_CUSTOM_ALLOC returned NULL.
+ * @retval MLD_ERR_FAIL          Signature verification failed.
+ */
 MLD_API_QUALIFIER
 MLD_API_MUST_CHECK_RETURN_VALUE
 int MLD_API_NAMESPACE(verify)(
@@ -514,29 +543,28 @@ int MLD_API_NAMESPACE(verify)(
 #endif
 );
 
-/*************************************************
- * Name:        crypto_sign_verify_extmu
- *
- * Description: Verifies signature.
- *
- * Arguments:
- *     - const uint8_t *sig: pointer to input signature
- *     - size_t siglen:      length of signature
- *     - const uint8_t mu[MLDSA_CRHBYTES]:
- *                           input mu
- *     - const uint8_t pk[MLDSA_PUBLICKEYBYTES(MLD_CONFIG_API_PARAMETER_SET)]:
- *                           bit-packed public key
- *
- * Returns:
- *     - 0: Success
- *     - MLD_ERR_OUT_OF_MEMORY: If MLD_CONFIG_CUSTOM_ALLOC_FREE is
- *         used and an allocation via MLD_CUSTOM_ALLOC returned NULL.
- *     - MLD_ERR_FAIL: Signature verification failed
- *
- * Specification: Implements @[FIPS204 Algorithm 3 (ML-DSA.Verify external mu
- *                variant)]
- *
- **************************************************/
+/**
+ * Verify signature in "external mu" mode: the caller has already computed
+ * the message representative mu = SHAKE256(tr || M', 64), where
+ * tr = SHAKE256(pk, 64) and M' is the FIPS 204 formatted message (e.g.
+ * 0x00 || ctxlen || ctx || msg for pure ML-DSA). The same mu must have
+ * been used at signing time.
+ *
+ * @spec{Implements @[FIPS204 Algorithm 3 (ML-DSA.Verify external mu variant)].}
+ *
+ * @param[in] sig     Pointer to input signature.
+ * @param     siglen  Length of signature.
+ * @param[in] mu      Precomputed message representative.
+ * @param[in] pk      Bit-packed public key.
+ * @param     context Application context. Only present when
+ *                    MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                    MLD_CONFIG_CONTEXT_PARAMETER_TYPE.
+ *
+ * @retval 0                    Success.
+ * @retval MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was used and an
+ *                               allocation via MLD_CUSTOM_ALLOC returned NULL.
+ * @retval MLD_ERR_FAIL          Signature verification failed.
+ */
 MLD_API_QUALIFIER
 MLD_API_MUST_CHECK_RETURN_VALUE
 int MLD_API_NAMESPACE(verify_extmu)(
@@ -548,28 +576,26 @@ int MLD_API_NAMESPACE(verify_extmu)(
 #endif
 );
 
-/*************************************************
- * Name:        crypto_sign_open
- *
- * Description: Verify signed message.
- *
- * Arguments:
- *     - uint8_t *m:         pointer to output message (allocated array with
- *                           smlen bytes), can be equal to sm
- *     - size_t *mlen:       pointer to output length of message
- *     - const uint8_t *sm:  pointer to signed message
- *     - size_t smlen:       length of signed message
- *     - const uint8_t *ctx: pointer to context string
- *     - size_t ctxlen:      length of context string
- *     - const uint8_t pk[MLDSA_PUBLICKEYBYTES(MLD_CONFIG_API_PARAMETER_SET)]:
- *                           bit-packed public key
- *
- * Returns:
- *     - 0: Success
- *     - MLD_ERR_OUT_OF_MEMORY: If MLD_CONFIG_CUSTOM_ALLOC_FREE is
- *         used and an allocation via MLD_CUSTOM_ALLOC returned NULL.
- *     - MLD_ERR_FAIL: Signature verification failed
- **************************************************/
+/**
+ * Verify signed message.
+ *
+ * @param[out] m       Pointer to output message (allocated array with smlen
+ *                     bytes); can be equal to sm.
+ * @param[out] mlen    Pointer to output length of message.
+ * @param[in]  sm      Pointer to signed message.
+ * @param      smlen   Length of signed message.
+ * @param[in]  ctx     Pointer to context string.
+ * @param      ctxlen  Length of context string.
+ * @param[in]  pk      Bit-packed public key.
+ * @param      context Application context. Only present when
+ *                     MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                     MLD_CONFIG_CONTEXT_PARAMETER_TYPE.
+ *
+ * @retval 0                    Success.
+ * @retval MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was used and an
+ *                               allocation via MLD_CUSTOM_ALLOC returned NULL.
+ * @retval MLD_ERR_FAIL          Signature verification failed.
+ */
 MLD_API_QUALIFIER
 MLD_API_MUST_CHECK_RETURN_VALUE
 int MLD_API_NAMESPACE(open)(
@@ -581,10 +607,10 @@ int MLD_API_NAMESPACE(open)(
     MLD_CONFIG_CONTEXT_PARAMETER_TYPE context
 #endif
 );
+#endif /* !MLD_CONFIG_CORE_API_ONLY */
+#endif /* !MLD_CONFIG_NO_VERIFY_API */
 
-/*************************************************
- * Hash algorithm constants for domain separation
- **************************************************/
+/* Hash algorithm constants for domain separation */
 #define MLD_PREHASH_NONE 0
 #define MLD_PREHASH_SHA2_224 1
 #define MLD_PREHASH_SHA2_256 2
@@ -599,41 +625,43 @@ int MLD_API_NAMESPACE(open)(
 #define MLD_PREHASH_SHAKE_128 11
 #define MLD_PREHASH_SHAKE_256 12
 
-/*************************************************
- * Name:        crypto_sign_signature_pre_hash_internal
- *
- * Description: FIPS 204: Algorithm 4 HashML-DSA.Sign.
- *              Computes signature with pre-hashed message.
- *
- * Arguments:
- *     - uint8_t sig[MLDSA_BYTES(MLD_CONFIG_API_PARAMETER_SET)]:
- *                               output signature
- *     - size_t *siglen:         pointer to output length of signature
- *     - const uint8_t *ph:      pointer to pre-hashed message
- *     - size_t phlen:           length of pre-hashed message
- *     - const uint8_t *ctx:     pointer to context string
- *     - size_t ctxlen:          length of context string
- *     - const uint8_t rnd[MLDSA_RNDBYTES]:
- *                               random seed
- *     - const uint8_t sk[MLDSA_SECRETKEYBYTES(MLD_CONFIG_API_PARAMETER_SET)]:
- *                               bit-packed secret key
- *     - int hashalg:            hash algorithm constant (one of MLD_PREHASH_*)
- *
- * Returns:
- *     - 0: Success
- *     - MLD_ERR_OUT_OF_MEMORY: If MLD_CONFIG_CUSTOM_ALLOC_FREE is
- *         used and an allocation via MLD_CUSTOM_ALLOC returned NULL.
- *     - MLD_ERR_FAIL: Other kinds of failure
+#if !defined(MLD_CONFIG_CORE_API_ONLY)
+#if !defined(MLD_CONFIG_NO_SIGN_API)
+/**
+ * FIPS 204: Algorithm 4 HashML-DSA.Sign. Compute signature with pre-hashed
+ * message.
  *
  * Supported hash algorithm constants:
  *   MLD_PREHASH_SHA2_224, MLD_PREHASH_SHA2_256, MLD_PREHASH_SHA2_384,
  *   MLD_PREHASH_SHA2_512, MLD_PREHASH_SHA2_512_224, MLD_PREHASH_SHA2_512_256,
  *   MLD_PREHASH_SHA3_224, MLD_PREHASH_SHA3_256, MLD_PREHASH_SHA3_384,
- *   MLD_PREHASH_SHA3_512, MLD_PREHASH_SHAKE_128, MLD_PREHASH_SHAKE_256
+ *   MLD_PREHASH_SHA3_512, MLD_PREHASH_SHAKE_128, MLD_PREHASH_SHAKE_256.
  *
- * Warning: This is an unstable API that may change in the future. If you need
+ * @warning This is an unstable API that may change in the future. If you need
  * a stable API use crypto_sign_signature_pre_hash_shake256.
- **************************************************/
+ *
+ * @param[out] sig     Output signature.
+ * @param[out] siglen  Pointer to output length of signature.
+ * @param[in]  ph      Pointer to pre-hashed message.
+ * @param      phlen   Length of pre-hashed message.
+ * @param[in]  ctx     Pointer to context string.
+ * @param      ctxlen  Length of context string.
+ * @param[in]  rnd     Random seed.
+ * @param[in]  sk      Bit-packed secret key.
+ * @param      hashalg Hash algorithm constant (one of MLD_PREHASH_*).
+ * @param      context Application context. Only present when
+ *                     MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                     MLD_CONFIG_CONTEXT_PARAMETER_TYPE.
+ *
+ * @retval 0                               Success.
+ * @retval MLD_ERR_OUT_OF_MEMORY           MLD_CONFIG_CUSTOM_ALLOC_FREE was
+ *                                         used and an allocation via
+ *                                         MLD_CUSTOM_ALLOC returned NULL.
+ * @retval MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED The rejection-sampling loop exceeded
+ *                                         MLD_CONFIG_MAX_SIGNING_ATTEMPTS
+ *                                         iterations.
+ * @retval MLD_ERR_FAIL                    Other kinds of failure.
+ */
 MLD_API_QUALIFIER
 MLD_API_MUST_CHECK_RETURN_VALUE
 int MLD_API_NAMESPACE(signature_pre_hash_internal)(
@@ -647,38 +675,39 @@ int MLD_API_NAMESPACE(signature_pre_hash_internal)(
     MLD_CONFIG_CONTEXT_PARAMETER_TYPE context
 #endif
 );
+#endif /* !MLD_CONFIG_NO_SIGN_API */
 
-/*************************************************
- * Name:        crypto_sign_verify_pre_hash_internal
- *
- * Description: FIPS 204: Algorithm 5 HashML-DSA.Verify.
- *              Verifies signature with pre-hashed message.
- *
- * Arguments:
- *     - const uint8_t *sig:     pointer to input signature
- *     - size_t siglen:          length of signature
- *     - const uint8_t *ph:      pointer to pre-hashed message
- *     - size_t phlen:           length of pre-hashed message
- *     - const uint8_t *ctx:     pointer to context string
- *     - size_t ctxlen:          length of context string
- *     - const uint8_t pk[MLDSA_PUBLICKEYBYTES(MLD_CONFIG_API_PARAMETER_SET)]:
- *                               bit-packed public key
- *     - int hashalg:            hash algorithm constant (one of MLD_PREHASH_*)
- *
- * Returns:     - 0: Success
- *              - MLD_ERR_OUT_OF_MEMORY: If MLD_CONFIG_CUSTOM_ALLOC_FREE is
- *                  used and an allocation via MLD_CUSTOM_ALLOC returned NULL.
- *              - MLD_ERR_FAIL: Signature verification failed
+#if !defined(MLD_CONFIG_NO_VERIFY_API)
+/**
+ * FIPS 204: Algorithm 5 HashML-DSA.Verify. Verifies signature with pre-hashed
+ * message.
  *
  * Supported hash algorithm constants:
  *   MLD_PREHASH_SHA2_224, MLD_PREHASH_SHA2_256, MLD_PREHASH_SHA2_384,
  *   MLD_PREHASH_SHA2_512, MLD_PREHASH_SHA2_512_224, MLD_PREHASH_SHA2_512_256,
  *   MLD_PREHASH_SHA3_224, MLD_PREHASH_SHA3_256, MLD_PREHASH_SHA3_384,
- *   MLD_PREHASH_SHA3_512, MLD_PREHASH_SHAKE_128, MLD_PREHASH_SHAKE_256
+ *   MLD_PREHASH_SHA3_512, MLD_PREHASH_SHAKE_128, MLD_PREHASH_SHAKE_256.
  *
- * Warning: This is an unstable API that may change in the future. If you need
+ * @warning This is an unstable API that may change in the future. If you need
  * a stable API use crypto_sign_verify_pre_hash_shake256.
- **************************************************/
+ *
+ * @param[in] sig     Pointer to input signature.
+ * @param     siglen  Length of signature.
+ * @param[in] ph      Pointer to pre-hashed message.
+ * @param     phlen   Length of pre-hashed message.
+ * @param[in] ctx     Pointer to context string.
+ * @param     ctxlen  Length of context string.
+ * @param[in] pk      Bit-packed public key.
+ * @param     hashalg Hash algorithm constant (one of MLD_PREHASH_*).
+ * @param     context Application context. Only present when
+ *                    MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                    MLD_CONFIG_CONTEXT_PARAMETER_TYPE.
+ *
+ * @retval 0                    Success.
+ * @retval MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was used and an
+ *                               allocation via MLD_CUSTOM_ALLOC returned NULL.
+ * @retval MLD_ERR_FAIL          Signature verification failed.
+ */
 MLD_API_QUALIFIER
 MLD_API_MUST_CHECK_RETURN_VALUE
 int MLD_API_NAMESPACE(verify_pre_hash_internal)(
@@ -691,34 +720,36 @@ int MLD_API_NAMESPACE(verify_pre_hash_internal)(
     MLD_CONFIG_CONTEXT_PARAMETER_TYPE context
 #endif
 );
-
-/*************************************************
- * Name:        crypto_sign_signature_pre_hash_shake256
- *
- * Description: FIPS 204: Algorithm 4 HashML-DSA.Sign with SHAKE256.
- *              Computes signature with pre-hashed message using SHAKE256.
- *              This function computes the SHAKE256 hash of the message
- *              internally.
- *
- * Arguments:
- *     - uint8_t sig[MLDSA_BYTES(MLD_CONFIG_API_PARAMETER_SET)]:
- *                           output signature
- *     - size_t *siglen:     pointer to output length of signature
- *     - const uint8_t *m:   pointer to message to be hashed and signed
- *     - size_t mlen:        length of message
- *     - const uint8_t *ctx: pointer to context string
- *     - size_t ctxlen:      length of context string
- *     - const uint8_t rnd[MLDSA_RNDBYTES]:
- *                           random seed
- *     - const uint8_t sk[MLDSA_SECRETKEYBYTES(MLD_CONFIG_API_PARAMETER_SET)]:
- *                           bit-packed secret key
- *
- * Returns:
- *     - 0: Success
- *     - MLD_ERR_OUT_OF_MEMORY: If MLD_CONFIG_CUSTOM_ALLOC_FREE is
- *         used and an allocation via MLD_CUSTOM_ALLOC returned NULL.
- *     - MLD_ERR_FAIL: Other kinds of failure
- **************************************************/
+#endif /* !MLD_CONFIG_NO_VERIFY_API */
+
+#if !defined(MLD_CONFIG_NO_SIGN_API)
+/**
+ * FIPS 204: Algorithm 4 HashML-DSA.Sign with SHAKE256.
+ *
+ * Compute signature with pre-hashed message using SHAKE256. This function
+ * computes the SHAKE256 hash of the message internally.
+ *
+ * @param[out] sig     Output signature.
+ * @param[out] siglen  Pointer to output length of signature.
+ * @param[in]  m       Pointer to message to be hashed and signed.
+ * @param      mlen    Length of message.
+ * @param[in]  ctx     Pointer to context string.
+ * @param      ctxlen  Length of context string.
+ * @param[in]  rnd     Random seed.
+ * @param[in]  sk      Bit-packed secret key.
+ * @param      context Application context. Only present when
+ *                     MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                     MLD_CONFIG_CONTEXT_PARAMETER_TYPE.
+ *
+ * @retval 0                               Success.
+ * @retval MLD_ERR_OUT_OF_MEMORY           MLD_CONFIG_CUSTOM_ALLOC_FREE was
+ *                                         used and an allocation via
+ *                                         MLD_CUSTOM_ALLOC returned NULL.
+ * @retval MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED The rejection-sampling loop exceeded
+ *                                         MLD_CONFIG_MAX_SIGNING_ATTEMPTS
+ *                                         iterations.
+ * @retval MLD_ERR_FAIL                    Other kinds of failure.
+ */
 MLD_API_QUALIFIER
 MLD_API_MUST_CHECK_RETURN_VALUE
 int MLD_API_NAMESPACE(signature_pre_hash_shake256)(
@@ -731,31 +762,31 @@ int MLD_API_NAMESPACE(signature_pre_hash_shake256)(
     MLD_CONFIG_CONTEXT_PARAMETER_TYPE context
 #endif
 );
-
-/*************************************************
- * Name:        crypto_sign_verify_pre_hash_shake256
- *
- * Description: FIPS 204: Algorithm 5 HashML-DSA.Verify with SHAKE256.
- *              Verifies signature with pre-hashed message using SHAKE256.
- *              This function computes the SHAKE256 hash of the message
- *internally.
- *
- * Arguments:
- *     - const uint8_t *sig: pointer to input signature
- *     - size_t siglen:      length of signature
- *     - const uint8_t *m:   pointer to message to be hashed and verified
- *     - size_t mlen:        length of message
- *     - const uint8_t *ctx: pointer to context string
- *     - size_t ctxlen:      length of context string
- *     - const uint8_t pk[MLDSA_PUBLICKEYBYTES(MLD_CONFIG_API_PARAMETER_SET)]:
- *                           bit-packed public key
- *
- * Returns:
- *     - 0: Success
- *     - MLD_ERR_OUT_OF_MEMORY: If MLD_CONFIG_CUSTOM_ALLOC_FREE is
- *         used and an allocation via MLD_CUSTOM_ALLOC returned NULL.
- *     - MLD_ERR_FAIL: Signature verification failed
- **************************************************/
+#endif /* !MLD_CONFIG_NO_SIGN_API */
+
+#if !defined(MLD_CONFIG_NO_VERIFY_API)
+/**
+ * FIPS 204: Algorithm 5 HashML-DSA.Verify with SHAKE256.
+ *
+ * Verify signature with pre-hashed message using SHAKE256. This function
+ * computes the SHAKE256 hash of the message internally.
+ *
+ * @param[in] sig     Pointer to input signature.
+ * @param     siglen  Length of signature.
+ * @param[in] m       Pointer to message to be hashed and verified.
+ * @param     mlen    Length of message.
+ * @param[in] ctx     Pointer to context string.
+ * @param     ctxlen  Length of context string.
+ * @param[in] pk      Bit-packed public key.
+ * @param     context Application context. Only present when
+ *                    MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                    MLD_CONFIG_CONTEXT_PARAMETER_TYPE.
+ *
+ * @retval 0                    Success.
+ * @retval MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was used and an
+ *                               allocation via MLD_CUSTOM_ALLOC returned NULL.
+ * @retval MLD_ERR_FAIL          Signature verification failed.
+ */
 MLD_API_QUALIFIER
 MLD_API_MUST_CHECK_RETURN_VALUE
 int MLD_API_NAMESPACE(verify_pre_hash_shake256)(
@@ -767,79 +798,76 @@ int MLD_API_NAMESPACE(verify_pre_hash_shake256)(
     MLD_CONFIG_CONTEXT_PARAMETER_TYPE context
 #endif
 );
+#endif /* !MLD_CONFIG_NO_VERIFY_API */
+#endif /* !MLD_CONFIG_CORE_API_ONLY */
 
 /* Maximum formatted domain separation message length */
 #define MLD_DOMAIN_SEPARATION_MAX_BYTES (2 + 255 + 11 + 64)
 
-/*************************************************
- * Name:        mld_prepare_domain_separation_prefix
- *
- * Description: Prepares domain separation prefix for ML-DSA signing.
- *              For pure ML-DSA (hashalg == MLD_PREHASH_NONE):
- *                Format: 0x00 || ctxlen (1 byte) || ctx
- *              For HashML-DSA (hashalg != MLD_PREHASH_NONE):
- *                Format: 0x01 || ctxlen (1 byte) || ctx || oid (11 bytes) || ph
- *
- * Arguments:   - uint8_t prefix[MLD_DOMAIN_SEPARATION_MAX_BYTES]:
- *                output domain separation prefix buffer
- *              - const uint8_t *ph: pointer to pre-hashed message
- *                (ignored for pure ML-DSA)
- *              - size_t phlen: length of pre-hashed message
- *                (ignored for pure ML-DSA)
- *              - const uint8_t *ctx: pointer to context string (may be NULL)
- *              - size_t ctxlen: length of context string
- *              - int hashalg: hash algorithm constant
- *                (MLD_PREHASH_NONE for pure ML-DSA, or MLD_PREHASH_* for
- *                 HashML-DSA)
- *
- * Returns the total length of the formatted prefix, or 0 on error.
+#if !defined(MLD_CONFIG_CORE_API_ONLY)
+/**
+ * Prepare domain separation prefix for ML-DSA signing.
+ *
+ * For pure ML-DSA (hashalg == MLD_PREHASH_NONE):
+ *   Format: 0x00 || ctxlen (1 byte) || ctx.
+ *
+ * For HashML-DSA (hashalg != MLD_PREHASH_NONE):
+ *   Format: 0x01 || ctxlen (1 byte) || ctx || oid (11 bytes) || ph.
  *
  * This function is useful for building incremental signing APIs.
  *
- * Specification:
- * - For HashML-DSA (hashalg != MLD_PREHASH_NONE), implements
- *   @[FIPS204, Algorithm 4, L23]
- * - For Pure ML-DSA (hashalg == MLD_PREHASH_NONE), implements
- *    ```
- *       M' <- BytesToBits(IntegerToBytes(0, 1)
- *              || IntegerToBytes(|ctx|, 1)
- *              || ctx
- *    ```
- *    which is part of @[FIPS204, Algorithm 2 (ML-DSA.Sign), L10] and
- *    @[FIPS204, Algorithm 3 (ML-DSA.Verify), L5].
- *
- **************************************************/
+ * @spec{For HashML-DSA (hashalg != MLD_PREHASH_NONE), implements
+ * @[FIPS204, Algorithm 4, L23]. For Pure ML-DSA (hashalg == MLD_PREHASH_NONE),
+ * implements
+ * ```
+ *    M' <- BytesToBits(IntegerToBytes(0, 1)
+ *           || IntegerToBytes(|ctx|, 1)
+ *           || ctx
+ * ```
+ * which is part of @[FIPS204, Algorithm 2 (ML-DSA.Sign), L10] and
+ * @[FIPS204, Algorithm 3 (ML-DSA.Verify), L5].}
+ *
+ * @param[out] prefix  Output domain separation prefix buffer.
+ * @param[in]  ph      Pointer to pre-hashed message (ignored for pure
+ *                     ML-DSA).
+ * @param      phlen   Length of pre-hashed message (ignored for pure ML-DSA).
+ * @param[in]  ctx     Pointer to context string (may be NULL).
+ * @param      ctxlen  Length of context string.
+ * @param      hashalg Hash algorithm constant (MLD_PREHASH_NONE for pure
+ *                     ML-DSA, or MLD_PREHASH_* for HashML-DSA).
+ *
+ * @return The total length of the formatted prefix, or 0 on error.
+ */
 MLD_API_QUALIFIER
 MLD_API_MUST_CHECK_RETURN_VALUE
 size_t MLD_API_NAMESPACE(prepare_domain_separation_prefix)(
     uint8_t prefix[MLD_DOMAIN_SEPARATION_MAX_BYTES], const uint8_t *ph,
     size_t phlen, const uint8_t *ctx, size_t ctxlen, int hashalg);
 
-/*************************************************
- * Name:        crypto_sign_pk_from_sk
- *
- * Description: Performs basic validity checks on secret key, and derives
- *              public key.
- *
- *              Referring to the decoding of the secret key
- *              `sk=(rho, K, tr, s1, s2, t0)`
- *              (cf. [@FIPS204, Algorithm 25 skDecode]),
- *              the following checks are performed:
- *                - Check that s1 and s2 have coefficients in
- *                  [-MLDSA_ETA, MLDSA_ETA]
- *                - Check that t0 and tr stored in sk match recomputed values.
- *
- * Arguments:   - uint8_t pk[CRYPTO_PUBLICKEYBYTES]: output public key
- *              - const uint8_t sk[CRYPTO_SECRETKEYBYTES]: input secret key
- *
- * Returns:     - 0: Success
- *              - MLD_ERR_OUT_OF_MEMORY: If MLD_CONFIG_CUSTOM_ALLOC_FREE is
- *                  used and an allocation via MLD_CUSTOM_ALLOC returned NULL.
- *              - MLD_ERR_FAIL: Secret key validation failed
- *
- * Note: This function leaks whether the secret key is valid or invalid
- *       through its return value and timing.
- **************************************************/
+#if !defined(MLD_CONFIG_NO_KEYPAIR_API)
+/**
+ * Perform basic validity checks on secret key, and derive public key.
+ *
+ * Referring to the decoding of the secret key `sk=(rho, K, tr, s1, s2, t0)`
+ * (cf. @[FIPS204, Algorithm 25 skDecode]), the following checks are
+ * performed:
+ *   - Check that s1 and s2 have coefficients in [-MLDSA_ETA, MLDSA_ETA].
+ *   - Check that t0 and tr stored in sk match recomputed values.
+ *
+ * @note This function leaks whether the secret key is valid or invalid
+ * through its return value and timing.
+ *
+ * @param[out] pk      Output public key.
+ * @param[in]  sk      Input secret key.
+ * @param      context Application context. Only present when
+ *                     MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by
+ *                     MLD_CONFIG_CONTEXT_PARAMETER_TYPE.
+ *
+ * @retval 0                    Success.
+ * @retval MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was used and an
+ *                               allocation via MLD_CUSTOM_ALLOC returned NULL.
+ * @retval MLD_ERR_FAIL          Secret key validation failed.
+ */
 MLD_API_QUALIFIER
 MLD_API_MUST_CHECK_RETURN_VALUE
 int MLD_API_NAMESPACE(pk_from_sk)(
@@ -850,6 +878,8 @@ int MLD_API_NAMESPACE(pk_from_sk)(
     MLD_CONFIG_CONTEXT_PARAMETER_TYPE context
 #endif
 );
+#endif /* !MLD_CONFIG_NO_KEYPAIR_API */
+#endif /* !MLD_CONFIG_CORE_API_ONLY */
 
 #ifdef __cplusplus
 }
@@ -912,31 +942,37 @@ int MLD_API_NAMESPACE(pk_from_sk)(
  */
 /* check-magic: off */
 #if defined(MLD_API_LEGACY_CONFIG) || !defined(MLD_CONFIG_REDUCE_RAM)
-#define MLD_TOTAL_ALLOC_44_KEYPAIR_NO_PCT 45248
-#define MLD_TOTAL_ALLOC_44_KEYPAIR_PCT 56640
-#define MLD_TOTAL_ALLOC_44_SIGN 52896
-#define MLD_TOTAL_ALLOC_44_VERIFY 38816
-#define MLD_TOTAL_ALLOC_65_KEYPAIR_NO_PCT 71872
-#define MLD_TOTAL_ALLOC_65_KEYPAIR_PCT 85856
-#define MLD_TOTAL_ALLOC_65_SIGN 80576
-#define MLD_TOTAL_ALLOC_65_VERIFY 62432
-#define MLD_TOTAL_ALLOC_87_KEYPAIR_NO_PCT 112832
-#define MLD_TOTAL_ALLOC_87_KEYPAIR_PCT 130816
-#define MLD_TOTAL_ALLOC_87_SIGN 123584
-#define MLD_TOTAL_ALLOC_87_VERIFY 99552
+#define MLD_TOTAL_ALLOC_44_KEYPAIR_NO_PCT 26912
+#define MLD_TOTAL_ALLOC_44_KEYPAIR_PCT 48480
+#define MLD_TOTAL_ALLOC_44_PK_FROM_SK 28480
+#define MLD_TOTAL_ALLOC_44_SIGN 44704
+#define MLD_TOTAL_ALLOC_44_VERIFY 24448
+#define MLD_TOTAL_ALLOC_65_KEYPAIR_NO_PCT 44320
+#define MLD_TOTAL_ALLOC_65_KEYPAIR_PCT 74624
+#define MLD_TOTAL_ALLOC_65_PK_FROM_SK 46720
+#define MLD_TOTAL_ALLOC_65_SIGN 69312
+#define MLD_TOTAL_ALLOC_65_VERIFY 39872
+#define MLD_TOTAL_ALLOC_87_KEYPAIR_NO_PCT 75040
+#define MLD_TOTAL_ALLOC_87_KEYPAIR_PCT 115488
+#define MLD_TOTAL_ALLOC_87_PK_FROM_SK 78272
+#define MLD_TOTAL_ALLOC_87_SIGN 108224
+#define MLD_TOTAL_ALLOC_87_VERIFY 68800
 #else /* MLD_API_LEGACY_CONFIG || !MLD_CONFIG_REDUCE_RAM */
-#define MLD_TOTAL_ALLOC_44_KEYPAIR_NO_PCT 32992
-#define MLD_TOTAL_ALLOC_44_KEYPAIR_PCT 36192
-#define MLD_TOTAL_ALLOC_44_SIGN 32448
-#define MLD_TOTAL_ALLOC_44_VERIFY 22464
-#define MLD_TOTAL_ALLOC_65_KEYPAIR_NO_PCT 46304
-#define MLD_TOTAL_ALLOC_65_KEYPAIR_PCT 50048
-#define MLD_TOTAL_ALLOC_65_SIGN 44768
-#define MLD_TOTAL_ALLOC_65_VERIFY 30720
-#define MLD_TOTAL_ALLOC_87_KEYPAIR_NO_PCT 62688
-#define MLD_TOTAL_ALLOC_87_KEYPAIR_PCT 66336
-#define MLD_TOTAL_ALLOC_87_SIGN 59104
-#define MLD_TOTAL_ALLOC_87_VERIFY 41216
+#define MLD_TOTAL_ALLOC_44_KEYPAIR_NO_PCT 11584
+#define MLD_TOTAL_ALLOC_44_KEYPAIR_PCT 16896
+#define MLD_TOTAL_ALLOC_44_PK_FROM_SK 13152
+#define MLD_TOTAL_ALLOC_44_SIGN 13120
+#define MLD_TOTAL_ALLOC_44_VERIFY 9120
+#define MLD_TOTAL_ALLOC_65_KEYPAIR_NO_PCT 14656
+#define MLD_TOTAL_ALLOC_65_KEYPAIR_PCT 22560
+#define MLD_TOTAL_ALLOC_65_PK_FROM_SK 17056
+#define MLD_TOTAL_ALLOC_65_SIGN 17248
+#define MLD_TOTAL_ALLOC_65_VERIFY 10208
+#define MLD_TOTAL_ALLOC_87_KEYPAIR_NO_PCT 18752
+#define MLD_TOTAL_ALLOC_87_KEYPAIR_PCT 28608
+#define MLD_TOTAL_ALLOC_87_PK_FROM_SK 21984
+#define MLD_TOTAL_ALLOC_87_SIGN 21344
+#define MLD_TOTAL_ALLOC_87_VERIFY 12512
 #endif /* !(MLD_API_LEGACY_CONFIG || !MLD_CONFIG_REDUCE_RAM) */
 /* check-magic: on */
 
@@ -957,19 +993,20 @@ int MLD_API_NAMESPACE(pk_from_sk)(
 
 #define MLD_MAX3_(a, b, c) \
   ((a) > (b) ? ((a) > (c) ? (a) : (c)) : ((b) > (c) ? (b) : (c)))
+#define MLD_MAX4_(a, b, c, d) MLD_MAX3_((a), (b), MLD_MAX3_((c), (d), (d)))
 
 /*
- * `MLD_TOTAL_ALLOC_{44,65,87}` is the maximum across all operations for each
- * parameter set.
+ * `MLD_TOTAL_ALLOC_{44,65,87}` is the maximum across standard API operations
+ * (keygen, sign, verify) for each parameter set.
  */
-#define MLD_TOTAL_ALLOC_44                                       \
-  MLD_MAX3_(MLD_TOTAL_ALLOC_44_KEYPAIR, MLD_TOTAL_ALLOC_44_SIGN, \
-            MLD_TOTAL_ALLOC_44_VERIFY)
-#define MLD_TOTAL_ALLOC_65                                       \
-  MLD_MAX3_(MLD_TOTAL_ALLOC_65_KEYPAIR, MLD_TOTAL_ALLOC_65_SIGN, \
-            MLD_TOTAL_ALLOC_65_VERIFY)
-#define MLD_TOTAL_ALLOC_87                                       \
-  MLD_MAX3_(MLD_TOTAL_ALLOC_87_KEYPAIR, MLD_TOTAL_ALLOC_87_SIGN, \
-            MLD_TOTAL_ALLOC_87_VERIFY)
+#define MLD_TOTAL_ALLOC_44                                             \
+  MLD_MAX4_(MLD_TOTAL_ALLOC_44_KEYPAIR, MLD_TOTAL_ALLOC_44_PK_FROM_SK, \
+            MLD_TOTAL_ALLOC_44_SIGN, MLD_TOTAL_ALLOC_44_VERIFY)
+#define MLD_TOTAL_ALLOC_65                                             \
+  MLD_MAX4_(MLD_TOTAL_ALLOC_65_KEYPAIR, MLD_TOTAL_ALLOC_65_PK_FROM_SK, \
+            MLD_TOTAL_ALLOC_65_SIGN, MLD_TOTAL_ALLOC_65_VERIFY)
+#define MLD_TOTAL_ALLOC_87                                             \
+  MLD_MAX4_(MLD_TOTAL_ALLOC_87_KEYPAIR, MLD_TOTAL_ALLOC_87_PK_FROM_SK, \
+            MLD_TOTAL_ALLOC_87_SIGN, MLD_TOTAL_ALLOC_87_VERIFY)
 
 #endif /* !MLD_H */