Diese Seite ist eine maschinelle Übersetzung der englischen Seite, die maßgeblich ist. Englische Seite lesen
Den Key-Encryption-Key (KEK) verwalten
Der Server verschlüsselt die Secrets, die er in der Datenbank speichert, mit einem Key-Encryption-Key (KEK), den er dort nie ablegt. Diese Seite beschreibt, wie du den KEK erzeugst, aufbewahrst, sicherst und rotierst, wie du ihn stattdessen in einem KMS hältst und was zu tun ist, wenn er verloren geht oder durchsickert. Die Konfigurationsreferenz listet jede Einstellung auf.
So funktioniert es
Abschnitt betitelt „So funktioniert es“- In der Datenbank gespeicherte Secrets, etwa die privaten Schlüssel der Actors, werden mit AES-256-GCM unter einem für jedes Secret erzeugten Data-Encryption-Key (DEK) verschlüsselt. Der DEK wird mit einem Key-Encryption-Key (KEK) verpackt und neben dem Chiffretext gespeichert (Envelope Encryption).
- Der KEK wird nicht in der Datenbank gespeichert, daher legt ein durchgesickerter Datenbank-Dump allein die Secrets nicht offen.
- Jeder Chiffretext trägt die Schlüssel-ID des KEK, der seinen DEK verpackt hat. Mit
key_manager = localist die Schlüssel-IDlocal:gefolgt von 16 hexadezimalen Ziffern, die aus dem KEK abgeleitet werden, derselbe KEK ergibt also immer dieselbe ID. Du vergibst nie IDs. - Ein Chiffretext ist an die Zeilen-ID und den Spaltennamen gebunden, wo er gespeichert ist. Wird er in eine andere Zeile oder Spalte kopiert, lässt er sich nicht mehr entschlüsseln.
- Die versiegelten Spalten, benannt wie
my kek statussie ausgibt, sindlocal_account_private_keys.private_key_enc(private Schlüssel der Actors),totp_enrollments.secret_enc(Secrets der Zwei-Faktor-Authentifizierung),login_provider_secrets.sealed_secret(Client-Secrets der Anmeldeanbieter),webhook_secrets.sealed_secret(Signatur-Secrets von Webhooks),instance_secrets.sealed_secret(der Signaturschlüssel des Media-Proxys und der Schlüssel der Idempotenz-Fingerabdrücke),tls_acme_accounts.sealed_private_key(die Schlüssel der ACME-Konten, wenn der Server seine Zertifikate selbst bezieht) undtls_certificates.sealed_private_key(die Schlüssel dieser Zertifikate). - Der Zustand einer Passkey-Anmeldung oder einer Anmeldung über einen externen Anbieter wird auf dieselbe Weise versiegelt, aber nicht gespeichert: Der Browser hält ihn höchstens 30 Minuten.
- Der Signaturschlüssel (HMAC-SHA256) für Media-Proxy-URLs ist ein zufälliger Schlüssel, den der Server beim ersten Start erzeugt und verschlüsselt wie die anderen Secrets in der Datenbank speichert.
Er ändert sich nicht, wenn du den KEK rotierst, daher funktionieren Media-Proxy-URLs über Rotationen hinweg weiter, und
my kek rewrapverpackt ihn zusammen mit den anderen Secrets neu. key_manageristlocal(der Standard: er verwendet die Einstellungkek),gcpkms(der KEK bleibt in Google Cloud KMS; siehe Google Cloud KMS),awskms(der KEK bleibt in AWS KMS; siehe AWS KMS) oderplugin(der KEK bleibt bei einem Programm von dir; siehe Ein Plugin).
Was passiert, wenn du den KEK verlierst
Abschnitt betitelt „Was passiert, wenn du den KEK verlierst“Ohne den KEK kannst du nach dem Wiederherstellen der Datenbank die privaten Schlüssel der Actors nicht entschlüsseln. Ist ein privater Schlüssel verloren, können andere Server die Signaturen dieses Actors nicht mehr prüfen, und die Identität des Actors im Fediverse ist zerstört (die Beziehungen der Follower lassen sich nicht übertragen). Behandle den KEK mit derselben Sorgfalt wie die Datenbank.
Was nicht versiegelt ist, bleibt lesbar: Beiträge, Konten, Follows und der Rest der Datenbank sowie die Mediendateien im Speicher.
Jeder versiegelte Wert schlägt mit dem Fehler unknown key-encryption key fehl: die privaten Schlüssel der Actors, die Secrets der Zwei-Faktor-Authentifizierung,
die Client-Secrets der Anmeldeanbieter, die Signatur-Secrets von Webhooks, der Signaturschlüssel des Media-Proxys und die Schlüssel der Zertifikate, die der Server selbst bezogen hat.
Dasselbe passiert, wenn anstelle des KEK, der die Secrets verpackt hat, ein anderer gesetzt ist oder wenn der KMS-Schlüssel oder der Schlüssel des Plugins, der sie verpackt hat, deaktiviert oder zerstört ist.
Einen KEK erzeugen
Abschnitt betitelt „Einen KEK erzeugen“Kodiere 32 Zufallsbytes mit Standard-Base64.
openssl rand -base64 32Wo openssl nicht verfügbar ist, funktioniert auch head -c 32 /dev/urandom | base64. Lass den erzeugten Wert nicht in deinem Terminalverlauf oder in Tickets stehen.
Aufbewahren und bereitstellen
Abschnitt betitelt „Aufbewahren und bereitstellen“Der KEK ist eine geheime Einstellung und kann daher nur über die Umgebungsvariable MY_KEK oder über MY_KEK_FILE, den Pfad einer Datei mit dem Wert, übergeben werden. Steht er in der Konfigurationsdatei (TOML), startet der Server nicht.
| Ziel | Beispiel, wie du ihn bereitstellst |
|---|---|
| Selbst gehostet (Binary / systemd) | Lege ihn in einer Datei ab, die nur der Eigentümer lesen kann (chmod 600), und richte MY_KEK_FILE darauf |
| Docker / Compose | Binde ein Docker-Secret unter /run/secrets/my_kek ein und setze MY_KEK_FILE=/run/secrets/my_kek. Die Dateien in deploy/docker tun das aus secrets/kek (Docker-Compose-Dateien): Zum Rotieren ersetzt du diese Datei und setzt MY_KEK_PREVIOUS in .env |
| Kubernetes / microk8s | Binde ein Secret als Datei ein und richte MY_KEK_FILE darauf |
| Cloud Run | Stelle ein Secret-Manager-Secret als Datei oder als Umgebungsvariable bereit |
| AWS ECS | Übergib ihn aus Secrets Manager oder SSM Parameter Store (SecureString) |
- Gib jedem Prozess, etwa Web und Worker, denselben KEK.
- Der KEK erscheint nie in Logs oder Fehlermeldungen (nur die Schlüssel-ID).
my config checkprüft das Format des KEK (Base64 von 32 Bytes) und gibt den Wert als(redacted)aus. Im Profilproductionschlägt es außerdem bei einem KEK fehl, der nicht zufällig ist, etwa nur aus Nullen oder einem wiederholten Byte, undmy serveprotokolliert dazu eine Warnung (siehe die Produktions-Checkliste).
Sichern
Abschnitt betitelt „Sichern“Sichere die Datenbank und den KEK getrennt.
- Bewahre den KEK an einem anderen Ort auf als die Datenbank-Backups (ein Passwortmanager, Offline-Medien, ein Secret-Store in einem anderen Konto und so weiter). Liegen beide an einem Ort, macht ein Leck dieses Ortes die Verschlüsselung der Datenbank sinnlos.
- Nimm bei einer Rotation die Schlüssel aus
kek_previousins Backup auf, solange in der Datenbank noch Chiffretext liegt, der damit verpackt wurde. - Nimm den KEK in dein Wiederherstellungsverfahren auf und teste Wiederherstellungen regelmäßig (Backup und Wiederherstellung). Setze nach dem Wiederherstellen einer Datenbank den KEK (und
kek_previous), der zur Zeit des Backups in Verwendung war, auf dieselben Werte. Mit einem anderen KEK schlägt alles, was ein Secret liest, mit einem Fehlerunknown key-encryption keyfehl, der die Schlüssel-ID nennt.
Den KEK rotieren
Abschnitt betitelt „Den KEK rotieren“Ein KEK in kek_previous wird nur zum Entschlüsseln verwendet, und neue Secrets werden immer mit kek verschlüsselt.
Damit ein Rolling Deploy, bei dem alte und neue Prozesse nebeneinander laufen, nie Chiffretext erzeugt, den ein Prozess nicht lesen kann, wechselst du in zwei Schritten.
- Erzeuge einen neuen KEK und sichere ihn.
- Starte jeden Prozess mit
MY_KEK=<old KEK>undMY_KEK_PREVIOUS=<new KEK>neu. Jetzt kann jeder Prozess mit dem neuen KEK entschlüsseln. - Starte jeden Prozess mit
MY_KEK=<new KEK>undMY_KEK_PREVIOUS=<old KEK>neu. Ab jetzt werden Secrets mit dem neuen KEK verpackt, und Chiffretext des alten KEK ist weiterhin lesbar. - Verpacke die gespeicherten Secrets mit dem neuen KEK neu: Führe
my kek rewrapeinmal aus, mit derselben Konfiguration wie in Schritt 3 (siehe Die gespeicherten Secrets neu verpacken). Wenn es mit 0 endet, braucht kein Secret in der Datenbank den alten KEK mehr. - Warte nach Schritt 3 mindestens 30 Minuten, damit die kurzlebigen Anmelde-Tokens, die mit dem alten KEK ausgestellt wurden, abgelaufen sind, und starte dann jeden Prozess mit
MY_KEK=<new KEK>und ohnekek_previousneu. Bewahre das Backup des alten KEK so lange auf, wie du Datenbank-Backups aufbewahrst, die vor Schritt 4 erstellt wurden: Zum Wiederherstellen eines davon braucht man ihn wieder.
kek_previous akzeptiert mehrere durch Kommas getrennte Schlüssel. Wird derselbe Schlüssel zweimal oder derselbe Schlüssel wie kek aufgeführt, startet der Server nicht.
Die gespeicherten Secrets neu verpacken
Abschnitt betitelt „Die gespeicherten Secrets neu verpacken“my kek rewrap ersetzt nur den verpackten Data-Encryption-Key jedes Secrets und behält dessen Chiffretext; es schreibt oder gibt nie ein Secret aus.
my kek status # count the stored secrets by the key ID of the KEK that wraps them; decrypts nothingmy kek rewrap # re-wrap every secret that a key of kek_previous wraps with kekmy kek statusgibt eine Zeile pro Spalte und Schlüssel-ID aus, markiert die Schlüssel-ID vonkekmit(current)und sagt am Ende, ob noch ein Secret einen Schlüssel auskek_previousbraucht. Eine Schlüssel-ID, die wederkeknoch inkek_previousist, bedeutet, dass in der Konfiguration ein KEK fehlt.my kek rewrapliest die Secrets in Stapeln von 100 und schreibt jeden Stapel in einer kurzen Transaktion. Es gibt pro Spalte aus, wie viele Secrets es neu verpackt hat und wie viele bereits mitkekverpackt waren. Es kann laufen, während der Server Anfragen bedient, und lässt sich jederzeit gefahrlos stoppen oder erneut ausführen: Es überspringt die Secrets, die bereits mitkekverpackt sind, und ein Secret, das der Server inzwischen neu geschrieben hat, bleibt so, wie der Server es geschrieben hat.- Ein Secret, das sich nicht neu verpacken lässt, bleibt unverändert und wird mit seiner Zeilen-ID gemeldet, und der Befehl endet mit 1. Entweder ist sein KEK nicht konfiguriert
(die Meldung nennt die Schlüssel-ID: Füge diesen KEK zu
kek_previoushinzu und führe es erneut aus), oder der gespeicherte Wert ist beschädigt oder wurde aus einer anderen Zeile kopiert. Entferne keinen KEK auskek_previous, solangemy kek statusnoch Secrets darunter zählt.
Google Cloud KMS
Abschnitt betitelt „Google Cloud KMS“Mit key_manager = gcpkms verpackt ein symmetrischer Cloud-KMS-Schlüssel (ein CryptoKey mit dem Zweck ENCRYPT_DECRYPT) die Data-Encryption-Keys, und der KEK verlässt Cloud KMS nie.
Ein durchgesickerter Datenbank-Dump und eine durchgesickerte Konfiguration zusammen legen die Secrets trotzdem nicht offen: Zum Entschlüsseln braucht man die Berechtigung, den Schlüssel zu verwenden.
- Setze
kms_keyauf den Ressourcennamen des Schlüssels, ohne Version:projects/{project}/locations/{location}/keyRings/{ring}/cryptoKeys/{key}. Namen, die länger als 248 Bytes sind, werden beim Start abgelehnt. Die Schlüssel-ID der gespeicherten Secrets istgcpkms:gefolgt von diesem Namen. - Der Server authentifiziert sich mit Application Default Credentials: auf Cloud Run mit dem Servicekonto des Dienstes, anderswo mit
GOOGLE_APPLICATION_CREDENTIALS. - Gib diesem Servicekonto
roles/cloudkms.cryptoKeyEncrypterDecrypterauf dem Schlüssel (nicht auf dem Projekt), für jeden Prozess, etwa Web und Worker, und für die Befehlemy kek statusundmy kek rewrap. Ohne sie schlägt das Lesen eines Secrets mit einem Fehler fehl, der die Rolle nennt; eine fehlende oder deaktivierte Schlüsselversion schlägt ebenso fehl, und diese Fehler werden nicht wiederholt, bis die Konfiguration behoben ist. Ein Kontingentfehler oder ein nicht erreichbares Cloud KMS ist vorübergehend, und die Arbeit, die das Secret brauchte, wird wiederholt. - Der Server behält einen Data-Encryption-Key, den Cloud KMS entschlüsselt hat, für
kms_dek_cache_ttl(Standard10m), sodass die meisten Lesezugriffe auf ein Secret Cloud KMS nicht aufrufen.
Den Schlüssel in Cloud KMS rotieren
Abschnitt betitelt „Den Schlüssel in Cloud KMS rotieren“Eine Rotation in Cloud KMS (von Hand oder mit einem Rotationszeitraum am Schlüssel) fügt eine neue primäre Version hinzu und lässt die alten Versionen aktiviert.
Neue Secrets werden mit der neuen Version verpackt, der Server entschlüsselt jedes Secret mit der Version, die es verpackt hat, und die Schlüssel-ID ändert sich nicht, eine Rotation braucht also kein my kek rewrap.
Deaktiviere oder zerstöre keine alte Version, solange Secrets sie noch brauchen: Ein Secret, das mit einer deaktivierten oder zerstörten Version verpackt wurde, lässt sich nicht mehr entschlüsseln. Cloud KMS sagt nicht, welche Secrets eine Version verpackt hat. Um Schlüsselmaterial außer Betrieb zu nehmen, verschiebst du die Secrets daher zuerst auf einen neuen Schlüssel:
- Erstelle einen neuen Schlüssel (er darf im selben Key Ring liegen) und gib dem Servicekonto die Rolle dafür.
- Starte jeden Prozess mit
kms_keyauf den neuen Schlüssel undkms_key_previousauf den alten gesetzt neu. Der alte Schlüssel entschlüsselt nun nur noch. - Führe
my kek rewrapmit derselben Konfiguration aus. Wennmy kek statusunter der ID des alten Schlüssels keine Secrets mehr zählt, entfernekms_key_previousund starte neu. - Erst dann deaktivierst du die Versionen des alten Schlüssels und hältst sie wiederherstellbar, solange du Datenbank-Backups aufbewahrst, die vor Schritt 3 erstellt wurden: Zum Wiederherstellen eines davon braucht man sie wieder.
AWS KMS
Abschnitt betitelt „AWS KMS“Mit key_manager = awskms verpackt ein symmetrischer AWS-KMS-Schlüssel (Key Spec SYMMETRIC_DEFAULT, Key Usage ENCRYPT_DECRYPT, vom Kunden verwaltet) die Data-Encryption-Keys, und der KEK verlässt AWS KMS nie.
Ein durchgesickerter Datenbank-Dump und eine durchgesickerte Konfiguration zusammen legen die Secrets trotzdem nicht offen: Zum Entschlüsseln braucht man die Berechtigung, den Schlüssel zu verwenden.
-
Setze
kms_keyauf den ARN des Schlüssels (arn:aws:kms:{region}:{account}:key/{key-id}), einen Alias (alias/{name}oder dessen ARN) oder die Schlüssel-ID. Beim Start löst der Server den Namen in den ARN des Schlüssels auf, und die Schlüssel-ID der gespeicherten Secrets istawskms:gefolgt von diesem ARN. Ein Alias, den du auf einen anderen Schlüssel zeigen lässt, ändert daher bis zum nächsten Start nichts und danach nur für neue Secrets: Die bereits gespeicherten Secrets nennen weiter den alten Schlüssel, setze ihn also inkms_key_previous(siehe Einen AWS-KMS-Schlüssel außer Betrieb nehmen). Von AWS verwaltete Schlüssel (alias/aws/...) werden abgelehnt; nur der AWS-Dienst, dem einer gehört, kann ihn verwenden. -
Der Server authentifiziert sich mit der Standard-Credential-Chain des AWS SDK: auf ECS mit der Rolle der Task, auf EC2 mit dem Instance Profile, anderswo mit der Umgebung (
AWS_ACCESS_KEY_IDund Ähnlichem) oder den gemeinsamen Konfigurationsdateien. Die Region ist die des ARN des Schlüssels; setze für einen Alias oder eine Schlüssel-IDAWS_REGION. -
Erlaube
kms:Encrypt,kms:Decryptundkms:DescribeKeyauf dem Schlüssel, für jeden Prozess, etwa Web und Worker, und für die Befehlemy kek statusundmy kek rewrap. Eine Richtlinie der IAM-Rolle:{"Effect": "Allow","Action": ["kms:Encrypt", "kms:Decrypt", "kms:DescribeKey"],"Resource": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"}Die Ressource ist der ARN des Schlüssels, auch wenn
kms_keyein Alias ist. Die Key Policy muss außerdem zulassen, dass die IAM-Richtlinien des Kontos Zugriff gewähren (die Standard-Key-Policy tut das). -
Der Server startet nicht, wenn der Schlüssel nicht existiert, deaktiviert ist, zur Löschung ansteht oder kein symmetrischer Verschlüsselungsschlüssel ist. Später lässt eine fehlende Berechtigung oder ein deaktivierter Schlüssel das Lesen eines Secrets mit einem Fehler scheitern, der die Ursache nennt, und diese Fehler werden nicht wiederholt, bis die Konfiguration behoben ist. Drosselung (
ThrottlingException) oder ein nicht erreichbares AWS KMS ist vorübergehend, und die Arbeit, die das Secret brauchte, wird wiederholt. -
Der Encryption Context jedes Aufrufs enthält die Zeilen-ID und den Spaltennamen des Secrets (
{"my-aad": ...}, in base64url). CloudTrail protokolliert ihn im Klartext; er enthält kein Secret. -
Kosten: AWS berechnet eine monatliche Gebühr für jeden vom Kunden verwalteten Schlüssel (zum Zeitpunkt des Schreibens 1 USD, zuzüglich desselben Betrags für jede der ersten beiden Rotationen seines Schlüsselmaterials) und eine Gebühr pro Anfrage oberhalb eines monatlichen Freikontingents (siehe AWS-KMS-Preise). Der Server behält einen Data-Encryption-Key, den AWS KMS entschlüsselt hat, für
kms_dek_cache_ttl(Standard10m), ein Server mit zehn Actors, die ständig zustellen, stellt also etwa 43.000 Anfragen pro Monat und Prozess, einige Cent oberhalb des Freikontingents.
Einen AWS-KMS-Schlüssel außer Betrieb nehmen
Abschnitt betitelt „Einen AWS-KMS-Schlüssel außer Betrieb nehmen“Die automatische Schlüsselrotation in AWS KMS behält den ARN des Schlüssels und sein früheres Schlüsselmaterial, die Schlüssel-ID ändert sich also nicht, und eine Rotation braucht kein my kek rewrap.
Um einen Schlüssel nicht mehr zu verwenden oder um einen Alias auf einen anderen Schlüssel zeigen zu lassen, verschiebst du die Secrets zuerst auf den neuen Schlüssel. Deaktiviere den alten Schlüssel nicht und plane seine Löschung nicht, solange Secrets ihn noch brauchen: Ein damit verpacktes Secret lässt sich nicht mehr entschlüsseln.
- Erstelle den neuen Schlüssel und erlaube der Rolle, ihn zu verwenden.
- Starte jeden Prozess mit
kms_keyauf den neuen Schlüssel undkms_key_previousauf den alten gesetzt (sein ARN, nicht der Alias) neu. Der alte Schlüssel entschlüsselt nun nur noch. - Führe
my kek rewrapmit derselben Konfiguration aus. Wennmy kek statusunter der ID des alten Schlüssels keine Secrets mehr zählt, entfernekms_key_previousund starte neu. - Erst dann deaktivierst du den alten Schlüssel und behältst ihn, solange du Datenbank-Backups aufbewahrst, die vor Schritt 3 erstellt wurden: Zum Wiederherstellen eines davon braucht man ihn wieder.
Ein Plugin
Abschnitt betitelt „Ein Plugin“Mit key_manager = plugin hält ein Plugin von dir den KEK, in Vault, in einem HSM oder wo es will, und verpackt die Data-Encryption-Keys für den Server.
Das Plugin liegt in derselben Vertrauensgrenze wie der KEK. Es sieht jeden Data-Encryption-Key im Klartext, also kann jeder, der es oder den Host, auf dem es läuft, kontrolliert, jedes Secret des Servers lesen, auch die privaten Schlüssel der Actors. Gib ihm den Schutz, den du dem KEK gibst. Deshalb kann auch keine andere Einstellung als die Konfigurationsdatei und die Umgebung seine Adresse ändern.
MY_KEY_MANAGER=pluginMY_PLUGIN_KEY_MANAGER_ADDRESS=unix:///run/my/key_manager.sock- Die Adresse ist
unix://oderhttps://. Der Server lehnthttp://ab, auch auf Loopback, da die Schlüssel im Klartext übertragen würden. Die übrigen Einstellungen des Ziels stehen in Plugins. - Führe
my plugin test --kind key_manager <address>aus, bevor du den Server auf ein Plugin richtest (Ein Plugin testen). Es verpackt nur Schlüssel, die es sich ausdenkt und wegwirft. - Die Schlüssel-ID der gespeicherten Secrets ist
plugin:gefolgt von der ID des Plugins für seinen KEK, die aus 1 bis 248 Bytes sichtbarem ASCII besteht. - Behalte jeden KEK, den ein gespeichertes Secret noch nennt. Eine Rotation im Plugin zeigt sich als neue ID beim nächsten Verpacken. Die zuvor verpackten Secrets nennen weiter die alte ID, und das Plugin muss sie weiterhin öffnen können.
my kek rewrapverschiebt sie auf die aktuelle ID, undmy kek statuszählt die übrigen. - Ein Plugin und ein KMS bedienen nie zusammen:
kms_keyundkms_key_previouswerden mit einem Plugin abgelehnt, ebensoplugin_key_manager_addressmitkey_manager = gcpkmsoderawskms.
Wenn der Server startet
Abschnitt betitelt „Wenn der Server startet“Jeder Prozess und jeder my-Befehl, der die Datenbank öffnet, etwa my kek status, tut dies vor allem anderen. Es ist die einzige Art von Plugin, deren Ausfall einen Start verhindert.
- Er fragt das Plugin nach der ID seines aktuellen KEK.
- Er führt einen Selbsttest mit einem zufälligen Schlüssel aus, den er wegwirft: Ein Verpacken und ein Entpacken müssen den Schlüssel zurückgeben, ein Entpacken mit anderen authentifizierten Daten muss mit
OUTCOME_DECRYPTantworten, zwei Verpackungen des Schlüssels müssen sich unterscheiden, und der verpackte Wert darf den Schlüssel nicht enthalten.
Ein Plugin, das nicht antwortet oder mit 503 antwortet, wird bis zu 30 Sekunden lang erneut versucht, für einen Sidecar, der nach dem Server hochkommt. Danach beendet sich der Prozess mit einem Fehler. Eine falsche Antwort und jeder andere Fehler, etwa ein abgelehntes Token, stoppt ihn sofort: Der Selbsttest soll ein Plugin aufhalten, das die authentifizierten Daten ignoriert oder Schlüssel durchreicht, und Warten behebt das nicht.
Wenn das Plugin nicht erreichbar ist
Abschnitt betitelt „Wenn das Plugin nicht erreichbar ist“Der Server schlägt geschlossen fehl. Was auch schiefgeht, ein abgelehnter Aufruf, ein Aufruf mit Zeitüberschreitung oder eine leere, unbekannte oder fehlerhafte Antwort, die Operation, die den Schlüssel brauchte, scheitert mit einem Fehler. Er speichert nie ein Secret im Klartext, wechselt nie zum lokalen KEK oder einem anderen Schlüssel und behandelt nie einen Fehler als Ergebnis. Ein Job, der so scheitert, wird später wiederholt, und eine Anfrage scheitert für die Person, die sie gestellt hat. Jeder fehlgeschlagene Aufruf zählt in my.plugin.failures nach Art und Connect-Code, und das Log enthält keinen Schlüssel, keine authentifizierten Daten und keinen verpackten Wert, auch nichts, was das Plugin gesagt hat.
Das Verpacken wird nie zwischengespeichert, und ein Wert, der gerade versiegelt wurde, hat nichts im Cache, daher stoppen diese sofort:
- Das Erstellen eines Kontos, das die Schlüssel des Actors erzeugt.
- Das Einrichten der Zwei-Faktor-Authentifizierung sowie das Registrieren eines Passkeys oder die Anmeldung mit einem, deren Abläufe ihren Zustand versiegelt halten.
- Die Anmeldung über einen externen Anbieter und das Speichern des Client-Secrets eines Anbieters.
- Das Registrieren eines Webhooks und
my kek rewrap.
Das Lesen eines gespeicherten Secrets funktioniert nur, solange der Prozess seinen Data-Encryption-Key von einem früheren Lesezugriff hält, höchstens kms_dek_cache_ttl (Standard 10m). Danach, oder für ein Secret, das er noch nicht gelesen hat, stoppen auch diese:
- Föderations-Zustellung und signierte Abrufe, die die privaten Schlüssel der Actors brauchen. Die Zustellung holt über die Wiederholungen ihrer Jobs auf, sobald das Plugin wieder da ist.
- Das Prüfen eines Zwei-Faktor-Codes bei der Anmeldung.
- Die Webhook-Zustellung.
Ein Neustart stoppt wie oben beschrieben, starte den Server also nicht neu, um einen Ausfall des Plugins zu beheben: Ein Server, der läuft, bedient weiter, was sein Cache abdeckt, und einer, der neu startet, bedient nichts, bis das Plugin antwortet. Was kein Secret braucht, etwa das Lesen von Timelines und das Verfassen von Beiträgen, läuft weiter. Der Signaturschlüssel des Media-Proxys wird beim Start gelesen und bleibt im Speicher. Auch ein erneuertes Client-Zertifikat oder eine CA-Datei braucht keinen Neustart: Der Server liest die Dateien erneut, sobald sie sich ändern (Plugins).
Der Vertrag
Abschnitt betitelt „Der Vertrag“Die RPCs sind die von my.plugin.key_manager.v1.KeyManagerService, mit einer Standard-Deadline von 5 Sekunden und Nachrichten von höchstens 128 KiB in jede Richtung.
POST /my.plugin.key_manager.v1.KeyManagerService/Describe{}{"outcome":"OUTCOME_OK","keyId":"transit/my-kek-3"}
POST /my.plugin.key_manager.v1.KeyManagerService/WrapKey{"dek":"<base64>","aad":"<base64>"}{"outcome":"OUTCOME_OK","keyId":"transit/my-kek-3","wrapped":"<base64>"}
POST /my.plugin.key_manager.v1.KeyManagerService/UnwrapKey{"keyId":"transit/my-kek-3","wrapped":"<base64>","aad":"<base64>"}{"outcome":"OUTCOME_OK","dek":"<base64>"}keyIdist die eigene ID des Plugins, ohneplugin:.UnwrapKeydarf eine ältere ID als die aktuelle nennen.wrappedhat 1 bis 65.535 Bytes und darf den Schlüssel nicht enthalten. Zwei Verpackungen eines Schlüssels unterscheiden sich.aadsind authentifizierte Daten, die Zeilen-IDs und Spaltennamen enthalten, undUnwrapKeymuss scheitern, wenn sie nicht dem entsprechen, wasWrapKeyerhalten hat. Das verhindert, dass ein Secret in eine andere Zeile kopiert wird.- Protokolliere nie
dek,aadoderwrapped.
outcome |
Bedeutung |
|---|---|
OUTCOME_OK |
Der Aufruf war erfolgreich |
OUTCOME_UNKNOWN_KEY |
UnwrapKey: Das Plugin hält den KEK von keyId nicht |
OUTCOME_DECRYPT |
UnwrapKey: wrapped oder aad lässt sich nicht authentifizieren |
Antworte mit einem HTTP- oder Connect-Fehler, wenn du nicht antworten kannst, etwa weil der Schlüsselspeicher nicht erreichbar ist. Antworte dann nicht mit OUTCOME_DECRYPT oder OUTCOME_UNKNOWN_KEY: Für den Server besagen sie, dass der Wert selbst schlecht ist. Der Server wiederholt einen Aufruf nicht selbst, ein Plugin kann denselben Aufruf also von einem Job erneut erhalten.
Zwischen dem lokalen KEK und einem KMS wechseln
Abschnitt betitelt „Zwischen dem lokalen KEK und einem KMS wechseln“Eine Schlüssel-ID beginnt mit der Art des Key Managers, der sie verpackt hat (local:, gcpkms:, awskms:, plugin:). Der Server verpackt neue Secrets mit dem aktuellen key_manager
und entpackt jedes gespeicherte Secret mit dem Key Manager, den seine Schlüssel-ID nennt, ein Wechsel zwischen dem lokalen KEK und einem KMS ist also eine Rotation über Arten hinweg.
- Mit einem KMS entschlüsseln
kekundkek_previousnur: Sie öffnen die Secrets, die noch mit dem lokalen KEK verpackt sind, und jedes neue Secret wird mitkms_keyverpackt.kms_key_previouslistet frühere Schlüssel desselben KMS auf, die ebenfalls nur entschlüsseln. - Mit
key_manager = localentschlüsselnkms_keyundkms_key_previous, wenn gesetzt, nur: Sie öffnen die Secrets, die noch mit dem KMS verpackt sind. - Vom lokalen KEK zu einem KMS:
- Erstelle den Schlüssel und gewähre die Berechtigungen wie in Google Cloud KMS oder AWS KMS.
- Starte jeden Prozess mit
key_manager = gcpkmsoderawskms,kms_keyauf den Schlüssel gesetzt und dem aktuellen KEK vonkeknachkek_previousverschoben neu. Secrets werden nun mit dem KMS verpackt, und die mit dem lokalen KEK verpackten lassen sich weiterhin öffnen. - Führe
my kek rewrapmit derselben Konfiguration aus. - Wenn
my kek statusunter einerlocal:-Schlüssel-ID keine Secrets mehr zählt, entfernekek_previousund starte neu. Bewahre das Backup des KEK so lange auf, wie du Datenbank-Backups aufbewahrst, die vor Schritt 3 erstellt wurden.
- Von einem KMS zurück zum lokalen KEK machst du dasselbe in die andere Richtung: Setze
key_manager = localund einen neuenkekund lasskms_keygesetzt, der nun nur entschlüsselt, bismy kek rewrapjedes Secret verschoben hat undmy kek statusunter einergcpkms:- oderawskms:-Schlüssel-ID keine Secrets mehr zählt. Die Schlüssel inkms_keyundkms_key_previousmüssen dann alle zum selben KMS gehören. - Um vom KMS einer Cloud zu dem einer anderen zu wechseln, wechselst du zuerst zum lokalen KEK und dann zum anderen KMS; einen direkten Wechsel gibt es nicht.
- Ein Plugin wechselt auf dieselbe Weise, allein über den lokalen KEK:
- Zu ihm: Starte jeden Prozess mit
key_manager = plugin,plugin_key_manager_addressund dem aktuellen KEK vonkeknachkek_previousverschoben neu und führe dannmy kek rewrapaus. Wennmy kek statusunter einerlocal:-Schlüssel-ID keine Secrets mehr zählt, entfernekek_previousund starte neu. - Von ihm: Starte jeden Prozess mit
key_manager = local, einem neuenkekund beibehaltenerplugin_key_manager_address, die nun nur entschlüsselt, neu und führe dannmy kek rewrapaus. Wennmy kek statusunter einerplugin:-Schlüssel-ID keine Secrets mehr zählt, entferne die Adresse und starte neu. Bis dahin muss das Plugin weiterhin die Prüfungen beim Start bestehen, zu denen ein Verpacken gehört.
- Zu ihm: Starte jeden Prozess mit
- Der Server behält einen Data-Encryption-Key, den der KMS oder das Plugin entschlüsselt hat, für
kms_dek_cache_ttl(Standard10m, höchstenskms_dek_cache_entries, Standard1024), ein verwendetes Secret erreicht ihn also etwa einmal pro Zeitraum und Prozess.0in einer der beiden Einstellungen deaktiviert den Cache.
Wenn der KEK durchsickert
Abschnitt betitelt „Wenn der KEK durchsickert“Ist nur der KEK durchgesickert, rotiere ihn wie oben. Wenn sowohl der KEK als auch die Datenbank durchgesickert sein können, schützt dich eine Rotation nicht: Die privaten Schlüssel der Actors in der Datenbank sind bereits lesbar, also müssen die Schlüssel der Actors selbst neu erzeugt werden.
VAPID-Schlüssel für Web Push
Abschnitt betitelt „VAPID-Schlüssel für Web Push“Web Push wird mit dem VAPID-Schlüssel des Servers signiert (P-256, RFC 8292). Er ist ein vom KEK getrenntes Secret und wird nicht in der Datenbank gespeichert.
- Erstelle ein Schlüsselpaar mit
my config vapid-keyund gib jedem Prozess den privaten Schlüssel (den Wert vonvapid_private_key = ...) überMY_VAPID_PRIVATE_KEYoderMY_VAPID_PRIVATE_KEY_FILE. Der Server leitet den öffentlichen Schlüssel aus dem privaten ab und gibt ihn an Clients weiter, du konfigurierst ihn also nicht. - Wenn du ihn nicht setzt, ist Web Push deaktiviert, und Clients bieten es nicht an. Im Profil
productionwarnenmy config checkund der Start vonmy servedavor. - Browser binden ein Abo an den öffentlichen Schlüssel, daher beendet eine Änderung des Schlüssels die Zustellung an bestehende Abos. Wenn Nutzer Push-Benachrichtigungen in den Einstellungen wieder einschalten, abonniert der Client mit dem neuen Schlüssel neu. Ändere den Schlüssel nur, wenn er durchgesickert ist; falls er durchsickert, wechsle zu einem neuen Schlüssel und bitte die Nutzer, Benachrichtigungen erneut einzuschalten.
Für LLMs und Coding-Agenten:llms.txt,llms-full.txt, llms-small.txt