Add missing API documentation for Doxy

[devin-ai-integration[bot]]

Description

This PR adds Doxygen documentation for native wolfSSL API functions that were previously undocumented. It includes documentation notes for APIs gated on specific preprocessor macros: the _Id and _Label init helpers (wc_AesInit_Id, wc_AesInit_Label) require WOLF_PRIVATE_KEY_ID which is set for PKCS11 support, and the New/Delete constructor functions (wc_AesNew/Delete, wc_curve25519_new/delete, wc_ed25519_new/delete, wc_NewRsaKey/DeleteRsaKey) require WC_NO_CONSTRUCTORS to not be defined, noting that WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is defined.

The New/Delete functions are documented as being exposed to support allocation of structures using dynamic memory to provide better ABI compatibility. Additionally, ASN functions marked with WOLFSSL_ASN_API include notes indicating they are not public by default and require WOLFSSL_PUBLIC_ASN to be defined.

Updates since last revision

• Removed OpenSSL compatibility layer documentation (wolfSSL_* functions) from dsa.h, sha.h, rsa.h, ed25519.h, and ripemd.h - these belong in wolfssl/openssl/*.h, not native wolfcrypt docs
• Added WOLF_PRIVATE_KEY_ID notes to additional _id/_label init functions: wc_InitRsaKey_Id/Label, wc_ecc_init_id/label
• Added WOLFSSL_DUAL_ALG_CERTS notes to wc_GeneratePreTBS and wc_MakeSigWithBitStr for Post-Quantum dual algorithm certificate signing (TBS = "To Be Signed")
• Restored bn.h (leave as-is per feedback)
• Reverted hmac.h: removed wolfSSL_HMAC, WOLFSSL_HMAC_CTX_* (OpenSSL compat), and wc_HmacSetKey_Software/Update/Final (KCAPI only)
• Reverted logging.h: removed WOLFSSL_START/END/MSG/ENTER/LEAVE/etc macros (internal debug macros)
• Reverted md5.h: removed WOLFSSL_MD5_CTX APIs (OpenSSL compat)
• Reverted ocsp.h: removed OpenSSL compat APIs
• Reverted sha3.h changes
• Removed wc_backtrace_render (linux kernel module only, not public API)
• Removed xfree from types.h (debug internal function)
• Fixed trailing whitespace in 18 documentation files
• Fixed overlong line in asn_public.h
• Squashed all commits into single commit

Testing

• Generating documentation using documentation repo "make wolfssl".

Checklist

• [ ] added tests
• [x] updated/added doxygen
• [ ] updated appropriate READMEs
• [ ] Updated manual and documentation

Human Review Checklist

• [ ] Verify OpenSSL compatibility functions were correctly identified and removed (only functions from wolfssl/openssl/*.h headers)
• [ ] Verify WOLF_PRIVATE_KEY_ID notes accurately describe PKCS11 support requirement
• [ ] Verify WC_NO_CONSTRUCTORS notes correctly describe WOLFSSL_NO_MALLOC relationship
• [ ] Verify WOLFSSL_DUAL_ALG_CERTS notes correctly describe Post-Quantum dual algorithm signing feature
• [ ] Verify no internal/debug APIs were accidentally documented (e.g., KCAPI-only, kernel module-only functions)
• [ ] Spot check documentation accuracy for a few APIs against actual function signatures

---

Requested by: David Garske ([email protected]) Link to Devin run: https://app.devin.ai/sessions/e5ddefed4c1c468f8a22e6bfa25ea2ed

[devin-ai-integration[bot]]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• [ ] Disable automatic comment and CI monitoring

[wolfSSL-Bot]

Can one of the admins verify this patch?

[devin-ai-integration[bot]]

@dgarske Regarding your question about testing example code compilation:

Yes! I created a test script that extracts and compiles example code snippets. I tested a representative sample of 12 examples from key files (aes.h, sha256.h, rsa.h, ecc.h):

• 4 examples passed compilation (33% success rate)
• 8 examples failed, mostly due to:
  • Placeholder values (e.g., "some 16 byte key")
  • Simplified code for documentation purposes
  • Missing initialization code

The ECC examples all compiled successfully, and one RSA example passed. The failures are expected for documentation examples that use placeholders or are intentionally simplified. The examples that do compile demonstrate that the syntax and structure are correct.

Would you like me to expand the testing to more files or focus on fixing specific examples that should compile but don't?

[dgarske]

Devin please resolve merge conflicts and squash all the commits. The current state of changes looks good.

[devin-ai-integration[bot]]

@dgarske Rebase and squash completed!

All 110 commits have been rebased onto the latest master and squashed into a single commit. Merge conflicts were resolved during the rebase process:

• Type changes (e.g., Md4* → wc_Md4*, ed448_key* → const ed448_key*) were resolved by keeping the HEAD versions
• OpenSSL compatibility functions that were previously removed are not included

The PR now contains a single clean commit with all documentation changes. CI checks are running.

[devin-ai-integration[bot]]

Fixed leftover merge conflict markers in poly1305.h that were missed during the rebase. The conflict markers have been removed and the file now uses the correct HEAD version with const byte* parameters. CI is re-running with the fix.

[devin-ai-integration[bot]]

The CI failure in 6.16 (rng-tools) appears to be a flaky test unrelated to the documentation-only changes in this PR. The test shows:

FAIL: rngtestjitter.sh
rngtest: FIPS 140-2 successes: 99
rngtest: FIPS 140-2 failures: 1
rngtest: FIPS 140-2(2001-10-10) Poker: 1

This is a single probabilistic FIPS 140-2 Poker test failure (1 out of 100 runs), which is expected to occur occasionally in random number generator tests. The changes in commits e8873eba8 through 7c8123c25 only modified Doxygen documentation in doc/dox_comments/header_files/asn_public.h and doc/dox_comments/header_files/dsa.h.

Could you please re-run the failed 6.16 job?