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, und

  • eine 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.3. Autorisierung: Geltungsbereiche

Jeder Endpunkt deklariert den Geltungsbereich, den er verlangt, in derselben Tabelle, aus der die Dispatch-Tabelle und das OpenAPI-Dokument erzeugt werden. Was dieses Handbuch verspricht und was der Server durchsetzt, kann also nicht auseinandergehen.

Geltungsbereich

Gewährt

config:read

Die effektive Konfiguration und ihre Herkunft lesen (Geheimnisse maskiert).

config:write

Die Konfigurations-Überlagerung ändern.

keys:read

Lokale Identitäten, Korrespondentenschlüssel und Vertrauensanker lesen.

keys:write

Lokale Identitäten ändern und Vertrauensanker entfernen.

peers:write

Den Schlüssel eines Korrespondenten importieren, eine Entdeckungsabfrage in die Warteschlange stellen oder einen zwischengespeicherten Schlüssel vergessen.

queue:read

Die Gesundheitszusammenfassung und die Nachrichtenwarteschlange lesen.

queue:write

Eine eingereihte Nachricht erneut einreihen, umleiten oder löschen.

logs:read

Das Prüfprotokoll, das Maillog, TLS-Ergebnisse und den DNS-Cache lesen.

setup:write

Konten und Token verwalten und das Online-Setup steuern.

secure:read

Secure-Link-Metadaten lesen: für wen eine gespeicherte Nachricht ist, wann sie gelesen wurde, wie oft die PIN falsch eingegeben wurde. Nie ihren Inhalt.

secure:write

Eine Secure-Link-Nachricht widerrufen und damit die einzige Kopie von ihr zerstören.

own:<address>

Autorität über genau eine E-Mail-Adresse.

Ein lokaler Administrator hält jeden Geltungsbereich außer own:. Ein Prinzipal kann nie ein Credential prägen, das mächtiger ist als er selbst: Ein Konto oder ein Token mit einem Geltungsbereich zu erzeugen, den der Aufrufer nicht hält, wird mit scope_escalation abgelehnt.

24.3.1. Der Geltungsbereich own:<address>

own:<address> verengt die Autorität auf eine einzige Adresse. Ein Endbenutzer erhält einen solchen Prinzipal per E-Mail: Ein an die Adresse geschickter Einmal-Link öffnet eine Browser-Sitzung, die genau own:<address> hält (siehe Anmelden per E-Mail). Ein Administrator kann einen solchen Prinzipal auch als Token oder als Konto mit diesem Geltungsbereich erzeugen. Der Geltungsbereich ist auf jedem Endpunkt, der eine Adresse entgegennimmt, definiert und durchgesetzt, denn ein Autorisierungsmodell nachträglich auf Endpunkte aufzusetzen, die ohne eines geschrieben wurden, ist die teure Hälfte der Arbeit.

Ein Prinzipal, der nur own:-Geltungsbereiche hält, darf seine eigenen Identitäten und Korrespondentenschlüssel lesen (eine ungefilterte Auflistung wird auf seine Adresse verengt statt abgelehnt, und eine unbekannte Adresse ergibt eine leere Seite, niemals alle Datensätze; siehe Portale und APIs legen Benutzerdaten oder Schlüsselmaterial ohne Authentifizierung offen) sowie seine eigenen Datensätze des Maillogs (dort muss er ?address= mit seiner eigenen Adresse angeben). Er darf die von niemand anderem lesen, darf die installationsweiten Objekte (den Korrespondentenschlüssel-Cache, die Vertrauensanker) nicht anfassen und darf die Konfiguration weder lesen noch schreiben. Ein Administrator kann eine Adresse delegieren, indem er ein solches Token ausstellt; ein Token, das nur Zugangsdaten erzeugen kann, kann keine Adressautorität herbeizaubern, die es selbst nicht hält.

Er darf außerdem seine eigenen Schlüssel verwalten (die Selbstbedienung im Stil von pEp; siehe Schlüsselverwaltung): einen servergeführten Schlüssel anfordern (POST /api/v1/identities), den eigenen öffentlichen Schlüssel des Benutzers registrieren (POST /api/v1/identities/client) und mit PATCH /api/v1/identities/{id} die Flags seiner eigenen Identität ändern, einschließlich einer Anforderung zum Hochladen auf einen Schlüsselserver und ihres Widerrufs. Jeder dieser Aufrufe prüft die Adresse erneut, und jeder stellt nur eine Aufgabe in die Warteschlange (die beiden POST-Routen, ein widerrufendes PATCH und, für einen solchen Prinzipal, jedes Flags ändernde PATCH), die der Applier noch einmal gegen den own:-Geltungsbereich des Prinzipals und seinen zweiten Faktor prüft. Das Löschen des Datensatzes einer Identität bleibt keys:write vorbehalten.

Er darf die vom Greylisting zurückgestellte Mail an seine Adresse lesen (GET /api/v1/greylist/triplets, auf seine Adresse verengt; ein anderes ?rcpt= wird abgelehnt) und einen Absender auf seine eigene weiße Liste setzen (POST /api/v1/greylist/allow-sender). Dieser Schreibvorgang erfolgt sofort, statt eingereiht zu werden: Die SQL-Funktion dahinter nimmt eine einzige wörtliche Adresse entgegen und lehnt jede weiße Liste außer der eigenen eines Benutzers ab (siehe Greylisting). Die Zähler und die Regeln des Greylistings bleiben beim Betreiber.

Er darf die von ihm eingereihten Aufgaben bis zu ihrem Ende verfolgen: GET /api/v1/setup/tasks/{id} antwortet für eine Aufgabe, die dieser Prinzipal selbst eingereiht hat, und GET /api/v1/setup/tasks listet genau diese auf (siehe Einer Aufgabe folgen). Alles andere auf der Setup-Oberfläche bleibt setup:write.

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"}}
    

    code ist ein stabiles Token, auf das man verzweigen kann; hint ist Prosa für einen Menschen und kann sich ändern; detail trä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 total gelten

GET /api/v1/queue

?stage= ?status=

GET /api/v1/events

?kind= (Präfix) ?actor=

GET /api/v1/mail-log

?address=

GET /api/v1/secure-messages

?include_expired=

GET /api/v1/greylist/triplets

?state= ?domain= ?ip= ?rcpt= (für einen own:-Prinzipal auf die Adresse des Aufrufers verengt)

GET /api/v1/quarantine

—

GET /api/v1/identities

?address= ?protocol=

GET /api/v1/peers

?address=

GET /api/v1/peers/unclaimed

?address=

GET /api/v1/ca-trust

—

GET /api/v1/accounts

—

GET /api/v1/tokens

—

GET /api/v1/setup/tasks

— (ohne setup:write auf die eigenen Aufgaben des Aufrufers verengt)

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 total zu 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

POST

/api/v1/auth/login

—

Liefert ein Sitzungs-Cookie und ein CSRF-Token zurück.

POST

/api/v1/auth/login/second-factor

—

Der zweite Schritt einer Anmeldung, die mit second_factor_required beantwortet wurde.

GET

/api/v1/auth/webauthn

—

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.

POST

/api/v1/auth/logout

—

Idempotent.

GET

/api/v1/auth/whoami

—

Das Erste, was zu prüfen ist, wenn etwas mit 403 antwortet.

GET POST

/api/v1/accounts

setup:write

Passwort-Hashes werden nie zurückgegeben.

PATCH DELETE

/api/v1/accounts/{id}

setup:write

Ein Konto zu löschen beendet seine Sitzungen.

GET DELETE

/api/v1/accounts/{id}/webauthn

setup:write

Die Sicherheitsschlüssel eines Kontos; DELETE entfernt sie alle und beendet seine Sitzungen (Wiederherstellung nach einem verlorenen Schlüssel). Im Prüfprotokoll als auth.webauthn.reset erfasst.

GET POST

/api/v1/tokens

setup:write

Das Geheimnis steht in der POST-Antwort und sonst nirgends.

DELETE

/api/v1/tokens/{id}

setup:write

Widerruf.

GET

/api/v1/status

queue:read

Identisch zu pepsi-status --json. ?limit= begrenzt die Liste steckengebliebener Nachrichten; keine Auflistung, daher kein ?offset=.

GET

/api/v1/queue

queue:read

?stage= ?status=

GET

/api/v1/queue/{id}

queue:read

Umschlag, Stage, Status und state. Nie die Nachricht.

POST

/api/v1/queue/{id}/requeue

queue:write

Wieder ausstehend an seiner aktuellen Stage.

POST

/api/v1/queue/{id}/bounce

queue:write

Body {"stage": "<bounce stage>"}.

POST

/api/v1/queue/{id}/cancel

queue:write

Löscht die Nachricht.

GET

/api/v1/events

logs:read

Das Prüfprotokoll. ?kind= (Präfix) ?actor=

GET

/api/v1/mail-log

logs:read

?address= Leer, sofern [pepsi] MAIL_LOG nicht an ist; meldet den Modus.

GET

/api/v1/tls-sessions

logs:read

?days=

GET

/api/v1/dns-cache

logs:read

MX-Adressen, die derzeit scheitern.

GET

/api/v1/dmarc-reports

logs:read

?days= ?limit= Die über die bedienten Domains empfangenen DMARC-Aggregatberichte: Urteile je Domain und Quellen.

GET

/api/v1/greylist

logs:read

?hours= (24) — die Greylisting-Entscheidungen nach Ergebnis und Grund. Siehe Greylisting.

GET

/api/v1/greylist/triplets

logs:read oder own:<address>

Die Tripel aus Absender, Empfänger und Client, neueste zuerst.

GET POST

/api/v1/greylist/rules

logs:read; config:write zum Hinzufügen

Die nicht abgelaufenen Regeln; eine hinzufügen oder erneuern.

DELETE

/api/v1/greylist/rules/{id}

config:write

Eine Regel entfernen.

POST

/api/v1/greylist/allow-sender

config:write oder own:<address>

Einen Absender auf die eigene weiße Liste einer Adresse setzen (keine Regel).

GET

/api/v1/quarantine

queue:read

Die Nachrichten in den Quarantäne-Stages. Siehe Quarantäne.

GET

/api/v1/quarantine/{token}

queue:read

Eine zurückgehaltene Nachricht: Umschlag und Quarantäne-Eintrag, nie ihr Inhalt.

POST

/api/v1/quarantine/{token}/release

queue:write

Eine zurückgehaltene Nachricht an ihre RELEASE_STAGE weiterschicken.

POST

/api/v1/quarantine/{token}/delete

queue:write

Eine Nachricht in einer Quarantäne-Stage löschen, ohne sie zuzustellen.

GET

/api/v1/config

config:read

?scope= Effektive Werte mit Herkunft; Geheimnisse maskiert.

GET

/api/v1/config/{section}

config:read

Ein Abschnitt.

PUT DELETE

/api/v1/config/{section}/{option}

config:write

Vor dem Speichern validiert. Siehe unten.

POST

/api/v1/config/validate

config:read

Trockenlauf; antwortet in beiden Fällen mit 200 und einem Urteil.

GET

/api/v1/identities

keys:read

?address= ?protocol=

GET PATCH DELETE

/api/v1/identities/{id}

keys:read / keys:write

PATCH setzt is_primary (true), published, vks_wanted (sofort mit keys:write; unter own:<address> wird eine set-identity-flags-Aufgabe eingereiht, und es antwortet mit 202); oder, für sich allein, status (nur revoked, mit einem optionalen revocation_reason), was eine revoke-identity-Aufgabe in die Warteschlange stellt. Siehe unten. GET und PATCH stehen own:<address> für diese Adresse offen; DELETE nicht.

GET

/api/v1/identities/{id}/public

keys:read

Die öffentliche Hälfte, base64.

POST

/api/v1/identities/{id}/csr

keys:write oder own:<address>

Eine identity-csr-Aufgabe in die Warteschlange stellen: {"display_name": ...} (optional). Die PKCS#10-Anforderung erscheint im result.csr_pem der Aufgabe. Nur S/MIME-Identitäten mit privater Hälfte. Siehe unten.

POST

/api/v1/identities/{id}/certificate

keys:write oder own:<address>

Eine identity-certificate-Aufgabe in die Warteschlange stellen: {"certificate": "<PEM or base64 DER>"}, höchstens 64 KiB. Siehe unten.

POST

/api/v1/identities

keys:write oder own:<address>

Eine generate-identity-Aufgabe in die Warteschlange stellen: {"address": ..., "vks": true|false}. Siehe unten.

POST

/api/v1/identities/client

keys:write oder own:<address>

Eine register-client-key-Aufgabe in die Warteschlange stellen: {"address": ..., "key": "<armoured public key>"}. Siehe unten.

DELETE

/api/v1/otp/{address}

keys:write

Eine reset-otp-Aufgabe in die Warteschlange stellen, die den zweiten Faktor der Adresse entfernt (und sie damit entsperrt). Siehe unten.

DELETE

/api/v1/webauthn/{address}

keys:write

Jeden Sicherheitsschlüssel des Endbenutzers entfernen, der sich mit dieser Adresse anmeldet (darf nie von einem own:-Prinzipal angefordert werden).

DELETE

/api/v1/webauthn/members/{address}

setup:write

Jeden Sicherheitsschlüssel des Listenmitgliedskontos entfernen, das sich mit dieser verifizierten Adresse anmeldet.

GET

/api/v1/peers

keys:read

?address=

POST

/api/v1/peers

peers:write

Den Schlüssel eines Korrespondenten von Hand importieren. Siehe unten.

POST

/api/v1/peers/discover

peers:write

Reiht eine Entdeckungsabfrage ein; es holt nicht ab. Siehe unten.

DELETE

/api/v1/peers/{id}

peers:write

Einen zwischengespeicherten Schlüssel vergessen.

POST

/api/v1/peers/{id}/recheck

peers:write

Einen zwischengespeicherten Schlüssel ablaufen lassen und eine neue Suche nach seiner Adresse in die Warteschlange stellen. Siehe unten.

GET

/api/v1/peers/unclaimed

keys:read

?address= — bediente Adressen, für die wir keine Identität halten, für die aber dennoch ein Schlüssel zwischengespeichert ist. Eine paginierte Auflistung.

GET

/api/v1/keys/dkim

keys:read

Der öffentliche Status des DKIM-Signier-Daemons. Rotieren mit einer dkim-rotate-Setup-Aufgabe. Siehe unten.

GET

/api/v1/ca-trust

keys:read

Die S/MIME-Vertrauensanker.

POST

/api/v1/ca-trust

keys:write

Einen Vertrauensanker hinzufügen: {"certificate": "<PEM or base64 DER>", "label": ...}. Nur ein CA-Zertifikat. Ändert, welche eingehenden Signaturen gültig sind. Siehe unten.

DELETE

/api/v1/ca-trust/{id}

keys:write

Ändert, welche eingehenden Signaturen validieren.

PUT

/api/v1/ca-trust/{id}/scope

keys:write

Den Geltungsbereich des Ankers setzen oder aufheben: {"permitted_domains": ["example.org", ...]} oder null. Ändert, welche eingehenden Signaturen gültig sind. Siehe unten.

GET

/api/v1/mpki/domains

keys:read

Die Managed-PKI-Domains und ihre Einstellungen. Siehe Managed PKI.

GET

/api/v1/mpki/domains/{domain}

keys:read

Die Einstellungen einer Domain.

PATCH

/api/v1/mpki/domains/{domain}

keys:write

Legt die Einstellungen einer Domain an oder ändert sie. Entscheidet, was die CA der Organisation in Rechnung stellt.

GET

/api/v1/mpki/users

keys:read

?domain= ?deleted=1 — die Benutzer, jeder mit seinen neuesten Bestellungen.

POST

/api/v1/mpki/users

keys:write

Fügt einen Benutzer unter einem Namen hinzu, für den der Aufrufer bürgt.

PATCH

/api/v1/mpki/users/{address}

keys:write

Korrigiert den Namen eines Benutzers oder gibt ihn frei, wählt den Benutzer aus oder wählt ihn ab.

DELETE

/api/v1/mpki/users/{address}

keys:write

Löscht einen Benutzer; seine Zertifikate werden widerrufen.

GET

/api/v1/mpki/orders

keys:read

?domain= ?address= ?open=1 ?limit= — die bei der CA aufgegebenen Bestellungen, die neuesten zuerst.

GET

/api/v1/mpki/notices

keys:read

?unread=1 ?limit= — die Hinweise für Administratoren, mit der Zahl der ungelesenen.

POST

/api/v1/mpki/notices/read

keys:write

Markiert Hinweise als gelesen, für jeden Administrator.

GET

/api/v1/secure-messages

secure:read

Ausstehende Secure-Link-Nachrichten, nur Metadaten. ?include_expired=1.

GET

/api/v1/secure-messages/{token}

secure:read

Eine Nachricht mit ihrer Zugriffshistorie. Nie ihr Inhalt.

DELETE

/api/v1/secure-messages/{token}

secure:write

Widerrufen; das zerstört die einzige Kopie der Nachricht.

GET

/api/v1/dns-records

config:read

Die zu veröffentlichenden Einträge und das letzte Live-Urteil. Siehe unten.

GET

/api/v1/setup/questions

setup:write

Das Setup-Interview als Daten.

GET

/api/v1/setup/telemetry

setup:write

Ob das Einschalten der Funktionstelemetrie wirksam werden könnte und, falls nicht, was auf dem Server zu tun ist. Siehe unten.

GET

/api/v1/setup/answers

setup:write

Die vorgemerkten Antworten; Zugangsdaten maskiert.

PUT

/api/v1/setup/answers

setup:write

Antworten in die vorgemerkte (Entwurfs-)Menge einmischen.

DELETE

/api/v1/setup/answers

setup:write

Das vorgemerkte Interview verwerfen.

GET

/api/v1/setup/tasks

setup:write oder ein beliebiger Prinzipal für seine eigenen Aufgaben

Privilegierte Einrichtungsaufgaben, neueste zuerst; ohne setup:write nur die eigenen des Aufrufers.

POST

/api/v1/setup/tasks

setup:write

Den Applier um eine Aktion aus seiner geschlossenen Menge bitten.

GET

/api/v1/setup/tasks/{id}

setup:write oder ein beliebiger Prinzipal für seine eigenen Aufgaben

Eine Aufgabe, mit ?since=, das ihren Fortschritt streamt, und ?wait=, das die Antwort zurückhält, bis es Neuigkeiten gibt.

POST

/api/v1/setup/preflight

setup:write

Die Umgebung prüfen (Ports, Resolver-DNSSEC).

POST

/api/v1/setup/dns-check

setup:write

Live-DNS mit dem vergleichen, was das Setup veröffentlichen würde.

POST

/api/v1/setup/certificates

setup:write

Die von der Konfiguration benötigten Zertifikate beziehen.

GET

/api/v1/openapi.json

—

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}/csr reiht identity-csr ein ({"display_name": ...}, optional, höchstens 128 Byte: der CN des 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 als pepsi-crypto und hält sie im Ergebnis der Aufgabe als csr_pem fest; der anfragende Prinzipal liest sie aus GET /api/v1/setup/tasks/{id} (oder auf der Aufgabenseite der Konsole, die das PEM für sich anzeigt).

  • POST /api/v1/identities/{id}/certificate reiht identity-certificate ein ({"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 seinem rfc822Name nennt, das ein CA-Zertifikat ist, dem emailProtection oder 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ält key.identity.certificate fest. 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 ihrem binding-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_limit und notify_address. null bedeutet bei organization_id die einzige Organisation des Kontos und bei notify_address keine Mail. Die Antwort ist die Domain, wie sie gespeichert ist. Im Prüfprotokoll als mpki.domain.set erfasst.

  • POST /api/v1/mpki/users nimmt {"address": ..., "given_name": ..., "surname": ..., "selection": ...} entgegen; beide Namen sind Pflicht, da der Aufrufer für sie bürgt, und selection (default, yes oder no) ist optional. Es holt auch einen gelöschten Benutzer zurück. Im Prüfprotokoll als mpki.user.add erfasst.

  • PATCH /api/v1/mpki/users/{address} nimmt given_name und surname zusammen entgegen (ein neuer Name, der damit bestätigt ist), confirm_name: true (der Name, wie er ist) und selection; "selection": "no" wählt den Benutzer ab und widerruft seine Zertifikate. DELETE löscht den Benutzer und widerruft seine Zertifikate ebenfalls. Ein Benutzer, der nicht existiert oder gelöscht wurde, ergibt 404. Im Prüfprotokoll als mpki.user.set und mpki.user.delete erfasst, mit warning, wenn Zertifikate widerrufen werden.

  • GET /api/v1/mpki/users listet jeden Benutzer mit wanted (ob die Einstellungen ihm ein Zertifikat geben), hold_reason (warum eine Bestellung für ihn warten würde) und seinen fünf neuesten orders auf.

  • GET /api/v1/mpki/orders gibt nie den verpackten Schlüssel einer Bestellung zurück, den pepsi-httpd nicht lesen kann; has_key sagt, ob die Bestellung einen hat.

  • POST /api/v1/mpki/notices/read nimmt {"ids": [...]} oder {"all": true} entgegen; fehlt beides, ergibt das 422. Es antwortet mit {"marked": N} und wird im Prüfprotokoll als mpki.notice.read erfasst.

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/greylist antwortet 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_retried zä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-status tut das.

  • GET /api/v1/greylist/triplets nimmt ?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, wie pepsi-greylist list; ein fehlerhaftes state oder ip ergibt ein 400.

  • POST /api/v1/greylist/rules nimmt {"action": "allow"|"deny", "kind": "ip"|"network"|"domain"|"sender"|"rcpt", "value": ..., "note": ..., "expires_in": "90 days"} entgegen; note und expires_in sind optional. Die Regel wird von greylist_rule_add geschrieben, das den Wert normalisiert und einen fehlerhaften ablehnt (422 mit seinem Satz); dieselbe Aktion, dieselbe Art und derselbe Wert erneuern eine Regel. Es antwortet mit {"rule_id": N}. Die Regel hält origin = console und die Identität des Aufrufers fest. DELETE /api/v1/greylist/rules/{id} entfernt eine über greylist_rule_remove. Im Prüfprotokoll als greylist.rule.added und greylist.rule.removed erfasst, wie auf der Kommandozeile.

  • POST /api/v1/greylist/allow-sender nimmt {"sender": ..., "address": ...} entgegen. Ein own:-Prinzipal lässt address weg (oder nennt seine eigene); config:write nennt 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, die WHITELIST_BYPASS des Daemons für diesen Empfänger befragt. Der Datensatz ist der, den pepsi-whitelist add für eine Adresse schreibt (ein verankertes Literal, das gegen From: 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 Antwort 409 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"} (added ist false, wenn der Absender bereits dort stand) und wird im Prüfprotokoll als whitelist.sender.added erfasst.

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}/release gibt eine zurückgehaltene Nachricht als pending an ihre Quarantäne-Stage zurück, die sie an ihre RELEASE_STAGE weiterschickt. Es verwendet nicht workqueue_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 ein 404.

  • POST /api/v1/quarantine/{token}/delete löscht die Nachricht, sofern kein Worker sie hat (409), und hält die Löschung im optionalen Maillog fest, wie es pepsi-queue quarantine delete tut.

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.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.16.2. Wenn es keinen Applier gibt: 503 setup_applier_unavailable

Die privilegierte Hälfte ist ein eigenes Debian-Paket, pepsi-httpd-admin, das nur pepsi-setup-apply.socket und pepsi-setup-apply.service enthält; diese beiden bilden den gesamten Weg von einer HTTP-Anfrage zu einer Änderung unterhalb von /etc/pepsi. Das Paket pepsi empfiehlt es, es wird also standardmäßig installiert und ist entfernbar; eine Quellinstallation erhält denselben Hebel mit make install INSTALL_ADMIN_UNITS=no. Es zu entfernen durchtrennt den Kreis am Mechanismus: Nichts leert setup_task, ein INSERT bleibt also wirkungslos.

pepsi-httpd erkennt das und stuft sich auf Nur-Lesen zurück, statt Anfragen einzureihen, die niemals jemand ausführt. Jeder Endpunkt, der den Applier bitten würde, antwortet mit 503, dem code setup_applier_unavailable und einem detail, das Paket und Unit benennt, sodass ein Deployment-Skript keine Prosa parsen muss:

{"code": "setup_applier_unavailable",
 "hint": "the administrative package 'pepsi-httpd-admin' is not installed …",
 "detail": {"package": "pepsi-httpd-admin", "unit": "pepsi-setup-apply.socket"}}

Welche Endpunkte davon abhängig sind, ist der interessante Teil:

Endpunkt

Von einem Applier abhängig?

PUT /api/v1/setup/answers

Ja. Ein Entwurfsdatensatz ist für sich genommen harmlos, aber der einzige Zweck eines Antwortsatzes ist es, angewendet zu werden; ein Assistent, der auf einem Host, auf dem nichts sie anwenden kann, klammheimlich sechs Schritte an Antworten speichert, ist genau der stille Leerlauf, den die Paketaufteilung vermeiden soll.

DELETE /api/v1/setup/answers

Nein, absichtlich. Einen Entwurf zu verwerfen kann keine privilegierte Änderung auslösen, und ein festgefahrenes Interview muss löschbar bleiben.

GET /api/v1/setup/questions, GET /api/v1/setup/answers, GET /api/v1/setup/tasks, GET /api/v1/setup/tasks/{id}, GET /api/v1/dns-records

Nein. Sie lesen. (Ein wait auf eine Aufgabe, die nie jemand abarbeiten wird, läuft einfach ab.)

POST /api/v1/setup/tasks, POST /api/v1/setup/preflight, POST /api/v1/setup/dns-check, POST /api/v1/setup/certificates, POST /api/v1/identities, POST /api/v1/identities/client, PATCH /api/v1/identities/{id} mit "status": "revoked", ein Flags änderndes PATCH eines Eigentümers, POST /api/v1/identities/{id}/csr, POST /api/v1/identities/{id}/certificate, DELETE /api/v1/otp/{address}

Ja — jeder von ihnen erreicht das einzige ask_applier, das require_applier aufruft, bevor es irgendetwas schreibt. (Ein PATCH eines Betreibers, das nur is_primary, published oder vks_wanted umschaltet, tut das nicht.)

PUT/DELETE /api/v1/config/{section}/{option}

Nein. Die Konfigurations-Überlagerung schreibt nach pepsi.config_override, eine Datenbanktabelle, nicht nach /etc. Sie funktionieren auch ohne Applier weiter.

503 statt 501: Die Fähigkeit ist nur ein Paket entfernt, es handelt sich also um eine Einrichtung, die hier und jetzt nicht vorhanden ist, nicht um eine Operation, die die API nicht besitzt. Es ist außerdem ein anderer Code als das obige setup_write_unavailable, weil die Abhilfen sich unterscheiden: „pepsi-httpd-admin installieren und dessen Socket starten“ im einen Fall, „diesem Server eine CONFIG_DB-Verbindung geben“ im anderen.

Die Erkennung besteht aus zwei Dateisystemtests, beide erforderlich und keiner überflüssig: Die Unit-Datei liegt irgendwo, wo systemd sucht (installiert), und [pepsi-admin] APPLY_SOCKET (Standardwert /run/pepsi/setup-apply.sock) ist ein Socket, den dieses Konto beschreiben darf (scharfgeschaltet). Es wird nie verbunden, denn das Verbinden ist das Klingeln an der Tür und würde je Seitenaufbau einen root-Prozess starten. Die Hälfte mit der Unit-Datei gibt es, weil RemoveOnStop= in systemd standardmäßig aus ist, sodass ein veralteter Socket-Inode sonst als lebendige Türklingel gelesen würde und ausgerechnet in dem Szenario, für das es die Funktion gibt, offen fehlschlüge; die ausgelieferte Unit setzt zusätzlich RemoveOnStop=yes. Jede Ungewissheit wird als „nicht verfügbar“ gelesen. [pepsi-admin] APPLIER = auto|yes|no übersteuert die Prüfung für einen cron-gesteuerten oder nicht von systemd verwalteten Applier, und no schaltet das privilegierte Setup rundweg ab.

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 mit 429 beantwortet werden, bis das Kontingent sich wieder auffüllt. „Quelladresse“ ist die des Clients, aus X-Forwarded-For genommen, 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 429 beantwortet, 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) und MAX_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": true ersetzt. 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, der config:read hält.

  • Kein Nachrichteninhalt ist erreichbar. Die Warteschlangenendpunkte antworten mit dem Umschlag, der Stage, dem Status und dem state-JSON, nie mit headers oder body. Mail zu lesen ist keine administrative Funktion.

  • Antworten tragen Cache-Control: no-store, X-Content-Type-Options: nosniff und eine frame-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:

off

Der Standardwert. Nichts wird geschrieben; pepsi.mail_log bleibt leer.

summary

Ein Datensatz, wenn die Nachricht die Pipeline verlässt: der Umschlagabsender und die Empfänger, die Richtung (outbound für lokal eingelieferte Mail, sonst inbound), 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).

full

Das 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/login liefert das CSRF-Token im Antwort-Body zurück und setzt es als pepsi_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.