softhsm-kube

SoftHSM2 as a Kubernetes pod with gRPC interface — PKCS#11 crypto operations over the network.

What

A containerized SoftHSM2 instance exposed via gRPC, designed to run as a pod in Kubernetes. Any component that needs HSM-backed crypto (Vault/OpenBao unseal, K8s KMS encryption-at-rest, certificate signing) can use it as a drop-in replacement for a hardware HSM.

┌──────────────────────────────┐
│  softhsm-kube pod            │
│  ┌────────────────────────┐  │
│  │ SoftHSM2 + gRPC shim  │  │
│  │ PKCS#11 operations:    │  │
│  │  - encrypt / decrypt   │  │
│  │  - sign / verify       │  │
│  │  - key generation      │  │
│  │  - key wrapping        │  │
│  └────────────────────────┘  │
│  ┌────────────────────────┐  │
│  │ Envoy sidecar (opt)    │  │
│  │  - mTLS termination    │  │
│  │  - rate limiting       │  │
│  │  - audit logging       │  │
│  └────────────────────────┘  │
│  PV: /var/lib/softhsm/      │
│  Service: :5696 (gRPC)       │
└──────────────────────────────┘
         ↑ gRPC
         │
  Any PKCS#11 client:
  - Bank-Vaults (OpenBao unseal)
  - vault-kubernetes-kms (etcd encryption)
  - cert-manager (PKI signing)
  - Custom apps

Why

Without softhsm-kube	With softhsm-kube
Unseal keys in plaintext K8s Secret	Unseal keys encrypted by HSM key
etcd secrets encrypted with static key	etcd secrets encrypted via HSM-backed KMS
No key isolation — keys in process memory	Keys never leave the HSM pod
Production needs real HSM ($$$$)	SoftHSM for dev/staging, swap to real HSM in prod

Use Cases

1. OpenBao/Vault unseal — Bank-Vaults operator uses PKCS#11 to encrypt/decrypt unseal keys via softhsm-kube instead of storing them in plaintext.

2. K8s etcd encryption-at-rest — vault-kubernetes-kms or direct KMS v2 plugin uses Transit-over-HSM or PKCS#11 for envelope encryption of all K8s Secrets.

3. PKI key protection — Root CA private key stored in HSM slot; signing operations happen inside the HSM pod, key never exported.

4. Dev/staging HSM — Teams developing HSM-integrated apps can test against softhsm-kube locally without a Thales Luna or AWS CloudHSM.

Architecture

Production path:
  App → gRPC → softhsm-kube pod    (dev/staging)
  App → gRPC → Thales Luna Network HSM  (production)
  App → gRPC → AWS CloudHSM             (cloud production)

Same gRPC interface, different backend. Swap by changing the Service endpoint.

Status

🚧 In development — scaffolding phase.

License

MPL-2.0