# SSHKeyVault – Handbuch

SSHKeyVault (`sshkv`) verwaltet SSH-Schlüssel zentral: Schlüsselpaare erzeugen, Public Keys in
`authorized_keys` verteilen, Private Keys gezielt auf andere Hosts legen, Ist und Soll abgleichen –
alles protokolliert. Installation und Betrieb: [../betrieb/installation.md](../betrieb/installation.md),
Sicherung: [../betrieb/sicherung.md](../betrieb/sicherung.md), Sicherheit:
[../betrieb/sicherheit.md](../betrieb/sicherheit.md).

**Grundsatz:** Auf einem Host ändert sich nur etwas, nachdem Sie einen **Dry-Run** gesehen und
„Änderung anwenden“ geklickt haben. Alles, was sshkv in `authorized_keys`, `~/.ssh/config` und
`known_hosts` schreibt, steht in einem verwalteten Block:

```
# BEGIN SSHKV MANAGED – nicht manuell bearbeiten
…
# END SSHKV MANAGED
```

Zeilen außerhalb dieses Blocks bleiben unverändert – außer Sie übernehmen einen Schlüssel ausdrücklich
in die Verwaltung.

1. [Anmelden](#1-anmelden)
2. [Übersicht](#2-übersicht)
3. [Einen Host aufnehmen](#3-einen-host-aufnehmen)
4. [Kern-Anwendungsfall: Host A meldet sich bei Host B an](#4-kern-anwendungsfall-host-a-meldet-sich-bei-host-b-an)
5. [Deployment-Zugang für Claude Code mit dem Assistenten](#5-deployment-zugang-für-claude-code-mit-dem-assistenten)
6. [Abgleich, Drift und Übernahme](#6-abgleich-drift-und-übernahme)
7. [Rotation und Widerruf](#7-rotation-und-widerruf)
8. [Personen, Self-Service und Zuweisungsmatrix](#8-personen-self-service-und-zuweisungsmatrix)
9. [Vorlagen](#9-vorlagen)
10. [Private Key anzeigen oder löschen](#10-private-key-anzeigen-oder-löschen)

---

## 1. Anmelden

![Anmeldeseite](bilder/anmelden-desktop.png)

- **Mit authentik anmelden** – der Normalfall. Ihre Rolle (Leser, Operator, Admin) kommt aus den
  authentik-Gruppen und wird bei jeder Anmeldung neu bestimmt.
- **Notfallzugang** – nur, wenn authentik ausfällt. Anmeldename, Passwort und ein Code aus einer
  Authenticator-App. Bei der ersten Anmeldung richtet der Notfall-Admin den zweiten Faktor ein
  (QR-Code scannen, Code bestätigen).

Kritische Aktionen (Private Key anzeigen, Benutzer mit sudo anlegen, Massenwiderruf, Host-Key
ersetzen) verlangen eine **erneute Bestätigung**; sie gilt fünf Minuten.

## 2. Übersicht

![Übersicht](bilder/uebersicht-desktop.png)

Kennzahlen, Hosts mit Abweichung, bald ablaufende Schlüssel und die letzten Aktionen. Von hier aus:
**Jetzt abgleichen** (alle Hosts), **Host-zu-Host-Assistent**, **Neuer Schlüssel**.

## 3. Einen Host aufnehmen

**Hosts → + Host anlegen:** Name (z. B. `srv-pve01`), Adresse, Port, Gruppen, Tags. Bei
**Anmeldung** ist „Dienstbenutzer `sshkv` mit sudo“ empfohlen – im auth.log des Hosts ist dann
eindeutig zu sehen, was von sshkv kam, und root-Login kann aus bleiben.

**Host-Key bestätigen.** „Host-Key abrufen“ holt den Fingerprint, ohne sich anzumelden. Vergleichen
Sie ihn direkt am Host:

```bash
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
```

![Host-Key bestätigen](bilder/hostkey-bestaetigen-desktop.png)

Erst nach „Fingerprint stimmt – vertrauen“ verbindet sich sshkv. Ändert sich der Host-Key später,
bricht jede Verbindung ab und die Hostseite warnt deutlich – annehmen nur, wenn der Host wirklich neu
installiert wurde.

**Bootstrap.** Zwei Wege, den Deployment-Key von sshkv auf den Host zu bringen:

- **Einmalig per Passwort** (root oder ein Benutzer mit sudo). Das Passwort wird nicht gespeichert.
- **Per Befehl:** den angezeigten Befehl auf dem Host einfügen, danach „Einrichtung prüfen“.

![Eingerichteter Host](bilder/host-eingerichtet-desktop.png)

Danach zeigt die Hostseite den **sshd-Befund**. Steht dort „root darf sich per Passwort anmelden“,
empfiehlt sich `PermitRootLogin prohibit-password` in `/etc/ssh/sshd_config` – sshkv ändert das nicht
von sich aus.

## 4. Kern-Anwendungsfall: Host A meldet sich bei Host B an

Beispiel: Der Backup-Server `srv-backup01` soll sich als `root` per SSH auf `srv-pve01` anmelden.
Beide Hosts sind aufgenommen (Kapitel 3).

**1. Schlüssel erzeugen.** *Schlüssel → + Schlüssel anlegen → Erzeugen*: Zweck „Backup srv-backup01 →
srv-pve01“, Typ ed25519, optional Ablaufdatum. Keine Passphrase – ein Cronjob kann sie nicht eingeben.

![Schlüssel anlegen](bilder/schluessel-neu-desktop.png)

**2a. Private Key auf A.** In der Karte *Private Key ausgerollt auf* → **+ Ausrollen**: Quell-Host
`srv-backup01`, Benutzer `root`, Pfad `~/.ssh/id_ed25519_…`. Mit **Eintrag in ~/.ssh/config** und
Ziel-Host `srv-pve01` legt sshkv einen Alias an und trägt den (bereits bestätigten) Host-Key von B in
`known_hosts` von A ein. *HostName* ist die Adresse, unter der **A** den Host B erreicht.

**2b. Public Key auf B.** In der Karte *Public Key ausgerollt auf* → **+ Ausrollen**: Ziel
`srv-pve01`, Benutzer `root`, optional Einschränkungen wie `from="10.0.0.12",no-pty`.

2a und 2b sind unabhängig und jederzeit nachholbar.

**3. Dry-Run und anwenden.** *Dry-Run starten* zeigt je Host, was sich ändert – beim Private Key nur
„wird angelegt“, nie den Inhalt.

![Dry-Run](bilder/kern-dry-run-desktop.png)

„Änderung anwenden“ schreibt genau das, was Sie gesehen haben (mit Sicherung der Dateien). Hat sich
in der Zwischenzeit etwas auf dem Host geändert, bricht sshkv ab – dann den Dry-Run neu starten.

**4. Verbindung testen.** In der Private-Karte „Verbindung testen“ ruft auf A
`ssh -o BatchMode=yes <alias> true` auf – genau das, was später der Cronjob braucht.

![Ausgerollt und getestet](bilder/kern-ausgerollt-desktop.png)

## 5. Deployment-Zugang für Claude Code mit dem Assistenten

Szenario: Claude Code auf `srv-rz-claude-linux` soll eine Anwendung per SSH auf `srv-app01`
ausrollen. **Übersicht → Host-zu-Host-Assistent** (nur Admins):

1. **Vorlage „Deployment-Zugang“** wählen, Zweck „Claude Code Deployment → srv-app01“. Die Vorlage
   setzt Benutzer `deploy`, 90 Tage Laufzeit, `from="<IP von A>"` und den Alias `deploy-<Ziel>`.
2. **Quelle:** `srv-rz-claude-linux`, Benutzer, unter dem Claude Code läuft.
3. **Ziel:** `srv-app01`, Benutzer `deploy` – „Benutzer anlegen“ ist vorgewählt; sudo nach Bedarf
   (keine, bestimmte Befehle mit Vorschau der sudoers-Datei, oder voll). Fingerprint von B bestätigen.

![Assistent – Ziel](bilder/assistent-ziel-desktop.png)

4. **Prüfen** und „Vorbereiten“: sshkv erzeugt den Schlüssel, legt `deploy` an (frische Bestätigung
   nötig – sie öffnet sich in einem neuen Tab, Ihre Eingaben bleiben stehen) und legt die
   Zuweisungen an.
5. **Ausrollen:** Dry-Run, anwenden, „Verbindung von A nach B testen“.

![Assistent – fertig](bilder/assistent-fertig-desktop.png)

Claude Code kann danach einfach `ssh deploy-srv-app01` benutzen. Wählen Sie `root` als Ziel, warnt
der Assistent: Ein KI-Agent hätte dann uneingeschränkten Zugriff.

**Nach Projektende** (oder Ablaufdatum): auf der Schlüsselseite **Widerrufen** – entfernt Public und
Private Key, config- und known_hosts-Eintrag und auf Wunsch den Benutzer `deploy` samt sudoers-Datei.

## 6. Abgleich, Drift und Übernahme

Nachts um 02:30 (einstellbar) und auf Knopfdruck vergleicht sshkv jeden Host mit dem Soll. Gefunden
werden fehlende Schlüssel, von Hand geänderte Blöcke, **unbekannte Schlüssel** außerhalb des Blocks,
falsche Rechte von `~/.ssh` und veränderte Private Keys. Der Abgleich ändert auf dem Host nichts.

![Abgleich](bilder/abgleich-desktop.png)

Ein unbekannter Schlüssel lässt sich **übernehmen**: nur als bekannt aufnehmen (der Befund
verschwindet) oder „in den verwalteten Block holen“ – dann wandert die Zeile beim nächsten Ausrollen
(mit Dry-Run) in den Block.

## 7. Rotation und Widerruf

**Rotieren** (Schlüsselseite): Ein neuer Schlüssel kommt an alle Stellen des alten, der Alias in
`~/.ssh/config` zeigt auf die neue Datei, die Verbindungen werden getestet – **erst dann** wird der
alte entfernt. Die Rotation lässt sich jederzeit fortsetzen.

![Rotation](bilder/rotation-desktop.png)

**Widerrufen** (Schlüsselseite, Gefahr-Knopf): Der Dialog zeigt, was entfernt wird; danach Dry-Run
und anwenden. Ist ein Host nicht erreichbar, bleibt der Schlüssel als „Widerruf unvollständig“
markiert, bis auch dort alles entfernt ist. **Massenwiderruf:** in der Schlüsselliste mehrere
auswählen (nur Admin).

![Widerruf](bilder/widerruf-desktop.png)

## 8. Personen, Self-Service und Zuweisungsmatrix

- **Personen:** Admins, Mitarbeiter, Dienstleister mit ihren Schlüsseln. Private Keys von Personen
  speichert sshkv nie.
- **Meine Schlüssel:** Jede angemeldete Person kann eigene Public Keys hinterlegen. Wirksam werden
  sie erst, wenn ein Operator oder Admin sie einem Host zuweist.

![Meine Schlüssel](bilder/meine-schluessel-desktop.png)

- **Zuweisungen:** Matrix Schlüssel × Host mit Filtern; ein Klick auf eine Zelle zeigt die
  Zuweisungen und erlaubt neue. Export als CSV.

![Zuweisungen](bilder/zuweisungen-desktop.png)

## 9. Vorlagen

Vorlagen legen Schlüsseltyp, Laufzeit, Zielbenutzer (samt Anlegen und sudo), `authorized_keys`-
Optionen und das Alias-Muster vor. Platzhalter: `{{quellHost}}`, `{{quellHostIp}}`, `{{zielHost}}`,
`{{zielHostIp}}`. Eingebaut: „Deployment-Zugang“, „Backup-Zugang“, „Admin-Zugang Person“.

![Vorlage bearbeiten](bilder/vorlage-bearbeiten-desktop.png)

## 10. Private Key anzeigen oder löschen

Nur Admins, nur nach erneuter Bestätigung: „anzeigen (Re-Auth)“ in der Info-Leiste eines Schlüssels.
Der Key wird genau einmal ausgeliefert und nirgends zwischengespeichert; jede Anzeige steht im
Protokoll. **Private Key löschen** entfernt ihn endgültig aus sshkv – auf den Hosts bleibt er; neu
ausrollen geht danach nicht mehr.