Pkcs11Manager
The thread-safe, multi-token PKCS#11 façade — list tokens, list certificates, unlock, watch for hot-plug, and the supporting types
Vendor PKCS#11 driver .dll/.sos are not thread-safe, so Pkcs11Manager funnels all module
access through a single dedicated worker thread (an actor). Callers hold a cheap-clone
Pkcs11Manager handle; every call blocks on a request/reply to the worker, so from an async runtime
wrap calls in tokio::task::spawn_blocking (or your runtime's equivalent).
Three layers
(1) list_tokens — connected tokens + hardware info + PIN flags + certificate
count, no PIN. (2) list_certificates — one token's certificates, filtered,
no PIN. (3) unlock — log in and get a Signer ready for sign_pdf.
Lifecycle and observability
The worker stays alive while any Pkcs11Manager clone or an unlocked signer exists; it ends (and
logs the token out) when the last one drops. The manager emits tracing spans/events on the
mudrit_keystore::pkcs11_manager target — worker lifecycle, module load, unlock/sign/logout outcomes,
token plug/remove. Nothing is recorded until you install a subscriber
(e.g. tracing_subscriber::fmt().init()), and PINs are never logged — Pin doesn't even
Debug-print its value.
Pkcs11Manager
Feature pkcs11. Clone — a cheap handle to the worker.
Prop
Type
Prop
Type
use mudrit::mudrit_keystore::{Pkcs11Manager, Pin};
let mgr = Pkcs11Manager::new(["eps2003csp11v2.dll".to_string()]);
for t in mgr.list_tokens()? {
println!("{} ({} certs)", t.label, t.certificate_count);
}
let signer = mgr.unlock_by_serial("1a2b3c", Some(Pin::new("123456")))?;
let signed = sign_pdf(&pdf, signer.as_ref(), &cfg)?;Pkcs11ManagerBuilder
Fluent configuration for Pkcs11Manager; Default uses no modules, the file-exists validator, the
default SignatureAlgorithm, and no auto-logout.
Prop
Type
TokenRef
A stable, serializable reference to one connected token: the module path + PKCS#11 slot id.
Debug + Clone + PartialEq + Eq + Hash.
Prop
Type
TokenSummary
A connected token: hardware info + PIN flags + certificate count — all read with no PIN.
Returned by list_tokens.
Prop
Type
PinStatus
The token's PIN state — PKCS#11 exposes flags, not an exact remaining count. Copy + Default.
Prop
Type
ModuleStatus
Per-module load result, after validation + C_Initialize.
Prop
Type
ModuleValidator
pub type ModuleValidator = Arc<dyn Fn(&str) -> Result<()> + Send + Sync>;A pluggable module-path validator run before loading; return Err to reject a path. The built-in
default validator checks that the path exists on disk (Path::new(p).exists()) and returns
Error::NotFound otherwise.
use std::sync::Arc;
use mudrit::mudrit_keystore::{Pkcs11ManagerBuilder, Error};
let mgr = Pkcs11ManagerBuilder::default()
.module("eps2003csp11v2.dll")
.validator(Arc::new(|p: &str| {
if p.ends_with(".dll") { Ok(()) } else { Err(Error::NotFound(format!("not a DLL: {p}"))) }
}))
.build();Pin
A token PIN held in memory that is zeroized on drop. Clone; Debug prints Pin(***), never
the value.
Prop
Type
TokenInfo
Pkcs11Manager shares the same connected-token metadata shape used by Pkcs11MultiStore — see
TokenInfo in the Backends reference for the full field table.