docs: add PKCS#11 mock fixtures how-to#593
Conversation
Task-first user-facing how-to for the `uselesskey-pkcs11-mock` crate. Walks readers through provisioning a deterministic mock slot, the provider surface (slot info, key handles, sign/verify, certificate DER, sign counter), wiring the mock behind an `HsmSession`-style abstraction, and the three direct negative paths (unknown handle, wrong slot label, signature tamper). Mirrors the OIDC / TLS how-to pattern: explicit "what this proves / does not prove" claim boundaries, scanner-safety note, and pointers to the analogue how-tos and the crate README. Pure docs PR; no source changes.
|
Warning You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again! |
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (1)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 250364b0d3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | `certificate_der(handle)` | `Option<&[u8]>` | DER-looking bytes, not a parseable X.509 | | ||
| | `sign(handle, msg)` | `Option<Vec<u8>>` | `None` for unknown handles | | ||
| | `verify(handle, msg, sig)` | `bool` | `false` for unknown handles or wrong signature | | ||
| | `next_sign_count()` | `u64` | Monotonic counter for "did the HSM see this call?" assertions | |
There was a problem hiding this comment.
Don't describe next_sign_count as observing sign calls
This wording is misleading for tests that try to assert whether a signing request reached the mock: MockPkcs11Provider::sign only hashes and returns a signature, while next_sign_count() increments the mutex counter only when that method is called directly, so the counter is not tied to sign/verify activity. A reader following this how-to could write assertions that pass without any HSM-shaped signing call actually occurring; the doc should either explain that callers must advance the counter themselves or avoid presenting it as a "did the HSM see this call?" signal.
Useful? React with 👍 / 👎.
Pure docs PR. Task-first how-to for PKCS#11 mock fixtures. Part of the Phase 4 task-first user-paths sweep.
File added
docs/how-to/use-pkcs11-mock-fixtures.md— task-first walkthrough ofuselesskey-pkcs11-mock: provisioning the mock slot, theMockPkcs11Providersurface (slot info, key handles, sign / verify, certificate DER, sign counter), wiring it behind anHsmSession-style abstraction, the three direct negative paths (unknown handle, wrong slot label, signature tamper), explicit "what this proves / does not prove" claim boundaries, scanner-safety note, and pointers to the crate README and the OIDC / TLS analogue how-tos.No source changes. No CHANGELOG update.
Validation
cargo xtask docs-sync --check— cleancargo xtask typos— cleangit diff --check— clean