From 1be3f648ce0e204660e1baa222460a26f649ea27 Mon Sep 17 00:00:00 2001 From: Takashi Kojo Date: Tue, 20 Jan 2026 10:07:36 +0900 Subject: [PATCH 1/2] API doc: ML-DSA, ML-KEM --- doc/dox_comments/header_files/dilithium.h | 332 +++++++++++++ .../header_files/doxygen_groups.h | 2 + doc/dox_comments/header_files/doxygen_pages.h | 3 +- doc/dox_comments/header_files/mlkem.h | 437 ++++++++++++++++++ 4 files changed, 773 insertions(+), 1 deletion(-) create mode 100644 doc/dox_comments/header_files/dilithium.h create mode 100644 doc/dox_comments/header_files/mlkem.h diff --git a/doc/dox_comments/header_files/dilithium.h b/doc/dox_comments/header_files/dilithium.h new file mode 100644 index 00000000000..726f5750444 --- /dev/null +++ b/doc/dox_comments/header_files/dilithium.h @@ -0,0 +1,332 @@ +/*! + \ingroup MLDSA + + \brief This macro initializes a provided MlDsaKey structure. + + MlDsaKey is an alias of dilithium_key. This macro maps to + wc_dilithium_init_ex(). + + \return 0 Returned upon successfully initializing the key structure + \return BAD_FUNC_ARGS Returned if the key pointer evaluates to NULL + \return MEMORY_E Returned if memory allocation fails (when applicable) + + \param key pointer to the MlDsaKey structure to initialize + \param heap pointer to a heap identifier, for use with memory overrides + \param devId ID to use with crypto callbacks or async hardware. + Set to INVALID_DEVID (-2) if not used. + + _Example_ + \code + MlDsaKey key; + wc_MlDsaKey_Init(&key, NULL, INVALID_DEVID); + \endcode + + \sa wc_MlDsaKey_Free + \sa wc_MlDsaKey_SetParams +*/ +int wc_MlDsaKey_Init(MlDsaKey *key, void *heap, int devId); + +/*! + \ingroup MLDSA + + \brief This macro sets the ML-DSA parameter set on an initialized MlDsaKey. + + Supported parameter identifiers include: + - WC_ML_DSA_44 + - WC_ML_DSA_65 + - WC_ML_DSA_87 + (Draft variants may also be available depending on build.) + + This macro maps to wc_dilithium_set_level(). + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent) + + \param key pointer to the initialized MlDsaKey structure + \param id parameter set identifier (e.g., WC_ML_DSA_44 / _65 / _87) + + _Example_ + \code + wc_MlDsaKey_SetParams(&key, WC_ML_DSA_65); + \endcode + + \sa wc_MlDsaKey_GetParams + \sa wc_MlDsaKey_MakeKey +*/ +int wc_MlDsaKey_SetParams(MlDsaKey *key, byte id); + +/*! + \ingroup MLDSA + + \brief This macro gets the ML-DSA parameter set configured in the key. + + This macro maps to wc_dilithium_get_level(). + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent) + + \param key pointer to the initialized MlDsaKey structure + \param id output pointer receiving the current parameter set identifier + + \sa wc_MlDsaKey_SetParams +*/ +int wc_MlDsaKey_GetParams(MlDsaKey *key, byte id); + +/*! + \ingroup MLDSA + + \brief This macro frees resources associated with an MlDsaKey structure. + + This macro maps to wc_dilithium_free(). + + \return 0 Returned upon success (implementation dependent) + \return BAD_FUNC_ARGS Returned if key is NULL (implementation dependent) + + \param key pointer to the MlDsaKey structure to free + + \sa wc_MlDsaKey_Init +*/ +void wc_MlDsaKey_Free(MlDsaKey *key); +/*! + \ingroup MLDSA + + \brief This macro generates an ML-DSA public/private key pair. + + The key must be initialized and have parameters set prior to calling. + This macro maps to wc_dilithium_make_key(). + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if key or rng is NULL + \return RNG_FAILURE_E Returned if RNG fails (when applicable) + + \param key pointer to the initialized MlDsaKey structure + \param rng pointer to an initialized WC_RNG structure + + \sa wc_MlDsaKey_Sign + \sa wc_MlDsaKey_Verify +*/ +int wc_MlDsaKey_MakeKey(MlDsaKey *key, WC_RNG *rrng); + +/*! + \ingroup MLDSA + + \brief This macro exports the private key in raw (algorithm-specific) format. + + This macro maps to wc_dilithium_export_private_only(). + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent) + \return BUFFER_E Returned if output buffer is too small (when applicable) + + \param key pointer to the MlDsaKey structure containing a private key + \param out output buffer for raw private key + \param outLen in/out: on input, size of out; on output, bytes written (implementation dependent) + + \sa wc_MlDsaKey_GetPrivLen + \sa wc_MlDsaKey_ImportPrivRaw +*/ +int wc_MlDsaKey_ExportPrivRaw(MlDsaKey *key, byte *out, word32 *outLen); + +/*! + \ingroup MLDSA + + \brief This macro imports the private key from raw (algorithm-specific) format. + + This macro maps to wc_dilithium_import_private_only(). + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent) + \return BUFFER_E Returned if input length is invalid (when applicable) + + \param key pointer to the MlDsaKey structure to receive the private key + \param in input buffer containing raw private key + \param inLen length of input in bytes + + \sa wc_MlDsaKey_ExportPrivRaw +*/ +int wc_MlDsaKey_ImportPrivRaw(MlDsaKey *key, byte *in, word32 inLen); + +/*! + \ingroup MLDSA + + \brief This macro exports the public key in raw (algorithm-specific) format. + + This macro maps to wc_dilithium_export_public(). + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent) + \return BUFFER_E Returned if output buffer is too small (when applicable) + + \param key pointer to the MlDsaKey structure containing a public key + \param out output buffer for raw public key + \param outLen in/out: on input, size of out; on output, bytes written (implementation dependent) + + \sa wc_MlDsaKey_GetPubLen + \sa wc_MlDsaKey_ImportPubRaw +*/ +inte wc_MlDsaKey_ExportPubRaw(MlDsaKey *key, byte *out, word32 *outLen); + +/*! + \ingroup MLDSA + + \brief This macro imports the public key from raw (algorithm-specific) format. + + This macro maps to wc_dilithium_import_public(). + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent) + \return BUFFER_E Returned if input length is invalid (when applicable) + + \param key pointer to the MlDsaKey structure to receive the public key + \param in input buffer containing raw public key + \param inLen length of input in bytes + + \sa wc_MlDsaKey_ExportPubRaw +*/ +int wc_MlDsaKey_ImportPubRaw(MlDsaKey *key, byte *in, word32 inLen); + +/*! + \ingroup MLDSA + + \brief This macro signs a message using an ML-DSA private key. + + This macro maps to wc_dilithium_sign_msg(). + Note the argument order: (msg,msgSz) are provided after (sig,sigSz). + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent) + \return BUFFER_E Returned if the signature buffer is too small (when applicable) + \return RNG_FAILURE_E Returned if RNG fails (when applicable) + + \param key pointer to the MlDsaKey structure containing a private key + \param sig output buffer for signature + \param sigSz in/out: on input, size of sig; on output, signature length written + \param msg pointer to message buffer to sign + \param msgSz size of message in bytes + \param rng pointer to an initialized WC_RNG structure + + _Example_ + \code + byte sigBuf[DILITHIUM_ML_DSA_44_SIG_SIZE]; + word32 sigSz = sizeof(sigBuf); + + wc_MlDsaKey_Sign(&key, sigBuf, &sigSz, msg, msgSz, &rng); + \endcode + + \sa wc_MlDsaKey_Verify + \sa wc_MlDsaKey_GetSigLen +*/ +int wc_MlDsaKey_Sign(MlDsaKey *key, byte *sig, word43 sigSz, const byte *msg, mword32 sgSz, WC_RNG *rng); + +/*! + \ingroup MLDSA + + \brief This macro verifies an ML-DSA signature using an ML-DSA public key. + + This macro maps to wc_dilithium_verify_msg(). + + The verification result is written to \p res. + + \return 0 Returned upon success (verification executed) + \return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent) + + \param key pointer to the MlDsaKey structure containing a public key + \param sig pointer to signature buffer + \param sigSz size of signature in bytes + \param msg pointer to message buffer to verify + \param msgSz size of message in bytes + \param res output: verification result (typically 1 = valid, 0 = invalid) + + _Example_ + \code + int verified = 0; + wc_MlDsaKey_Verify(&pub, sigBuf, sigSz, msg, msgSz, &verified); + if (verified != 1) { + // invalid + } + \endcode + + \sa wc_MlDsaKey_Sign +*/ +int wc_MlDsaKey_Verify(MlDsaKey *key, const byte *sig, word32 sigSz, const byte *msg, word32 msgSz, int *res); +/*! + \ingroup MLDSA + + \brief This macro exports the ML-DSA public key to DER format. + + This macro maps to wc_Dilithium_PublicKeyToDer(). + + \return bytes Returned as the number of bytes written upon success (> 0) + \return negative error code Returned upon failure + + \param key pointer to MlDsaKey + \param output output buffer for DER + \param len size of output buffer in bytes + \param withAlg non-zero to include AlgorithmIdentifier when supported + + \sa wc_MlDsaKey_PrivateKeyToDer +*/ +int wc_MlDsaKey_PublicKeyToDer(MlDsaKey *key, byte *output, word32 len, int withAlg); + +/*! + \ingroup MLDSA + + \brief This macro exports the ML-DSA private key to DER format. + + This macro maps to wc_Dilithium_PrivateKeyToDer(). + + \return bytes Returned as the number of bytes written upon success (> 0) + \return negative error code Returned upon failure + + \param key pointer to MlDsaKey + \param output output buffer for DER + \param len size of output buffer in bytes + + \sa wc_MlDsaKey_PublicKeyToDer +*/ +int wc_MlDsaKey_PrivateKeyToDer(MlDsaKey *key, byte *output, word32 len); + +/*! + \ingroup MLDSA + + \brief This function returns the raw private key length in bytes for the configured parameter set. + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if key or len is NULL + + \param key pointer to an initialized MlDsaKey structure + \param len output pointer receiving private key length in bytes + + \sa wc_MlDsaKey_ExportPrivRaw +*/ +int wc_MlDsaKey_GetPrivLen(MlDsaKey *key, int *len); + +/*! + \ingroup MLDSA + + \brief This function returns the raw public key length in bytes for the configured parameter set. + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if key or len is NULL + + \param key pointer to an initialized MlDsaKey structure + \param len output pointer receiving public key length in bytes + + \sa wc_MlDsaKey_ExportPubRaw +*/ +int wc_MlDsaKey_GetPubLen(MlDsaKey *key, int *len); + +/*! + \ingroup MLDSA + + \brief This function returns the signature length in bytes for the configured parameter set. + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if key or len is NULL + + \param key pointer to an initialized MlDsaKey structure + \param len output pointer receiving signature length in bytes + + \sa wc_MlDsaKey_Sign +*/ +int wc_MlDsaKey_GetSigLen(MlDsaKey *key, int *len); diff --git a/doc/dox_comments/header_files/doxygen_groups.h b/doc/dox_comments/header_files/doxygen_groups.h index 5cac25e2ddd..76b63987f89 100644 --- a/doc/dox_comments/header_files/doxygen_groups.h +++ b/doc/dox_comments/header_files/doxygen_groups.h @@ -198,6 +198,8 @@ \defgroup MD2 Algorithms - MD2 \defgroup MD4 Algorithms - MD4 \defgroup MD5 Algorithms - MD5 + \defgroup MLDSA Algorithms - ML-DSA + \defgroup MLKEM Algorithms - ML-KEM \defgroup PKCS7 Algorithms - PKCS7 \defgroup PKCS11 Algorithms - PKCS11 \defgroup Password Algorithms - Password Based diff --git a/doc/dox_comments/header_files/doxygen_pages.h b/doc/dox_comments/header_files/doxygen_pages.h index 2765449ac82..cfa269a7c05 100644 --- a/doc/dox_comments/header_files/doxygen_pages.h +++ b/doc/dox_comments/header_files/doxygen_pages.h @@ -49,6 +49,8 @@
  • \ref MD2
  • \ref MD4
  • \ref MD5
    • +
  • \ref MLDSA
    • +
  • \ref MLKEM
  • \ref Password
  • \ref PKCS7
  • \ref PKCS11
    • @@ -74,4 +76,3 @@ - \ref SAKKE_RSK - \ref SAKKE_Operations */ - diff --git a/doc/dox_comments/header_files/mlkem.h b/doc/dox_comments/header_files/mlkem.h new file mode 100644 index 00000000000..a6a004cd017 --- /dev/null +++ b/doc/dox_comments/header_files/mlkem.h @@ -0,0 +1,437 @@ +/*! + \ingroup MLKEM + + \brief This function allocates and initializes an MlKemKey object. + + The returned key is initialized for the specified ML-KEM parameter set + (WC_ML_KEM_512 / WC_ML_KEM_768 / WC_ML_KEM_1024, or KYBER* types when + WOLFSSL_MLKEM_KYBER is enabled). + + \return pointer Returned upon success + \return NULL Returned if allocation or initialization fails + + \param type ML-KEM parameter set identifier (WC_ML_KEM_512 / _768 / _1024, + or KYBER512 / KYBER768 / KYBER1024 when enabled) + \param heap pointer to a heap identifier, for use with memory overrides + \param devId ID to use with crypto callbacks or async hardware. + Set to INVALID_DEVID (-2) if not used. + + _Example_ + \code + MlKemKey* kem = wc_MlKemKey_New(WC_ML_KEM_512, NULL, INVALID_DEVID); + if (kem == NULL) { + // error + } + \endcode + + \sa wc_MlKemKey_Delete + \sa wc_MlKemKey_Init +*/ +WOLFSSL_API MlKemKey *wc_MlKemKey_New(int type, void *heap, int devId); + +/*! + \ingroup MLKEM + + \brief This function frees an MlKemKey object allocated by wc_MlKemKey_New(). + + If \p key_p is not NULL, it can be used to clear the caller's pointer. + + \return 0 Returned upon successfully freeing the key + \return BAD_FUNC_ARGS Returned if key is NULL (implementation dependent) + + \param key pointer to the MlKemKey object to delete + \param key_p optional pointer to the key pointer to be cleared (may be NULL) + + _Example_ + \code + MlKemKey* kem = wc_MlKemKey_New(WC_ML_KEM_512, NULL, INVALID_DEVID); + // ... + wc_MlKemKey_Delete(kem, &kem); // kem becomes NULL (when supported) + \endcode + + \sa wc_MlKemKey_New +*/ +WOLFSSL_API int wc_MlKemKey_Delete(MlKemKey *key, MlKemKey **key_p); +/*! + \ingroup MLKEM + + \brief This function initializes a provided MlKemKey structure. + + This API is used when MlKemKey is allocated by the caller (e.g., on stack). + The key is initialized for the specified ML-KEM parameter set. + + \return 0 Returned upon successfully initializing the ML-KEM key structure + \return BAD_FUNC_ARGS Returned if the key pointer evaluates to NULL + \return MEMORY_E Returned if memory allocation fails (when applicable) + + \param key pointer to the MlKemKey structure to initialize + \param type ML-KEM parameter set identifier (WC_ML_KEM_512 / _768 / _1024, + or KYBER512 / KYBER768 / KYBER1024 when enabled) + \param heap pointer to a heap identifier, for use with memory overrides + \param devId ID to use with crypto callbacks or async hardware. + Set to INVALID_DEVID (-2) if not used. + + _Example_ + \code + MlKemKey kem; + int ret = wc_MlKemKey_Init(&kem, WC_ML_KEM_512, NULL, INVALID_DEVID); + if (ret != 0) { + // error + } + \endcode + + \sa wc_MlKemKey_Free + \sa wc_MlKemKey_MakeKey +*/ +WOLFSSL_API int wc_MlKemKey_Init(MlKemKey *key, int type, void *heap, int devId); + +/*! + \ingroup MLKEM + + \brief This function frees resources associated with a provided MlKemKey structure. + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if key is NULL (implementation dependent) + + \param key pointer to the MlKemKey structure to free + + _Example_ + \code + MlKemKey kem; + wc_MlKemKey_Init(&kem, WC_ML_KEM_512, NULL, INVALID_DEVID); + + // ... use kem ... + + wc_MlKemKey_Free(&kem); + \endcode + + \sa wc_MlKemKey_Init +*/ +WOLFSSL_API int wc_MlKemKey_Free(MlKemKey *key); +/*! + \ingroup MLKEM + + \brief This function generates an ML-KEM public/private key pair. + + The MlKemKey must be initialized prior to calling. + RNG must be initialized before use. + + \return 0 Returned upon successfully generating a key pair + \return BAD_FUNC_ARGS Returned if key or rng is NULL + \return RNG_FAILURE_E Returned if RNG fails (when applicable) + + \param key pointer to the initialized MlKemKey structure + \param rng pointer to an initialized WC_RNG structure + + _Example_ + \code + MlKemKey kem; + WC_RNG rng; + + wc_InitRng(&rng); + wc_MlKemKey_Init(&kem, WC_ML_KEM_512, NULL, INVALID_DEVID); + + wc_MlKemKey_MakeKey(&kem, &rng); + + wc_MlKemKey_Free(&kem); + wc_FreeRng(&rng); + \endcode + + \sa wc_MlKemKey_MakeKeyWithRandom +*/ +WOLFSSL_API int wc_MlKemKey_MakeKey(MlKemKey *key, WC_RNG *rng); + +/*! + \ingroup MLKEM + + \brief This function generates an ML-KEM key pair using caller-provided randomness. + + The required random length is fixed per API contract and should be + WC_ML_KEM_MAKEKEY_RAND_SZ bytes. + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if key or rand is NULL + \return BUFFER_E Returned if len is not the required size (when applicable) + + \param key pointer to the initialized MlKemKey structure + \param rand pointer to random bytes used to generate the key pair + \param len length of \p rand in bytes (expected WC_ML_KEM_MAKEKEY_RAND_SZ) + + _Example_ + \code + byte r[WC_ML_KEM_MAKEKEY_RAND_SZ]; + // fill r with deterministic test vector, etc. + + wc_MlKemKey_MakeKeyWithRandom(&kem, r, sizeof(r)); + \endcode + + \sa wc_MlKemKey_MakeKey +*/ +WOLFSSL_API int wc_MlKemKey_MakeKeyWithRandom(MlKemKey *key, + const unsigned char *rand, int len); +/*! + \ingroup MLKEM + + \brief This function returns the ciphertext size in bytes for the key's parameter set. + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if key or len is NULL + + \param key pointer to the initialized MlKemKey structure + \param len output pointer receiving ciphertext size in bytes + + _Example_ + \code + word32 ctSz; + wc_MlKemKey_CipherTextSize(&kem, &ctSz); + \endcode + + \sa wc_MlKemKey_Encapsulate + \sa wc_MlKemKey_Decapsulate +*/ +WOLFSSL_API int wc_MlKemKey_CipherTextSize(MlKemKey *key, word32 *len); + +/*! + \ingroup MLKEM + + \brief This function returns the shared secret size in bytes for the key's parameter set. + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if key or len is NULL + + \param key pointer to the initialized MlKemKey structure + \param len output pointer receiving shared secret size in bytes + + _Example_ + \code + word32 ssSz; + wc_MlKemKey_SharedSecretSize(&kem, &ssSz); + \endcode + + \sa wc_MlKemKey_Encapsulate + \sa wc_MlKemKey_Decapsulate +*/ +WOLFSSL_API int wc_MlKemKey_SharedSecretSize(MlKemKey *key, word32 *len); + +/*! + \ingroup MLKEM + + \brief This function returns the encoded private key size in bytes. + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if key or len is NULL + + \param key pointer to the initialized MlKemKey structure + \param len output pointer receiving private key size in bytes + + \sa wc_MlKemKey_EncodePrivateKey + \sa wc_MlKemKey_DecodePrivateKey +*/ +WOLFSSL_API int wc_MlKemKey_PrivateKeySize(MlKemKey *key, word32 *len); + +/*! + \ingroup MLKEM + + \brief This function returns the encoded public key size in bytes. + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if key or len is NULL + + \param key pointer to the initialized MlKemKey structure + \param len output pointer receiving public key size in bytes + + \sa wc_MlKemKey_EncodePublicKey + \sa wc_MlKemKey_DecodePublicKey +*/ +WOLFSSL_API int wc_MlKemKey_PublicKeySize(MlKemKey *key, word32 *len); +/*! + \ingroup MLKEM + + \brief This function encapsulates a shared secret to an ML-KEM public key. + + On success, this function outputs: + - ciphertext (\p ct) to be sent to the recipient + - shared secret (\p ss) to be kept locally + + The caller must allocate \p ct and \p ss with appropriate sizes for the key type. + Use wc_MlKemKey_CipherTextSize() and wc_MlKemKey_SharedSecretSize() to obtain sizes. + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if key, ct, ss, or rng is NULL + \return RNG_FAILURE_E Returned if RNG fails (when applicable) + + \param key pointer to the MlKemKey structure containing the recipient public key + \param ct output buffer for ciphertext (size depends on key type) + \param ss output buffer for shared secret (size depends on key type) + \param rng pointer to an initialized WC_RNG structure + + _Example_ + \code + word32 ctSz, ssSz; + wc_MlKemKey_CipherTextSize(&peerPub, &ctSz); + wc_MlKemKey_SharedSecretSize(&peerPub, &ssSz); + + byte* ct = XMALLOC(ctSz, NULL, DYNAMIC_TYPE_TMP_BUFFER); + byte* ss = XMALLOC(ssSz, NULL, DYNAMIC_TYPE_TMP_BUFFER); + + wc_MlKemKey_Encapsulate(&peerPub, ct, ss, &rng); + \endcode + + \sa wc_MlKemKey_Decapsulate + \sa wc_MlKemKey_EncapsulateWithRandom +*/ +WOLFSSL_API int wc_MlKemKey_Encapsulate(MlKemKey *key, unsigned char *ct, + unsigned char *ss, WC_RNG *rng); + +/*! + \ingroup MLKEM + + \brief This function encapsulates using caller-provided randomness. + + The required random length is fixed per API contract and should be + WC_ML_KEM_ENC_RAND_SZ bytes. + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if key, ct, ss, or rand is NULL + \return BUFFER_E Returned if len is not the required size (when applicable) + + \param key pointer to the MlKemKey structure containing the recipient public key + \param ct output buffer for ciphertext (size depends on key type) + \param ss output buffer for shared secret (size depends on key type) + \param rand pointer to random bytes used for encapsulation + \param len length of \p rand in bytes (expected WC_ML_KEM_ENC_RAND_SZ) + + _Example_ + \code + byte r[WC_ML_KEM_ENC_RAND_SZ]; + // fill r with deterministic test vector, etc. + + wc_MlKemKey_EncapsulateWithRandom(&peerPub, ct, ss, r, sizeof(r)); + \endcode + + \sa wc_MlKemKey_Encapsulate +*/ +WOLFSSL_API int wc_MlKemKey_EncapsulateWithRandom(MlKemKey *key, + unsigned char *ct, unsigned char *ss, const unsigned char *rand, int len); + +/*! + \ingroup MLKEM + + \brief This function decapsulates a shared secret using an ML-KEM private key. + + The ciphertext buffer \p ct must contain the ciphertext produced by + wc_MlKemKey_Encapsulate(), and \p len must be the ciphertext length in bytes. + Use wc_MlKemKey_CipherTextSize() to obtain the expected length. + + The caller must allocate \p ss with the correct size for the key type. + Use wc_MlKemKey_SharedSecretSize() to obtain the size. + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if key, ss, or ct is NULL + \return BUFFER_E Returned if len is invalid (when applicable) + + \param key pointer to the MlKemKey structure containing the recipient private key + \param ss output buffer for shared secret (size depends on key type) + \param ct input buffer containing ciphertext + \param len ciphertext length in bytes + + _Example_ + \code + word32 ctSz, ssSz; + + wc_MlKemKey_CipherTextSize(&myPriv, &ctSz); + wc_MlKemKey_SharedSecretSize(&myPriv, &ssSz); + + byte ss2[WC_ML_KEM_SS_SZ]; // if using fixed 32-byte SS + wc_MlKemKey_Decapsulate(&myPriv, ss2, ct, ctSz); + \endcode + + \sa wc_MlKemKey_Encapsulate +*/ +WOLFSSL_API int wc_MlKemKey_Decapsulate(MlKemKey *key, unsigned char *ss, + const unsigned char *ct, word32 len); +/*! + \ingroup MLKEM + + \brief This function decodes an encoded private key into an MlKemKey object. + + The key object must be initialized for the intended parameter set. + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if key or in is NULL + \return BUFFER_E Returned if len is invalid (when applicable) + + \param key pointer to the initialized MlKemKey structure + \param in input buffer containing the encoded private key + \param len size of the input buffer in bytes + + \sa wc_MlKemKey_EncodePrivateKey + \sa wc_MlKemKey_PrivateKeySize +*/ +WOLFSSL_API int wc_MlKemKey_DecodePrivateKey(MlKemKey *key, + const unsigned char *in, word32 len); + +/*! + \ingroup MLKEM + + \brief This function decodes an encoded public key into an MlKemKey object. + + The key object must be initialized for the intended parameter set. + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if key or in is NULL + \return BUFFER_E Returned if len is invalid (when applicable) + + \param key pointer to the initialized MlKemKey structure + \param in input buffer containing the encoded public key + \param len size of the input buffer in bytes + + \sa wc_MlKemKey_EncodePublicKey + \sa wc_MlKemKey_PublicKeySize +*/ +WOLFSSL_API int wc_MlKemKey_DecodePublicKey(MlKemKey *key, + const unsigned char *in, word32 len); + +/*! + \ingroup MLKEM + + \brief This function encodes an ML-KEM private key to a byte buffer. + + The caller must allocate \p out with at least the size returned by + wc_MlKemKey_PrivateKeySize(). + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if key or out is NULL + \return BUFFER_E Returned if len is too small (when applicable) + + \param key pointer to the MlKemKey structure containing a private key + \param out output buffer for encoded private key + \param len size of the output buffer in bytes + + \sa wc_MlKemKey_DecodePrivateKey + \sa wc_MlKemKey_PrivateKeySize +*/ +WOLFSSL_API int wc_MlKemKey_EncodePrivateKey(MlKemKey *key, unsigned char *out, + word32 len); + +/*! + \ingroup MLKEM + + \brief This function encodes an ML-KEM public key to a byte buffer. + + The caller must allocate \p out with at least the size returned by + wc_MlKemKey_PublicKeySize(). + + \return 0 Returned upon success + \return BAD_FUNC_ARGS Returned if key or out is NULL + \return BUFFER_E Returned if len is too small (when applicable) + + \param key pointer to the MlKemKey structure containing a public key + \param out output buffer for encoded public key + \param len size of the output buffer in bytes + + \sa wc_MlKemKey_DecodePublicKey + \sa wc_MlKemKey_PublicKeySize +*/ +WOLFSSL_API int wc_MlKemKey_EncodePublicKey(MlKemKey *key, unsigned char *out, + word32 len); From d4d338e52b40467d98674370fb7762483d819056 Mon Sep 17 00:00:00 2001 From: Takashi Kojo Date: Thu, 22 Jan 2026 08:57:05 +0900 Subject: [PATCH 2/2] Eliminate ML-DSA to Dilithium mapping. --- doc/dox_comments/header_files/dilithium.h | 54 ++++++----------------- 1 file changed, 14 insertions(+), 40 deletions(-) diff --git a/doc/dox_comments/header_files/dilithium.h b/doc/dox_comments/header_files/dilithium.h index 726f5750444..b56c6641448 100644 --- a/doc/dox_comments/header_files/dilithium.h +++ b/doc/dox_comments/header_files/dilithium.h @@ -1,10 +1,7 @@ /*! \ingroup MLDSA - \brief This macro initializes a provided MlDsaKey structure. - - MlDsaKey is an alias of dilithium_key. This macro maps to - wc_dilithium_init_ex(). + \brief This function initializes a provided MlDsaKey structure. \return 0 Returned upon successfully initializing the key structure \return BAD_FUNC_ARGS Returned if the key pointer evaluates to NULL @@ -29,7 +26,7 @@ int wc_MlDsaKey_Init(MlDsaKey *key, void *heap, int devId); /*! \ingroup MLDSA - \brief This macro sets the ML-DSA parameter set on an initialized MlDsaKey. + \brief This function sets the ML-DSA parameter set on an initialized MlDsaKey. Supported parameter identifiers include: - WC_ML_DSA_44 @@ -37,8 +34,6 @@ int wc_MlDsaKey_Init(MlDsaKey *key, void *heap, int devId); - WC_ML_DSA_87 (Draft variants may also be available depending on build.) - This macro maps to wc_dilithium_set_level(). - \return 0 Returned upon success \return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent) @@ -58,9 +53,7 @@ int wc_MlDsaKey_SetParams(MlDsaKey *key, byte id); /*! \ingroup MLDSA - \brief This macro gets the ML-DSA parameter set configured in the key. - - This macro maps to wc_dilithium_get_level(). + \brief This function gets the ML-DSA parameter set configured in the key. \return 0 Returned upon success \return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent) @@ -75,9 +68,7 @@ int wc_MlDsaKey_GetParams(MlDsaKey *key, byte id); /*! \ingroup MLDSA - \brief This macro frees resources associated with an MlDsaKey structure. - - This macro maps to wc_dilithium_free(). + \brief This function frees resources associated with an MlDsaKey structure. \return 0 Returned upon success (implementation dependent) \return BAD_FUNC_ARGS Returned if key is NULL (implementation dependent) @@ -90,10 +81,9 @@ void wc_MlDsaKey_Free(MlDsaKey *key); /*! \ingroup MLDSA - \brief This macro generates an ML-DSA public/private key pair. + \brief This function generates an ML-DSA public/private key pair. The key must be initialized and have parameters set prior to calling. - This macro maps to wc_dilithium_make_key(). \return 0 Returned upon success \return BAD_FUNC_ARGS Returned if key or rng is NULL @@ -110,9 +100,7 @@ int wc_MlDsaKey_MakeKey(MlDsaKey *key, WC_RNG *rrng); /*! \ingroup MLDSA - \brief This macro exports the private key in raw (algorithm-specific) format. - - This macro maps to wc_dilithium_export_private_only(). + \brief This function exports the private key in raw (algorithm-specific) format. \return 0 Returned upon success \return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent) @@ -130,9 +118,7 @@ int wc_MlDsaKey_ExportPrivRaw(MlDsaKey *key, byte *out, word32 *outLen); /*! \ingroup MLDSA - \brief This macro imports the private key from raw (algorithm-specific) format. - - This macro maps to wc_dilithium_import_private_only(). + \brief This function imports the private key from raw (algorithm-specific) format. \return 0 Returned upon success \return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent) @@ -149,9 +135,7 @@ int wc_MlDsaKey_ImportPrivRaw(MlDsaKey *key, byte *in, word32 inLen); /*! \ingroup MLDSA - \brief This macro exports the public key in raw (algorithm-specific) format. - - This macro maps to wc_dilithium_export_public(). + \brief This function exports the public key in raw (algorithm-specific) format. \return 0 Returned upon success \return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent) @@ -169,9 +153,7 @@ inte wc_MlDsaKey_ExportPubRaw(MlDsaKey *key, byte *out, word32 *outLen); /*! \ingroup MLDSA - \brief This macro imports the public key from raw (algorithm-specific) format. - - This macro maps to wc_dilithium_import_public(). + \brief This function imports the public key from raw (algorithm-specific) format. \return 0 Returned upon success \return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent) @@ -188,10 +170,7 @@ int wc_MlDsaKey_ImportPubRaw(MlDsaKey *key, byte *in, word32 inLen); /*! \ingroup MLDSA - \brief This macro signs a message using an ML-DSA private key. - - This macro maps to wc_dilithium_sign_msg(). - Note the argument order: (msg,msgSz) are provided after (sig,sigSz). + \brief This function signs a message using an ML-DSA private key. \return 0 Returned upon success \return BAD_FUNC_ARGS Returned if arguments are invalid (implementation dependent) @@ -221,9 +200,7 @@ int wc_MlDsaKey_Sign(MlDsaKey *key, byte *sig, word43 sigSz, const byte *msg, mw /*! \ingroup MLDSA - \brief This macro verifies an ML-DSA signature using an ML-DSA public key. - - This macro maps to wc_dilithium_verify_msg(). + \brief This function verifies an ML-DSA signature using an ML-DSA public key. The verification result is written to \p res. @@ -249,12 +226,11 @@ int wc_MlDsaKey_Sign(MlDsaKey *key, byte *sig, word43 sigSz, const byte *msg, mw \sa wc_MlDsaKey_Sign */ int wc_MlDsaKey_Verify(MlDsaKey *key, const byte *sig, word32 sigSz, const byte *msg, word32 msgSz, int *res); + /*! \ingroup MLDSA - \brief This macro exports the ML-DSA public key to DER format. - - This macro maps to wc_Dilithium_PublicKeyToDer(). + \brief This function exports the ML-DSA public key to DER format. \return bytes Returned as the number of bytes written upon success (> 0) \return negative error code Returned upon failure @@ -271,9 +247,7 @@ int wc_MlDsaKey_PublicKeyToDer(MlDsaKey *key, byte *output, word32 len, int with /*! \ingroup MLDSA - \brief This macro exports the ML-DSA private key to DER format. - - This macro maps to wc_Dilithium_PrivateKeyToDer(). + \brief This function exports the ML-DSA private key to DER format. \return bytes Returned as the number of bytes written upon success (> 0) \return negative error code Returned upon failure