Zum Inhalt springen
Trainingslager IT-Trainingslager

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-pkcs11 aus openbao-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: pcscd auf 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-Cluster bao-lab bleibt 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 -L

Erwartet (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 oaep

Erwartet (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: --initialize lö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.pbe

Erwartet (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.yaml

Plugin 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.txt

Erwartet:

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-hsm

Warum 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.yaml

Warum 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-peers

Erwartet: 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.snap

Die 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 privkey

Erwartet (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/test

Erwartet:

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 pcscd

Kontrollpunkt

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=120s

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