Anhang C: HSM per PKCS#11 – Backup, Storage weg, Restore
Ziel: OpenBao mit 3 Pods entsiegelt sich über ein USB-HSM; du sicherst, löschst den Storage, installierst neu und spielst das Backup zurück. · Dauer: ca. 120 min · Voraussetzung: Tag 14, Linux-Host, Nitrokey HSM 2
Briefing
- Seit 2.7 ist PKCS#11 ein Plugin (
kms-pkcs11ausopenbao-plugins). Du baust ein eigenes Image mit Plugin und OpenSC. - OpenBao erzeugt keinen Key. Du legst ein RSA-Schlüsselpaar im HSM
an. Der Nitrokey kann über PKCS#11 kein AES-GCM, darum
CKM_RSA_PKCS_OAEP. - Ein USB-Stick, drei Pods:
pcscdauf dem Host teilt den Stick, die Pods sprechen über dessen Socket. Das geht nur unter Linux, weil dort die kind-Nodes direkt auf dem Host laufen. - Eigener Cluster
bao-hsm, ohne TLS. Der Lab-Clusterbao-labbleibt unberührt.
Linux-Host kind-Cluster "bao-hsm"
┌─────────────────────┐ ┌──────────────────────────────────┐
│ Nitrokey HSM 2 │ │ openbao-0 ┐ │
│ │ USB │ /run/pcscd │ openbao-1 ├─ kms-pkcs11-Plugin │
│ pcscd ── Socket ────┼───────────►│ openbao-2 ┘ + opensc-pkcs11.so │
└─────────────────────┘ └──────────────────────────────────┘
Achtung: Dieser Anhang ist gegen Helm-Chart 0.30.2 und den Quelltext des Plugins v0.2.1 geprüft, aber noch nicht mit echter Hardware gelaufen. Ausgaben sind „(gekürzt, kann abweichen)“.
Drill 1: Host vorbereiten
mkdir -p ~/bao-lab/anhang-c && cd ~/bao-lab/anhang-c
sudo apt install -y opensc pcscd # Fedora: sudo dnf install opensc pcsc-lite
sudo systemctl enable --now pcscd.socket
ls -l /run/pcscd/
pkcs11-tool -LErwartet (gekürzt, kann abweichen):
srw-rw-rw- 1 root root 0 ... pcscd.comm
Available slots:
Slot 0 (0x0): Nitrokey Nitrokey HSM ...
token label : SmartCard-HSM (UserPIN)
pkcs11-tool nutzt ohne --module automatisch
OpenSC.
Fortschritt speichern? Kostenlos registrieren
Drill 2: HSM initialisieren und Key anlegen
sc-hsm-tool --initialize --so-pin 3537363231383830 --pin 648219 \
--label bao-hsm --dkek-shares 1 # Lab: beide PINs = Werkseinstellung
sc-hsm-tool --create-dkek-share dkek-share-1.pbe # fragt nach einem Passwort
sc-hsm-tool --import-dkek-share dkek-share-1.pbe
pkcs11-tool --login --pin 648219 --keypairgen --key-type rsa:2048 \
--label bao-root-key --id 01
pkcs11-tool -L | grep 'token label'
pkcs11-tool -M | grep -i oaepErwartet (gekürzt, kann abweichen):
token label : bao-hsm (UserPIN)
RSA-PKCS-OAEP, keySize={1024,4096}, hw, decrypt
Übernimm das Token-Label exakt so in Drill 5. Fehlt
RSA-PKCS-OAEP, ist OpenSC zu alt.
Achtung:
--initializelöscht alle Keys auf dem Stick. Nur jetzt, nie im Desaster-Fall.
Warum DKEK? Mit dem Device Key Encryption Key lässt sich der Key verschlüsselt aus dem Stick exportieren. Ohne ihn stirbt der Key mit dem Stick.
Fortschritt speichern? Kostenlos registrieren
Drill 3: HSM-Key sichern
pkcs15-tool -D | grep -E 'Label|Key ref'
sc-hsm-tool --wrap-key bao-root-key.wky --key-reference 1 --pin 648219
ls -l bao-root-key.wky dkek-share-1.pbeErwartet (gekürzt, kann abweichen):
Label : bao-root-key
Key ref : 1 (0x01)
-rw-r--r-- 1 thomas thomas 1234 ... bao-root-key.wky
-rw-r--r-- 1 thomas thomas 64 ... dkek-share-1.pbe
Steht bei Key ref ein anderer Wert, nimm diesen. Beide
Dateien plus Passwort ergeben zusammen die Sicherung des HSM-Keys: Mit
sc-hsm-tool --unwrap-key stellst du ihn auf einem zweiten
Nitrokey wieder her, der mit demselben DKEK-Share und demselben Label
(--label bao-hsm) initialisiert wurde.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Cluster und Image
cat > kind-hsm.yaml <<'EOF'
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
name: bao-hsm
nodes:
- role: control-plane
- role: worker
extraMounts: [{ hostPath: /run/pcscd, containerPath: /run/pcscd }]
- role: worker
extraMounts: [{ hostPath: /run/pcscd, containerPath: /run/pcscd }]
- role: worker
extraMounts: [{ hostPath: /run/pcscd, containerPath: /run/pcscd }]
EOF
kind create cluster --config kind-hsm.yamlPlugin laden und prüfen:
V=kms-pkcs11-v0.2.1
F=openbao-plugin-kms-pkcs11_linux_amd64_v1 # arm64: _linux_arm64_v8, auch im Dockerfile
U=https://github.com/openbao/openbao-plugins/releases/download/$V
curl -LO $U/$F.tar.gz
curl -LO $U/checksums-kms-pkcs11.txt
tar -xzf $F.tar.gz
sha256sum -c --ignore-missing checksums-kms-pkcs11.txtErwartet:
openbao-plugin-kms-pkcs11_linux_amd64_v1: OK
openbao-plugin-kms-pkcs11_linux_amd64_v1.tar.gz: OK
Image bauen und in kind laden:
cat > Dockerfile <<'EOF'
FROM quay.io/openbao/openbao:2.7.0
USER root
RUN apk add --no-cache opensc pcsc-lite-libs && mkdir -p /openbao/plugins
COPY --chmod=0755 openbao-plugin-kms-pkcs11_linux_amd64_v1 \
/openbao/plugins/openbao-plugin-kms-pkcs11
USER openbao
EOF
docker build -t openbao-hsm:2.7.0-pkcs11 .
kind load docker-image openbao-hsm:2.7.0-pkcs11 --name bao-hsmWarum klappt ein glibc-Plugin im Alpine-Image? Das offizielle Image
bringt gcompat mit. OpenSC kommt aus Alpine und liegt unter
/usr/lib/pkcs11/opensc-pkcs11.so.
Fortschritt speichern? Kostenlos registrieren
Drill 5: PIN, Werte, Installation
kubectl config use-context kind-bao-hsm
kubectl create namespace openbao
kubectl -n openbao create secret generic openbao-hsm-pin --from-literal=pin=648219--from-literal schreibt die PIN ohne Zeilenumbruch. Das
ist wichtig, denn das Plugin liest die Datei unverändert.
cat > values-hsm.yaml <<'EOF'
global:
tlsDisable: true # Nur Lab: Fokus liegt auf dem HSM
injector:
enabled: false
server:
image:
registry: docker.io # so heißt das Image nach kind load
repository: library/openbao-hsm
tag: "2.7.0-pkcs11"
pullPolicy: Never
podManagementPolicy: Parallel
volumes:
- name: pcscd
hostPath:
path: /run/pcscd # Socket von pcscd auf dem Host
type: Directory
volumeMounts:
- name: pcscd
mountPath: /run/pcscd
extraVolumes:
- type: secret
name: openbao-hsm-pin # -> /openbao/userconfig/openbao-hsm-pin/pin
affinity: |
podAntiAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- labelSelector:
matchLabels:
app.kubernetes.io/name: {{ template "openbao.name" . }}
app.kubernetes.io/instance: "{{ .Release.Name }}"
component: server
topologyKey: kubernetes.io/hostname
dataStorage:
enabled: true
size: 1Gi
standalone:
enabled: false
ha:
enabled: true
replicas: 3
raft:
enabled: true
setNodeId: true
config: |
ui = true
plugin_directory = "/openbao/plugins"
listener "tcp" {
address = "[::]:8200"
cluster_address = "[::]:8201"
tls_disable = 1
}
storage "raft" {
path = "/openbao/data"
retry_join {
leader_api_addr = "http://openbao-0.openbao-internal:8200"
}
retry_join {
leader_api_addr = "http://openbao-1.openbao-internal:8200"
}
retry_join {
leader_api_addr = "http://openbao-2.openbao-internal:8200"
}
}
plugin "kms" "pkcs11" {
command = "openbao-plugin-kms-pkcs11"
sha256sum = "e88632ee52600513bd0e77242823ef57641f1eaac019d8c66515c8bca81e007d"
}
seal "pkcs11" {
lib = "/usr/lib/pkcs11/opensc-pkcs11.so"
token_label = "bao-hsm (UserPIN)"
pin = "file:///openbao/userconfig/openbao-hsm-pin/pin"
key_label = "bao-root-key"
mechanism = "CKM_RSA_PKCS_OAEP"
}
service_registration "kubernetes" {}
EOF
helm -n openbao install openbao openbao/openbao --version 0.30.2 -f values-hsm.yamlWarum pin = "file://…" statt einer Umgebungsvariable?
Das Plugin läuft als eigener Prozess und sieht die Variablen des Pods
nicht. Die Datei liest es selbst. So steht die PIN auch nicht in der
ConfigMap.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Initialisieren
kubectl -n openbao wait pod/openbao-0 --for=jsonpath='{.status.phase}'=Running \
--timeout=120s
sleep 10 # Plugin-Start und HSM-Login abwarten
kubectl -n openbao exec openbao-0 -- bao operator init \
-recovery-shares=1 -recovery-threshold=1 -format=json > init.json # nur Lab
kubectl -n openbao wait pod/openbao-0 pod/openbao-1 pod/openbao-2 \
--for=condition=Ready --timeout=180s
kubectl -n openbao exec openbao-1 -- bao status | grep -E 'Seal Type|Sealed'Erwartet (gekürzt, kann abweichen):
Seal Type pkcs11
Sealed false
Eine Hilfsfunktion für alle weiteren Befehle, immer gegen den aktiven Pod:
T=$(jq -r .root_token init.json)
b() {
A=$(kubectl -n openbao get pod -l openbao-active=true -o name)
kubectl -n openbao exec -i "$A" -- env BAO_TOKEN="$T" bao "$@"
}
b operator raft list-peersErwartet: drei Peers, ein leader, zwei
follower.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Daten schreiben und Backup erstellen
b secrets enable -path=secret kv-v2
b kv put -mount=secret hsm/test wert=vorher
b operator raft snapshot save /tmp/hsm.snap
kubectl -n openbao cp "${A#pod/}:/tmp/hsm.snap" hsm.snap
ls -l hsm.snapDie Variable A hat die Funktion b gesetzt;
sie zeigt auf den aktiven Pod.
Was gehört zum Backup? Fehlt eins davon, ist der Restore gefährdet:
| Teil | Datei / Ort | Wofür |
|---|---|---|
| Snapshot | hsm.snap |
alle Daten, Root-Key verschlüsselt mit dem HSM-Key |
| HSM-Key | im Stick, Kopie bao-root-key.wky +
dkek-share-1.pbe |
entschlüsselt den Root-Key |
| Seal-Konfiguration | values-hsm.yaml |
findet HSM-Token und Key |
| PINs, Recovery-Key | Tresor, init.json |
Login am HSM, Notfall-Root |
Fortschritt speichern? Kostenlos registrieren
Drill 8: Storage löschen
helm -n openbao uninstall openbao
for i in 0 1 2; do kubectl -n openbao delete pvc data-openbao-$i; done
kubectl -n openbao get pvc
pkcs11-tool --login --pin 648219 --list-objects --type privkeyErwartet (gekürzt, kann abweichen):
No resources found in openbao namespace.
Private Key Object; RSA
label: bao-root-key
ID: 01
Die Daten sind weg, der Key ist noch da. Das HSM kennt keinen Cluster-Zustand. Nicht neu initialisieren!
Fortschritt speichern? Kostenlos registrieren
Drill 9: Neu deployen und Backup einspielen
helm -n openbao install openbao openbao/openbao --version 0.30.2 -f values-hsm.yaml
kubectl -n openbao wait pod/openbao-0 --for=jsonpath='{.status.phase}'=Running \
--timeout=120s
sleep 10 # Plugin-Start und HSM-Login abwarten
kubectl -n openbao exec openbao-0 -- bao operator init \
-recovery-shares=1 -recovery-threshold=1 -format=json > temp-init.json
kubectl -n openbao wait pod/openbao-0 --for=condition=Ready --timeout=120s
kubectl -n openbao cp hsm.snap openbao-0:/tmp/hsm.snap
TT=$(jq -r .root_token temp-init.json)
kubectl -n openbao exec openbao-0 -- env BAO_TOKEN="$TT" \
bao operator raft snapshot restore -force /tmp/hsm.snap
kubectl -n openbao delete pod openbao-0 openbao-1 openbao-2
kubectl -n openbao wait pod/openbao-0 pod/openbao-1 pod/openbao-2 \
--for=condition=Ready --timeout=180s
T=$(jq -r .root_token init.json) # ab jetzt gilt wieder das alte init.json
b kv get -mount=secret -field=wert hsm/testErwartet:
vorher
Warum -force? Der temporäre Cluster hat einen anderen
Root-Key als der Snapshot (Tag 14, Szenario 5). Dass der HSM-Key passt,
beweist erst der Neustart: Alle drei Pods entsiegeln sich selbst.
Fortschritt speichern? Kostenlos registrieren
Wenn es hakt
Symptom im Pod-Log
(kubectl -n openbao logs openbao-0) |
Ursache | Abhilfe |
|---|---|---|
| Zugriff auf den Kartenleser verweigert | polkit von pcscd blockt Container |
Lab: pcscd mit --disable-polkit starten
(systemd-Override) |
| Protokoll-Fehler bei pcsc | pcsc-lite im Image und auf dem Host zu verschieden | Host-Distribution mit aktuellem pcsc-lite (2.x) |
| HSM-Token nicht gefunden | token_label stimmt nicht |
Label aus pkcs11-tool -L exakt übernehmen |
| Plugin startet nicht | Prüfsumme oder Pfad falsch | sha256sum, Dateiname in /openbao/plugins
prüfen |
polkit für das Lab abschalten (Pfad zu pcscd je nach
Distribution; --disable-polkit gibt es ab pcsc-lite 2.x,
prüfen mit pcscd -h):
sudo mkdir -p /etc/systemd/system/pcscd.service.d
printf '%s\n' '[Service]' 'ExecStart=' \
'ExecStart=/usr/sbin/pcscd -f --auto-exit --disable-polkit' \
| sudo tee /etc/systemd/system/pcscd.service.d/lab.conf
sudo systemctl daemon-reload && sudo systemctl restart pcscdKontrollpunkt
ok() { echo "✔ $1"; }
nok() { echo "✘ $1"; }
for i in 0 1 2; do
kubectl -n openbao exec openbao-$i -- bao status 2>/dev/null \
| grep -q 'Seal Type *pkcs11' && ok "openbao-$i: Seal pkcs11" \
|| nok "openbao-$i: Seal pkcs11"
done
[ "$(b kv get -mount=secret -field=wert hsm/test)" = vorher ] \
&& ok "Daten aus dem Backup" || nok "Daten aus dem Backup"
[ -s bao-root-key.wky ] && ok "HSM-Key gesichert" || nok "HSM-Key gesichert"Das Skript nutzt die Funktion b aus Drill 6. Füge es
darum in dasselbe Terminal ein, in dem du Drill 6 bis 9 ausgeführt
hast.
Challenge
Ziehe den Stick ab und starte openbao-1 neu. Was
passiert mit openbao-1, was mit den anderen Pods? Bring den
Cluster wieder in Ordnung.
Hinweis: Laufende Pods haben den Root-Key im Speicher (Tag 10).
Lösung
kubectl -n openbao delete pod openbao-1
kubectl -n openbao get pod openbao-1 # 0/1, Neustarts
kubectl -n openbao logs openbao-1 --tail=20 | grep -i pkcs11
b kv get -mount=secret -field=wert hsm/test # geht weiter
# Stick wieder einstecken
kubectl -n openbao delete pod openbao-1
kubectl -n openbao wait pod/openbao-1 --for=condition=Ready --timeout=120sDanach die anderen Pods einzeln neu starten (Standbys zuerst, den
Active nach bao operator step-down), damit alle eine
frische HSM-Session haben.
openbao-1 startet nicht (Neustarts, nicht Ready), die
anderen laufen weiter. Starten alle drei neu, solange der Stick fehlt,
steht der Cluster.
Fortschritt speichern? Kostenlos registrieren
Aufräumen
kind delete cluster --name bao-hsm
rm ~/bao-lab/anhang-c/{init.json,temp-init.json,hsm.snap}bao-root-key.wky und dkek-share-1.pbe nur
löschen, wenn du den Key nicht mehr brauchst. Den Stick vor anderer
Nutzung neu initialisieren und eigene PINs setzen.
Enterprise-Notiz
- Statt eines USB-Sticks ein Netzwerk-HSM oder einen HSM-Cluster: Ein Stick bindet alle Pods an einen Host und ist ein Single Point of Failure.
- Den HSM-Key auf einem zweiten HSM bereithalten (beim Nitrokey per
DKEK und
--unwrap-key). DKEK-Shares auf mehrere Personen verteilen (--dkek-shares 3). - PIN nicht als einfaches Kubernetes-Secret, sondern aus einem externen Tresor, verschlüsselt im etcd.
- TLS einschalten wie in Tag 7 bis 13.
- Restore regelmäßig gegen das echte HSM üben, nicht nur gegen das Lab.