Skip to content

PKCS#11 profiles, lazy registration, token detection and catalog - #519

Open
kwart wants to merge 7 commits into
masterfrom
feaet/multi-pkcs11
Open

kwart wants to merge 7 commits into
masterfrom
feaet/multi-pkcs11

Conversation

@kwart

@kwart kwart commented Sep 29, 2026

Copy link
Copy Markdown
Member

Implements design-doc/3.3-pkcs11-profiles.md. Closes #187, closes #491.

Changes

  • Profiles: <cfg>/pkcs11.cfg is read in place as default; each <cfg>/pkcs11/<id>.cfg is another profile. Metadata (label, provider, catalog) is kept in #jsignpdf: comments.
  • Registration is lazy. Startup only parses files; a profile's provider registers on first use (Load Keys, -lk, signing). Failures are stored per profile with a readable reason: missing library, architecture mismatch, duplicate name, no slot.
  • Selection: new ksProvider option, persisted in the main config and in presets. Key loading uses KeyStore.getInstance(type, provider), and OpenPDF signs through the selected provider. Before this change the first registered provider was used even when another token was selected.
  • CLI: --keystore-provider / -kspr and --list-keystore-providers / -lkp. With several profiles and no -kspr, the CLI fails with the profile ids instead of picking one.
  • JavaFX:
    • One PKCS11 — <label> entry per profile; failed or invalid profiles are disabled, with the reason as a tooltip.
    • The keystore file field is hidden for PKCS#11 types.
    • Load Keys shows success or the failure reason in the panel.
  • Preferences → PKCS#11 is now a profile editor:
    • add / duplicate / rename / remove profiles
    • library file chooser
    • Detect tokens and Add from catalog, each with a confirmation step
    • changes apply immediately, no restart
  • Catalog: a bundled catalog.json (OpenSC, p11-kit proxy, YubiKey PIV, Belgian eID, SafeNet eToken). Config keys are allowlisted and their values validated. Inside Flatpak only the p11-kit proxy is offered.
  • A legacy pkcs11.cfg without #jsignpdf:provider still accepts JSIGNPKCS11, so 3.2 configs that selected it keep working.
  • Swing UI: honours a saved ksProvider and the same selection rules; it has no profile selector.

Tests

  • Unit tests for profiles, catalog, detector and config-text editing, CLI parsing, options round-trip and the validator.
  • Pkcs11SoftHsmSigningTest: two SoftHSM2 tokens as two profiles. It checks that key listing and OpenPDF signing hit the selected token. The test is skipped when SoftHSM2 is missing; pr-builder.yaml installs it on Linux.
  • mvn install passes locally, including the SoftHSM2 test.

Notes for review

  • The bundled catalog entries use each vendor's documented install paths but have not been tested against real hardware, so tested[] is empty for every entry. Certilia is not included because I couldn't confirm its paths.
  • The catalog is parsed by a small internal JSON reader, so engines/api gets no new dependency (this also keeps the Flatpak dependency list unchanged).
  • Docs: new Using hardware tokens for signing chapter in JSignPdf.adoc, plus distribution/doc/release-notes/3.3.0.md.

…d catalog

Implements design-doc/3.3-pkcs11-profiles.md (#187, #491).

- Profiles: <cfg>/pkcs11.cfg is read as "default", every <cfg>/pkcs11/<id>.cfg
  is a further profile; #jsignpdf: comment metadata (label, provider, catalog).
- Providers register lazily on first use; failures are captured per profile
  with a readable reason instead of breaking startup.
- Keys are loaded and OpenPDF signs through the selected profile's provider,
  fixing the wrong-token selection when several share the PKCS11 type.
- CLI: --keystore-provider/-kspr and --list-keystore-providers/-lkp.
- JavaFX: one keystore entry per profile, hidden file picker for PKCS#11,
  Load Keys feedback; Preferences PKCS#11 tab becomes a profile editor with
  library chooser, token detection and a bundled driver catalog.
- Tests: profile/catalog/detector unit tests and a SoftHSM2 two-token
  integration test (skipped when SoftHSM2 is not installed).
- Docs: user guide chapter and 3.3.0 release notes.
- FX: a profile whose registration failed stays selectable, so Load Keys can
  retry; the failure reason is no longer replaced by "profile not found".
  Invalid profile files are listed even when no valid profile exists.
- Load the driver outside the Pkcs11Profiles monitor, so a hanging driver
  cannot block list()/status() on the FX thread.
- Type-only keystore loading (TSA client certificate) resolves the PKCS#11
  provider through the single-profile rule again, as in 3.2.
- Keystore type list includes JSIGNPKCS11 for a legacy pkcs11.cfg, so the
  Swing combo keeps a saved selection.
- The id "default" can be created again from Preferences; a rename is
  forgotten once the old id is reused; -lk reports PKCS#11 errors as a message.
- applyEdits writes new files before deleting old ones; catalog description
  values are quoted; the "no slot" classification is narrower.
- Flatpak: drop the unverified p11-kit forwarding claim; detection and the
  catalog offer nothing inside the sandbox.
- SoftHSM2 test only touches target/softhsm and also signs with the DSS
  engine; CI runs apt-get update first.
- Release notes use only bold/code markup; AGENTS.md and the design doc
  describe the implemented behaviour.
… providers

- Type-only keystore loading rethrows Pkcs11Exception, so a TSA client
  certificate on a token stops signing with the profile ids when several
  profiles provide the type, instead of continuing without a client key.
  The FX TSA panel offers a PKCS#11 type only while one profile provides it.
- A provider that ends up not registered (profile changed while the driver
  loaded, name already taken) is logged out and cleared; a taken provider
  name is detected before the driver is loaded.
- FX tests for the keystore combo selection and the Preferences profile
  editor.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

PKCS11 user experience improvement Multiple PKCS11 providers

1 participant