feat(pkcs11): PKCS#11 v3.0 interface discovery, C_LoginUser, and conformance profiles

[Manuthor]

PKCS#11 v3.0 interface discovery foundation: C_GetInterfaceList/C_GetInterface, C_LoginUser, and self-declared conformance profiles — additive only, existing v2.40 consumers unaffected.

• Adds v3 interface discovery (C_GetInterfaceList/C_GetInterface) with a v3 function-pointer table populated once via Once; keeps legacy C_GetFunctionList (v2.40) untouched.
• Adds C_LoginUser, synthetic CKO_PROFILE objects (baseline / extended-provider / auth-token / public-certs), and CKA_UNIQUE_ID attribute support.
• Hardens login: PIN/username size caps + UTF-8 validation, rejects CKU_CONTEXT_SPECIFIC/unknown user types; fixes C_GetAttributeValue buffer-too-small handling (security advisory COSMIAN-2026-022).
• Closes several TOCTOU/state races around interface discovery vs. logout/backend registration.
• Adds HSM consumer-side C_GetInterfaceList capability probe (capped at 4096 interfaces).

Closes #1153

[Copilot]

🟡 Changes recommended

There are correctness and integration blockers (FFI CK_INTERFACE layout risk, missing nav.yml sync, incorrect mechanisms/logging docs, and an FFI null-out-pointer crash in C_GetFunctionList).

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR extends the PKCS#11 surface to cover Cryptoki v3.x “interfaces” discovery (provider side) and adds an additive v3 capability probe for HSM consumers, alongside documentation, tests, and changelog entries to support the rollout.

Changes:

• Add C_GetInterfaceList/C_GetInterface/C_LoginUser, a v3.0 function list table, and non-null v3-only stubs in the PKCS#11 provider/module.
• Add consumer-side v3 interface capability probing (supports_pkcs11_v3_interfaces / list_pkcs11_v3_interfaces) and a SoftHSM2 additive probe test.
• Add docs + ADR + changelog updates describing PKCS#11 v3 scope and behavior (profiles, logging, mechanisms).

File summaries

File	Description
README.md	Link “PKCS#11 integrations” to the new provider-module documentation page.
lychee.toml	Exclude eviden.com from link checking due to crawler 503 responses.
documentation/docs/SUMMARY.md	Add the new PKCS#11 provider doc page to mdBook navigation (but nav.yml is not updated).
documentation/docs/integrations/pkcs11_provider.md	New provider reference page (mechanisms + logging sections need correction).
documentation/docs/hsm_support/hsm_operations.md	Document consumer-side v2.40 compatibility + additive v3 capability probe; link to ADR.
documentation/docs/adr/2026-09-03-pkcs11-v3-scope-decision-ffi-foundation.md	New ADR; scope text contradicts actual provider-side changes in this PR.
crate/hsm/softhsm2/src/tests.rs	Add an ignored integration test asserting v3 probe is additive for SoftHSM2 (v2.40).
crate/hsm/base_hsm/src/pkcs11_v3.rs	New consumer-side v3 interface parsing/types (FFI layout risk called out in comments).
crate/hsm/base_hsm/src/lib.rs	Export InterfaceDescriptor and register the new pkcs11_v3 module.
crate/hsm/base_hsm/src/hsm_lib.rs	Resolve C_GetInterfaceList best-effort and implement interface listing with allocation cap.
crate/crypto/src/openssl/ocsp.rs	Minor import reordering (warn).
crate/clients/pkcs11/provider/src/tests.rs	Add provider-side tests for v3 interface discovery, C_LoginUser, and profile objects.
crate/clients/pkcs11/provider/src/lib.rs	Share backend init across v2/v3 entrypoints; implement C_GetInterfaceList/C_GetInterface.
crate/clients/pkcs11/module/src/sessions.rs	Add supported profile IDs and return CKO_PROFILE objects in find-objects flow.
crate/clients/pkcs11/module/src/pkcs11.rs	Add v3.0 function list table + CK_INTERFACE descriptor + v3-only non-null stubs + C_LoginUser.
crate/clients/pkcs11/module/src/core/object.rs	Make CKO_PROFILE objects public (CKA_PRIVATE = CK_FALSE).
CHANGELOG/pkcs11_v3.md	Branch changelog capturing provider+consumer PKCS#11 v3 work, docs, and tests.

Review details

Suppressed comments (4)

crate/hsm/base_hsm/src/hsm_lib.rs:323

• Same as above: #[expect(unsafe_code)] is likely to produce unfulfilled_lint_expectations warnings (unless unsafe_code is enabled at warn/deny) and is a new lint attribute on freshly added code. The // SAFETY: comment is sufficient.

        let mut buffer = vec![CkInterface::default(); count_usize];
        #[expect(unsafe_code)]
        // SAFETY: `buffer` was allocated using the exact count returned by the first
        // call, as required by the PKCS#11 v3.0 specification for `C_GetInterfaceList`.
        let rv = unsafe { get_interface_list(buffer.as_mut_ptr(), &raw mut count) };

crate/clients/pkcs11/provider/src/tests.rs:694

• Same issue here: #[expect(unsafe_code)] can create unfulfilled_lint_expectations warnings unless the crate enables unsafe_code at warn/deny. Prefer relying on the existing // SAFETY: comments around the unsafe calls instead of the lint attribute.

#[test]
#[serial]
#[expect(unsafe_code)]
fn test_get_interface_rejects_mismatches() -> Pkcs11Result<()> {
    let _backend = initialize_backend()?;

crate/clients/pkcs11/provider/src/tests.rs:759

• Same here: #[expect(unsafe_code)] is likely to cause unfulfilled_lint_expectations warnings unless unsafe_code is enabled. Removing it should keep the test intent intact (the unsafe blocks are already locally documented).

#[test]
#[serial]
#[expect(unsafe_code)]
fn test_c_login_user() -> Pkcs11Result<()> {
    let _backend = initialize_backend()?;

crate/clients/pkcs11/provider/src/tests.rs:815

• Same issue: #[expect(unsafe_code)] may trigger unfulfilled_lint_expectations warnings unless unsafe_code is enabled at warn/deny. Prefer removing the lint attribute and keeping the existing // SAFETY: documentation for each unsafe call.

#[test]
#[serial]
#[expect(unsafe_code)]
fn test_profile_objects_self_declared() -> Pkcs11Result<()> {
    let _backend = initialize_backend()?;

• Files reviewed: 17/17 changed files
• Comments generated: 9
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.