Skip to content

About

Hardware key store security provider for GoodNet — PKCS#11 backend (YubiKey, SoftHSM, enterprise HSMs).

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

goodnet-security-pkcs11

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)

Scope

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 through gn_core_install_identity_from_provider(core, "gn.identity.pkcs11", "<CKA_LABEL>"). get_pubkey reads CKA_EC_POINT, sign runs C_Sign with CKM_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.

v0.2: identity-side landed (Phase 3 of the kernel refactor)

The kernel-side identity refactor lands in five phases; this plugin covers Phase 3:

  1. Phase 1 (landed, kernel commit a7013095) — kernel grew the IdentitySigner abstraction with a LibsodiumSigner default.
  2. Phase 2 (landed, kernel commit 72e2185) — kernel published sdk/extensions/identity.h + gn_core_install_identity_from_provider so plugins can hand the kernel an external IdentitySigner before the first attestation runs.
  3. Phase 3 (landed in this commit, v0.2) — this .so registers the identity-side gn.identity.pkcs11 extension. The vtable embeds itself as the first member of an IdentitySignerCtx wrapper so the kernel's ctx = &vtable convention recovers the wrapper struct via cast in every thunk.
  4. Phases 4–5 (pending) — operator UX (goodnetd identity import-hsm, doctor checks, quickstart HSM option) and the SDK-side Identity::from_hsm() factory in gn::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.

Backend choices

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.

Configuration (env vars)

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=.

Provisioning an Ed25519 key in SoftHSM2 (development)

# 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=goodnet

A 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.

Build

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 tests

The kernel monorepo also builds this plugin in-tree through its own nix run .#build -- release — operator install consumes every bundled .so from there.

Load

Manifest entry pins the SHA-256 digest. gn_plugin_init builds the shared Pkcs11Provider; gn_plugin_register then registers both:

  1. The pkcs11 security provider under extension id gn.security.pkcs11 (via host_api->register_security).
  2. The identity-signer vtable under extension id gn.identity.pkcs11 (via host_api->register_extension at version GN_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).

Contract

  • Extension ids: gn.security.pkcs11 (transport, MVP) and gn.identity.pkcs11 (identity signer). Both declared in ext_provides[].
  • Provider id: pkcs11 (returned by provider_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, see sdk/extensions/identity.h).
  • Kernel-side trust-class policy: docs/contracts/security-trust.en.md in the kernel monorepo.

About

Hardware key store security provider for GoodNet — PKCS#11 backend (YubiKey, SoftHSM, enterprise HSMs).

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages