95.1.9. pepsi-dkim

hold the DKIM and ARC signing keys and sign

Handbuchabschnitt:

1

95.1.9.1.1. Name

pepsi-dkim - der Signier-Daemon, der die privaten DKIM- und ARC-Schlüssel hält, sie rotiert und die DNS-Einträge meldet, die sie brauchen.

95.1.9.1.2. Übersicht

pepsi-dkim [GLOBAL-OPTIONS] serve

pepsi-dkim [GLOBAL-OPTIONS] status [–json]

pepsi-dkim [GLOBAL-OPTIONS] records [DOMAIN]

pepsi-dkim [GLOBAL-OPTIONS] rotate [–hard] [DOMAIN…]

pepsi-dkim [GLOBAL-OPTIONS] sync-domains DOMAIN…

95.1.9.1.3. Beschreibung

pepsi-dkim hält die privaten Schlüssel, mit denen pepsi-stage-dkim-sign(1) und pepsi-stage-arc(1) signieren. Es läuft unter einem eigenen Konto, pepsi-dkim, und hält die Schlüssel in seinem Zustandsverzeichnis (STATE_DIR, Standardwert /var/lib/pepsi-dkim, Modus 0700), wo jeder Schlüssel eine Datei mit Modus 0600 ist. Kein Stage-Worker kann einen Schlüssel lesen. Die Stages hashen den Nachrichtentext und bauen das Signaturfeld selbst. Dann senden sie den kanonisierten Header-Block über einen UNIX-Socket an den Daemon (SOCKET, Standardwert /run/pepsi-dkim/sign.sock, Modus 0660, Gruppe pepsi), und der Daemon signiert ihn und gibt den Signaturwert zurück. Wenn der Daemon nicht erreichbar ist, wiederholen die Stages die Nachricht später; sie senden sie nie unsigniert.

Das schützt die Schlüssel vor Offenlegung. Es beschränkt ihre Verwendung nicht über die unten beschriebene Richtlinie hinaus: Jeder Prozess der Gruppe pepsi kann den Socket um eine Signatur für eine bediente Domain bitten, und jede Pipeline-Stage kann ein eingereihtes From: umschreiben und pepsi-stage-dkim-sign das Ergebnis signieren lassen. Eine kompromittierte Stage kann daher Signaturen erhalten, solange sie läuft, aber keinen Schlüssel mitnehmen.

95.1.9.1.3.1. Schlüssel und Selektoren

Jede signierende Domain hat Schlüssel für die Algorithmen, die [pepsi] DKIM_ALGORITHMS nennt (RSA, Ed25519 oder beide); die [pepsi] ARC_DOMAIN erhält außerdem einen Schlüssel für [pepsi] ARC_ALGORITHM. RSA-Schlüssel haben RSA_BITS Bit und werden von AWS-LC erzeugt. Schlüssel, die zusammen erzeugt werden, bilden eine Generation; ihre Selektoren sind <DKIM_SELECTOR>-YYYYMM für RSA und <DKIM_SELECTOR>-YYYYMM-ed25519 für Ed25519 ([pepsi] DKIM_SELECTOR, Standardwert pepsi, und der Monat, in dem die Generation erzeugt wurde, in UTC). Eine zweite Generation im selben Monat erhält einen Buchstaben nach dem Datum: pepsi-202610b. Jeder Schlüssel hat so einen eigenen Eintragsnamen, <selector>._domainkey.<domain>.

95.1.9.1.3.2. Lebenszyklus

Eine Generation durchläuft vier Zustände:

next

Vor einer Rotation erzeugt; signiert nichts. Ihre Einträge müssen veröffentlicht sein, bevor sie übernehmen darf.

current

Signiert. Eine Domain hat genau eine aktuelle Generation.

retiring

Durch eine neuere Generation ersetzt; signiert nichts, aber ihre Einträge bleiben RETIRE_AFTER_DAYS lang im DNS, sodass die Signaturen, die sie in den Tagen vor dem Wechsel erstellt hat, weiterhin verifizieren.

retired

Die privaten Schlüssel werden gelöscht (oder, mit PUBLISH_RETIRED_KEYS, veröffentlicht, sobald das DNS ihre Einträge nicht mehr ausliefert), und die Einträge dürfen entfernt werden. Die Generation bleibt 90 Tage verzeichnet und wird dann verworfen.

Eine bediente Domain ohne aktuelle Generation (eine frische Installation, eine der Konfiguration hinzugefügte Domain, ein verlorenes oder nicht wiederhergestelltes Zustandsverzeichnis) erhält sofort eine, und diese signiert sofort: Bis ihre Einträge veröffentlicht sind, können Empfänger ihre Signaturen nicht verifizieren. Jede unten beschriebene Schnittstelle meldet die Einträge, die noch ausstehen.

Die Rotation ist aus, sofern ROTATION_DAYS nicht gesetzt ist. Damit wird eine next-Generation ROTATION_LEAD_DAYS vor dem fälligen Wechsel erzeugt. Mit WAIT_FOR_DNS (der Standard) wartet der Wechsel, bis jeder autoritative Server der Zone jeden Eintrag der next-Generation ausliefert; die aktuellen Schlüssel signieren derweil weiter, und die Verzögerung wird gemeldet. rotate verlangt einen Wechsel jetzt, und rotate –hard wechselt, ohne auf das DNS zu schauen. Zehn Minuten nach einem Wechsel signiert der bis dahin aktuelle Selektor noch für die Nachrichten in Bearbeitung; einer Stage, die nach einem älteren Selektor fragt, wird gesagt, nach dem aktuellen zu fragen.

Wird eine Domain aus der Konfiguration entfernt, wird ihre aktuelle Generation auf dieselbe Weise ausgemustert, und eine next-Generation von ihr, die nie signiert hat, wird sofort ausgemustert.

95.1.9.1.3.3. DNS

Alle DNS_CHECK_INTERVAL fragt der Daemon jeden autoritativen Server der Zone nach dem Eintrag jedes Schlüssels, der im DNS sein muss, und stuft ihn als visible (jeder Server liefert ihn mit dem Schlüssel aus), missing (keiner tut es), disagree (einige tun es, einige nicht: ein Sekundärserver, der nicht nachgezogen hat) oder unknown (es ließ sich keine Antwort ermitteln) ein.

Standardmäßig veröffentlicht der Betreiber die Einträge. Mit DNS_UPDATE = rfc2136 fügt der Daemon die Einträge der next- und current-Generationen selbst hinzu und entfernt die der ausgemusterten, per RFC-2136-UPDATE, signiert mit TSIG (RFC 8945), gesendet an DNS_UPDATE_SERVER oder sonst an den primären Server der Zone (das SOA-MNAME). Ein Fehlschlag beim Erreichen des Servers wird beim nächsten Takt wiederholt; eine Ablehnung (ein falscher Schlüssel, eine Zonenrichtlinie, die den Namen verbietet) wird am Schlüssel festgehalten, bis zum Neustart des Daemons nicht wiederholt und dem Postmaster gemailt.

Mit NOTIFY (der Standard) mailt der Daemon an NOTIFY_ADDRESS (Standardwert postmaster@ der ersten bedienten Domain), wenn ein Eintrag hinzugefügt werden muss, ein Eintrag eines ausgemusterten Schlüssels entfernt werden darf, eine Rotation auf ihre Einträge wartet oder eine DNS-Aktualisierung abgelehnt wurde. Die Benachrichtigungen gehen über den lokalen Einlieferungs-Socket. Jeder Zustand wird höchstens einmal täglich gemailt, solange er andauert.

95.1.9.1.3.4. Das Statusdokument

Nach jeder Änderung schreibt der Daemon alles Öffentliche über die Schlüssel in PUBLIC_DIR/status.json (für alle lesbar): die Selektoren, die Zustände, die TXT-Einträge, was die autoritativen Server ausliefern, die ausstehenden DNS-Änderungen und eine Rotation, die auf das DNS wartet. pepsi-status(1) (Abschnitt „DKIM-Schlüssel“), pepsi-setup(1) (run, check), GET /api/v1/keys/dkim und die DKIM-Seite der Konsole lesen es; keiner von ihnen liest einen Schlüssel.

95.1.9.1.4. Befehle

serve

Den Daemon ausführen: den Socket binden, den Lebenszyklus einmal pro Minute voranbringen, das DNS prüfen, das Statusdokument schreiben und dem Postmaster mailen. pepsi-dkim.service führt ihn als pepsi-dkim aus; als root gestartet, wird er selbst zu diesem Konto.

status [–json]

Gibt jeden Schlüssel mit seinem Algorithmus, Zustand, DNS-Urteil und Datum aus, eine Rotation, die auf das DNS wartet, und die ausstehenden DNS-Änderungen. –json gibt stattdessen das Statusdokument aus. Der laufende Daemon antwortet; antwortet keiner, wird die Statusdatei gelesen.

records [DOMAIN]

Gibt als Zonendatei-Zeilen jeden Eintrag aus, der im DNS sein muss (einer DOMAIN oder aller), und, als Kommentare, die Einträge ausgemusterter Schlüssel, die entfernt werden dürfen.

rotate [–hard] [DOMAIN…]

Erzeugt für jede DOMAIN (jede bediente Domain, wenn keine genannt ist) eine next-Generation und wechselt zu ihr: sobald ihre Einträge sichtbar sind (mit WAIT_FOR_DNS) oder sofort mit –hard oder ohne WAIT_FOR_DNS. Verwenden Sie –hard, nachdem ein Schlüssel offengelegt worden sein könnte; die Einträge der neuen Generation müssen sofort veröffentlicht werden, da DKIM bei Empfängern fehlschlägt, bis sie es sind. Erfordert root oder das Konto pepsi-dkim. rotate now der Konsole bittet den root-Applier (pepsi-setup apply), dies auszuführen.

sync-domains DOMAIN…

Hält DOMAIN… als die Menge der signierenden Domains fest, erzeugt Schlüssel für jede davon, die keine hat, mustert die Schlüssel jeder nicht genannten Domain aus und gibt das Statusdokument als JSON (und nichts sonst) auf der Standardausgabe aus. pepsi-setup run ruft es mit jeder Domain auf, für die die Installation signiert, und entnimmt dem Ergebnis die DKIM-Einträge, die es für die Zone ausgibt.

rotate und sync-domains fragen den laufenden Daemon. Antwortet keiner, nehmen sie die Sperre des Zustandsverzeichnisses und erledigen die Arbeit an den Dateien selbst, ohne DNS-Prüfungen; als root ausgeführt, legen sie fehlende Verzeichnisse an und laufen als pepsi-dkim weiter.

95.1.9.1.5. Socket-Protokoll und Richtlinie

Ein JSON-Objekt pro Zeile in jede Richtung; eine Verbindung kann viele Anfragen tragen, und eine Anfragezeile ist höchstens 256 KiB groß. Die Anfragen sind selectors (die aktuellen Selektoren einer Domain), sign, status und die administrativen reload und rotate, die der Daemon nur von root und seinem eigenen Konto annimmt (geprüft mit SO_PEERCRED). Eine sign-Anfrage trägt die genauen zu signierenden Bytes: die kanonisierten Header-Felder, die die Signatur abdeckt, dann das Signaturfeld mit leerem b=. Der Daemon lehnt ab:

  • eine Domain, die er nicht bedient (unserved-domain), oder jede Domain, solange pepsi-setup run ihm noch keine Liste von Domains übergeben hat (not-configured, was die Stages als vorübergehend behandeln und wiederholen);

  • ein letztes Feld, das nicht das Signaturfeld der Art der Anfrage ist (DKIM-Signature, ARC-Message-Signature oder ARC-Seal), ein d=, s= oder a=, das von der Anfrage abweicht, ein nicht leeres b=, ein doppeltes Tag oder mehr als 512 Felder (policy:..., malformed);

  • bei DKIM: ein h=, das from nicht nennt, kein From:-Feld oder ein From:-Feld mit einer Mailbox, deren Domain nicht mit d= ausgerichtet ist (dieselbe Organisationsdomain);

  • bei ARC: ein d= außer [pepsi] ARC_DOMAIN;

  • einen Selektor, der weder aktuell ist noch innerhalb der letzten zehn Minuten aktuell war (stale-selector).

Mit PUBLISH_RETIRED_KEYS wird ein ausgemusterter Schlüssel erst veröffentlicht, wenn das DNS seinen Eintrag nicht mehr ausliefert: Bis dahin wird er unveröffentlicht behalten, weil ein veröffentlichter privater Schlüssel, dessen Eintrag noch auflöst, jeden für die Domain signieren ließe. Wird sein Eintrag noch ausgeliefert, wenn die Generation verworfen wird (90 Tage nach der Ausmusterung), wird der Schlüssel stattdessen gelöscht.

Jede Signatur und jede Ablehnung wird mit der Prozess-ID des Anfragenden protokolliert.

95.1.9.1.6. Konfiguration

Der Daemon liest [pepsi-dkim], [pepsi] DKIM_SELECTOR, DKIM_ALGORITHMS, ARC_DOMAIN und ARC_ALGORITHM sowie den [pepsi-sendmail]-Socket, über den seine Benachrichtigungen gehen. pepsi-setup validate prüft den Abschnitt.

[pepsi-dkim]
SOCKET

Der Signier-Socket (Standardwert /run/pepsi-dkim/sign.sock). Die Stages lesen dieselbe Option, um ihn zu finden.

STATE_DIR

Die privaten Schlüssel und der private Zustand (Standardwert /var/lib/pepsi-dkim).

PUBLIC_DIR

Das Statusdokument und die veröffentlichten ausgemusterten Schlüssel (Standardwert /var/lib/pepsi-dkim-public).

RSA_BITS

Die Größe der RSA-Schlüssel, die der Daemon erzeugt: 2048, 3072 oder 4096 (Standardwert 2048). Vorhandene Schlüssel behalten ihre Größe bis zur nächsten Rotation. Schlüssel über 2048 Bit brauchen einen in mehrere Zeichenketten aufgeteilten TXT-Eintrag, den manche DNS-Hosting-Oberflächen verstümmeln; pepsi-setup check meldet einen Eintrag, der abgeschnitten ausgeliefert wird.

ROTATION_DAYS

Wie lange eine Generation signiert, bevor die nächste übernimmt (Standardwert 0: nie von selbst).

ROTATION_LEAD_DAYS

Wie lange vor dem Wechsel die next-Generation erzeugt wird, damit ihre Einträge veröffentlicht werden können (Standardwert 28; muss kürzer als ROTATION_DAYS sein).

RETIRE_AFTER_DAYS

Wie lange die Einträge einer ausscheidenden Generation bleiben, bevor ihre Schlüssel ausgemustert werden (Standardwert 14, mindestens 1). Muss das SIGNATURE_EXPIRATION_DAYS jeder pepsi-stage-dkim-sign- und pepsi-stage-arc-Stage übersteigen, was pepsi-setup validate prüft.

WAIT_FOR_DNS

Ob ein geplanter oder weicher Wechsel wartet, bis jeder autoritative Server die Einträge der next-Generation ausliefert (Standardwert yes).

DNS_CHECK_INTERVAL

Wie oft jeder Eintrag nachgeschlagen wird (Standardwert 1 h, mindestens 1 min).

DNS_UPDATE

none (Standard: Der Betreiber veröffentlicht) oder rfc2136.

DNS_UPDATE_SERVER

Mit rfc2136: der Server, an den die Aktualisierungen gehen, als Hostname oder Adresse mit optionalem Port (Standardwert: das SOA-MNAME der Zone).

DNS_UPDATE_TTL

Die TTL der hinzugefügten Einträge (Standardwert 3600 Sekunden).

TSIG_KEY_NAME

Mit rfc2136: der Name des TSIG-Schlüssels (erforderlich).

TSIG_ALGORITHM

hmac-sha256 (Standard), hmac-sha384 oder hmac-sha512.

TSIG_SECRET

Mit rfc2136: der TSIG-Schlüssel, Base64 (erforderlich). Ein Geheimnis: pepsi-setup hält es in secrets.d/pepsi-dkim.secret, lesbar allein für pepsi-dkim. Wer es hat, kann ändern, was immer der Schlüssel in der Zone aktualisieren darf, gewähren Sie dem Schlüssel daher nur Aktualisierungen von _domainkey-Namen.

PUBLISH_RETIRED_KEYS

Einen ausgemusterten privaten Schlüssel veröffentlichen statt löschen, sobald das DNS seine Einträge nicht mehr ausliefert (Standardwert no): Sobald jeder damit eine Signatur erstellen kann, beweist eine alte Signatur nicht mehr, wer sie erstellt hat. pepsi-httpd(1) liefert die Dateien aus. Die Option ist mit Rotation sinnvoll; pepsi-setup validate warnt, wenn ROTATION_DAYS 0 ist oder kein Listener HTTPS für die Öffentlichkeit ausliefert.

NOTIFY

Den Postmaster über ausstehende DNS-Änderungen anmailen (Standardwert yes).

NOTIFY_ADDRESS

Wohin die Benachrichtigungen gehen (Standardwert postmaster@ der ersten bedienten Domain).

95.1.9.1.7. Globale Optionen

-c FILE, –config FILE

Liest die Konfiguration aus FILE, statt die Standardorte zu durchsuchen.

-L LOGLEVEL, –log LOGLEVEL

Setzt die Log-Ausführlichkeit. LOGLEVEL ist eines von error, warn, info, debug oder trace (Standardwert: [pepsi] LOG, sonst info).

95.1.9.1.8. Dateien

/var/lib/pepsi-dkim/keys/<domain>/<selector>.key

Die privaten Schlüssel: PKCS#8-PEM, Modus 0600, Eigentümer pepsi-dkim, in 0700-Verzeichnissen. Sichern Sie sie nicht: Nach einer Wiederherstellung ohne sie erzeugt der Daemon frische Schlüssel, was eine Rotation ist, deren Einträge veröffentlicht werden müssen.

/var/lib/pepsi-dkim/state.json, domains, lock

Der Lebenszyklus-Zustand (0600), die bedienten Domains und die Sperre, die hält, wer sie ändert.

/var/lib/pepsi-dkim-public/status.json

Das öffentliche Statusdokument (0644).

/var/lib/pepsi-dkim-public/retired/<domain>/<selector>.pem

Ausgemusterte private Schlüssel, mit PUBLISH_RETIRED_KEYS (0644); pepsi-httpd(1) liefert sie unter /.well-known/pepsi-dkim-retired/<domain>/<selector>.pem aus.

/run/pepsi-dkim/sign.sock

Der Signier-Socket (0660, Gruppe pepsi; das Verzeichnis gehört dem Daemon, 0711).

/etc/pepsi/secrets.d/pepsi-dkim.secret

TSIG_SECRET, lesbar allein für pepsi-dkim.

95.1.9.1.9. Exit-Status

0 bei Erfolg; 1, wenn die Konfiguration nicht gelesen, der Socket nicht gebunden oder das Zustandsverzeichnis nicht verwendet werden kann oder ein Befehl fehlschlägt.

95.1.9.1.10. Siehe auch

pepsi-stage-dkim-sign(1), pepsi-stage-arc(1), pepsi-setup(1), pepsi-status(1), pepsi-httpd(1), pepsi.conf(5)