API doc: ML-DSA, ML-KEM

Author: kojo1

doc/dox_comments/header_files/dilithium.h

@@ -0,0 +1,338 @@
+/*!
+    \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
+*/
+#define wc_MlDsaKey_Init(key, heap, devId) wc_dilithium_init_ex(key, heap, 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
+*/
+#define wc_MlDsaKey_SetParams(key, id) wc_dilithium_set_level(key, 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
+*/
+#define wc_MlDsaKey_GetParams(key, id) wc_dilithium_get_level(key, 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
+*/
+#define wc_MlDsaKey_Free(key) wc_dilithium_free(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
+*/
+#define wc_MlDsaKey_MakeKey(key, rng) wc_dilithium_make_key(key, rng)
+
+/*!
+    \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
+*/
+#define wc_MlDsaKey_ExportPrivRaw(key, out, outLen) \
+    wc_dilithium_export_private_only(key, out, 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
+*/
+#define wc_MlDsaKey_ImportPrivRaw(key, in, inLen) \
+    wc_dilithium_import_private_only(in, inLen, key)
+
+/*!
+    \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
+*/
+#define wc_MlDsaKey_ExportPubRaw(key, out, outLen) \
+    wc_dilithium_export_public(key, out, 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
+*/
+#define wc_MlDsaKey_ImportPubRaw(key, in, inLen) \
+    wc_dilithium_import_public(in, inLen, key)
+/*!
+    \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
+*/
+#define wc_MlDsaKey_Sign(key, sig, sigSz, msg, msgSz, rng) \
+    wc_dilithium_sign_msg(msg, msgSz, sig, sigSz, key, 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
+*/
+#define wc_MlDsaKey_Verify(key, sig, sigSz, msg, msgSz, res) \
+    wc_dilithium_verify_msg(sig, sigSz, msg, msgSz, res, key)
+/*!
+    \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
+*/
+#define wc_MlDsaKey_PublicKeyToDer(key, output, len, withAlg) \
+    wc_Dilithium_PublicKeyToDer(key, output, len, 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
+*/
+#define wc_MlDsaKey_PrivateKeyToDer(key, output, len) \
+    wc_Dilithium_PrivateKeyToDer(key, output, 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
+*/
+WOLFSSL_API 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
+*/
+WOLFSSL_API 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
+*/
+WOLFSSL_API int wc_MlDsaKey_GetSigLen(MlDsaKey *key, int *len);