KEK providers

A KEK provider wraps and unwraps data-encryption keys. CertAutoPilot ships two: env (software, KEK bytes in environment variables) and pkcs11 (hardware, KEK lives in a PKCS#11 HSM). The choice is made at install time and is immutable thereafter.

01Comparison

02env provider

The simplest provider. Raw 32-byte KEK material is supplied via CERTAUTOPILOT_ENCRYPTION_ENV_KEK_V{N} (one env var per version). The backend loads every present version at startup and reads the kek_versions collection to decide which one is active for new writes — rotation flips that pointer via certautopilot kek rotate, no per-host env var change is involved.

Storage:

• Standalone — /etc/certautopilot/secrets.env, mode 0600, loaded by systemd via EnvironmentFile=.
• Kubernetes — a Secret consumed via envFrom.secretRef, rendered either inline by the Helm chart or from an external Secret (SealedSecrets, External Secrets, Vault injector).

Key material generation:

openssl rand -hex 32

Always 64 hex chars = 32 bytes. Shorter values are rejected on startup.

03pkcs11 provider

The HSM provider never lets the KEK enter the backend's address space. CertAutoPilot dlopens the vendor's PKCS#11 library, logs into the token with the operator PIN, and invokes CKM_AES_GCM on key handles. The wrapped DEK and the nonce come back to the backend; the KEK stays in the HSM.

The provider stores only keystore metadata in MongoDB — the HSM key label / handle + version, never raw material. A mismatch between the config-declared provider and the kek_install record aborts startup.

Tested HSMs: SoftHSM2 (dev/CI), AWS CloudHSM, Thales Luna Network HSM. Any FIPS-approved HSM supporting CKM_AES_GCM should work — we run a capability probe before committing.

04The install lock

At install time, the chosen provider is written into a singleton MongoDB document kek_install. Every subsequent startup reads this document and refuses to run if the config-declared provider disagrees. This prevents a misconfigured restart from silently switching storage backends — a mistake that would tag fresh envelopes with a provider tag that cannot unwrap the old ones.

Switching providers on an already-provisioned system requires a fresh install + data re-import. See Provider migration.

05How to choose

Pick env if any of these hold:

• You do not have an HSM.
• You are not in a regulated vertical that requires one.
• You want the smallest operational surface area.

Pick pkcs11 if any of these hold:

• SOC 2 / PCI-DSS / HIPAA auditors will ask where the KEK lives.
• Your security model treats backend memory dumps as a realistic threat.
• You have an HSM already (CloudHSM, Luna, Fortanix) and want to consolidate root-of-trust on it.

You can start with env and move to pkcs11 later — but because the switch requires a fresh install, decide early where possible.

06Rotation within the same provider

Both providers support seamless rotation via certautopilot kek rotate. The flow is identical:

1. Add a new version (new env var, or kek pkcs11-init --version=N+1).
2. Roll the fleet so every process loads both versions.
3. kek verify --target=N+1 confirms readiness.
4. kek rotate --from-version=N --to-version=N+1 re-wraps every envelope. --from-version defaults to the keystore's active row but passing it explicitly keeps the intended transition unambiguous on the audit record.
5. (Optional) kek remove --version=N retires the old version.

See KEK rotation.