Add Kryoptic user guide#443
Conversation
Adds a new user guide (`doc/User_Guide.md`) to document the configuration and usage of the Kryoptic PKCS#11 soft token. This documentation is added to provide users with a centralized reference for interacting with the library. It explains supported environment variables, TOML configuration structures (including global and slot-specific options), and provides practical examples for initializing tokens via `pkcs11-tool` and integrating with OpenSSL. Co-authored-by: Gemini <gemini@google.com> Signed-off-by: Simo Sorce <simo@redhat.com>
|
Thank you, this looks great. LGTM |
|
Looks good! The only though I have if we should convert this to manual page so its directly accessible for Fedora users rather than having just upstream documentation or some documentation which is hard to discover. |
|
I have some code in IPA that turns markdown to man pages |
|
I think there is a pandoc filter for md -> grof, lemme see if I can easily add something here, the main question is how to integrate this with cargo doc ? Or should we do this only in the Fedora spec file and not through cargo ? |
|
You can do that with mdbook renderers: https://rust-lang.github.io/mdBook/format/configuration/renderers.html#custom-backend-commands. I have this in Akamu: The renderer script copies rustdoc output into mdbook's output. It can do whatever you want |
|
Thinking a bit furhter, the manual pages should be more specifc. I think there should be a generic one for kryoptic (libkryptic_pkcs11?), separate for kryoptic.conf and eventually manuals for the tools (but it looks like we do not install these in Fedora?)/ |
Yeah we do not install the tools in fedora, they are mostly for testing, except the softhsm migration one. I can create manpages for them I guess, but should we do it in this PR? |
|
@Jakuje It took me little to generate three manpages, let me know if these go in the direction we need |
simo5
force-pushed
the
userguide
branch
3 times, most recently
from
4284181 to
f7a7469
Compare
This adds markdown-formatted manual pages for the Kryoptic project to provide clear, user-facing documentation for the module and its utilities. The new documentation includes: - kryoptic(7): General overview, initialization, and environment variables. - kryoptic.conf(5): Configuration syntax, global options, and slot setup. - softhsm_migrate(1): Command-line options and usage for the SoftHSM v2 migration tool. Adding these files ensures users have the necessary reference material to successfully configure the PKCS#11 token, understand its runtime behavior, and migrate existing keys from SoftHSM. Co-authored-by: Gemini <gemini@google.com> Signed-off-by: Simo Sorce <simo@redhat.com>
This adds man page generation from markdown sources for kryoptic, its configuration, and the softhsm_migrate tool to provide system documentation for users. The Makefile and RPM spec file are updated to build these pages using pandoc and package them. Additionally, a new Cargo build script using mandown is introduced to generate the tool man pages during the Rust build process. Co-authored-by: Gemini <gemini@google.com> Signed-off-by: Simo Sorce <simo@redhat.com>
3 participants
Description
Adds a new user guide (
doc/User_Guide.md) to document the configuration and usage of the Kryoptic PKCS#11 soft token.This documentation is added to provide users with a centralized reference for interacting with the library. It explains supported environment variables, TOML configuration structures (including global and slot-specific options), and provides practical examples for initializing tokens via
pkcs11-tooland integrating with OpenSSL.Fixes #441
Checklist
Test suite updatedRustdoc string were added or updatedReviewer's checklist: