Merge pull request #9585 from dgarske/add-missing-api-docs

Add missing API documentation

Author: JacobBarthelmeh

doc/dox_comments/header_files/aes.h

@@ -57,3 +57,57 @@ int wc_Arc4Process(Arc4* arc4, byte* out, const byte* in, word32 length);
     \sa wc_Arc4Process
 */
 int wc_Arc4SetKey(Arc4* arc4, const byte* key, word32 length);
+
+/*!
+    \ingroup ARC4
+    \brief This function initializes an ARC4 structure for use with
+    asynchronous cryptographic operations. It sets up the heap hint and
+    device ID for hardware acceleration support.
+
+    \return 0 On success.
+    \return BAD_FUNC_ARG If arc4 is NULL.
+
+    \param arc4 pointer to the Arc4 structure to initialize
+    \param heap pointer to heap hint for memory allocation (can be NULL)
+    \param devId device ID for hardware acceleration (use INVALID_DEVID
+    for software)
+
+    _Example_
+    \code
+    Arc4 arc4;
+    int ret = wc_Arc4Init(&arc4, NULL, INVALID_DEVID);
+    if (ret != 0) {
+        // initialization failed
+    }
+    // use arc4 for encryption/decryption
+    wc_Arc4Free(&arc4);
+    \endcode
+
+    \sa wc_Arc4SetKey
+    \sa wc_Arc4Free
+*/
+int wc_Arc4Init(Arc4* arc4, void* heap, int devId);
+
+/*!
+    \ingroup ARC4
+    \brief This function frees an ARC4 structure, releasing any resources
+    allocated for asynchronous cryptographic operations. It should be
+    called when the ARC4 structure is no longer needed.
+
+    \return none No return value.
+
+    \param arc4 pointer to the Arc4 structure to free
+
+    _Example_
+    \code
+    Arc4 arc4;
+    wc_Arc4Init(&arc4, NULL, INVALID_DEVID);
+    wc_Arc4SetKey(&arc4, key, keyLen);
+    // use arc4 for encryption/decryption
+    wc_Arc4Free(&arc4);
+    \endcode
+
+    \sa wc_Arc4Init
+    \sa wc_Arc4SetKey
+*/
+void wc_Arc4Free(Arc4* arc4);

doc/dox_comments/header_files/arc4.h

@@ -466,4 +466,109 @@ int wc_AsconAEAD128_DecryptUpdate(wc_AsconAEAD128* a, byte* out, const byte* in,
     */
 int wc_AsconAEAD128_DecryptFinal(wc_AsconAEAD128* a, const byte* tag);
 
+/*!
+    \ingroup ASCON
+    \brief This function allocates and initializes a new Ascon Hash256
+    context. The returned context must be freed with wc_AsconHash256_Free
+    when no longer needed.
+
+    \return Pointer to allocated wc_AsconHash256 structure on success.
+    \return NULL on allocation or initialization failure.
+
+    _Example_
+    \code
+    wc_AsconHash256* hash = wc_AsconHash256_New();
+    if (hash == NULL) {
+        // handle allocation error
+    }
+    byte data[]; // data to hash
+    wc_AsconHash256_Update(hash, data, sizeof(data));
+    byte digest[ASCON_HASH256_SZ];
+    wc_AsconHash256_Final(hash, digest);
+    wc_AsconHash256_Free(hash);
+    \endcode
+
+    \sa wc_AsconHash256_Free
+    \sa wc_AsconHash256_Init
+*/
+wc_AsconHash256* wc_AsconHash256_New(void);
+
+/*!
+    \ingroup ASCON
+    \brief This function frees an Ascon Hash256 context that was allocated
+    with wc_AsconHash256_New. It clears the context before freeing to
+    prevent information leakage.
+
+    \return none No return value.
+
+    \param a pointer to the wc_AsconHash256 structure to free
+
+    _Example_
+    \code
+    wc_AsconHash256* hash = wc_AsconHash256_New();
+    if (hash != NULL) {
+        // use hash context
+        wc_AsconHash256_Free(hash);
+    }
+    \endcode
+
+    \sa wc_AsconHash256_New
+    \sa wc_AsconHash256_Clear
+*/
+void wc_AsconHash256_Free(wc_AsconHash256* a);
+
+/*!
+    \ingroup ASCON
+    \brief This function clears an Ascon Hash256 context by zeroing all
+    internal state. This should be called to securely erase sensitive
+    data from memory.
+
+    \return none No return value.
+
+    \param a pointer to the wc_AsconHash256 structure to clear
+
+    _Example_
+    \code
+    wc_AsconHash256 hash;
+    wc_AsconHash256_Init(&hash);
+    byte data[]; // data to hash
+    wc_AsconHash256_Update(&hash, data, sizeof(data));
+    byte digest[ASCON_HASH256_SZ];
+    wc_AsconHash256_Final(&hash, digest);
+    wc_AsconHash256_Clear(&hash);
+    \endcode
+
+    \sa wc_AsconHash256_Init
+    \sa wc_AsconHash256_Free
+*/
+void wc_AsconHash256_Clear(wc_AsconHash256* a);
+
+/*!
+    \ingroup ASCON
+    \brief This function allocates and initializes a new Ascon AEAD128
+    context. The returned context must be freed with wc_AsconAEAD128_Free
+    when no longer needed.
+
+    \return Pointer to allocated wc_AsconAEAD128 structure on success.
+    \return NULL on allocation or initialization failure.
+
+    _Example_
+    \code
+    wc_AsconAEAD128* aead = wc_AsconAEAD128_New();
+    if (aead == NULL) {
+        // handle allocation error
+    }
+    byte key[ASCON_AEAD128_KEY_SZ] = { }; // key
+    byte nonce[ASCON_AEAD128_NONCE_SZ] = { }; // nonce
+    wc_AsconAEAD128_SetKey(aead, key);
+    wc_AsconAEAD128_SetNonce(aead, nonce);
+    // perform encryption/decryption
+    wc_AsconAEAD128_Free(aead);
+    \endcode
+
+    \sa wc_AsconAEAD128_Free
+    \sa wc_AsconAEAD128_Init
+*/
+wc_AsconAEAD128* wc_AsconAEAD128_New(void);
+