Documentation overhaul

docs/src/0-Index.md

@@ -0,0 +1,72 @@
+# wolfHSM Documentation
+
+A portable, open-source client-server framework for hardware cryptography, non-volatile memory, and secure processing.
+
+## Table of Contents
+
+### [1. Overview](1-Overview.md)
+Introduction to wolfHSM, its feature set, and supported hardware platforms.
+
+- Overview
+- Features
+- Supported Platforms
+
+### [2. FAQs](2-FAQs.md)
+Answers to common questions about wolfHSM's purpose, scope, dependencies, and capabilities.
+
+### [3. Quickstart](3-Quickstart.md)
+Step-by-step guide to getting a client and server up and running.
+
+- Client Quickstart
+- Server Quickstart
+- Deep Dive: Transport, Comm Layer, NVM, wolfCrypt init, server context, request processing
+
+### [4. Architecture](4-Architecture.md)
+Architectural overview of the client/server libraries and communication stack.
+
+- Client/Server libraries
+- Code and API organization (Client API, Server API, source modules, compilation)
+- Client/Server communication and communication stack
+- Library configuration
+- Internals deep dive: modular architecture
+
+### [5. Features](5-Features.md)
+Detailed reference for each major wolfHSM subsystem.
+
+- Cryptography and wolfCrypt integration (offload, algorithms, hardware acceleration, blocking/non-blocking, request timeouts)
+- Non-Volatile Memory (NVM interface, metadata, backends, flash abstraction)
+- Keystore (key cache, key IDs, global keys, wrapped keys, usage policies)
+- Certificate management (trusted roots, chain verification, verify cache, Acert support)
+- Communication layer and transport backends
+- DMA support (DMA crypto device, callbacks, allowlisting, 32/64-bit addressing)
+- AUTOSAR SHE subsystem
+- Non-volatile monotonic counters
+- Image manager (image/firmware verification, verify methods and actions, wolfBoot images)
+- Custom callbacks (application-defined server operations)
+- Concurrency support (per-context threading model, lock abstraction)
+- Authentication manager (PIN/certificate login, permissions; experimental)
+
+### [6. Utilities](6-Utilities.md)
+Tools shipped with wolfHSM for provisioning and validation.
+
+- NVM Provisioning Tool (`whnvmtool`)
+- Benchmark Suite (POSIX, real hardware)
+- Test Suite (POSIX, real hardware)
+
+### [7. Examples](7-Examples.md)
+Reference applications demonstrating wolfHSM usage.
+
+- POSIX example server and client (building, transport selection, NVM init)
+- Demo client library (philosophy, demo categories)
+
+### [8. Integration](8-Integration.md)
+Guides for integrating wolfHSM with the wider wolfSSL ecosystem.
+
+### [9. Configuration](9-Configuration.md)
+Build-time and runtime configuration options for wolfHSM.
+
+### [10. Client API Reference](10-API-docs-client.md)
+Reference documentation for the wolfHSM client-side API.
+
+### [11. Server API Reference](11-API-docs-server.md)
+Reference documentation for the wolfHSM server-side API.

docs/src/1-Overview.md

@@ -0,0 +1,80 @@
+# wolfHSM Documentation
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Features](#features)
+- [Supported Platforms](#supported-platforms)
+
+## Overview
+
+wolfHSM is a software framework that provides a portable and open-source client-server
+abstraction for hardware cryptography, non-volatile memory, and isolated secure processing
+that maximizes security and performance. It consists of a client-server library architecture,
+where the wolfHSM server application runs in a trusted environment, and client applications
+communicate with the server through the wolfHSM client library. wolfHSM is intended to simplify
+the challenge of moving between hardware with enhanced security features without being tied to
+any vendor-specific library calls. wolfHSM also dramatically simplifies client HSM applications
+by allowing direct use of wolfCrypt APIs, with the framework automatically offloading all sensitive
+cryptographic operations to the wolfHSM server as remote procedure calls with no additional logic
+required by the client app.
+
+Although initially targeted to automotive-style HSM-enabled microcontrollers,
+wolfHSM can run on any platform that provides a secure/trusted execution environment
+for the server. wolfHSM provides an extensible solution to support future capabilities
+of any platform while still supporting standardized interfaces and protocols such as AUTOSAR SHE.
+
+## Features
+
+* Unified client and server library APIs abstracting common HSM operations
+* Transport-agnostic architecture with reference implementations for shared memory buffers, POSIX TCP sockets, wolfSSL TLS on top of TCP, and POSIX inter-process shared memory
+* Non-volatile object store with fail-safe atomic updates and fine-grained access control policies
+* Per-client and global key stores supporting non-volatile and RAM-backed key slots, configurable usage policies, and encrypted (wrapped) keys
+* Tight integration with the wolfCrypt cryptography library
+    * Client applications may use the wolfCrypt API directly, with supported algorithms and key storage transparently offloaded to the HSM server
+    * Server applications gain access to all wolfCrypt software algorithms, with optional device-specific hardware acceleration where available
+    * Support for Post-Quantum Cryptography (PQC) algorithms
+* DMA support for shared-memory systems, including address allowlisting and configurable pre- and post-access callbacks for cache synchronization and address remapping
+* X.509 certificate chain verification, including support for RFC 5755 attribute and authorization certificates
+* Server image manager for authenticating firmware images or arbitrary regions of memory with customizable post-verification actions
+* Extensible server behavior via user-defined callbacks for runtime functionality and message handling
+* Non-volatile monotonic counters
+* AUTOSAR Secure Hardware Extension (SHE) interface support
+* Support for user authentication with full role-based access control
+
+## Supported Platforms
+
+### Infineon
+
+- TC2xx
+- TC3xx
+- TC4xx
+
+### ST Microelectronics
+
+- Stellar SR6G
+- SPC58N Bernina
+- STM32H5 Trust Zone
+
+### Texas Instruments
+
+- TDA4VH
+
+### Renesas
+
+- Renesas RH850
+
+### Microchip
+
+- PIC32CZ
+
+### AMD/Xilinx
+
+- Zynq UltraScale+
+
+### Planned Ports
+
+- Microchip PIC32CN
+- NXP S32K3 and S32G
+- AMD/Xilinx Versal
+

docs/src/10-API-docs-client.md

@@ -0,0 +1,7 @@
+# Client API Reference
+
+This chapter is the complete reference for the wolfHSM **client** API. It is generated directly from the documentation comments in the public client headers (`wolfhsm/wh_client.h`, `wolfhsm/wh_client_crypto.h`, and `wolfhsm/wh_client_she.h`), so it always tracks the source. For a conceptual, feature-oriented walkthrough of what these functions are for, see [Features](5-Features.md); this chapter documents the precise signatures, parameters, and return values.
+
+- **[Client API](wh__client_8h.md)** — client context lifecycle, communication, NVM, keystore, certificate, image-manager, and counter operations (`wolfhsm/wh_client.h`).
+- **[Client Crypto API](wh__client__crypto_8h.md)** — split-transaction, non-blocking crypto request/response calls (`wolfhsm/wh_client_crypto.h`).
+- **[Client SHE API](wh__client__she_8h.md)** — AUTOSAR SHE (Secure Hardware Extension) client interface: key update protocol (M1–M5), encrypted message handling, secure boot, deterministic PRNG, and status register access (`wolfhsm/wh_client_she.h`).

docs/src/11-API-docs-server.md

@@ -0,0 +1,9 @@
+# Server API Reference
+
+This chapter is the complete reference for the wolfHSM **server** API. It is generated directly from the documentation comments in the public server headers (`wolfhsm/wh_server.h`, `wolfhsm/wh_server_keystore.h`, `wolfhsm/wh_server_img_mgr.h`, `wolfhsm/wh_server_cert.h`, and `wolfhsm/wh_server_cert_cache.h`), so it always tracks the source. For a conceptual, feature-oriented walkthrough of what these functions are for, see [Features](5-Features.md); this chapter documents the precise signatures, parameters, and return values.
+
+- **[Server API](wh__server_8h.md)** — server context lifecycle, configuration, and top-level request dispatch (`wolfhsm/wh_server.h`).
+- **[Server Keystore API](wh__server__keystore_8h.md)** — server-side key cache and keystore operations: cache and evict slots, NVM commit, key export, and metadata access (`wolfhsm/wh_server_keystore.h`).
+- **[Server Image Manager API](wh__server__img__mgr_8h.md)** — image manager configuration, verification, and verify-state queries (`wolfhsm/wh_server_img_mgr.h`).
+- **[Server Cert API](wh__server__cert_8h.md)** — server-side certificate manager: trusted root storage, chain verification, attribute certificate support, and the user-injectable verify callback (`wolfhsm/wh_server_cert.h`).
+- **[Server Cert Cache API](wh__server__cert__cache_8h.md)** — trusted-cert verify-result cache: hash-based result lookup and invalidation (`wolfhsm/wh_server_cert_cache.h`).