Add PKCS#11 Doxygen documentation

.gitignore

@@ -72,3 +72,7 @@ tests/token_path_test
 tests/rsa_session_persistence_test
 
 IDE/VisualStudio/.vs
+
+doc/doxygen_warnings
+doc/html/
+doc/refman.pdf

Makefile.am

@@ -38,6 +38,8 @@ include tests/include.am
 include IDE/include.am
 include debian/include.am
 include Docker/include.am
+include doc/include.am
+
 
 EXTRA_DIST+= README.md
 EXTRA_DIST+= LICENSE

doc/README_DOXYGEN

@@ -0,0 +1,39 @@
+wolfPKCS11 with Doxygen
+
+---- Dependencies ----
+
+- cmake
+- make
+- git
+- doxygen
+- latex (optional, for PDF generation; pdflatex provided by texlive)
+
+On Debian/Ubuntu you can install LaTeX with:
+  sudo apt install texlive texlive-latex-extra
+
+---- Generating the Documentation ----
+
+From the top-level wolfPKCS11 directory, run:
+
+    make dox       # builds both HTML and PDF (PDF requires LaTeX)
+    make dox-html  # builds only HTML
+    make dox-pdf   # builds only PDF
+
+The first run with -install will build doxygen from source if it is not found,
+so the target may take longer the first time.
+
+After generation:
+- Open doc/html/index.html in a browser to view HTML documentation.
+- The PDF (if built) will be available at doc/refman.pdf.
+
+---- Notes on Configuration ----
+
+Doxygen configuration files live under:
+- doc/formats/html/Doxyfile  (HTML settings)
+- doc/formats/pdf/Doxyfile   (PDF/LaTeX settings)
+
+This documentation targets the public PKCS#11 API:
+- wolfpkcs11/pkcs11.h
+- wolfpkcs11/version.h
+
+Internal sources and tests are excluded from the documentation.

doc/dox_comments/header_files/doxygen_groups.h

@@ -0,0 +1,129 @@
+/**
+ * \defgroup pkcs11_01_core Core
+ * Core library initialization and finalization functions.
+ * 
+ * These functions handle the basic lifecycle of the PKCS#11 library.
+ * Start here: C_Initialize() must be called before any other functions.
+ * @{
+ * \}
+ */
+
+/**
+ * \defgroup pkcs11_structs Data Structures
+ * PKCS#11 data structures supported by wolfPKCS11.
+ *
+ * These types include core Cryptoki structures (e.g., CK_INFO, CK_SLOT_INFO,
+ * CK_TOKEN_INFO, CK_SESSION_INFO, CK_ATTRIBUTE, CK_MECHANISM, CK_RSA_PKCS_PSS_PARAMS,
+ * CK_RSA_PKCS_OAEP_PARAMS, CK_ECDH1_DERIVE_PARAMS, CK_GCM_PARAMS, CK_CCM_PARAMS,
+ * CK_TLS12_MASTER_KEY_DERIVE_PARAMS, CK_SSL3_KEY_MAT_OUT, CK_TLS12_KEY_MAT_PARAMS,
+ * CK_PKCS5_PBKD2_PARAMS, CK_PKCS5_PBKD2_PARAMS2, CK_TLS_MAC_PARAMS) and related
+ * scalar typedefs. Detailed per-structure docs are provided in header_files.
+ * @{
+ * \}
+ */
+
+/**
+ * \defgroup pkcs11_02_slot_token SlotsAndTokens
+ * Slot and token discovery and management.
+ * 
+ * Functions to enumerate available slots, get token information,
+ * and manage token state.
+ * @{
+ * \}
+ */
+
+/**
+ * \defgroup pkcs11_03_session Sessions
+ * Session management and authentication.
+ * 
+ * Functions to open/close sessions, login/logout, and manage
+ * session state and operations.
+ * @{
+ * \}
+ */
+
+/**
+ * \defgroup pkcs11_04_object Objects
+ * Object creation, discovery, and attribute management.
+ * 
+ * Functions to create, find, destroy, and manipulate cryptographic
+ * objects such as keys and certificates.
+ * @{
+ * \}
+ */
+
+/**
+ * \defgroup pkcs11_05_key KeyManagement
+ * Key generation, derivation, and wrapping operations.
+ * 
+ * Functions for generating symmetric and asymmetric keys,
+ * deriving keys, and wrapping/unwrapping key material.
+ * @{
+ * \}
+ */
+
+/**
+ * \defgroup pkcs11_06_random Random
+ * Random number generation and entropy seeding.
+ * 
+ * Functions to generate random data and seed the random
+ * number generator.
+ * @{
+ * \}
+ */
+
+/**
+ * \defgroup pkcs11_07_digest Digest
+ * Message digest and hashing operations.
+ * 
+ * Functions for computing cryptographic hashes and message
+ * authentication codes (MACs).
+ * @{
+ * \}
+ */
+
+/**
+ * \defgroup pkcs11_08_encrypt_decrypt EncryptDecrypt
+ * Symmetric and asymmetric encryption/decryption.
+ * 
+ * Functions for encrypting and decrypting data using various
+ * symmetric and asymmetric algorithms.
+ * @{
+ * \}
+ */
+
+/**
+ * \defgroup pkcs11_09_sign_verify SignVerify
+ * Digital signature creation and verification.
+ * 
+ * Functions for creating and verifying digital signatures
+ * using various signature algorithms.
+ * @{
+ * \}
+ */
+
+/**
+ * \defgroup pkcs11_10_extensions wolfPKCS11 Extensions
+ * wolfPKCS11-specific extensions to the PKCS#11 specification.
+ * 
+ * These functions and features are specific to wolfPKCS11 and extend
+ * the standard PKCS#11 API with additional functionality for debugging,
+ * configuration, and wolfSSL integration.
+ * @{
+ * \}
+ */
+
+/**
+ * \defgroup pkcs11_nss_extensions_overview NSS Extensions
+ * Mozilla NSS compatibility extensions for wolfPKCS11.
+ * 
+ * These extensions provide compatibility with Mozilla NSS (Network Security
+ * Services) and enable wolfPKCS11 to be used as a drop-in replacement for
+ * NSS's PKCS#11 module. Features include NSS-specific mechanisms for TLS
+ * operations, trust objects for certificate management, and PKCS#12 PBE
+ * key generation.
+ * 
+ * NSS extensions are enabled using the --enable-nss configure flag.
+ * @{
+ * \}
+ */

doc/dox_comments/header_files/doxygen_pages.h

@@ -0,0 +1,118 @@
+/**
+ * \mainpage wolfPKCS11 Documentation
+ *
+ * \section intro Introduction
+ *
+ * wolfPKCS11 is a PKCS#11 (Cryptoki) implementation backed by wolfSSL's
+ * wolfCrypt. It provides a standard API for cryptographic tokens such as HSMs,
+ * smart cards, and software tokens.
+ *
+ * \section scope Scope
+ *
+ * This documentation focuses on the public PKCS#11 API exposed by
+ * wolfPKCS11 via wolfpkcs11/pkcs11.h. Functions are organized into logical
+ * groups that follow the typical PKCS#11 application workflow.
+ *
+ * \section api_groups API Organization
+ *
+ * The PKCS#11 API is organized into the following functional groups,
+ * listed in the typical order of use:
+ *
+ * 1. **\ref pkcs11_01_core "Core"** - Library initialization and finalization
+ * 2. **\ref pkcs11_02_slot_token "SlotsAndTokens"** - Slot and token management
+ * 3. **\ref pkcs11_03_session "Sessions"** - Session management and authentication
+ * 4. **\ref pkcs11_04_object "Objects"** - Object creation and management
+ * 5. **\ref pkcs11_05_key "KeyManagement"** - Key generation and key operations
+ * 6. **\ref pkcs11_06_random "Random"** - Random number generation
+ * 7. **\ref pkcs11_07_digest "Digest"** - Message digest operations
+ * 8. **\ref pkcs11_08_encrypt_decrypt "EncryptDecrypt"** - Encryption and decryption
+ * 9. **\ref pkcs11_09_sign_verify "SignVerify"** - Digital signatures
+ * 10. **\ref pkcs11_10_extensions "wolfPKCS11 Extensions"** - wolfPKCS11-specific extensions
+ *
+ * \section getting_started Getting Started
+ *
+ * The typical application flow follows these steps:
+ *
+ * \code
+ * // 1. Get the function list
+ * CK_FUNCTION_LIST_PTR p11;
+ * rv = C_GetFunctionList(&p11);
+ *
+ * // 2. Initialize the library
+ * rv = p11->C_Initialize(NULL_PTR);
+ *
+ * // 3. Get available slots
+ * rv = p11->C_GetSlotList(CK_TRUE, NULL_PTR, &slotCount);
+ *
+ * // 4. Open a session
+ * rv = p11->C_OpenSession(slotID, CKF_SERIAL_SESSION | CKF_RW_SESSION,
+ *                         NULL_PTR, NULL_PTR, &hSession);
+ *
+ * // 5. Login if required
+ * rv = p11->C_Login(hSession, CKU_USER, pin, pinLen);
+ *
+ * // 6. Create or find objects (keys, certificates)
+ * rv = p11->C_FindObjectsInit(hSession, template, templateCount);
+ *
+ * // 7. Perform cryptographic operations
+ * rv = p11->C_EncryptInit(hSession, &mechanism, hKey);
+ * rv = p11->C_Encrypt(hSession, plaintext, plaintextLen, ciphertext, &ciphertextLen);
+ *
+ * // 8. Cleanup
+ * rv = p11->C_Logout(hSession);
+ * rv = p11->C_CloseSession(hSession);
+ * rv = p11->C_Finalize(NULL_PTR);
+ * \endcode
+ *
+ * \section workflow Application Workflow
+ *
+ * ### Initialization Phase
+ * - Use \ref pkcs11_01_core "Core" functions to initialize the library
+ * - Use \ref pkcs11_02_slot_token "SlotsAndTokens" functions to discover available tokens
+ * - Use \ref pkcs11_03_session "Sessions" functions to establish a session
+ *
+ * ### Setup Phase
+ * - Use \ref pkcs11_04_object "Objects" functions to find existing keys/certificates
+ * - Use \ref pkcs11_05_key "KeyManagement" functions to generate new keys if needed
+ * - Use \ref pkcs11_06_random "Random" functions for nonce generation
+ *
+ * ### Operations Phase
+ * - Use \ref pkcs11_07_digest "Digest" functions for hashing
+ * - Use \ref pkcs11_08_encrypt_decrypt "EncryptDecrypt" functions for data protection
+ * - Use \ref pkcs11_09_sign_verify "SignVerify" functions for authentication
+ *
+ * ### Cleanup Phase
+ * - Close sessions and finalize the library
+ *
+ * \section extensions wolfPKCS11 Extensions
+ *
+ * wolfPKCS11 provides several extensions beyond the standard PKCS#11 specification:
+ * - Use \ref pkcs11_10_extensions "wolfPKCS11 Extensions" for debugging and wolfSSL integration
+ * - Debug logging functions for troubleshooting
+ * - Custom attributes for wolfSSL crypto callback integration
+ * - STM32U5 DHUK support for hardware-specific features
+ * - NSS compatibility extensions:
+ *   - See \ref pkcs11_nss_extensions_overview "NSS Extensions Overview"
+ *   - \ref pkcs11_nss_mechanisms "NSS Mechanisms"
+ *   - \ref pkcs11_nss_objects "NSS Object Types"
+ *   - \ref pkcs11_nss_attributes "NSS Attributes"
+ *   - \ref pkcs11_nss_structures "NSS Parameter Structures"
+ *   - \ref pkcs11_nss_examples "NSS Extension Examples"
+ *   - \ref pkcs11_nss_compatibility "NSS Compatibility Notes"
+ *
+ * \section data_structs Data Structures
+ *
+ * For definitions of the PKCS#11 data structures supported by wolfPKCS11, see \ref data_structures.h "data_structures.h". These populate Doxygen's "Data Structure Index" and "Data Structure Documentation".
+ *
+ * \section standards Standards Compliance
+ *
+ * wolfPKCS11 implements PKCS#11 v2.40 specification. For detailed information
+ * about the standard, refer to the OASIS PKCS#11 Cryptographic Token Interface Standard
+ *
+ * \section support Support and Examples
+ *
+ * For additional help:
+ * - Check the examples/ directory for sample applications
+ * - Visit wolfSSL documentation at docs.wolfssl.com
+ * - Contact wolfSSL support for commercial licensing and support
+ */

doc/dox_comments/header_files/internal.h

@@ -0,0 +1,7 @@
+/**
+ * \file internal.h
+ * \brief Internal API documentation for wolfPKCS11.
+ *
+ * This file aligns with the installed header wolfpkcs11/internal.h.
+ * Internal structures and helper APIs may be documented here.
+ */