95.1.8. pepsi-stage-dkim-sign¶
DKIM-sign a message in the Pepsi pipeline
- Handbuchabschnitt:
1
95.1.8.1.1. Name¶
pepsi-stage-dkim-sign - DKIM-Signier-Stage der Pepsi-Pipeline.
95.1.8.1.2. Übersicht¶
pepsi-stage-dkim-sign [GLOBAL-OPTIONS] worker
95.1.8.1.3. Beschreibung¶
pepsi-stage-dkim-sign ist ein Stage-Programm, das von pepsi-dispatch(1) als persistenter Worker ausgeführt wird, der Nachrichten-IDs von der Standardeingabe liest. Es stellt den Rohbytes der Nachricht einen DKIM-Signature-Header je Algorithmus in [pepsi] DKIM_ALGORITHMS voran (standardmäßig zwei: einen RSA, einen Ed25519) und schaltet den Datensatz zu seiner NEXT_STAGE (einer Zustell-Stage) weiter. Signieren stellt nur Header-Zeilen voran, sodass bestehende Signaturen weiter unten in der Nachricht ungestört bleiben. Es fasst den state des Datensatzes nicht an (abgesehen von dem einen unten beschriebenen Flag), sodass alle RFC-3461-Parameter in state.dsn für spätere Stages zur Beachtung erhalten bleiben.
Eine Nachricht, deren Nachrichtentext 8-Bit-Oktette trägt, wird zuerst in ein 7-Bit-Content-Transfer-Encoding konvertiert (RFC 6376 Abschnitt 5.3): Jeder 8-Bit-MIME-Blattteil wird als Quoted-Printable (text/*) oder Base64 neu kodiert, und ein Nicht-ASCII-Parameter im eigenen Header eines Teils (der Dateiname eines Anhangs) erhält die Form von RFC 2231. Sonst würde eine Relay-Stage diese Konvertierung nach dem Signieren vornehmen, gegenüber einem nächsten Hop, der kein 8BITMIME ankündigt, und damit die Signatur ungültig machen. Wird der Nachrichtentext vorher konvertiert, findet das Relay nichts mehr zu ändern. Der konvertierte Nachrichtentext wird anstelle des ursprünglichen gespeichert, und state.origin.body_8bit wird gelöscht, damit das Relay nicht mehr BODY=8BITMIME ankündigt. In folgenden Fällen wird die Nachricht stattdessen unverändert signiert: wenn ihr eigener Header-Block Nicht-ASCII-Oktette enthält (sie braucht ohnehin SMTPUTF8); wenn sie bereits eine DKIM-Signature oder ARC-Message-Signature trägt, etwa die Signatur eines Autors auf einer weitergeleiteten Nachricht oder Pepsis eigenes ARC-Siegel, denn beide decken den 8-Bit-Nachrichtentext ab und würden bei jedem Hop brechen; wenn einer ihrer Teile ein multipart/signed ist, dessen OpenPGP- oder S/MIME-Signatur die darunterliegenden kodierten Oktette abdeckt; oder wenn die Konvertierung den Nachrichtentext nicht 7-bittig machen kann (ein zu tief verschachtelter MIME-Baum).
Die signierende Domain (d=) ist SIGNING_DOMAIN, falls konfiguriert, sonst die Domain der ersten Mailbox im From:-Header der Nachricht. Dieser Header wird strikt gelesen: Sofern sich nicht jede Mailbox darin als RFC-5322-Mailbox parsen lässt, gilt die Nachricht als ohne verwendbares From:. Manche Felder lösen Mail-Clients zu verschiedenen Adressen auf (<me@example.org>:<ceo@example.com>, eine zweite <...>-Adresse, Gruppensyntax, ein Encoded-Word innerhalb der Adresse; CERT/CC VU#517845). Ein solches Feld wird nie als die Domain signiert, die ein nachsichtiger Leser wählen würde.
Die Stage hält keinen Schlüssel. Die DKIM-Schlüssel je Domain gehören dem Signier-Daemon pepsi-dkim(1), der unter einem eigenen Konto läuft. Die Stage berechnet den Body-Hash, baut das DKIM-Signature-Feld (eines je Algorithmus von [pepsi] DKIM_ALGORITHMS, mit den Selektoren, die der Daemon als aktuell nennt) und sendet den kanonisierten Header-Block an den Socket des Daemons ([pepsi-dkim] SOCKET, Standardwert /run/pepsi-dkim/sign.sock). Der Daemon prüft den Block gegen seine Richtlinie und gibt die Signatur zurück. Er signiert nur für eine Domain, die er bedient, und eine DKIM-Signatur nur, wenn jede Mailbox des From: zur Organisation der d=-Domain gehört und h= From nennt. Findet zwischen der Wahl eines Selektors und dem Signieren ein Schlüsselwechsel statt, fragt die Stage noch einmal nach den aktuellen Selektoren.
Diese Stage existiert, damit der Bau der Nachricht und das DKIM-Signieren getrennte Schritte sind. Insbesondere baut pepsi-stage-bounce(1) eine unsignierte DSN und richtet ihr NEXT_STAGE hierher, sodass ein erzeugter Bounce vor der Zustellung als die Domain seines Postmasters signiert wird.
Eine Nachricht, die von außen eintraf, wird unsigniert weitergeschaltet, wenn eine Domain ihres From: mit der signierenden Domain ausgerichtet ist (dieselbe Domain, eine Eltern- oder Subdomain davon oder eine, die ihre letzten beiden Labels teilt) und der Ingress sie weder per DMARC (state.auth.dmarc) noch per mit dem From: ausgerichteter DKIM-Signatur (state.auth.dkim) authentifiziert hat. Unsere Signatur wäre genau die ausgerichtete, nach der DMARC sucht. Würde die Stage eine solche Nachricht signieren, bestünde eine Fälschung unserer eigenen Domain beim nächsten Hop DMARC. Eine solche Fälschung kann von irgendwoher empfangen und weitergeleitet werden (durch einen Alias, der außerhalb der Site expandiert, ein ~/.forward oder den Relay-Signierer, den SIGN_RELAYED des Assistenten einfügt). Die Nachricht geht hinaus, wie jeder Weiterleiter ohne unseren Schlüssel sie senden würde, und die Entscheidung wird protokolliert. Ein From:, das sich nicht strikt lesen lässt, gilt als ausgerichtet. Hier eingelieferte Mail (state.local_origin) wird immer signiert, ebenso Mail, die Pepsi selbst verfasst und die keine Ingress-Urteile trägt: DSNs, automatische Antworten und Benachrichtigungen sowie Mailinglisten-Kopien (die Listensoftware ist ihr Autor und wendet ihre eigene Beitragsrichtlinie an). Mit SIGNING_DOMAIN wird von außen empfangene Mail, deren From: zu einer anderen Organisation gehört (weitergeleitete Mail eines fremden Autors), unsigniert weitergeschaltet: Der Signier-Daemon signiert nur ein mit d= ausgerichtetes From:, und die Nachricht behält die eigenen Signaturen ihres Autors. Hier eingelieferte oder verfasste Mail mit einem solchen From: wird stattdessen mit einer 5.7.1-DSN abgelehnt. Die SPF-Hälfte derselben Regel ist die dedizierte SRS-Domain (siehe pepsi-stage-srs(1)); beide sind unter „Forwarded forgeries of our own domain“ im Sicherheitskapitel des Pepsi-Handbuchs dargelegt.
Der Daemon hält die Schlüssel außerhalb der Reichweite jeder Stage, sodass eine kompromittierte Stage sie nicht kopieren kann. Er kann eine solche Stage aber nicht daran hindern, die Schlüssel zu verwenden: Der Socket antwortet jedem Prozess der Gruppe pepsi, sodass eine DKIM-Signatur nur so stark ist wie die Rolle pepsi. Jede kompromittierte Stage kann, solange sie läuft, Mail einer bedienten Domain signieren lassen und das From: einer eingereihten Nachricht umschreiben, bevor diese Stage sie sieht. Das Kapitel Threat model des Handbuchs hält dies als dokumentiertes Restrisiko fest. Die Stage schützt den Ruf der Domain, nicht eine Vorliebe eines Benutzers, führen Sie sie daher nicht in den EDITABLE_STAGES von pepsi-stage-edit-settings(1) auf.
Abgesehen von diesen bewussten Fällen ist das Signieren fail-closed: Eine Nachricht, die sich nicht signieren lässt, wird nie unsigniert weitergeschaltet. Was stattdessen geschieht, hängt davon ab, wessen Schuld es ist:
Die Nachricht hat
dkim-signfür eine Domain erreicht, für die hier niemand signiert: Es lässt sich keine signierende Domain bestimmen (keinSIGNING_DOMAINund kein verwendbarerFrom:-Header), pepsi-dkim(1) antwortet, dass es nicht für die Domain signiert, oder mitSIGNING_DOMAINgehört dasFrom:nicht zur Organisation dieser Domain (was der Daemon bei jeder Wiederholung ablehnen würde). Mit einer BOUNCE_STAGE wird die Nachricht zuerst in einen Datensatz je Empfänger aufgeteilt, damit dasNOTIFYjedes Empfängers beachtet wird, und dann mit einem DSN-Grund instate.bouncedorthin umgeleitet. Der Status ist5.7.1für eine Domain, für die der Daemon nicht signiert, oder einFrom:außerhalb vonSIGNING_DOMAIN, und5.6.0für eine Nachricht ohne verwendbaresFrom:; die Diagnose nennt die Domain. Ohne BOUNCE_STAGE wird die Nachricht in den terminalen Zustandfailedverschoben, mit dem Grund instate.last_error. Eine Null-Absender-Nachricht (selbst eine DSN oder eine automatische Antwort) wird immer fehlschlagen gelassen statt umgeleitet: Für einen Bounce wird nie ein Bounce erzeugt, und als fehlgeschlagener Datensatz bleibt sie für den Betreiber sichtbar.Der Daemon ist nicht erreichbar (
pepsi-dkim.servicegestoppt oder im Neustart) oder lehnt aus einem anderen Grund ab: Schuld ist der Host, nicht die Nachricht. Der Fehler wird erneut versucht (siehe pepsi-dispatch(1)): Die Nachricht bleibt an dieser Stagepaused, mit dem Grund instate.last_error, und wird erneut versucht, nach einer Minute und dann in sich verdoppelnden Abständen bis zu einer Stunde, bis sie länger in der Warteschlange steht als das MAX_LIFETIME der Stage (Standardwert120 h); erst dann wird sie aufgegeben. Sie sofort fehlschlagen zu lassen, würde für jede ausgehende Nachricht einen Bounce erzeugen, und die Bounces, die ebenfalls hier signiert werden, würden dann verworfen, ohne dass jemand davon erfährt.
Der eigene Abschnitt der Stage, [pepsi] und [pepsi-dkim] SOCKET werden beim Start des Workers geprüft: Eine Konfiguration, die sich nicht parsen lässt, lässt den Worker den Start verweigern (Exit 78), und der Dispatcher hält die Warteschlange zurück, bis sie korrigiert ist.
95.1.8.1.3.1. Abdeckung des Nachrichtentexts¶
Die Signatur deckt immer den gesamten Nachrichtentext strikt ab: jede Änderung des Nachrichtentexts während der Übertragung macht sie ungültig. Pepsi gibt das Tag für die Nachrichtentextlänge (l=) aus RFC 6376 nie aus, und es gibt keine Option, das zu tun.
Das Tag existiert, damit eine Signatur eine Mailingliste überlebt, die eine Fußzeile anhängt, doch kein Betreiber kann diesen Tausch sinnvoll eingehen. Pepsis eigener Verifizierer und jede mail-auth-/Stalwart-Installation verwenden den strikten Parser von mail-auth. Dieser weist jede Signatur mit l > 0 rundheraus zurück, statt bloß eine geringere Abdeckung zu dulden. Das Tag macht damit aus einer Signatur, die bestanden hätte, eine, die fehlschlägt. Der Fall, für den es existiert, ist zugleich der Fall, in dem das Umschreiben durch die Liste SPF bereits gebrochen hat, sodass unter einer DMARC-Richtlinie p=reject dieser DKIM-Fehler den Unterschied zwischen zugestellt und abgewiesen ausmacht. RFC 6376 §8.2 warnt gesondert, dass angehängter Inhalt das Original in den Augen des Lesers durch MIME-Umstrukturierung oder laxes HTML-Parsen ersetzen kann und dass „Signierer bei der Verwendung dieses Tags äußerst vorsichtig sein sollten“.
95.1.8.1.3.2. Abdeckung der Header¶
Die von der Signatur abgedeckten Header (das h=-Tag) sind die Liste SIGNED_HEADERS (Standardwert: die üblichen Originator-/MIME-Header). Jeder Header der Standardliste ist doppelt aufgeführt, damit er über-signiert wird (RFC 6376 §8.15). Ein Header, der einmal öfter genannt wird, als er tatsächlich vorkommt, wird ein zusätzliches (leeres) Mal signiert. Stellt ein Angreifer ein zweites From:, To:, Reply-To:, Date:, Content-Type: oder irgendein anderes aufgeführtes Feld voran, erzeugt er daher ein Vorkommen, das die Signatur nicht abdeckt, und die Verifikation schlägt fehl. Jedes dieser Felder kommt in einer wohlgeformten Nachricht höchstens einmal vor, sodass der zweite Eintrag nie ein legitimes Vorkommen unsigniert lässt. Wird in SIGNED_HEADERS ein Header aufgeführt, der in der Nachricht fehlt, wird er ebenso über-signiert (er kann später nicht hinzugefügt werden).
Die Standardliste deckt außerdem List-Unsubscribe und List-Unsubscribe-Post ab, über-signiert wie der Rest. RFC 8058 Abschnitt 4 erlaubt einem Empfänger, eine Abmeldung mit einem Klick nur anzubieten, wenn eine gültige DKIM-Signatur beide Felder abdeckt; andernfalls könnte jeder, der eine Kopie der Nachricht weiterleiten kann, die URI wählen, an die der Empfänger sendet.
95.1.8.1.4. Konfiguration¶
Die Stage wird über ihren eigenen [stage-<name>]-Abschnitt eingebunden und konfiguriert (PROGRAM = pepsi-stage-dkim-sign, eine erforderliche NEXT_STAGE, eine optionale BOUNCE_STAGE für die oben beschriebenen Ablehnungen). pepsi.conf(5) dokumentiert ihre Optionen HEADER_CANONICALIZATION/BODY_CANONICALIZATION (unabhängig voneinander gewählt), SIGNATURE_EXPIRATION_DAYS, SIGNED_HEADERS und SIGNING_DOMAIN zusammen mit den gemeinsamen [pepsi]-Optionen (DKIM_SELECTOR, DKIM_ALGORITHMS). Die Schlüssel, ihre Selektoren und ihre Rotation gehören pepsi-dkim(1). [pepsi-dkim] RETIRE_AFTER_DAYS des Daemons muss SIGNATURE_EXPIRATION_DAYS übersteigen, damit der Eintrag eines Schlüssels jede mit ihm erstellte Signatur überdauert; pepsi-setup validate prüft das. Der Hash ist immer SHA-256; standardmäßig werden sowohl eine RSA- als auch eine Ed25519-Signatur ausgegeben, jede mit einem x=-Ablauf sieben Tage nach dem Signieren (SIGNATURE_EXPIRATION_DAYS, 0 für keinen), sodass eine wieder eingespielte Kopie oder eine mit einem gestohlenen Schlüssel erstellte Signatur nach einer Woche nicht mehr verifiziert.
95.1.8.1.5. State¶
Eingaben: state.local_origin und die Ingress-Urteile state.auth.dmarc und state.auth.dkim, die entscheiden, ob eine Nachricht, deren From: mit der signierenden Domain ausgerichtet ist, signiert wird (siehe oben). Die signierende Domain stammt aus SIGNING_DOMAIN oder der Spalte from_header, der Body-Hash aus der geladenen Nachricht.
Ausgaben: Auf dem Signierpfad wird state.origin.body_8bit gelöscht, wenn der Nachrichtentext nach 7 Bit konvertiert wurde; sonst wird nichts hinzugefügt. Die Signaturen werden der Spalte headers vorangestellt (und der konvertierte Nachrichtentext ersetzt gegebenenfalls body); der Rest von state, einschließlich state.dsn, bleibt unverändert erhalten. Eine abgelehnte Nachricht erhält state.last_error und, wenn umgeleitet, state.bounce; eine wiederholte erhält state.last_error und state.temporary_failures. Das State-Layout wird in pepsi.state(7) beschrieben.
Übergänge: schaltet bei Erfolg zu NEXT_STAGE (der Zustell-Stage) weiter, nachdem es den oder die DKIM-Signature-Header vorangestellt hat. Wenn die Signierdomain nicht bestimmt werden kann oder hier keine Schlüssel hat, wird die Nachricht zu BOUNCE_STAGE umgeleitet (ein Datensatz je Empfänger, state.bounce gesetzt) oder, ohne eine solche oder bei einer Null-Absender-Nachricht, in den terminalen Zustand failed verschoben; wenn ihre Schlüssel nicht verwendet werden können, wird sie bis MAX_LIFETIME zur Wiederholung pausiert (fail-closed; siehe oben). Die Stage schließt nie eine Nachricht ab.
95.1.8.1.6. Befehle¶
Als Worker ausgeführt, signiert das Programm jede Nachricht und schaltet sie weiter.
95.1.8.1.7. Globale Optionen¶
- -c FILE, –config FILE
Liest die Konfiguration aus FILE statt aus dem Standard-Suchpfad.
- -L LOGLEVEL, –log LOGLEVEL
Setzt die Log-Ausführlichkeit (
error,warn,info,debug,trace; Standardwert[pepsi] LOG, sonstinfo).- -h, –help
Gibt eine Verwendungsübersicht aus und beendet sich.
- -V, –version
Gibt die Version aus und beendet sich.
95.1.8.1.8. Exit-Status¶
Das Ergebnis jeder Nachricht wird pepsi-dispatch(1) auf der Statuszeile des Workers gemeldet, nicht als Exit-Status.
- 0
Der Worker lief, bis seine Standardeingabe geschlossen wurde.
- 1
Ein fataler Fehler ist aufgetreten (unlesbare Konfiguration, die Datenbank konnte nicht geöffnet werden, oder Standardein-/-ausgabe schlug fehl). Der Grund wird in das Journal geschrieben.
- 78
Der Worker hat den Start verweigert: Sein Abschnitt oder
[pepsi]lässt sich nicht parsen. Der Dispatcher reiht erneut ein, was er übergeben hatte, und versucht die Stage später wieder.
95.1.8.1.9. Siehe auch¶
pepsi-config(1), pepsi-stage-bounce(1), pepsi-stage-relay-to-internet(1), pepsi-stage-relay-to-smarthost(1), pepsi-dispatch(1), pepsi-ingress(1), pepsi.conf(5), pepsi.state(7), pepsi-setup(1), pepsi-dkim(1)
95.1.8.1.10. Fehler¶
Melden Sie Fehler an den Pepsi-Issue-Tracker.