Hardware key store provider for GoodNet — PKCS#11 backend. The
Ed25519 identity-signing key lives on a token (YubiKey, SoftHSM,
or any enterprise HSM that exposes a PKCS#11 v3.0 module); the kernel
asks for signatures over the C_Sign entry, the private half never
materialises in process memory.
Kind: security provider + identity signer · Extension ids:
gn.security.pkcs11 (transport, MVP) and gn.identity.pkcs11
(identity signer) · Provider id: pkcs11 · Artefact: dynamic
plugin (.so via dlopen) · License: MIT (see LICENSE)
As of v0.2, the same .so dual-exposes two extension ids:
gn.identity.pkcs11— the real use-case. Plugs into the kernel's identity refactor throughgn_core_install_identity_from_provider(core, "gn.identity.pkcs11", "<CKA_LABEL>").get_pubkeyreadsCKA_EC_POINT,signrunsC_SignwithCKM_EDDSA. The Ed25519 private half never leaves the token.gn.security.pkcs11— security-provider MVP retained for back-compatibility. The handshake + transport-phase encrypt/decrypt path is still pass-through (Loopback / IntraNode trust classes only); hardware-backed transport-phase keys wait on a future symmetric-key extension. Most operators should ignore this surface and wire only the identity-side extension.
The kernel-side identity refactor lands in five phases; this plugin covers Phase 3:
- Phase 1 (landed, kernel commit
a7013095) — kernel grew theIdentitySignerabstraction with aLibsodiumSignerdefault. - Phase 2 (landed, kernel commit
72e2185) — kernel publishedsdk/extensions/identity.h+gn_core_install_identity_from_providerso plugins can hand the kernel an externalIdentitySignerbefore the first attestation runs. - Phase 3 (landed in this commit, v0.2) — this
.soregisters the identity-sidegn.identity.pkcs11extension. The vtable embeds itself as the first member of anIdentitySignerCtxwrapper so the kernel'sctx = &vtableconvention recovers the wrapper struct via cast in every thunk. - Phases 4–5 (pending) — operator UX (
goodnetd identity import-hsm, doctor checks, quickstart HSM option) and the SDK-sideIdentity::from_hsm()factory ingn::sdk::Core. These are kernel + operator-binary work, not changes to this plugin.
See the kernel's docs/contracts/identity.en.md §12 for the
authoritative 5-phase plan and docs/operator/identity-hsm-setup.en.md
for the operator workflow.
PKCS#11 is the portability layer; the actual token is loaded at
runtime via dlopen of the vendor module .so. Tested backends:
| Backend | Module .so path | Notes |
|---|---|---|
| SoftHSM2 (dev/CI) | ${softhsm}/lib/softhsm/libsofthsm2.so |
CI fixture; pure-software emulation of a token |
| YubiKey 5 | /usr/lib/x86_64-linux-gnu/libykcs11.so |
Ed25519 via the FIDO2/PIV applet |
| AWS CloudHSM | /opt/cloudhsm/lib/libcloudhsm_pkcs11.so |
Unverified in v0.1; same PKCS#11 contract |
| Thales Luna / DPoD | /usr/safenet/lunaclient/lib/libCryptoki2_64.so |
Unverified in v0.1; same PKCS#11 contract |
Set GOODNET_PKCS11_MODULE to override the default lookup path.
| Variable | Purpose |
|---|---|
GOODNET_PKCS11_MODULE |
Absolute path to the vendor PKCS#11 module .so (e.g. SoftHSM2's libsofthsm2.so). |
GOODNET_PKCS11_PIN |
User PIN passed to C_Login(CKU_USER, ...). Leave unset to skip login. |
GOODNET_PKCS11_LABEL |
CKA_LABEL of the Ed25519 private key on the token. Defaults to goodnet. |
GOODNET_PKCS11_SLOT |
Decimal or 0x... slot id. Defaults to the first slot that reports a token present. |
GOODNET_PKCS11_LIVE_TEST |
When set, enables the optional live-token test path (SignsMessage, WrongPinFails). CI does not set this. |
The PIN is never baked into source, tests, or documentation. The
env var is the canonical hook; a systemd service file can pull the
value from a credential file via LoadCredential=.
# 1. Initialise a SoftHSM2 token in slot 0.
softhsm2-util --init-token --slot 0 \
--label goodnet-dev --pin 1234 --so-pin 1234
# 2. Generate an Ed25519 keypair on the token with CKA_LABEL=goodnet.
pkcs11-tool --module ${softhsm}/lib/softhsm/libsofthsm2.so \
--login --pin 1234 \
--keypairgen --key-type "EC:edwards25519" --label goodnet
# 3. Point the plugin at the freshly-provisioned token.
export GOODNET_PKCS11_MODULE=${softhsm}/lib/softhsm/libsofthsm2.so
export GOODNET_PKCS11_PIN=1234
export GOODNET_PKCS11_LABEL=goodnetA YubiKey 5 with the FIDO2/PIV applet exposes Ed25519 the same way;
substitute libykcs11.so for the module path and use the YubiKey's
configured PIN.
This plugin lives in its own git with a flake that pulls the kernel SDK as a Nix input (p11-kit on the build path; SoftHSM + OpenSC for the test fixture). From this checkout:
nix run .#build # release build of libgoodnet_security_pkcs11.so
nix run .#test # vanilla ctest (LoadsModule + FindsKeyByLabel)
nix run .#test-asan # AddressSanitizer + UBSan
GOODNET_PKCS11_LIVE_TEST=1 nix run .#test # adds Sign + WrongPin testsThe kernel monorepo also builds this plugin in-tree through its own
nix run .#build -- release — operator install consumes every
bundled .so from there.
Manifest entry pins the SHA-256 digest. gn_plugin_init builds the
shared Pkcs11Provider; gn_plugin_register then registers both:
- The
pkcs11security provider under extension idgn.security.pkcs11(viahost_api->register_security). - The identity-signer vtable under extension id
gn.identity.pkcs11(viahost_api->register_extensionat versionGN_EXT_IDENTITY_SIGNER_VERSION).
Both ext_provides[] entries are declared in the descriptor so the
manifest gating sees them as a matched set. See docs/install.en.md
and docs/contracts/plugin-manifest.en.md in the kernel tree for
the manifest schema.
Operators install the identity-side backend through:
gn_core_install_identity_from_provider(core, "gn.identity.pkcs11",
"<CKA_LABEL>");<CKA_LABEL> is the label the keypair was provisioned under (see
"Provisioning" above; the default is goodnet).
- Extension ids:
gn.security.pkcs11(transport, MVP) andgn.identity.pkcs11(identity signer). Both declared inext_provides[]. - Provider id:
pkcs11(returned byprovider_id()thunk on the security side). - Trust mask:
(1 << GN_TRUST_LOOPBACK) | (1 << GN_TRUST_INTRA_NODE)— applies to the security-side extension only. The identity-side extension has no trust gating; it just signs. - Identity vtable version:
GN_EXT_IDENTITY_SIGNER_VERSION(1.0.0, seesdk/extensions/identity.h). - Kernel-side trust-class policy:
docs/contracts/security-trust.en.mdin the kernel monorepo.