Skip to content

Commit b2aa819

Browse files
dgarskedgarske
authored
Merge pull request #144 from wolfSSL/devin/1759157052-align-docs
Add PKCS#11 Doxygen documentation
2 parents d8d3e2d + f8ab528 commit b2aa819

File tree

13 files changed

+2814
-0
lines changed

13 files changed

+2814
-0
lines changed

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,3 +72,7 @@ tests/token_path_test
7272
tests/rsa_session_persistence_test
7373

7474
IDE/VisualStudio/.vs
75+
76+
doc/doxygen_warnings
77+
doc/html/
78+
doc/refman.pdf

‎Makefile.am‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,8 @@ include tests/include.am
3838
include IDE/include.am
3939
include debian/include.am
4040
include Docker/include.am
41+
include doc/include.am
42+
4143

4244
EXTRA_DIST+= README.md
4345
EXTRA_DIST+= LICENSE

‎doc/README_DOXYGEN‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
wolfPKCS11 with Doxygen
2+
3+
---- Dependencies ----
4+
5+
- cmake
6+
- make
7+
- git
8+
- doxygen
9+
- latex (optional, for PDF generation; pdflatex provided by texlive)
10+
11+
On Debian/Ubuntu you can install LaTeX with:
12+
sudo apt install texlive texlive-latex-extra
13+
14+
---- Generating the Documentation ----
15+
16+
From the top-level wolfPKCS11 directory, run:
17+
18+
make dox # builds both HTML and PDF (PDF requires LaTeX)
19+
make dox-html # builds only HTML
20+
make dox-pdf # builds only PDF
21+
22+
The first run with -install will build doxygen from source if it is not found,
23+
so the target may take longer the first time.
24+
25+
After generation:
26+
- Open doc/html/index.html in a browser to view HTML documentation.
27+
- The PDF (if built) will be available at doc/refman.pdf.
28+
29+
---- Notes on Configuration ----
30+
31+
Doxygen configuration files live under:
32+
- doc/formats/html/Doxyfile (HTML settings)
33+
- doc/formats/pdf/Doxyfile (PDF/LaTeX settings)
34+
35+
This documentation targets the public PKCS#11 API:
36+
- wolfpkcs11/pkcs11.h
37+
- wolfpkcs11/version.h
38+
39+
Internal sources and tests are excluded from the documentation.

‎doc/dox_comments/header_files/doxygen_groups.h‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
/**
2+
* \defgroup pkcs11_01_core Core
3+
* Core library initialization and finalization functions.
4+
*
5+
* These functions handle the basic lifecycle of the PKCS#11 library.
6+
* Start here: C_Initialize() must be called before any other functions.
7+
* @{
8+
* \}
9+
*/
10+
11+
/**
12+
* \defgroup pkcs11_structs Data Structures
13+
* PKCS#11 data structures supported by wolfPKCS11.
14+
*
15+
* These types include core Cryptoki structures (e.g., CK_INFO, CK_SLOT_INFO,
16+
* CK_TOKEN_INFO, CK_SESSION_INFO, CK_ATTRIBUTE, CK_MECHANISM, CK_RSA_PKCS_PSS_PARAMS,
17+
* CK_RSA_PKCS_OAEP_PARAMS, CK_ECDH1_DERIVE_PARAMS, CK_GCM_PARAMS, CK_CCM_PARAMS,
18+
* CK_TLS12_MASTER_KEY_DERIVE_PARAMS, CK_SSL3_KEY_MAT_OUT, CK_TLS12_KEY_MAT_PARAMS,
19+
* CK_PKCS5_PBKD2_PARAMS, CK_PKCS5_PBKD2_PARAMS2, CK_TLS_MAC_PARAMS) and related
20+
* scalar typedefs. Detailed per-structure docs are provided in header_files.
21+
* @{
22+
* \}
23+
*/
24+
25+
/**
26+
* \defgroup pkcs11_02_slot_token SlotsAndTokens
27+
* Slot and token discovery and management.
28+
*
29+
* Functions to enumerate available slots, get token information,
30+
* and manage token state.
31+
* @{
32+
* \}
33+
*/
34+
35+
/**
36+
* \defgroup pkcs11_03_session Sessions
37+
* Session management and authentication.
38+
*
39+
* Functions to open/close sessions, login/logout, and manage
40+
* session state and operations.
41+
* @{
42+
* \}
43+
*/
44+
45+
/**
46+
* \defgroup pkcs11_04_object Objects
47+
* Object creation, discovery, and attribute management.
48+
*
49+
* Functions to create, find, destroy, and manipulate cryptographic
50+
* objects such as keys and certificates.
51+
* @{
52+
* \}
53+
*/
54+
55+
/**
56+
* \defgroup pkcs11_05_key KeyManagement
57+
* Key generation, derivation, and wrapping operations.
58+
*
59+
* Functions for generating symmetric and asymmetric keys,
60+
* deriving keys, and wrapping/unwrapping key material.
61+
* @{
62+
* \}
63+
*/
64+
65+
/**
66+
* \defgroup pkcs11_06_random Random
67+
* Random number generation and entropy seeding.
68+
*
69+
* Functions to generate random data and seed the random
70+
* number generator.
71+
* @{
72+
* \}
73+
*/
74+
75+
/**
76+
* \defgroup pkcs11_07_digest Digest
77+
* Message digest and hashing operations.
78+
*
79+
* Functions for computing cryptographic hashes and message
80+
* authentication codes (MACs).
81+
* @{
82+
* \}
83+
*/
84+
85+
/**
86+
* \defgroup pkcs11_08_encrypt_decrypt EncryptDecrypt
87+
* Symmetric and asymmetric encryption/decryption.
88+
*
89+
* Functions for encrypting and decrypting data using various
90+
* symmetric and asymmetric algorithms.
91+
* @{
92+
* \}
93+
*/
94+
95+
/**
96+
* \defgroup pkcs11_09_sign_verify SignVerify
97+
* Digital signature creation and verification.
98+
*
99+
* Functions for creating and verifying digital signatures
100+
* using various signature algorithms.
101+
* @{
102+
* \}
103+
*/
104+
105+
/**
106+
* \defgroup pkcs11_10_extensions wolfPKCS11 Extensions
107+
* wolfPKCS11-specific extensions to the PKCS#11 specification.
108+
*
109+
* These functions and features are specific to wolfPKCS11 and extend
110+
* the standard PKCS#11 API with additional functionality for debugging,
111+
* configuration, and wolfSSL integration.
112+
* @{
113+
* \}
114+
*/
115+
116+
/**
117+
* \defgroup pkcs11_nss_extensions_overview NSS Extensions
118+
* Mozilla NSS compatibility extensions for wolfPKCS11.
119+
*
120+
* These extensions provide compatibility with Mozilla NSS (Network Security
121+
* Services) and enable wolfPKCS11 to be used as a drop-in replacement for
122+
* NSS's PKCS#11 module. Features include NSS-specific mechanisms for TLS
123+
* operations, trust objects for certificate management, and PKCS#12 PBE
124+
* key generation.
125+
*
126+
* NSS extensions are enabled using the --enable-nss configure flag.
127+
* @{
128+
* \}
129+
*/

‎doc/dox_comments/header_files/doxygen_pages.h‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
/**
2+
* \mainpage wolfPKCS11 Documentation
3+
*
4+
* \section intro Introduction
5+
*
6+
* wolfPKCS11 is a PKCS#11 (Cryptoki) implementation backed by wolfSSL's
7+
* wolfCrypt. It provides a standard API for cryptographic tokens such as HSMs,
8+
* smart cards, and software tokens.
9+
*
10+
* \section scope Scope
11+
*
12+
* This documentation focuses on the public PKCS#11 API exposed by
13+
* wolfPKCS11 via wolfpkcs11/pkcs11.h. Functions are organized into logical
14+
* groups that follow the typical PKCS#11 application workflow.
15+
*
16+
* \section api_groups API Organization
17+
*
18+
* The PKCS#11 API is organized into the following functional groups,
19+
* listed in the typical order of use:
20+
*
21+
* 1. **\ref pkcs11_01_core "Core"** - Library initialization and finalization
22+
* 2. **\ref pkcs11_02_slot_token "SlotsAndTokens"** - Slot and token management
23+
* 3. **\ref pkcs11_03_session "Sessions"** - Session management and authentication
24+
* 4. **\ref pkcs11_04_object "Objects"** - Object creation and management
25+
* 5. **\ref pkcs11_05_key "KeyManagement"** - Key generation and key operations
26+
* 6. **\ref pkcs11_06_random "Random"** - Random number generation
27+
* 7. **\ref pkcs11_07_digest "Digest"** - Message digest operations
28+
* 8. **\ref pkcs11_08_encrypt_decrypt "EncryptDecrypt"** - Encryption and decryption
29+
* 9. **\ref pkcs11_09_sign_verify "SignVerify"** - Digital signatures
30+
* 10. **\ref pkcs11_10_extensions "wolfPKCS11 Extensions"** - wolfPKCS11-specific extensions
31+
*
32+
* \section getting_started Getting Started
33+
*
34+
* The typical application flow follows these steps:
35+
*
36+
* \code
37+
* // 1. Get the function list
38+
* CK_FUNCTION_LIST_PTR p11;
39+
* rv = C_GetFunctionList(&p11);
40+
*
41+
* // 2. Initialize the library
42+
* rv = p11->C_Initialize(NULL_PTR);
43+
*
44+
* // 3. Get available slots
45+
* rv = p11->C_GetSlotList(CK_TRUE, NULL_PTR, &slotCount);
46+
*
47+
* // 4. Open a session
48+
* rv = p11->C_OpenSession(slotID, CKF_SERIAL_SESSION | CKF_RW_SESSION,
49+
* NULL_PTR, NULL_PTR, &hSession);
50+
*
51+
* // 5. Login if required
52+
* rv = p11->C_Login(hSession, CKU_USER, pin, pinLen);
53+
*
54+
* // 6. Create or find objects (keys, certificates)
55+
* rv = p11->C_FindObjectsInit(hSession, template, templateCount);
56+
*
57+
* // 7. Perform cryptographic operations
58+
* rv = p11->C_EncryptInit(hSession, &mechanism, hKey);
59+
* rv = p11->C_Encrypt(hSession, plaintext, plaintextLen, ciphertext, &ciphertextLen);
60+
*
61+
* // 8. Cleanup
62+
* rv = p11->C_Logout(hSession);
63+
* rv = p11->C_CloseSession(hSession);
64+
* rv = p11->C_Finalize(NULL_PTR);
65+
* \endcode
66+
*
67+
* \section workflow Application Workflow
68+
*
69+
* ### Initialization Phase
70+
* - Use \ref pkcs11_01_core "Core" functions to initialize the library
71+
* - Use \ref pkcs11_02_slot_token "SlotsAndTokens" functions to discover available tokens
72+
* - Use \ref pkcs11_03_session "Sessions" functions to establish a session
73+
*
74+
* ### Setup Phase
75+
* - Use \ref pkcs11_04_object "Objects" functions to find existing keys/certificates
76+
* - Use \ref pkcs11_05_key "KeyManagement" functions to generate new keys if needed
77+
* - Use \ref pkcs11_06_random "Random" functions for nonce generation
78+
*
79+
* ### Operations Phase
80+
* - Use \ref pkcs11_07_digest "Digest" functions for hashing
81+
* - Use \ref pkcs11_08_encrypt_decrypt "EncryptDecrypt" functions for data protection
82+
* - Use \ref pkcs11_09_sign_verify "SignVerify" functions for authentication
83+
*
84+
* ### Cleanup Phase
85+
* - Close sessions and finalize the library
86+
*
87+
* \section extensions wolfPKCS11 Extensions
88+
*
89+
* wolfPKCS11 provides several extensions beyond the standard PKCS#11 specification:
90+
* - Use \ref pkcs11_10_extensions "wolfPKCS11 Extensions" for debugging and wolfSSL integration
91+
* - Debug logging functions for troubleshooting
92+
* - Custom attributes for wolfSSL crypto callback integration
93+
* - STM32U5 DHUK support for hardware-specific features
94+
* - NSS compatibility extensions:
95+
* - See \ref pkcs11_nss_extensions_overview "NSS Extensions Overview"
96+
* - \ref pkcs11_nss_mechanisms "NSS Mechanisms"
97+
* - \ref pkcs11_nss_objects "NSS Object Types"
98+
* - \ref pkcs11_nss_attributes "NSS Attributes"
99+
* - \ref pkcs11_nss_structures "NSS Parameter Structures"
100+
* - \ref pkcs11_nss_examples "NSS Extension Examples"
101+
* - \ref pkcs11_nss_compatibility "NSS Compatibility Notes"
102+
*
103+
* \section data_structs Data Structures
104+
*
105+
* 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".
106+
*
107+
* \section standards Standards Compliance
108+
*
109+
* wolfPKCS11 implements PKCS#11 v2.40 specification. For detailed information
110+
* about the standard, refer to the OASIS PKCS#11 Cryptographic Token Interface Standard
111+
*
112+
* \section support Support and Examples
113+
*
114+
* For additional help:
115+
* - Check the examples/ directory for sample applications
116+
* - Visit wolfSSL documentation at docs.wolfssl.com
117+
* - Contact wolfSSL support for commercial licensing and support
118+
*/

‎doc/dox_comments/header_files/internal.h‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
/**
2+
* \file internal.h
3+
* \brief Internal API documentation for wolfPKCS11.
4+
*
5+
* This file aligns with the installed header wolfpkcs11/internal.h.
6+
* Internal structures and helper APIs may be documented here.
7+
*/

0 commit comments

Comments
 (0)