24. Die administrative API¶
pepsi-httpd bedient unter /api/v1 eine HTTP-API, die alles abdeckt, was die Kommandozeilenwerkzeuge des Betreibers tun: die Warteschlange, die Gesundheitszusammenfassung, die Konfiguration, den Schlüsselspeicher und die Journale. Die Browser-Konsole und ein unbeaufsichtigtes Skript sind Clients derselben dokumentierten Oberfläche.
Warnung
Die API ist noch nicht stabil. Der Pfad trägt v1, damit der Versionierungsmechanismus existiert und Clients dagegen geschrieben werden, aber solange die Version von Pepsi mit 0. beginnt, kann ein Release die Gestalt einer Anfrage oder einer Antwort noch ändern; solche Änderungen sind in NEWS aufgeführt. Anders als bei der Datenbank, die jedes Release vorwärts migriert (siehe Upgrade), muss ein Client unter Umständen angepasst werden. Den Vertrag einzufrieren, bevor die Konsole, ihr erster echter Client, ihn erprobt hat, würde blind getroffene Entscheidungen festschreiben.
24.1. Wo sie bedient wird¶
Nur auf einem Listener mit dem Flag ADMIN = yes. Auf jedem anderen Listener antworten die /api/v1-Routen mit einem schlichten 404, das Byte für Byte dem entspricht, was jeder unbekannte Pfad bekommt. Die Veröffentlichung des öffentlichen HTTPS-Listeners veröffentlicht also nicht die Administration, und ein öffentlicher Listener kann nicht einmal daraufhin sondiert werden, ob die Administration auf dieser Installation aktiviert ist.
Die ausgelieferte Konfiguration markiert genau einen Listener, einen UNIX-Socket:
[pepsi-httpd-listener-admin]
SERVE = unix
UNIXPATH = /run/pepsi/admin.sock
UNIXPATH_MODE = 660
UNIXPATH_GROUP = pepsi-admin
MODE = plain
ADMIN = yes
pepsi-httpd weigert sich, die administrativen Routen auf einem markierten Listener zu bedienen, der sie im Klartext von diesem Host forttragen würde: Klartext-TCP wird nur auf einer Loopback-Adresse angenommen, TLS und UNIX-Sockets immer. Ein Socket-aktivierter Listener (SERVE = systemd) qualifiziert sich nur mit TLS, weil die Adresse des geerbten Deskriptors für den Server nicht sichtbar ist. Ein markierter Listener, der die Prüfung nicht besteht, protokolliert beim Start eine Warnung und bedient nur die öffentlichen Endpunkte; pepsi-setup meldet dasselbe, wenn es die Konfiguration validiert, sodass der Fehler auffällt, bevor er Folgen hat.
Bemerkung
Ein Binärprogramm bedient beide Zielgruppen. Es gibt keinen separaten administrativen Daemon, also nur eine Sache, die man bauen, paketieren, beaufsichtigen und im Gleichlauf halten muss. Im Gegenzug ist ein Fehler im gemeinsamen Serverprozess ein Fehler in beiden Oberflächen. Die Isolierung ist daher vom Betreiber zu konfigurieren. Binden Sie den administrativen Listener an einen UNIX-Socket oder an das Loopback und stellen Sie einen Reverse Proxy davor, wenn er von anderswo erreichbar sein muss.
Bemerkung
Was einem Front-Server geglaubt wird. In dieser Topologie terminiert dieser Prozess kein TLS und sieht keine Client-Adresse, also liest er zwei Header vom Front-Server: X-Forwarded-Proto entscheidet, ob das Sitzungs-Cookie Secure hinausgeht (und unter seinem __Host--Namen), und das rechteste X-Forwarded-For-Element ist das, was die Ratenbegrenzungen als Schlüssel verwenden und was das Secure-Link-Portal als Peer eines Zugriffsversuchs festhält. Beide werden nur auf einer Verbindung gelesen, die nicht von außerhalb dieses Hosts stammen kann (einem UNIX-Socket oder einem Loopback-TCP-Peer), sodass ein Client, der direkt mit einem öffentlichen Listener spricht, nie eines von beiden behaupten kann. Die Proxy-Sites, die pepsi-setup schreibt, setzen beide. Ohne sie hat eine über einen Proxy betriebene Installation Cookies ohne Secure-Attribut und einen einzigen Ratenbegrenzungs-Zähler, den sich das ganze Internet teilt.
24.2. Authentifizierung¶
Es gibt drei Mechanismen und ein Identitätsmodell. Ein ausdrücklich vorgelegtes Credential gewinnt immer: Zuerst wird der Authorization-Header versucht, dann das Sitzungs-Cookie, und SO_PEERCRED nur, wenn keines von beiden vorhanden ist. Diese Reihenfolge ist wichtig: Gewönne peercred, bekäme ein Administrator, der bewusst ein eng gefasstes Token über den lokalen Socket vorlegt, stillschweigend die volle Autorität zurück.
24.2.1. Lokale Administratoren (SO_PEERCRED)¶
Ein Prozess, der sich über einen UNIX-Socket-Listener verbindet, wird über die Zugangsdaten identifiziert, die der Kernel bei connect(2) festgehalten hat und die der Peer nicht fälschen kann. root oder ein Mitglied von [pepsi-admin] ADMIN_GROUP (Standardwert pepsi-admin) ist ein Administrator ohne Credential, das man konfigurieren, speichern oder verlieren könnte:
# curl --unix-socket /run/pepsi/admin.sock http://localhost/api/v1/status
So funktioniert der Erstbootstrap auf einem System, das noch keine Konten hat, und deshalb darf der Socket gefahrlos den Modus 0660 mit einer Gruppe haben: Die Identität stammt vom Kernel, nicht vom Dateimodus.
24.2.2. Bearer-Token¶
Für die Automatisierung. Ein Token wird über die API geprägt und genau einmal angezeigt:
# curl --unix-socket /run/pepsi/admin.sock -X POST \
-H 'Content-Type: application/json' \
-d '{"label":"monitoring","scopes":["queue:read","logs:read"]}' \
http://localhost/api/v1/tokens
Die vorgelegte Form ist pepsi_<id>.<secret>. Nur der SHA-256 der geheimen Hälfte wird gespeichert, sodass ein Token nicht erneut angezeigt oder aus einer Datenbanksicherung wiederhergestellt werden kann; die Id-Hälfte ist ein öffentlicher Selektor, der die Tabelle indiziert, was den Vergleich zu einer konstantzeitigen Prüfung gegen einen Datensatz statt zu einem Tabellendurchlauf macht. Die geheime Hälfte ist zufällig und nicht aus etwas Erratbarem abgeleitet, daher braucht sie weder Salt noch langsamen Hash (siehe Offline-Raten schwacher Passwort-Hashes, Schlüssel-Passphrasen und abgeleiteter Schlüssel).
Legen Sie es als Authorization: Bearer pepsi_<id>.<secret> vor. Das ist das Bearer-Schema von RFC 6750, getragen im Authorization-Feld, das RFC 9110 §11.6.2 definiert. Schemanamen beachten keine Groß- und Kleinschreibung (RFC 7235 §2.1), sodass bearer und BEARER ebenfalls angenommen werden. Token können einen Ablauf tragen (expires_in_days) und werden durch Löschen widerrufen.
Das Token ist kein OAuth-2.0-Zugriffstoken (RFC 6749), und es gibt keinen Autorisierungsserver: Es handelt sich um ein lokal geprägtes Credential, das zufällig dasselbe Drahtformat verwendet. Pepsi spricht anderswo sehr wohl OAuth 2.0, ausgehend zu einem Smarthost (siehe pepsi-helper-token-refresh), und die beiden sollten nicht verwechselt werden.
24.2.3. Passwörter und Sitzungen¶
Für einen Browser. Konten liegen in pepsi.admin_account mit gesalzenen Argon2id-Passwort-Hashes (RFC 9106), um vorberechnetes und schnelles Offline-Raten zu verhindern (siehe Offline-Raten schwacher Passwort-Hashes, Schlüssel-Passphrasen und abgeleiteter Schlüssel und Offline-Raten schwacher Passwort-Hashes, Schlüssel-Passphrasen und abgeleiteter Schlüssel). POST /api/v1/auth/login tauscht einen Namen und ein Passwort gegen ein Sitzungs-Cookie (RFC 6265) plus ein CSRF-Token; bei einem Konto mit zweitem Faktor trägt die Anfrage außerdem den aktuellen sechsstelligen Code als "otp". Jede verändernde Anfrage aus einer Sitzung muss dieses Token im X-Pepsi-Csrf-Header wiederholen. Ein Bearer-Token und ein lokaler Peer brauchen kein CSRF-Token: Keines von beiden wird je von einem Browser im Auftrag eines anderen gesendet.
Ein Konto mit einem WebAuthn-Sicherheitsschlüssel (Sicherheitsschlüssel) meldet sich in zwei Schritten an. Sobald das Passwort stimmt, antwortet POST /api/v1/auth/login mit 401 und dem Code second_factor_required sowie in detail mit einer einmal verwendbaren challenge (base64url, fünf Minuten gültig), totp (ob stattdessen ein TOTP-Code antworten darf), register (true, wenn REQUIRE_WEBAUTHN das Konto erfasst und es noch keinen Schlüssel hat, sodass der Schritt eine Registrierung ist) und webauthn: mode (get oder create), rp_id, credential_ids, algorithms, user_id und user_name — was ein Skript an navigator.credentials übergibt. POST /api/v1/auth/login/second-factor nimmt dann {"challenge": …} mit einer Assertion (credential_id, client_data_json, authenticator_data, signature), einer Registrierung (client_data_json, attestation_object, optional label) oder otp entgegen, jedes Binärfeld als base64url ohne Padding, und antwortet wie eine abgeschlossene Anmeldung. Ein falsches Passwort erhält weiterhin das einheitliche invalid_credentials; der zweite Schritt verrät jedem, der das Passwort kennt, zwangsläufig, dass es richtig war.
Das Cookie trägt HttpOnly, SameSite=Strict und das Namenspräfix __Host-. Dieses Präfix ist das stärkste der drei: Der Browser weist das Cookie zurück, sofern es nicht über HTTPS ohne Domain-Attribut und mit Path=/ gesetzt wurde, sodass ein Geschwisterhost auf derselben registrierbaren Domain kein Sitzungs-Cookie für diesen setzen kann. Sitzungstoken werden nie in einer URL übertragen (siehe Reflektiertes und gespeichertes XSS oder HTML-Injektion in Portalen und Administratormails).
Das Präfix und Secure sind eine Entscheidung, und sie richtet sich nach dem Schema des Clients, nicht nach dem dieses Prozesses: ein Listener, der selbst TLS terminiert, oder ein Klartext-Listener hinter einem Front-Server, der wie oben beschrieben X-Forwarded-Proto: https behauptet. Auf dem Klartext-Pfad des lokalen Bootstraps (ein Loopback- oder UNIX-Listener ohne Front-Server) würde ein Browser ein Secure-Cookie rundweg ablehnen, also wird keines von beiden verwendet und das Cookie heißt pepsi_session. Beide Schreibweisen werden beim Eingang angenommen, sodass das Hinzufügen oder Entfernen eines TLS-Front-Servers nicht jeden Administrator abmeldet.
Diese Anforderungen sind auch der Grund, warum das Secure-Link-Portal, das sich einen Ursprung teilt, nicht dasselbe Präfix verwenden kann: __Host- schreibt Path=/ vor, was das Sitzungs-Cookie des Portals auch an /metrics, /resume und das Web Key Directory schicken würde. Es behält seine Pfadbegrenzung, verwendet stattdessen __Secure- und erkauft sich das, was das Präfix gegeben hätte, indem es den Cookie-Wert unter dem Server-Pfeffer versiegelt — siehe Das Secure-Link-Ausweichportal.
Sitzungen sind Datensätze, kein Prozessspeicher, sodass ein Neustart nicht alle abmeldet und zwei Serverprozesse sich einig sind, wer angemeldet ist. Sie laufen zweifach ab:
ein Leerlauf-Timeout (
SESSION_IDLE, Standardwert 30 Minuten), das bei jeder Anfrage vorgeschoben wird, undeine harte Lebensdauer (
SESSION_LIFETIME, Standardwert 12 Stunden), die nie verlängert wird.
Es gibt kein „Angemeldet bleiben“. Diese Konsole kann einen Schlüssel widerrufen, lesen, wer mit wem korrespondiert, und die Pipeline umschreiben; ein vergessener Browser-Tab sollte diese Macht morgen nicht mehr haben, und ein gestohlener Laptop sollte keine dauerhafte administrative Sitzung sein. Die Richtlinie ist tragbar, weil die Leute, die eine Installation am häufigsten verwalten, die lokalen Betreiber, überhaupt nie ein Passwort tippen.
Bemerkung
PAM wird nicht unterstützt. Es würde einen privilegierten Authentifizierungspfad und Systemkonto-Semantik in die Web-Schicht eines Mailservers setzen und die Sicherheit der API von einer Host-Konfiguration abhängig machen, die Pepsi nicht kontrolliert. Ein lokaler Administrator braucht es nicht; ein entfernter bekommt ein Konto in der Datenbank mit einer expliziten Liste von Geltungsbereichen.
24.4. Konventionen¶
Nur JSON. Anfragen und Antworten sind
application/json.Eine Fehlergestalt, bei jedem Fehlschlag:
{"code": "scope_required", "hint": "this endpoint requires the 'queue:write' scope", "detail": {"scope": "queue:write"}}
codeist ein stabiles Token, auf das man verzweigen kann;hintist Prosa für einen Menschen und kann sich ändern;detailträgt strukturierte Zusatzinformation, wenn es welche gibt.Einheitliche Authentifizierungsfehlschläge. Ein falsches Passwort, ein unbekanntes Konto und ein deaktiviertes Konto erzeugen alle dasselbe
invalid_credentials, und ein unbekanntes Konto zahlt dennoch für eine Passwort-Verifikation, sodass weder die Meldung noch die Antwortzeit Konten aufzählt.Interne Fehlschläge tragen nie eine Ursache. Der vollständige Fehler geht ins Prozessjournal; der Client bekommt
internal_error.Auflistungen antworten mit
{"items": [...], "total": N, "limit": L, "offset": O}, und jede einzelne meint damit dasselbe. Siehe Paginierung.ISO-8601-Zeitstempel, mit einem Versatz.
Keine nachgestellten Schrägstriche.
24.5. Paginierung¶
Dreizehn Endpunkte antworten mit der Auflistungshülle, und alle dreizehn verhalten sich gleich:
Endpunkt |
Filter, die auch für |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
— |
|
|
|
|
|
|
|
— |
|
— |
|
— |
|
— (ohne |
limit ist standardmäßig [pepsi-admin] PAGE_LIMIT (100) und wird auf 1–1000 begrenzt; offset wird auf nicht negative Werte begrenzt; ein Wert, der keine Zahl ist, ist ein 400. Die Hülle gibt das angewandte Fenster wieder, sodass eine Anfrage nach limit=100000 mit "limit": 1000 zurückkommt. Beide gehen ins SQL, und total ist ein COUNT(*) über dieselbe WHERE-Klausel wie die Seite, nie die Länge von items und nie die Größe eines zu groß abgerufenen Fensters. Jede Auflistung sortiert zuletzt nach etwas Eindeutigem (ihrer Datensatz-Id), sodass ein OFFSET weder einen Datensatz überspringen noch einen zweimal zeigen kann.
GET /api/v1/mail-log fügt der Hülle ein Mitglied hinzu, mode, denn eine leere Seite bedeutet etwas anderes, je nachdem, ob [pepsi] MAIL_LOG überhaupt etwas aufzeichnet. GET /api/v1/quarantine fügt aus demselben Grund stages hinzu, die Stages, die pepsi-stage-quarantine(1) ausführen: Gibt es keine, kann nichts zurückgehalten werden.
24.5.1. total und die Seite sind zwei Abfragen¶
Die Zählung läuft zuerst, dann die Seite, und nichts hält über die beiden hinweg einen Schnappschuss. Eine nur lesende Transaktion je Auflistung würde sie exakt konsistent machen, um den Preis, eine gepoolte Datenbankverbindung in einer Web-Schicht für eine Garantie zu binden, die kein Client braucht. Also gilt gegen eine nebenläufig beschriebene Tabelle:
zwischenzeitlich gelöschte Datensätze machen
totalzu einer Überschätzung. Die Warteschlange wird fortlaufend geleert, sodass dies dort der Normalfall ist, keine Kuriosität. Der sichtbare Effekt ist eine letzte Seite, die leer zurückkommt.zwischenzeitlich eingefügte Datensätze machen ihn zu einer Unterschätzung.
Blättern Sie, bis items kürzer als limit ist; behandeln Sie total als eine gute Zahl, die man einem Betreiber zeigt, nicht als Schleifengrenze, der man auf den Datensatz genau vertraut.
Die Zählung ist auf jeder dieser Tabellen ein echtes COUNT(*), keine Schätzung. Das ist vertretbar wegen dessen, was sie sind. pepsi.workqueue ist der lebende Rückstau: Der Datensatz einer zugestellten Nachricht wird von der Stage gelöscht, die sie zugestellt hat, sodass die Tabelle noch in Bearbeitung befindliche Mail enthält statt einer Historie von allem je Gesendeten. Der Schlüsselspeicher, die Konten und die Token sind Objekte in Installationsgröße. event_log und mail_log sind die beiden, die mit dem Verkehr wachsen; beide werden von den Aufbewahrungsdurchläufen begrenzt, die unter Das Prüfprotokoll und Das Maillog (standardmäßig aus) beschrieben sind.
24.5.2. Nicht diese Gestalt¶
GET /api/v1/status nimmt ein limit (wie viele steckengebliebene Nachrichten der Bericht auflistet), aber kein offset, und antwortet mit dem Bericht von pepsi-status statt mit einer Auflistung. GET /api/v1/tls-sessions antwortet mit {"days": D, "items": [...]}, begrenzt durch den Parameter days (1–365, Standardwert von pepsi-status); es gibt das angewandte Fenster wieder, so wie die Auflistungshülle limit/offset wiedergibt. GET /api/v1/dns-cache antwortet mit einem bloßen {"items": [...]}, nur begrenzt durch die Größe des DNS-Fehlschlag-Caches. Die Managed-PKI-Auflistungen antworten mit {"items": [...]} (Domains, Benutzer) oder {"items": [...], "limit": L} (Bestellungen sowie Hinweise, bei denen daneben "unread": N steht); limit ist standardmäßig PAGE_LIMIT und höchstens 1000, und es gibt kein offset. GET /api/v1/dmarc-reports antwortet mit {"days": D, "domains": [...], "items": [...]}: days (1–365, Standardwert [pepsi-dmarc-reports] WINDOW_DAYS) ist das Fenster, domains eine Zusammenfassung je Richtlinien-Domain mit ihrem verdict (aligned, unaligned oder no-reports, nur aus authentifizierten Berichten) und items die Quellen, nicht ausgerichtete zuerst, höchstens limit.
24.6. Endpunkte¶
Die maßgebliche Liste für einen gegebenen Build ist GET /api/v1/openapi.json, das aus der eigenen Routentabelle des Servers erzeugt wird, einschließlich der Parameter limit und offset, die es an genau den unter Paginierung aufgeführten Endpunkten deklariert. Die Spalte Anmerkungen unten gibt die übrigen Parameter jeder Auflistung an; jede Auflistung nimmt zusätzlich ?limit= und ?offset=.
Methode |
Pfad |
Geltungsbereich |
Anmerkungen |
|---|---|---|---|
|
|
— |
Liefert ein Sitzungs-Cookie und ein CSRF-Token zurück. |
|
|
— |
Der zweite Schritt einer Anmeldung, die mit |
|
|
— |
Die eigenen Sicherheitsschlüssel der aufrufenden Sitzung (nie ihre öffentlichen Schlüssel). Das Registrieren und Entfernen eines Schlüssels braucht einen Browser und geschieht auf der Seite Security keys der Konsole. |
|
|
— |
Idempotent. |
|
|
— |
Das Erste, was zu prüfen ist, wenn etwas mit |
|
|
|
Passwort-Hashes werden nie zurückgegeben. |
|
|
|
Ein Konto zu löschen beendet seine Sitzungen. |
|
|
|
Die Sicherheitsschlüssel eines Kontos; |
|
|
|
Das Geheimnis steht in der |
|
|
|
Widerruf. |
|
|
|
Identisch zu |
|
|
|
|
|
|
|
Umschlag, Stage, Status und |
|
|
|
Wieder ausstehend an seiner aktuellen Stage. |
|
|
|
Body |
|
|
|
Löscht die Nachricht. |
|
|
|
Das Prüfprotokoll. |
|
|
|
|
|
|
|
|
|
|
|
MX-Adressen, die derzeit scheitern. |
|
|
|
|
|
|
|
|
|
|
|
Die Tripel aus Absender, Empfänger und Client, neueste zuerst. |
|
|
|
Die nicht abgelaufenen Regeln; eine hinzufügen oder erneuern. |
|
|
|
Eine Regel entfernen. |
|
|
|
Einen Absender auf die eigene weiße Liste einer Adresse setzen (keine Regel). |
|
|
|
Die Nachrichten in den Quarantäne-Stages. Siehe Quarantäne. |
|
|
|
Eine zurückgehaltene Nachricht: Umschlag und Quarantäne-Eintrag, nie ihr Inhalt. |
|
|
|
Eine zurückgehaltene Nachricht an ihre |
|
|
|
Eine Nachricht in einer Quarantäne-Stage löschen, ohne sie zuzustellen. |
|
|
|
|
|
|
|
Ein Abschnitt. |
|
|
|
Vor dem Speichern validiert. Siehe unten. |
|
|
|
Trockenlauf; antwortet in beiden Fällen mit |
|
|
|
|
|
|
|
|
|
|
|
Die öffentliche Hälfte, base64. |
|
|
|
Eine |
|
|
|
Eine |
|
|
|
Eine |
|
|
|
Eine |
|
|
|
Eine |
|
|
|
Jeden Sicherheitsschlüssel des Endbenutzers entfernen, der sich mit dieser Adresse anmeldet (darf nie von einem |
|
|
|
Jeden Sicherheitsschlüssel des Listenmitgliedskontos entfernen, das sich mit dieser verifizierten Adresse anmeldet. |
|
|
|
|
|
|
|
Den Schlüssel eines Korrespondenten von Hand importieren. Siehe unten. |
|
|
|
Reiht eine Entdeckungsabfrage ein; es holt nicht ab. Siehe unten. |
|
|
|
Einen zwischengespeicherten Schlüssel vergessen. |
|
|
|
Einen zwischengespeicherten Schlüssel ablaufen lassen und eine neue Suche nach seiner Adresse in die Warteschlange stellen. Siehe unten. |
|
|
|
|
|
|
|
Der öffentliche Status des DKIM-Signier-Daemons. Rotieren mit einer |
|
|
|
Die S/MIME-Vertrauensanker. |
|
|
|
Einen Vertrauensanker hinzufügen: |
|
|
|
Ändert, welche eingehenden Signaturen validieren. |
|
|
|
Den Geltungsbereich des Ankers setzen oder aufheben: |
|
|
|
Die Managed-PKI-Domains und ihre Einstellungen. Siehe Managed PKI. |
|
|
|
Die Einstellungen einer Domain. |
|
|
|
Legt die Einstellungen einer Domain an oder ändert sie. Entscheidet, was die CA der Organisation in Rechnung stellt. |
|
|
|
|
|
|
|
Fügt einen Benutzer unter einem Namen hinzu, für den der Aufrufer bürgt. |
|
|
|
Korrigiert den Namen eines Benutzers oder gibt ihn frei, wählt den Benutzer aus oder wählt ihn ab. |
|
|
|
Löscht einen Benutzer; seine Zertifikate werden widerrufen. |
|
|
|
|
|
|
|
|
|
|
|
Markiert Hinweise als gelesen, für jeden Administrator. |
|
|
|
Ausstehende Secure-Link-Nachrichten, nur Metadaten. |
|
|
|
Eine Nachricht mit ihrer Zugriffshistorie. Nie ihr Inhalt. |
|
|
|
Widerrufen; das zerstört die einzige Kopie der Nachricht. |
|
|
|
Die zu veröffentlichenden Einträge und das letzte Live-Urteil. Siehe unten. |
|
|
|
Das Setup-Interview als Daten. |
|
|
|
Ob das Einschalten der Funktionstelemetrie wirksam werden könnte und, falls nicht, was auf dem Server zu tun ist. Siehe unten. |
|
|
|
Die vorgemerkten Antworten; Zugangsdaten maskiert. |
|
|
|
Antworten in die vorgemerkte (Entwurfs-)Menge einmischen. |
|
|
|
Das vorgemerkte Interview verwerfen. |
|
|
|
Privilegierte Einrichtungsaufgaben, neueste zuerst; ohne |
|
|
|
Den Applier um eine Aktion aus seiner geschlossenen Menge bitten. |
|
|
|
Eine Aufgabe, mit |
|
|
|
Die Umgebung prüfen (Ports, Resolver-DNSSEC). |
|
|
|
Live-DNS mit dem vergleichen, was das Setup veröffentlichen würde. |
|
|
|
Die von der Konfiguration benötigten Zertifikate beziehen. |
|
|
— |
Aus der Routentabelle erzeugt. |
Die Überwachungsendpunkte rufen die eigenen Funktionen von pepsi-status und pepsi-queue auf und serialisieren dieselben Strukturen, sodass pepsi-status --json und GET /api/v1/status konstruktionsbedingt dieselben Bytes sind. Die Konfigurationsendpunkte verwenden den Herkunftsdurchlauf von pepsi-config und dessen Validierung wieder.
24.7. Was dieser Server nicht kann¶
24.7.1. Schlüsselmaterial erzeugen oder widerrufen – es fragt stattdessen den Applier¶
Privates Schlüsselmaterial liegt in crypto_identity.private_wrapped, das pepsi-setup allein der Rolle pepsi-crypto gewährt (vom Schema-Eigentümer abgesehen) und jedem Dienstkonto entzieht, pepsi-httpd eingeschlossen: Eine Web-Schicht, die Signierschlüssel prägen kann, prägt sie für jeden, der sie kompromittiert.
POST /api/v1/identities erzeugt daher nichts. Es stellt eine generate-identity-Aufgabe in die Warteschlange ({"address": ..., "vks": true|false}; vks ist optional und hat als Standard [pepsi-keys] VKS_PUBLISH) und antwortet mit der Aufgabe ({"task": ..., "kind": "generate-identity", "applier_notified": ...}). Der root-Applier validiert sie erneut und erzeugt als Rolle pepsi-crypto einen OpenPGP-Schlüssel. Die Erzeugung auf Anfrage ist immer erlaubt, auch neben dem eigenen Schlüssel des Benutzers.
POST /api/v1/identities/client stellt auf dieselbe Weise eine register-client-key-Aufgabe in die Warteschlange ({"address": ..., "key": ...}, der Schlüssel ein ASCII-armierter öffentlicher OpenPGP-Schlüssel von höchstens 64 KiB). Sie läuft über den Applier, obwohl kein privates Material beteiligt ist, denn der MTA vertraut einem Schlüssel, der als eigener Schlüssel des Benutzers registriert ist: Er wird zum öffentlichen Gesicht der Adresse, und damit erstellte Signaturen werden als die des Benutzers verifiziert. Eine kompromittierte Web-Schicht darf also keinen einschleusen können. Der Applier verlangt ein OpenPGP-Zertifikat, dessen User-IDs die Adresse nennen, und registriert keinen Fingerabdruck, den die Adresse bereits hat, ob ausgemustert oder nicht. Das erschwert es, den Schlüssel eines anderen als den eigenen zu registrieren; die Prüfung liest User-IDs, ohne ihre Selbstsignaturen zu verlangen, und schließt es daher nicht aus (siehe Schlüssel und Zertifikate ohne Prüfung importiert oder vertraut).
PATCH /api/v1/identities/{id} mit {"status": "revoked"} (und einem optionalen "revocation_reason", einer Zeile von höchstens 1024 Byte) ist aus demselben Grund asynchron: Der Widerruf eines reinen Signierschlüssels vernichtet dessen private Hälfte, und dieses UPDATE nennt private_wrapped, was pepsi-httpd nicht darf. Es stellt eine revoke-identity-Aufgabe in die Warteschlange ({"address": ..., "identity_id": ..., "reason": ...}) und antwortet mit der Aufgabe, nicht mit dem geänderten Datensatz: {"identity_id": ..., "task": ..., "kind": "revoke-identity", "applier_notified": ...}. Der status der Identität lautet revoked, sobald der Applier gelaufen ist. GET /api/v1/setup/tasks/{task} zeigt die Aufgabe selbst, sowohl für setup:write als auch für den Prinzipal, der sie angefordert hat. Das result der Aufgabe nennt den Fingerabdruck, gibt an, ob die Identität durch diese Aufgabe widerrufen wurde oder bereits widerrufen war, und sagt, was veröffentlicht wurde: ein Widerrufszertifikat, signiert mit dem Schlüssel, solange dessen private Hälfte noch existierte (revocation_certificate), ausgeliefert vom Web Key Directory (wkd_serves_revocation) und fällig beim Schlüsselserver, auf den der Schlüssel hochgeladen worden war (key_server_upload_due), mit denselben Sätzen in published. Der Applier prüft, dass die Identität zur Adresse der Aufgabe gehört, und wendet dann dieselbe Regel an wie pepsi-keys identity revoke: Die private Hälfte eines reinen Signierschlüssels wird vernichtet, die eines Verschlüsselungsschlüssels behalten, damit bereits an ihn verschlüsselte Mail lesbar bleibt. Weil die Antwort eine Aufgabe ist, trägt ein widerrufendes PATCH nur status; zusammen mit is_primary, published oder vks_wanted wird es mit 400 abgelehnt, ebenso ein revocation_reason ohne status.
Auch die Flag-Änderungen eines Eigentümers werden angefragt. Unter own:<address> (ohne keys:write) ändert ein PATCH, das is_primary, published oder vks_wanted setzt, selbst nichts: Es stellt eine set-identity-flags-Aufgabe in die Warteschlange ({"address": ..., "identity_id": ..., "published": ..., "otp": ...}, mit den genannten Flags) und antwortet mit 202 Accepted und {"identity_id": ..., "task": ..., "kind": "set-identity-flags", "applier_notified": ...}. Welcher Schlüssel Korrespondenten gegeben wird und ob er veröffentlicht ist, sind Änderungen an den Schlüsseln des Eigentümers wie jede andere, daher brauchen sie den zweiten Faktor des Eigentümers, den nur der Applier prüfen kann; der Applier prüft außerdem, dass die Identität zur Adresse der Aufgabe gehört, und hält key.identity.update fest. Ein Betreiber, der keys:write hält, setzt die Flags direkt und erhält 200 mit den geänderten Feldern.
Für alle vier ist die Autorisierungsschranke des Appliers keys:write oder own:<address> für genau die Adresse in den Parametern der Aufgabe (setup:write allein genügt nicht, da die Verwaltung des Schlüssels eines Benutzers nicht die Konfiguration des Servers ist), und die Adresse muss in einer Domain aus [pepsi-ingress] ACCEPTED_DOMAINS liegen. Eine Aufgabe kann mit done, failed (der Applier hat es versucht und konnte nicht, der Grund steht in error) oder refused (der Applier hat den Datensatz gar nicht angenommen) enden, und der anfragende Prinzipal kann lesen, womit: Eine Widerrufsanfrage für einen kompromittierten Schlüssel wird mit GET /api/v1/setup/tasks/{task}?wait=60 verfolgt, bis status einer der drei ist, wie Einer Aufgabe folgen beschreibt. Ohne pepsi-httpd-admin antworten alle vier mit 503 setup_applier_unavailable, wie jeder Applier-Pfad, und ohne eine [pepsi-admin] CONFIG_DB-Verbindung mit 503 setup_write_unavailable (siehe Online-Setup: nur die Rolle pepsi-config darf einreihen). Das Erzeugen eines CSR und das Installieren eines ausgestellten Zertifikats (die Aufgaben identity-csr und identity-certificate) werden auf dieselbe Weise angefordert, abgesichert und beantwortet.
Der zweite Faktor des Eigentümers. Eine Adresse, deren Eigentümer einen zweiten Faktor eingerichtet hat (Schlüsselverwaltung, „Ein zweiter Faktor für Schlüsseländerungen“), benötigt für jede dieser Aufgaben den aktuellen Code, wenn die Aufgabe unter own:<address> angefordert wird: Fügen Sie dem Body "otp": "123456" hinzu (die Formulare der Konsole haben ein Feld dafür). pepsi-httpd kann den Code nicht prüfen (pepsi.otp_key ist allein pepsi-crypto gewährt), daher wird er in den Parametern der Aufgabe mitgeführt, und der Applier prüft ihn, bevor er handelt; ein fehlender, falscher, wiederverwendeter oder gesperrter Code lässt die Aufgabe mit dem Grund in error fehlschlagen. Eine mit keys:write angeforderte Aufgabe wird nicht auf den zweiten Faktor geprüft: Der Betreiber kann den zweiten Faktor ohnehin zurücksetzen. DELETE /api/v1/otp/{address} (nur keys:write, nie own:) reiht eine reset-otp-Aufgabe ein, die den zweiten Faktor der Adresse entfernt und sie damit entsperrt; ihr Eigentümer richtet ihn anschließend neu ein. Die Flag-Änderungen eines Eigentümers werden auf dieselbe Weise auf den zweiten Faktor geprüft, weil sie unter own:<address> ebenfalls Aufgaben sind (siehe Umgehung der Authentifizierung in Web-Oberflächen von Gateways, Listen und Portalen).
24.7.2. Die Konfiguration schreiben, sofern Sie nicht darum bitten¶
pepsi.config_override zu schreiben gehört der Datenbankrolle pepsi-config, die pepsi-setup gewährt und jedem Dienstkonto ausdrücklich entzieht: Eine Komponente, die Mail verarbeitet, darf die Pipeline, in der sie läuft, nicht umschreiben können. pepsi-httpd ist ein solches Konto, und die Peer-Authentifizierung richtet sich nach der effektiven uid, sodass seine eigene Verbindung nicht diese Rolle sein kann. config:write ist dennoch ein mächtiger Geltungsbereich: Das Overlay verdrahtet die Pipeline neu (welche Stages laufen, in welcher Reihenfolge, mit welchen Optionen), obwohl es nie ein ausführbares Programm benennen kann (siehe unten und Befehlsinjektion und XXE in Verwaltungsoberflächen von Mail-Gateways).
PUT und DELETE auf /api/v1/config antworten daher mit 503 config_write_unavailable, bis [pepsi-admin] CONFIG_DB eine Verbindung benennt, die sich als pepsi-config authentifiziert. In der Praxis ist das ein Passwort in einem secrets.d-Fragment, das nur pepsi-httpd lesen kann, oder eine pg_ident-Abbildung. Der Server prüft das beim Start mit SELECT current_user und lehnt alles andere ab.
PUT nimmt {"value": "...", "scope": "..."} entgegen, wobei scope global (der Standard), domain:<domain> oder address:<address> ist; DELETE nimmt dasselbe als ?scope= entgegen, und GET liest die effektive Konfiguration aus der Sicht dieses Geltungsbereichs. Beide Schreibzugriffe antworten mit einem reload-Objekt, das angibt, wie die Änderung wirksam wird (hot, restart mit der neu zu startenden Unit, oder ini-only).
Abschnitte, die nur aus der Konfigurationsdatei gelesen werden ([pepsi], [pepsi-postgres], [paths], [pepsi-admin], [pepsi-httpd], [pepsi-crypto], [pepsi-srs], [pepsi-origin], [pepsi-secure-link], [pepsi-wizard] sowie jeder [pepsi-httpd-listener-*]-, [pepsi-httpd-cert-*]- und [pepsi-ingress-listener-*]-Abschnitt), werden in jedem Fall mit 403 forbidden abgelehnt. Ebenso jede Zugangsdaten tragende Option in jedem anderen Abschnitt, also eine, unter deren durch Unterstriche getrennten Namensteilen PASS, PASSWORD, PASSPHRASE, SECRET, TOKEN, CREDENTIAL(S), CLIENT_ID, PEPPER oder SYSTEM_ID vorkommt (API_PASS, KEY_WRAP_SECRET, aber nicht SECRETARY). Das ist dieselbe Regel, die eine solche Option in GET maskiert, und sie deckt auch die Datei ab, aus der Zugangsdaten gelesen werden, sowie den Endpunkt, an den sie gesendet werden; Geheimnisse werden nie in der Datenbank gespeichert. Ebenso eine Option, die ein ausführbares Programm benennt (HELPER, SCAN_HELPER, MAILBOX_HELPER, PIN_COMMAND), und das PROGRAM einer Stage, sofern es kein bloßer pepsi-stage-*-Befehl ist. Ein domain:- oder address:-Geltungsbereich wird nur für [stage-*]-Abschnitte angenommen, die einzigen Abschnitte, die pro Korrespondent gelesen werden; jeder andere Abschnitt wird dort ebenfalls mit 403 abgelehnt. POST /api/v1/config/validate meldet dieselben Ablehnungen als "valid": false. Der Leser des Overlays wendet dieselbe Regel an, sodass ein Datensatz, der auf anderem Weg in die Tabelle gelangt ist, mit einer Warnung ignoriert wird.
24.7.3. Irgendetwas Privilegiertes tun¶
Das Setup schreibt /etc/pepsi/pepsi.conf, übergibt jedes secrets.d-Fragment dem einen Konto, das es liest, führt certbot aus, legt Datenbankrollen an und erzeugt Schlüsselmaterial, alles als root. pepsi-httpd gibt Privilegien ab, bevor es eine Verbindung annimmt, und darf sie nie zurückerlangen können.
Also handeln die Setup-Endpunkte nicht. Sie schreiben einen Absichts-Datensatz in pepsi.setup_task, und ein separates root-Programm, pepsi-setup apply, leert ihn. Root wird über eine Datenbanktabelle erreicht, nie über einen Socket, der ein Protokoll spricht. Wir tun dies, damit eine Schwachstelle in der Web-Schicht nicht zur Befehlsausführung als root werden kann (siehe Befehlsinjektion und XXE in Verwaltungsoberflächen von Mail-Gateways und Mail-Appliances speichern Geheimnisse für alle lesbar oder ungeschützt). pepsi-setup(1), „Das Vertrauensmodell des Appliers“, beschreibt das vollständige Vertrauensmodell: die geschlossene Aufgabenliste, die zwei Zulassungsschranken, was bewusst fehlt und was der Entwurf nicht versprechen kann. Es ist Pflichtlektüre, bevor das Browser-Setup eingesetzt wird.
24.7.4. Der S/MIME-Zertifikatsrundlauf – ebenfalls beim Applier angefragt¶
Eine S/MIME-Identität, die Pepsi erzeugt hat, trägt ein selbstsigniertes Zertifikat; eine CA stellt aus einer PKCS#10-Anforderung über denselben Schlüssel einen Ersatz aus (den manuellen Rundlauf dokumentiert pepsi-keys(1)). Beide Hälften berühren den privaten Schlüssel: Die Anforderung wird mit ihm signiert, und beim Installieren eines Zertifikats wird er neu verpackt, weil der verpackte Blob an den Fingerabdruck des Zertifikats gebunden ist. Daher sind beide Aufgaben:
POST /api/v1/identities/{id}/csrreihtidentity-csrein ({"display_name": ...}, optional, höchstens 128 Byte: derCNdes Subjekts). Der Subject Alternative Name ist immer die eigene Adresse der Identität und kein Parameter, sodass eine Aufgabe keine CA bitten kann, über diesen Schlüssel ein anderes Postfach zu zertifizieren. Der Applier signiert die Anforderung alspepsi-cryptound hält sie im Ergebnis der Aufgabe alscsr_pemfest; der anfragende Prinzipal liest sie ausGET /api/v1/setup/tasks/{id}(oder auf der Aufgabenseite der Konsole, die das PEM für sich anzeigt).POST /api/v1/identities/{id}/certificatereihtidentity-certificateein ({"certificate": ...}: PEM, wobei ein Bündel sein erstes Zertifikat beisteuert, oder DER als base64, höchstens 64 KiB). Der Applier lehnt ein Zertifikat ab, das nicht über den Schlüssel der Identität ausgestellt ist (geprüft gegen den geöffneten privaten Schlüssel), das die Adresse nicht in seinemrfc822Namenennt, das ein CA-Zertifikat ist, dememailProtectionoder die für den Zweck der Identität nötige Schlüsselverwendung fehlt oder das abgelaufen ist. Dann ersetzt er die öffentliche Hälfte, den Fingerabdruck (SHA-256 des neuen DER, den WKD und Korrespondenten sehen) und das Ablaufdatum, verpackt den privaten Schlüssel unter dem neuen Fingerabdruck neu und hältkey.identity.certificatefest. Das Installieren des bereits vorhandenen Zertifikats ändert nichts (already_installed).
Beide stehen dem eigenen own:<address>-Prinzipal der Adresse offen, mit dem otp-Feld und der Regel zum zweiten Faktor der anderen Schlüsselaufgaben, und antworten mit 400 für eine OpenPGP-Identität oder einen eigenen (MUA-)Schlüssel eines Benutzers, der hier keine private Hälfte hat. Ohne das Applier-Paket antworten sie wie jeder andere Applier-Pfad mit 503.
24.8. Korrespondentenschlüssel¶
POST /api/v1/peers speichert den öffentlichen Schlüssel eines Korrespondenten von Hand; es ist das Geschwister von pepsi-keys peer import. (Die Korrespondentenseite der Browser-Konsole bietet dieselben Import- und Suchformulare sowie je Zeile eine Schaltfläche Re-check; jede ruft die eigene Funktion des Handlers auf, sodass die Konsole nichts annehmen kann, was die API ablehnt.) Der Body benennt die address, das protocol (openpgp oder smime), das material (base64 oder Armored- bzw. PEM-Text wortgetreu) und ein optionales pin.
Zwei Ablehnungen sind wichtig:
Material, das kein Schlüssel ist, ist ein
422 invalid_value. OpenPGP-Eingabe läuft durch den gehärteten Parser, den die Entdeckungsmethoden verwenden, der nur die oberste Ebene durchläuft und einen Strom ablehnt, der ein komprimiertes oder verschlüsseltes Paket trägt: Ein übertragbarer öffentlicher Schlüssel enthält nie eines, und eine an einen Schlüsselbund angehängte Kompressionsbombe ist kein Schlüssel, den zu haben sich lohnt.Ein Schlüssel, der eine andere Adresse benennt, ist ein
422 invalid_value, das benennt, wessen Schlüssel er wirklich ist. Den Schlüssel eines Korrespondenten unter der Adresse eines anderen abzulegen leitet stillschweigend jede künftige Nachricht an ihn fehl. Ein Schlüssel, der keine Adresse benennt, wird gespeichert, denn Schweigen kann nichts widersprechen, und die Antwort sagt das in ihrembinding-Feld (matched/no-identity).
Der Datensatz wird mit source = api gespeichert, was die Konfliktregel neben einen von Hand eingetragenen Schlüssel einstuft: Er verdrängt einen entdeckten und verdrängt keinen gepinnten. Ein *@domain-Eintrag wird hier abgelehnt; das Schema lässt einen nur für source = manual zu, sodass das Weiten einer ganzen Domain eine an einem Terminal getroffene Entscheidung bleibt.
GET /api/v1/peers listet jeden zwischengespeicherten Datensatz auf, auch einen widerrufenen: Sein validity lautet revoked, und wenn pepsi-keydisc ihn aufgrund der Sperrliste seines Ausstellers ausgemustert hat, sagen revoked_at und revoked_reason, wann und welche Liste. Ein solcher Datensatz wird angezeigt, nicht verwendet: Keine Stage erhält ihn.
POST /api/v1/peers/discover stellt eine Abfrage in die Warteschlange und kehrt sofort zurück. Es holt nicht ab: Die Entdeckung spricht HTTPS, LDAP und DNS mit Hosts, die die Domain des Korrespondenten wählt, und das in einem Anfrage-Handler zu tun, ließe einen Fremden die Verbindung dieses Servers offenhalten. Aus demselben Grund parken die Verschlüsselungs- und Entschlüsselungs-Stages eine Nachricht, statt selbst einen Schlüssel nachzuschlagen. Der Endpunkt schreibt denselben pepsi.key_request-Datensatz, den eine Stage schreibt, wenn sie eine Nachricht parkt, über dieselbe SQL-Funktion, und ein pepsi-keydisc-Dienst erledigt die Arbeit. Die Antwort erscheint in GET /api/v1/peers, wenn einer sie gespeichert hat. {"force": true} fragt eine Adresse erneut an, deren frischer Negativ-Cache-Eintrag sagt, dass es keinen Schlüssel gibt. Es antwortet mit 501 no_discovery_method, wenn [pepsi-keydiscovery] SOURCES leer ist, da dann nie ein Dienst antworten würde, und mit 403 für eine Adresse, die ALLOW_DOMAINS/DENY_DOMAINS ausschließen.
POST /api/v1/peers/{id}/recheck ist die erneute Prüfung eines zwischengespeicherten Schlüssels auf Anforderung, gleichbedeutend mit pepsi-keys peer refresh --expire ID gefolgt von einer erzwungenen Suche. Es löscht refresh_after des Datensatzes (sodass die nächste Nachricht an die Adresse neu abruft, was auch sonst geschieht) und löst über dieselbe Funktion einen erzwungenen key_request für die Adresse aus; zurückgegeben werden das Ergebnis der Anforderung, cache_expired: true und die angefragten Methoden. In der Anfrage selbst wird aus dem oben genannten Grund nichts abgerufen; ein neuerer oder widerrufener Schlüssel, den der Dienst findet, ersetzt den Datensatz nach der gewöhnlichen Konfliktregel, und ein gepinnter Datensatz wird nie verdrängt. Ein von Hand eingetragener *@domain-Datensatz antwortet mit 400: Die Schlüsselentdeckung sucht einen solchen nie. Im Prüfprotokoll als key.peer.recheck erfasst.
24.9. Vertrauensanker¶
POST /api/v1/ca-trust fügt einen S/MIME-Vertrauensanker hinzu. Es ist das Geschwister von pepsi-keys ca add und läuft über denselben Parser, sodass beide Oberflächen dieselben Zertifikate annehmen und ablehnen. Der Body trägt das certificate (PEM wortgetreu oder DER als base64) und ein optionales einzeiliges label von höchstens 128 Byte. Nur ein CA-Zertifikat (basicConstraints CA:TRUE) wird angenommen: Ein Endzertifikat könnte keine Kette verankern, sodass sein Speichern eine Ankermenge ergäbe, die stillschweigend nichts validiert; ein Zertifikat mit einem strukturellen Mangel oder einer unbekannten kritischen Erweiterung wird abgelehnt, wie der Verifizierer es ablehnen würde. Der Aufruf ist idempotent bezüglich des SHA-256 des Zertifikats: Das Hinzufügen eines bereits vorhandenen aktualisiert dessen Label und antwortet mit inserted: false. Das Hinzufügen eines Ankers ändert, welche eingehenden Signaturen gültig sind, daher wird es wie DELETE /api/v1/ca-trust/{id} im Prüfprotokoll als key.ca.add auf Stufe warning erfasst. Nur öffentliches Material, daher speichert der Handler es selbst; ein auf eine Adresse beschränkter Prinzipal wird abgewiesen.
Der Geltungsbereich eines Ankers ist die Menge der Mail-Domains, für die ihm vertraut wird, jede einschließlich ihrer Subdomains. Er wird beim Hinzufügen als permitted_domains angegeben (nur auf einen neuen Anker angewandt) und mit PUT /api/v1/ca-trust/{id}/scope geändert ({"permitted_domains": [...]} oder null, um ihn aufzuheben), die Geschwister von pepsi-keys ca add --domain und ca scope. Domains werden als sortierte A-Labels in Kleinbuchstaben gespeichert; eine leere Liste, ein führender Punkt oder ein Name, der keine voll qualifizierte Domain ist, ergibt 422 invalid_value, eine unbekannte Id 404. Die Pfadvalidierung wendet den Geltungsbereich als Namensbeschränkung des Vertrauensankers zusätzlich zu den eigenen des Zertifikats an (siehe Sicherheitsmodell). Im Prüfprotokoll als key.ca.scope auf Stufe warning erfasst. GET /api/v1/ca-trust liefert je Anker permitted_domains und constrained (ob das Zertifikat nameConstraints trägt).
24.10. Managed PKI¶
Die Endpunkte /api/v1/mpki zeigen und ändern die Managed PKI, die S/MIME-Zertifikate für die Benutzer einer Domain bei einer CA bestellt (siehe Schlüsselverwaltung und pepsi-keys(1)). Sie sind die Geschwister von pepsi-keys mpki domain und mpki user, und die Seiten der Konsole (Verwaltete Zertifikate) rufen dieselben Funktionen auf. Lesen braucht keys:read; jede Änderung braucht keys:write, weil die Einstellungen und die Benutzer entscheiden, was der Organisation in Rechnung gestellt wird und wessen Namen ein Zertifikat trägt. Ein auf eine Adresse beschränkter Prinzipal wird bei jedem von ihnen abgewiesen. Ein Body mit einem Feld, das der Endpunkt nicht kennt, wird abgewiesen (400), denn eine falsch geschriebene Einstellung, die stillschweigend ignoriert wird, würde trotzdem abgerechnet; ein Wert, den die Bibliothek ablehnt (ein Schlüsselalgorithmus, den es nicht gibt, ein Erneuerungsfenster von 0 Tagen, ein einziges Zertifikat mit einem Schlüssel auf elliptischer Kurve), wird mit 422 invalid_value und dem zugehörigen Satz beantwortet.
PATCH /api/v1/mpki/domains/{domain}legt die Einstellungen der Domain an, ausgeschaltet, oder ändert sie. Jedes Feld ist optional, und ein fehlendes behält seinen Wert:enabled,api_url,organization_id,product,validity_years,enrolment,header_names,renew_days,certificates,key_algorithm,daily_limitundnotify_address.nullbedeutet beiorganization_iddie einzige Organisation des Kontos und beinotify_addresskeine Mail. Die Antwort ist die Domain, wie sie gespeichert ist. Im Prüfprotokoll alsmpki.domain.seterfasst.POST /api/v1/mpki/usersnimmt{"address": ..., "given_name": ..., "surname": ..., "selection": ...}entgegen; beide Namen sind Pflicht, da der Aufrufer für sie bürgt, undselection(default,yesoderno) ist optional. Es holt auch einen gelöschten Benutzer zurück. Im Prüfprotokoll alsmpki.user.adderfasst.PATCH /api/v1/mpki/users/{address}nimmtgiven_nameundsurnamezusammen entgegen (ein neuer Name, der damit bestätigt ist),confirm_name: true(der Name, wie er ist) undselection;"selection": "no"wählt den Benutzer ab und widerruft seine Zertifikate.DELETElöscht den Benutzer und widerruft seine Zertifikate ebenfalls. Ein Benutzer, der nicht existiert oder gelöscht wurde, ergibt404. Im Prüfprotokoll alsmpki.user.setundmpki.user.deleteerfasst, mitwarning, wenn Zertifikate widerrufen werden.GET /api/v1/mpki/userslistet jeden Benutzer mitwanted(ob die Einstellungen ihm ein Zertifikat geben),hold_reason(warum eine Bestellung für ihn warten würde) und seinen fünf neuestenordersauf.GET /api/v1/mpki/ordersgibt nie den verpackten Schlüssel einer Bestellung zurück, denpepsi-httpdnicht lesen kann;has_keysagt, ob die Bestellung einen hat.POST /api/v1/mpki/notices/readnimmt{"ids": [...]}oder{"all": true}entgegen; fehlt beides, ergibt das422. Es antwortet mit{"marked": N}und wird im Prüfprotokoll alsmpki.notice.readerfasst.
Nichts hier spricht mit der CA. Bestellungen aufgeben, freigeben, wiederholen und stornieren sowie die CA-Zugangsdaten sind Sache von pepsi-keys mpki: pepsi-httpd hat keine Berechtigung, mpki_order zu schreiben, und kann die Zugangsdaten-Datei nicht lesen.
24.11. Greylisting¶
Die Endpunkte /api/v1/greylist zeigen, was pepsi-greylist(1) entschieden hat, und ändern seine Regeln. Sie sind die Geschwister von pepsi-greylist stats, list, rules, allow, deny und unrule, und die Greylisting-Seiten der Konsole (Greylisting) rufen dieselben Funktionen auf. Lesen braucht logs:read, da die Tripel festhalten, wer wem geschrieben hat; eine Regel braucht config:write, da sie entscheidet, welche Mail für jeden Benutzer angenommen wird. Ein auf eine Adresse beschränkter Prinzipal liest nur die Tripel seiner eigenen Adresse und darf weder die Zähler noch die Regeln sehen.
GET /api/v1/greylistantwortet mit{"configured": ..., "hours": H, "counts": [{"outcome", "reason", "count"}], "totals": {outcome: n}, "never_retried": N}aus den stündlichen Zählern des Daemons (greylist_stats) und durchsucht daher nie die Tripel.never_retriedzählt die ersten Versuche, deren Wiederholungsfenster im Zeitraum ohne Wiederholung endete. Es prüft den Socket des Daemons nicht, den das Konto dieses Servers womöglich nicht öffnen darf;pepsi-statustut das.GET /api/v1/greylist/tripletsnimmt?state=(all,pending,passed,never-retried),?domain=(die Domain der Client-Identität oder die des Absenders oder eine übergeordnete Domain einer der beiden),?ip=(eine Adresse oder ein Netz) und?rcpt=entgegen, wiepepsi-greylist list; ein fehlerhaftesstateoderipergibt ein400.POST /api/v1/greylist/rulesnimmt{"action": "allow"|"deny", "kind": "ip"|"network"|"domain"|"sender"|"rcpt", "value": ..., "note": ..., "expires_in": "90 days"}entgegen;noteundexpires_insind optional. Die Regel wird vongreylist_rule_addgeschrieben, das den Wert normalisiert und einen fehlerhaften ablehnt (422mit seinem Satz); dieselbe Aktion, dieselbe Art und derselbe Wert erneuern eine Regel. Es antwortet mit{"rule_id": N}. Die Regel hältorigin = consoleund die Identität des Aufrufers fest.DELETE /api/v1/greylist/rules/{id}entfernt eine übergreylist_rule_remove. Im Prüfprotokoll alsgreylist.rule.addedundgreylist.rule.removederfasst, wie auf der Kommandozeile.POST /api/v1/greylist/allow-sendernimmt{"sender": ..., "address": ...}entgegen. Einown:-Prinzipal lässtaddressweg (oder nennt seine eigene);config:writenennt eine beliebige Adresse. Der Absender kommt auf die eigene weiße Liste der Adresse: die erste weiße Liste im eigenen Namensraum des Benutzers (<login>/…) unter denen, dieWHITELIST_BYPASSdes Daemons für diesen Empfänger befragt. Der Datensatz ist der, denpepsi-whitelist addfür eine Adresse schreibt (ein verankertes Literal, das gegenFrom:geprüft wird, mit DKIM als Pflicht), sodass er nur für Mail zählt, die die Domain des Absenders authentifiziert, und auch die Whitelist-Stage liest ihn. Gibt es keine solche weiße Liste (der Bypass ist aus, oder jede weiße Liste, die er befragt, ist gemeinsam genutzt), lautet die Antwort409 conflict: Eine gemeinsame weiße Liste ließe den Absender für alle durch, und das ist Aufgabe einer Regel. Es antwortet mit{"address", "sender", "whitelist", "added"}(addedist false, wenn der Absender bereits dort stand) und wird im Prüfprotokoll alswhitelist.sender.addederfasst.
pepsi-httpd darf die vier Greylisting-Tabellen lesen und nichts weiter: Eine Regel ändert sich nur über die beiden SECURITY DEFINER-Funktionen und ein Datensatz einer weißen Liste nur über whitelist_add_user_sender, das das Muster selbst aus einer einzigen Adresse baut und den Namen einer einteiligen (gemeinsamen) weißen Liste ablehnt. Der Server kann weder ein Tripel durchlassen noch irgendjemandes weiße Liste lesen.
24.12. Quarantäne¶
Die Endpunkte /api/v1/quarantine listen die Nachrichten auf, die eine pepsi-stage-quarantine(1)-Stage zurückhält, und geben eine davon per Token frei oder löschen sie, über die Funktionen, die pepsi-queue quarantine verwendet. Lesen braucht queue:read, Handeln queue:write. Jedes Element ist das, was pepsi-queue quarantine show --json ausgibt (Umschlag, From:, Subject: sowie since, until, by und reason des Quarantäne-Eintrags), plus held, das false ist, solange ein Worker die Nachricht hat oder sie auf eine Wiederholung wartet. Nie ihre Header oder ihr Nachrichtentext.
POST /api/v1/quarantine/{token}/releasegibt eine zurückgehaltene Nachricht alspendingan ihre Quarantäne-Stage zurück, die sie an ihreRELEASE_STAGEweiterschickt. Es verwendet nichtworkqueue_resume, das zurückgehaltene Mail ablehnt, sodass das Token des Zahlungs-Webhooks sie nicht freigeben kann. Eine Nachricht, die nicht zurückgehalten (paused) ist, ergibt ein404.POST /api/v1/quarantine/{token}/deletelöscht die Nachricht, sofern kein Worker sie hat (409), und hält die Löschung im optionalen Maillog fest, wie espepsi-queue quarantine deletetut.
Beide antworten mit {"workqueue_id": N, "token": ...} und werden im Prüfprotokoll als queue.quarantine-release und queue.quarantine-delete erfasst.
24.13. DKIM-Schlüssel¶
GET /api/v1/keys/dkim antwortet mit dem, was der Signier-Daemon pepsi-dkim(1) in seiner öffentlichen Statusdatei ([pepsi-dkim] PUBLIC_DIR/status.json) meldet: {"file": ..., "status": ..., "error": ...}. status ist das Dokument selbst oder null, solange der Daemon es nicht geschrieben hat, und error sagt, warum eine vorhandene Datei nicht gelesen werden konnte. Das Dokument führt je Signier-Domain die Schlüsselgenerationen auf, mit ihren Selektoren, Algorithmen, Zuständen (next, current, retiring, retired), TXT-Einträgen und der Angabe, ob jeder autoritative Server sie ausliefert, außerdem die ausstehenden DNS-Änderungen und eine auf DNS wartende Rotation. Dieser Server hält keinen DKIM-Schlüssel und liest keinen: Die Datei enthält nur öffentliches Material. Der Endpunkt ist schreibgeschützt. Eine Rotation wird mit POST /api/v1/setup/tasks der Art dkim-rotate angefordert ({"domain": ..., "hard": false}, setup:write), die der root-Applier durch Ausführen von pepsi-dkim rotate durchführt, da der Daemon Verwaltungsanfragen nur von root und seinem eigenen Konto annimmt.
24.14. Secure Links¶
GET /api/v1/secure-messages listet die Nachrichten auf, die das Secure-Link-Portal hält: von wem und für wen sie sind, wann sie erzeugt wurden und wann sie ablaufen, wie oft die PIN richtig und wie oft falsch eingegeben wurde, ob eine Sperre in Kraft ist und wie viele Bytes gespeichert sind. GET /api/v1/secure-messages/{token} fügt das Zugriffsprotokoll hinzu: den Zeitstempel, die Peer-Adresse und das Ergebnis jedes Versuchs. Es gibt bewusst keine Geolokalisierung und keinen User Agent.
Kein Endpunkt liefert die Nachricht zurück. pepsi-httpd ist das Portal, sodass es die eine Datenbankrolle ist, der secure_message.ciphertext gewährt ist. Genau deshalb liest nichts auf der Betreiberoberfläche diese Spalte. Die Abfragen hinter diesen Endpunkten benennen jede Spalte außer dieser und melden nur length(ciphertext), sodass die Eigenschaft durch das SQL durchgesetzt wird und nicht durch ein Feld, an dessen Weglassen jemand gedacht hat. Sie zu lesen hülfe auch nicht: Der Schlüssel ist Argon2id über einer PIN, die der Server nie sieht, je Datensatz gesalzen und aus einer Datei gepfeffert, die nur das Portal liest. Ein Datenbank-Dump allein erlaubt daher kein Raten der PIN; mit dem Pfeffer dazu bleibt nur noch die PIN-Länge (siehe Offline-Raten schwacher Passwort-Hashes, Schlüssel-Passphrasen und abgeleiteter Schlüssel).
DELETE /api/v1/secure-messages/{token} widerruft. Es löscht den Datensatz und mit ihm die einzige Kopie der Nachricht, denn es gibt keinen Hinterlegungsschlüssel, und das Portal führt keine zweite Kopie. Deshalb braucht es secure:write statt secure:read. Der Absender sendet erneut, wenn es ein Versehen war.
24.15. DNS-Einträge¶
GET /api/v1/dns-records antwortet mit den Einträgen, die diese Installation veröffentlichen sollte, dem letzten Live-DNS-Urteil zu jedem (ok / missing / mismatch / lookup-failed), der Abhilfe für jeden falschen und dem Zonentext, den pepsi-setup run ausgeben würde.
Es bedient eine gespeicherte Antwort, statt eine zu berechnen. Abzuleiten, was veröffentlicht werden sollte, bedeutet, die validierte Konfiguration und den Status des DKIM-Signier-Daemons zu lesen, und es zu vergleichen bedeutet, DNS abzufragen. Diese Arbeit gehört pepsi-setup, das dieser Server nicht aufrufen kann (die Abhängigkeit verläuft bereits andersherum), und eine Web-Schicht sollte dessen Eingaben nicht lesen. Also berechnet der privilegierte Applier es als Teil einer run-preflight-Aufgabe und schreibt es zurück, und dieser Endpunkt meldet es mit dem Zeitpunkt seiner Berechnung, immer: Ein Urteil ohne Altersangabe lädt dazu ein, einem veralteten zu vertrauen. POST /api/v1/setup/dns-check bittet um ein frisches und braucht entsprechend setup:write: Anzusehen, was gefunden wurde, ist ein Lesen, einen root-Prozess zu bitten hinzusehen aber nicht.
Bevor eine Prüfung gelaufen ist, ist die Antwort leer und benennt den Endpunkt, der eine ausführt, statt einer leeren Liste, die sich wie „alles ist in Ordnung“ liest.
24.16. Online-Setup¶
Dies ist der Browser-Weg durch pepsi-setup. Er beruht auf zwei Mechanismen:
Antworten werden vorgemerkt, nicht angewandt. PUT /api/v1/setup/answers mischt in eine Menge von Entwurfs-Datensätzen in pepsi.config_override ein, die jeder Konfigurationsleser strukturell herausfiltert (WHERE NOT draft). Nichts wird wirksam, während das Interview läuft, sodass eine Sitzung, die auf halbem Weg ausläuft, keinen halb konfigurierten Mailserver hinterlassen hat, und das Fortsetzen ist ein Zurücklesen der Entwürfe. Die Bezeichner sind die, die GET /api/v1/setup/questions veröffentlicht. Sie sind zugleich die Schlüssel, die pepsi-setup --answers liest und die der [pepsi-wizard]-Abschnitt hin- und zurückführt, sodass ein Interview im Browser begonnen und an einem Terminal beendet werden kann.
Der Telemetrie-Schalter wird nur dort angeboten, wo er wirksam werden kann. [pepsi] SHARE_TELEMETRY steht in der Konfigurationsdatei, wird also wie jede andere Antwort gesetzt und von der write-config-Aufgabe des Appliers geschrieben, die anschließend die Benachrichtigung telemetry_changed sendet (in beide Richtungen), sodass ein laufender pepsi-telemetry-client die Datei neu einliest. Dieser Daemon darf laufen, während die Telemetrie aus ist (ruhend, ohne etwas zu übermitteln), und er führt in pepsi.telemetry_client einen Lebendigkeitsdatensatz, der angibt, ob er läuft und ob eine SYSTEM_ID konfiguriert ist (ein Boolean; die Konsole sieht die Kennung nie). Die Konsole erzeugt nie eine Kennung, da genau das durch Opt-in ausgeschlossen ist; solange der Daemon also nicht läuft und eine hat, kann ja nicht wirksam werden: GET /api/v1/setup/questions markiert die Frage dann mit "disabled": true und einem disabled_reason, der dem Betreiber sagt, was auf dem Server zu tun ist (systemctl enable --now pepsi-telemetry-client.service; SYSTEM_ID = mit 64 hexadezimalen Zeichen in [pepsi] ergänzen), die Konsole stellt sie deaktiviert dar, und ein trotzdem über PUT /api/v1/setup/answers oder eine write-config-Aufgabe gesendetes ja wird mit 409 telemetry_client_not_ready abgewiesen. Das Ausschalten oder das Beibehalten einer Antwort, die bereits ja ist, wird nie abgewiesen. GET /api/v1/setup/telemetry antwortet mit dem Gesamtbild:
{"question": "SHARE_TELEMETRY", "sharing": false, "can_enable": true,
"reason": null,
"client": {"running": true, "enabled": false, "submitting": false,
"system_id_configured": true, "detail": null,
"version": "0.1.0", "last_seen": "2026-09-27T10:00:00+00"}}
Aktionen werden angefragt, nicht ausgeführt. POST /api/v1/setup/tasks reiht eine von sechzehn Arten ein (write-config, write-secret, obtain-certificate, install-schema, provision-roles, generate-keys, dkim-rotate, run-preflight, generate-identity, register-client-key, revoke-identity, set-identity-flags, reset-otp, confirm-enrolment, identity-csr, identity-certificate) mit streng validierten Parametern. (Eine siebzehnte, confirm-login, prüft den zweiten Faktor einer Konsolen-Anmeldung und wird allein vom Anmeldepfad eingereiht; dieser Endpunkt lehnt sie ab.) Die letzten acht wirken auf eine Adresse. Sie werden normalerweise über POST /api/v1/identities, /identities/client, ein widerrufendes oder Flags setzendes PATCH /api/v1/identities/{id}, DELETE /api/v1/otp/{address}, POST /api/v1/identities/{id}/csr und POST /api/v1/identities/{id}/certificate erreicht, confirm-enrolment über die Anmeldung per E-Mail an der Konsole (Anmelden per E-Mail); diese Art prüft nur den Code des zweiten Faktors eines Eigentümers und ändert nichts. Der Applier autorisiert sie über keys:write oder, bei allen außer reset-otp, über den eigenen own:-Geltungsbereich der Adresse, nicht über setup:write. Es gibt keine Art für beliebige Befehle, und es gibt keine Neustart-, Reload- oder Abschaltart: Eine Änderung, die den Neustart einer Komponente braucht, endet damit, dass der Betreiber sie neu startet, was die Konsole sagt, statt es zu verbergen. Der Applier lehnt alles andere ab, und jede Ablehnung, jeder Erfolg und jeder Fehlschlag ist ein Prüfeintrag.
Das Einreihen läuft über die [pepsi-admin] CONFIG_DB-Verbindung, genau wie Konfigurationsschreibvorgänge und aus demselben Grund: Nur die Rolle pepsi-config darf INSERT in setup_task ausführen, und der Applier lehnt jeden Datensatz ab, dessen written_by etwas anderes sagt. Ohne diese Verbindung antworten die Setup-Endpunkte mit 503 setup_write_unavailable; das eigene Konto des Servers darf die Warteschlange nur mit SELECT lesen, sodass die Konsole privilegierte Arbeit beobachten kann, ohne sie anfordern zu können.
GET /api/v1/setup/tasks/{id}?since=<seq> liefert die Fortschrittszeilen zurück, die der Applier bisher geschrieben hat, sodass ein certbot-Lauf oder eine Schemainstallation Zeile für Zeile beobachtet werden kann, ohne dass der Applier eine HTTP-Verbindung offenhält.
24.16.1. Einer Aufgabe folgen¶
Eine Aufgabe antwortet mit {"id", "kind", "status", "requested_by", "requested_at", "result", "error", "log"}; status ist pending oder running, bis er einer von done, failed oder refused ist, wonach der Applier nichts mehr in sie schreibt. params wird nie zurückgegeben, da der Parameter einer Art ein Credential ist.
Wer sie lesen darf. Ein Prinzipal, der setup:write hält, liest jede Aufgabe. Jeder andere authentifizierte Prinzipal liest die Aufgaben, die er selbst eingereiht hat. In der Praxis sind das die generate-identity-, register-client-key-, revoke-identity-, set-identity-flags-, identity-csr- und identity-certificate-Aufgaben, die er über die Schlüssel-Endpunkte eingereiht hat, die einzigen Aufgaben, die er einreihen kann. GET /api/v1/setup/tasks wird auf diese verengt statt abgelehnt, und GET /api/v1/setup/tasks/{id} antwortet für eine Aufgabe, die jemand anderes eingereiht hat, mit 404 not_found, genau wie für eine, die nicht existiert. Was eine solche Aufgabe zeigt, ist die eigene Angelegenheit des Anfragenden: die Art, die Adresse und Identität, die sie benannt hat, der Fingerabdruck des Schlüssels, die angeforderte Zertifikatsanforderung und warum sie fehlgeschlagen ist oder abgewiesen wurde. Die Parameter (ein registrierter öffentlicher Schlüssel, ein Widerrufsgrund, ein ausgestelltes Zertifikat) werden nicht zurückgegeben, und die Schlüssel-Endpunkte geben ohnehin nichts Privates heraus.
„Selbst eingereiht“ wird anhand eines mit der Aufgabe gespeicherten Schlüssels entschieden, requester_key, nicht anhand von requested_by. requested_by (token:<label>, session:<login>, peer:<login>) ist das, was die Aufgabe anzeigt und was das Prüfprotokoll festhält, aber es ist ein Name, und Namen werden wiederverwendet: Zwei Token können dasselbe Label tragen, und ein gelöschtes und unter demselben Login neu angelegtes Konto ist ein neues Konto. Der Schlüssel wird nie wiederverwendet: token:<selector> für ein Bearer-Token (die öffentliche <id>-Hälfte von pepsi_<id>.<secret>, eindeutig unter den Token), account:<n> für eine Passwortsitzung (die Datensatznummer des Kontos, die PostgreSQL nie zweimal vergibt) und peer:<login> für einen lokalen Peer, bei dem das Systemkonto selbst der Prinzipal ist. Ein neues Token mit dem Label eines alten oder ein neu angelegtes Konto liest also keine der Aufgaben seines Vorgängers. Eine von der Kommandozeile (pepsi-setup) eingereihte Aufgabe speichert einen leeren Schlüssel, zu dem kein Prinzipal passt.
Warten statt erneut fragen. ?wait=<seconds> (höchstens 60; ein größerer Wert wird als 60 genommen) hält die Antwort zurück, bis die Aufgabe beendet ist oder eine Fortschrittszeile nach since hat (0, wenn nicht angegeben), oder bis die Zeit abgelaufen ist, je nachdem, was zuerst eintritt, und antwortet dann genau wie ohne. Ein Client, der einer Aufgabe folgt, läuft daher in einer Schleife über ?since=<last seq>&wait=60: Jede Antwort trägt die Zeilen, die er noch nicht gesehen hat, und ein status, der nicht pending oder running ist, beendet die Schleife. In der Zwischenzeit fragt nichts die Datenbank ab. Die Schreibvorgänge des Appliers lösen zwei Benachrichtigungen mit der Aufgaben-ID aus: setup_task_progress für jede Fortschrittszeile und setup_task_done, wenn die Aufgabe endet (siehe pepsi-setup). pepsi-httpd hält eine Listener-Verbindung für sie, die jede auf diese Aufgabe wartende Anfrage weckt. Eine wartende Anfrage abonniert, bevor sie den Datensatz liest, sodass eine Aufgabe, die zwischen beidem endet, nie verpasst wird. Ist der Listener nicht verbunden (etwa weil PostgreSQL neu gestartet wurde), kehrt wait sofort zurück und hängt nie; der Listener verbindet sich von selbst neu. Ein wait, das keine ganze Zahl von Sekunden ist, ergibt ein 400.
Die Aufgabenseite der Konsole tut dasselbe für einen Browser, ohne Skript: Solange eine Aufgabe aussteht oder läuft, lädt sich die Seite sofort in eine Anfrage neu, die der Server bis zu 20 Sekunden lang zurückhält, bis es etwas Neues zu zeigen gibt, sodass das Ergebnis in dem Moment erscheint, in dem der Applier es festhält. Die Selbstbedienungs-Schlüsselformulare (erzeugen, registrieren, widerrufen) antworten mit dieser Seite für die Aufgabe, die sie eingereiht haben.
24.17. Härtung¶
Was ein gestohlenes Administratorpasswort oder eine kompromittierte Web-Schicht einem Angreifer verschaffen würde, steht in Ein delegierter Administrator und Eine kompromittierte Komponente; die Datenbankrechte, die pepsi-httpd einschränken, stehen in Die Privilegientrennung.
Ratenbegrenzungen, je Quelladresse (
RATE_LIMIT, Standardwert 120/Minute) und, auf dem Anmeldepfad, je Konto und je Quelladresse (LOGIN_RATE_LIMIT, Standardwert 10/Minute), denn viele Passwörter gegen ein Konto und ein Passwort gegen viele Konten sind verschiedene Angriffe; dazu eine tägliche Obergrenze für fehlgeschlagene Anmeldungen je Konto aus allen Quellen zusammen (LOGIN_DAILY_LIMIT, Standardwert 100), oberhalb derer die Passwort-Anmeldungen des Kontos mit429beantwortet werden, bis das Kontingent sich wieder auffüllt. „Quelladresse“ ist die des Clients, ausX-Forwarded-Forgenommen, wenn ein vertrauenswürdiger lokaler Front-Server eine behauptet; ein UNIX-Socket-Aufrufer ohne eine solche Behauptung hat keine Adresse, und der ganze Host teilt sich einen Schlüssel.Body-Obergrenzen (
MAX_BODY, Standardwert 1 MiB) und eine Frist von 30 Sekunden für jeden Anfrage-Body, sobald seine Header angekommen sind (die Header haben eigene 30 Sekunden, ein TLS-Handshake ebenso), sodass ein Client, der Bytes tröpfchenweise sendet, keinen Verbindungsplatz blockieren kann.Begrenzte Passwortprüfungen. Jede Argon2id-Verifikation läuft außerhalb des Anfrage-Executors, höchstens eine pro CPU gleichzeitig; eine Anmeldung, die innerhalb von fünf Sekunden keinen freien Platz findet, wird mit
429beantwortet, ohne dass etwas geprüft wird. Ein unbekanntes Konto wird gegen einen Dummy-Hash verifiziert, sodass auch die Antwortzeit keine Konten aufzählt.Verbindungsgrenzen für den ganzen Server, in
[pepsi-httpd]:MAX_CONNECTIONS(Standardwert 256) undMAX_CONNECTIONS_PER_IP(Standardwert 32, je IPv4-Adresse oder IPv6-/64; die UNIX-Socket-Verbindungen eines Reverse-Proxys werden nicht gezählt). Die Werte sind in Verfügbarkeit tabelliert.Konstantzeitiger Vergleich jedes Tokens und CSRF-Digests.
Kein Geheimnis wird je zurückgegeben von
GET /api/v1/config: Ein Wert, der eines sein könnte, wird durch"***"mit"secret": trueersetzt. Die Maskierung ist bewusst großzügig: Ein fälschlich maskierter Wert kostet einen Blick in die Datei, ein fälschlich gezeigter dagegen wird an jeden veröffentlicht, derconfig:readhält.Kein Nachrichteninhalt ist erreichbar. Die Warteschlangenendpunkte antworten mit dem Umschlag, der Stage, dem Status und dem
state-JSON, nie mitheadersoderbody. Mail zu lesen ist keine administrative Funktion.Antworten tragen
Cache-Control: no-store,X-Content-Type-Options: nosniffund eineframe-ancestors 'none'-Richtlinie.
24.18. Das Prüfprotokoll¶
Jede Konfigurationsänderung, Schlüsseloperation, Anmeldung, fehlgeschlagene Anmeldung, Konto- und Tokenänderung sowie administrative Warteschlangenaktion wird in pepsi.event_log festgehalten und ist über GET /api/v1/events lesbar:
event_id at actor kind subject severity detail
actor benennt den Prinzipal (peer:root, token:monitoring, session:alice) oder, für eine an einem Terminal vorgenommene Änderung, den aufrufenden Login (cli:alice). Die Kommandozeilenwerkzeuge des Betreibers schreiben in dasselbe Protokoll, sodass es vollständig ist, ganz gleich welche Oberfläche handelte; ein Protokoll, das nur bemerkte, was über HTTP geschah, lüde dazu ein, aus einem Fehlen den falschen Schluss zu ziehen.
Das Protokoll ist für alles, was Mail verarbeitet, nur anfügbar: pepsi-setup gewährt diesen Rollen INSERT und SELECT, entzieht UPDATE/DELETE und prüft den Entzug dann gegen den laufenden Server. Die Aufbewahrung wird durch [pepsi-admin] EVENT_RETENTION_DAYS (Standardwert 90) begrenzt und täglich von pepsi-httpd prune bereinigt, das pepsi-log-prune.timer unter dem Konto pepsi-httpd ausführt, unabhängig davon, ob der Webserver läuft.
Weder ein Konfigurationswert noch irgendein Schlüsselmaterial wird in einen Datensatz geschrieben: Was sich geändert hat, ist die prüfbare Tatsache, nicht, worauf es sich geändert hat.
24.19. Das Maillog (standardmäßig aus)¶
Warnung
``[pepsi] MAIL_LOG`` einzuschalten lässt diese Installation aufzeichnen, wer mit wem korrespondiert. Überlegen Sie, ob Sie diesen Nachweis brauchen und ob es dort, wo Sie tätig sind, rechtmäßig ist, ihn aufzubewahren, bevor Sie es einschalten.
Pepsi löscht den Datensatz einer Nachricht, wenn die Pipeline mit ihr fertig ist. Es gibt daher kein Erfolgsprotokoll je Nachricht: Eine gewöhnliche Installation sammelt keine Aufzeichnung der Korrespondenz ihrer Benutzer an und kann nicht gezwungen werden, eine herauszugeben, die sie nicht hat.
Manche Installationen brauchen diesen Nachweis wirklich. [pepsi] MAIL_LOG liefert ihn, als administrativen Akt mit ausgesprochener Konsequenz:
offDer Standardwert. Nichts wird geschrieben;
pepsi.mail_logbleibt leer.summaryEin Datensatz, wenn die Nachricht die Pipeline verlässt: der Umschlagabsender und die Empfänger, die Richtung (
outboundfür lokal eingelieferte Mail, sonstinbound), die Stage, an der sie endete, das Ergebnis und was die Pipeline über sie entschieden hat (das Authentifizierungsurteil, die Spam-/Bezahlt-Entscheidung, etwaige Fehlschlagsdetails des nächsten Hops).fullDas Obige plus die
Subject:-Zeile.
Nachrichteninhalt wird bei keiner Einstellung je aufgezeichnet. Datensätze sind über GET /api/v1/mail-log für einen Prinzipal lesbar, der logs:read hält (oder, für eine Adresse, own:<address>), sind für die mailverarbeitenden Konten genau wie das Prüfprotokoll nur anfügbar und werden nach [pepsi-admin] MAIL_LOG_RETENTION_DAYS Tagen (Standardwert 30) beschnitten.
Ein Datensatz wird geschrieben, wenn eine Stage mit einer Nachricht fertig wird (completed) und wenn eine Nachricht dauerhaft scheitert (failed); das sind die zwei Arten, auf die sie aufhört, sich zu bewegen. Der Schreibvorgang reitet auf derselben Anweisung wie das Terminal, das den Datensatz entfernt oder scheitern lässt, sodass das Aktivieren des Protokolls keinen zusätzlichen Datenbank-Round-Trip kostet.
24.20. Bootstrapping¶
Eine frische Installation hat keine Konten und braucht auch keines: Der UNIX-Socket plus SO_PEERCRED funktioniert für einen lokalen Administrator immer. Von dort aus
# curl --unix-socket /run/pepsi/admin.sock -X POST \
-H 'Content-Type: application/json' \
-d '{"login":"alice","password":"…","scopes":["queue:read","queue:write"]}' \
http://localhost/api/v1/accounts
legt das erste entfernte Konto an. Ein Konsolenpasswort muss mindestens zwölf Zeichen lang sein, darf nicht auf der Liste gängiger Passwörter stehen, die Pepsi mitliefert (ohne Beachtung der Groß-/Kleinschreibung verglichen), und darf den Kontonamen nicht enthalten; POST /api/v1/accounts und ein PATCH, das ein Passwort setzt, beantworten alles andere mit 400. Ein verlorenes Passwort sperrt nicht aus: Der lokale Socket ist weiterhin da.
Wenn der Socket nicht erreichbar ist (ein Betreiber, der von einer anderen Maschine arbeitet, oder ein Container ohne Shell auf dem Host), gibt pepsi-setup bootstrap, als root ausgeführt, ein Bearer-Token aus, das die volle Menge an Administrator-Geltungsbereichen hält, binnen einer Stunde abläuft und genau einmal angenommen wird: genug für ein POST /api/v1/accounts.
Es muss diese Menge halten statt setup:write allein, denn POST /api/v1/accounts weigert sich, einen Geltungsbereich auszustellen, den der Aufrufer nicht selbst hält. Ein Token mit nur setup:write könnte also überhaupt keinen Administrator erzeugen, und ein von ihm erzeugtes Konto könnte sich hinterher auch nicht selbst erweitern. Was das Credential begrenzt, sind seine Lebensdauer, seine einmalige Verwendung und dass das nächste pepsi-setup bootstrap es widerruft.
Das Token ist einmalig wegen des Ortes, an dem es ausgegeben wird. Ein Token auf einem Terminal steckt in einem Scrollback-Puffer, und ein Token im Journal ist für jeden lesbar, der das Journal lesen kann, was gewöhnlich ein weiterer Kreis von Leuten ist als „darf den Mailserver verwalten“. Es wird bei Vorlage durch eine Aktualisierung verbraucht, die nur eine konkurrierende Anfrage gewinnen kann, sodass ein Token, das zwei Personen gelesen haben, nur eine von ihnen einlässt. Es gibt kein Standardkonto und kein Standardpasswort, dessen Änderung man vergessen könnte (siehe Standardpasswörter und fehlende Anwendungsgeheimnisse). Nur sein Digest wird gespeichert, sodass es nicht wiederhergestellt werden kann; führen Sie den Befehl erneut aus, was zugleich den vorherigen widerruft.
24.21. Die Browser-Konsole¶
Die Verwaltungskonsole ist ein Client dieser API, unter /ui auf denselben ADMIN = yes-Listenern eingehängt, und teilt ihre Authentifizierung, ihre Geltungsbereiche und ihr Prüfprotokoll. Sie fügt keine Fähigkeit hinzu: Alles, was sie tut, ist hier mit curl erreichbar. Zwei Details des Sitzungsmechanismus existieren ihretwegen und sind beim Schreiben eines anderen Clients von Bedeutung:
POST /api/v1/auth/loginliefert das CSRF-Token im Antwort-Body zurück und setzt es alspepsi_csrf-Cookie (HttpOnly,SameSite=Strict; mit dem Namen__Host-pepsi_csrf, wann immer das Sitzungs-Cookie dieses Präfix trägt). Ein Programm liest den Body; die Konsole hat keinen anderen Weg, das Token in ein Formular zu bekommen, denn ihre Seiten enthalten kein Skript, das eines aus der Seite auslesen könnte. Keine der beiden Platzierungen ist die Prüfung: Die Prüfung ist, dass der Digest dessen, was eine verändernde Anfrage vorlegt, dem mit der Sitzung gespeicherten gleicht.Eine verändernde Anfrage darf das Token im
X-Pepsi-Csrf-Header vorlegen (was ein Programm tut) oder als_csrf-Formularfeld (was ein HTML-Formular tut). Ein Bearer-Token und ein UNIX-Socket-Peer werden nach keinem von beiden gefragt, da ein Browser sie nie im Auftrag eines anderen sendet.