95.1.9. pepsi-dkim

hold the DKIM and ARC signing keys and sign

Section du manuel:

1

95.1.9.1.1. Nom

pepsi-dkim - le démon de signature qui détient les clés privées DKIM et ARC, les renouvelle et indique les enregistrements DNS dont elles ont besoin.

95.1.9.1.2. Synopsis

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. Description

pepsi-dkim détient les clés privées avec lesquelles signent pepsi-stage-dkim-sign(1) et pepsi-stage-arc(1). Il s’exécute sous son propre compte, pepsi-dkim, et conserve les clés dans son répertoire d’état (STATE_DIR, par défaut /var/lib/pepsi-dkim, mode 0700), où chaque clé est un fichier de mode 0600. Aucun worker d’étape ne peut lire une clé. Les étapes calculent elles-mêmes l’empreinte du corps et construisent le champ de signature. Elles envoient ensuite le bloc d’en-têtes canonisé au démon via une socket UNIX (SOCKET, par défaut /run/pepsi-dkim/sign.sock, mode 0660, groupe pepsi), et le démon le signe et renvoie la valeur de signature. Lorsque le démon est injoignable, les étapes réessaient le message plus tard ; elles ne l’envoient jamais non signé.

Cela protège les clés contre la divulgation. Cela ne restreint pas leur utilisation au-delà de la politique ci-dessous : tout processus du groupe pepsi peut demander à la socket une signature pour un domaine servi, et toute étape du pipeline peut réécrire le From: d’un message en file et faire signer le résultat par pepsi-stage-dkim-sign. Une étape compromise peut donc obtenir des signatures tant qu’elle s’exécute, mais ne peut pas emporter une clé.

95.1.9.1.3.1. Clés et sélecteurs

Chaque domaine de signature a des clés pour les algorithmes que nomme [pepsi] DKIM_ALGORITHMS (RSA, Ed25519 ou les deux) ; le [pepsi] ARC_DOMAIN reçoit en outre une clé de [pepsi] ARC_ALGORITHM. Les clés RSA ont RSA_BITS bits et sont générées par AWS-LC. Les clés qui sont créées ensemble forment une génération ; ses sélecteurs sont <DKIM_SELECTOR>-YYYYMM pour RSA et <DKIM_SELECTOR>-YYYYMM-ed25519 pour Ed25519 ([pepsi] DKIM_SELECTOR, par défaut pepsi, et le mois de création de la génération, en UTC). Une deuxième génération dans le même mois reçoit une lettre après la date : pepsi-202610b. Chaque clé a ainsi un nom d’enregistrement qui lui est propre, <selector>._domainkey.<domain>.

95.1.9.1.3.2. Cycle de vie

Une génération passe par quatre états :

next

Créée en prévision d’un renouvellement ; ne signe rien. Ses enregistrements doivent être publiés avant qu’elle puisse prendre le relais.

current

Signe. Un domaine a exactement une génération courante.

retiring

Remplacée par une génération plus récente ; ne signe rien, mais ses enregistrements restent dans le DNS pendant RETIRE_AFTER_DAYS, de sorte que les signatures qu’elle a faites dans les jours précédant la bascule se vérifient toujours.

retired

Les clés privées sont supprimées (ou, avec PUBLISH_RETIRED_KEYS, publiées dès que le DNS ne sert plus leurs enregistrements) et les enregistrements peuvent être retirés. La génération reste consignée pendant 90 jours, puis est abandonnée.

Un domaine servi sans génération courante (une installation neuve, un domaine ajouté à la configuration, un répertoire d’état perdu ou non restauré) en reçoit une aussitôt, et elle signe aussitôt : tant que ses enregistrements ne sont pas publiés, les destinataires ne peuvent pas vérifier ses signatures. Chacune des interfaces décrites ci-dessous indique les enregistrements encore dus.

Le renouvellement est désactivé sauf si ROTATION_DAYS est défini. Avec cette option, une génération next est créée ROTATION_LEAD_DAYS avant l’échéance de la bascule. Avec WAIT_FOR_DNS (par défaut), la bascule attend que chaque serveur faisant autorité pour la zone serve chaque enregistrement de la génération next ; les clés courantes continuent de signer entre-temps, et le retard est signalé. rotate demande une bascule immédiate, et rotate –hard bascule sans regarder le DNS. Pendant dix minutes après une bascule, le sélecteur qui était courant jusque-là signe encore, pour les messages en transit ; une étape qui demande un sélecteur plus ancien se voit répondre de demander le sélecteur courant.

Lorsqu’un domaine est retiré de la configuration, sa génération courante est retirée de la même manière, et une génération next de ce domaine, qui n’a jamais signé, est retirée aussitôt.

95.1.9.1.3.3. DNS

Tous les DNS_CHECK_INTERVAL, le démon demande à chaque serveur faisant autorité pour la zone l’enregistrement de chaque clé qui doit figurer dans le DNS, et le classe comme visible (chaque serveur le sert avec la clé), missing (aucun ne le sert), disagree (certains le servent, d’autres non : un secondaire qui n’a pas rattrapé son retard) ou unknown (aucune réponse n’a pu être établie).

Par défaut, l’opérateur publie les enregistrements. Avec DNS_UPDATE = rfc2136, le démon ajoute lui-même les enregistrements des générations next et current et retire ceux des générations retirées, par UPDATE RFC 2136 signé avec TSIG (RFC 8945), envoyé à DNS_UPDATE_SERVER ou sinon au primaire de la zone (le MNAME du SOA). Un échec à joindre le serveur est réessayé au tick suivant ; un refus (une mauvaise clé, une politique de zone qui interdit le nom) est consigné sur la clé, n’est pas réessayé avant le redémarrage du démon, et est envoyé par courrier au postmaster.

Avec NOTIFY (par défaut), le démon écrit à NOTIFY_ADDRESS (par défaut postmaster@ le premier domaine servi) lorsqu’un enregistrement doit être ajouté, qu’un enregistrement d’une clé retirée peut être supprimé, qu’un renouvellement attend ses enregistrements, ou qu’une mise à jour DNS a été refusée. Les avis passent par la socket de soumission locale. Chaque situation fait l’objet d’au plus un courrier par jour tant qu’elle dure.

95.1.9.1.3.4. Le document d’état

Après chaque changement, le démon écrit tout ce qui est public au sujet des clés dans PUBLIC_DIR/status.json (lisible par tous) : les sélecteurs, les états, les enregistrements TXT, ce que servent les serveurs faisant autorité, les modifications DNS dues et un renouvellement qui attend le DNS. pepsi-status(1) (section « DKIM keys »), pepsi-setup(1) (run, check), GET /api/v1/keys/dkim et la page DKIM de la console le lisent ; aucun d’eux ne lit une clé.

95.1.9.1.4. Commandes

serve

Exécute le démon : lie la socket, fait avancer le cycle de vie une fois par minute, vérifie le DNS, écrit le document d’état et écrit au postmaster. pepsi-dkim.service l’exécute en tant que pepsi-dkim ; lancé en tant que root, il prend lui-même ce compte.

status [–json]

Affiche chaque clé avec son algorithme, son état, son verdict DNS et sa date, un renouvellement qui attend le DNS, et les modifications DNS dues. –json affiche à la place le document d’état. C’est le démon en cours d’exécution qui répond ; lorsqu’aucun ne répond, le fichier d’état est lu.

records [DOMAIN]

Affiche, sous forme de lignes de fichier de zone, chaque enregistrement qui doit figurer dans le DNS (d’un DOMAIN, ou de tous), et, en commentaires, les enregistrements des clés retirées qui peuvent être supprimés.

rotate [–hard] [DOMAIN…]

Crée une génération next pour chaque DOMAIN (chaque domaine servi lorsqu’aucun n’est nommé) et bascule sur elle : dès que ses enregistrements sont visibles (avec WAIT_FOR_DNS), ou aussitôt avec –hard ou sans WAIT_FOR_DNS. Utilisez –hard lorsqu’une clé a pu être exposée ; les enregistrements de la nouvelle génération doivent être publiés aussitôt, puisque DKIM échoue chez les destinataires tant qu’ils ne le sont pas. Nécessite root ou le compte pepsi-dkim. Le rotate now de la console demande à l’applicateur root (pepsi-setup apply) d’exécuter cette commande.

sync-domains DOMAIN…

Enregistre DOMAIN… comme l’ensemble des domaines de signature, crée des clés pour ceux qui n’en ont pas, retire les clés de tout domaine non nommé, et affiche le document d’état en JSON (rien d’autre) sur la sortie standard. pepsi-setup run l’appelle avec chaque domaine pour lequel le déploiement signe, et tire du résultat les enregistrements DKIM qu’il affiche pour la zone.

rotate et sync-domains s’adressent au démon en cours d’exécution. Lorsqu’aucun ne répond, ils prennent le verrou du répertoire d’état et font eux-mêmes le travail sur les fichiers, sans vérifications DNS ; exécutés en tant que root, ils créent les répertoires absents et continuent en tant que pepsi-dkim.

95.1.9.1.5. Protocole de la socket et politique

Un objet JSON par ligne dans chaque sens ; une connexion peut transporter de nombreuses requêtes, et une ligne de requête fait au plus 256 Kio. Les requêtes sont selectors (les sélecteurs courants d’un domaine), sign, status, et les requêtes administratives reload et rotate, que le démon n’accepte que de root et de son propre compte (vérifié avec SO_PEERCRED). Une requête sign porte les octets exacts à signer : les champs d’en-tête canonisés que couvre la signature, puis le champ de signature avec un b= vide. Le démon refuse :

  • un domaine qu’il ne sert pas (unserved-domain), ou tout domaine tant que pepsi-setup run ne lui a pas encore remis de liste de domaines (not-configured, que les étapes traitent comme temporaire et réessaient) ;

  • un dernier champ qui n’est pas le champ de signature du type de la requête (DKIM-Signature, ARC-Message-Signature ou ARC-Seal), un d=, s= ou a= qui diffère de la requête, un b= non vide, une balise dupliquée, ou plus de 512 champs (policy:..., malformed) ;

  • pour DKIM : un h= qui ne nomme pas from, l’absence de champ From:, ou un champ From: avec une boîte aux lettres dont le domaine n’est pas aligné avec d= (même domaine organisationnel) ;

  • pour ARC : un d= autre que [pepsi] ARC_DOMAIN ;

  • un sélecteur qui n’est pas courant, ni ne l’a été au cours des dix dernières minutes (stale-selector).

Avec PUBLISH_RETIRED_KEYS, une clé retirée n’est publiée qu’une fois que le DNS ne sert plus son enregistrement : jusque-là elle est conservée, non publiée, car une clé privée publiée dont l’enregistrement se résout encore permettrait à n’importe qui de signer pour le domaine. Si son enregistrement est encore servi lorsque la génération est abandonnée (90 jours après son retrait), la clé est supprimée à la place.

Chaque signature et chaque refus est journalisé avec l’identifiant du processus demandeur.

95.1.9.1.6. Configuration

Le démon lit [pepsi-dkim], [pepsi] DKIM_SELECTOR, DKIM_ALGORITHMS, ARC_DOMAIN et ARC_ALGORITHM, ainsi que la socket [pepsi-sendmail] par laquelle passent ses avis. pepsi-setup validate vérifie la section.

[pepsi-dkim]
SOCKET

La socket de signature (par défaut /run/pepsi-dkim/sign.sock). Les étapes lisent la même option pour la trouver.

STATE_DIR

Les clés privées et l’état privé (par défaut /var/lib/pepsi-dkim).

PUBLIC_DIR

Le document d’état et les clés retirées publiées (par défaut /var/lib/pepsi-dkim-public).

RSA_BITS

La taille des clés RSA que crée le démon : 2048, 3072 ou 4096 (par défaut 2048). Les clés existantes gardent leur taille jusqu’au renouvellement suivant. Les clés de plus de 2048 bits nécessitent un enregistrement TXT découpé en plusieurs chaînes, ce que certains panneaux d’hébergement DNS abîment ; pepsi-setup check signale un enregistrement servi tronqué.

ROTATION_DAYS

Combien de temps une génération signe avant que la suivante ne prenne le relais (par défaut 0 : jamais d’elle-même).

ROTATION_LEAD_DAYS

Combien de temps avant la bascule la génération next est créée, afin que ses enregistrements puissent être publiés (par défaut 28 ; doit être inférieur à ROTATION_DAYS).

RETIRE_AFTER_DAYS

Combien de temps les enregistrements d’une génération en retrait restent en place avant que ses clés ne soient retirées (par défaut 14, au moins 1). Doit dépasser le SIGNATURE_EXPIRATION_DAYS de chaque étape pepsi-stage-dkim-sign et pepsi-stage-arc, ce que vérifie pepsi-setup validate.

WAIT_FOR_DNS

Si une bascule planifiée ou douce attend que chaque serveur faisant autorité serve les enregistrements de la génération next (par défaut yes).

DNS_CHECK_INTERVAL

La fréquence à laquelle chaque enregistrement est consulté (par défaut 1 h, au moins 1 min).

DNS_UPDATE

none (par défaut : l’opérateur publie) ou rfc2136.

DNS_UPDATE_SERVER

Avec rfc2136 : le serveur auquel vont les mises à jour, sous forme de nom d’hôte ou d’adresse avec un port facultatif (par défaut : le MNAME du SOA de la zone).

DNS_UPDATE_TTL

Le TTL des enregistrements ajoutés (par défaut 3600 secondes).

TSIG_KEY_NAME

Avec rfc2136 : le nom de la clé TSIG (obligatoire).

TSIG_ALGORITHM

hmac-sha256 (par défaut), hmac-sha384 ou hmac-sha512.

TSIG_SECRET

Avec rfc2136 : la clé TSIG, en base64 (obligatoire). Un secret : pepsi-setup la conserve dans secrets.d/pepsi-dkim.secret, lisible par pepsi-dkim seul. Quiconque la détient peut modifier tout ce que la clé est autorisée à mettre à jour dans la zone ; n’accordez donc à la clé que les mises à jour des noms _domainkey.

PUBLISH_RETIRED_KEYS

Publie une clé privée retirée au lieu de la supprimer, une fois que le DNS ne sert plus ses enregistrements (par défaut no) : dès que n’importe qui peut produire une signature avec elle, une ancienne signature ne prouve plus qui l’a produite. pepsi-httpd(1) sert les fichiers. L’option a un sens avec le renouvellement ; pepsi-setup validate avertit lorsque ROTATION_DAYS vaut 0 ou qu’aucun écouteur ne sert HTTPS au public.

NOTIFY

Écrit au postmaster au sujet des modifications DNS dues (par défaut yes).

NOTIFY_ADDRESS

Où vont les avis (par défaut postmaster@ le premier domaine servi).

95.1.9.1.7. Options globales

-c FILE, –config FILE

Lit la configuration depuis FILE au lieu de parcourir les emplacements par défaut.

-L LOGLEVEL, –log LOGLEVEL

Règle la verbosité de journalisation. LOGLEVEL est l’un de error, warn, info, debug ou trace (par défaut : [pepsi] LOG, sinon info).

95.1.9.1.8. Fichiers

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

Les clés privées : PEM PKCS#8, mode 0600, propriétaire pepsi-dkim, dans des répertoires 0700. Ne les sauvegardez pas : après une restauration sans elles, le démon crée de nouvelles clés, ce qui est un renouvellement dont les enregistrements doivent être publiés.

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

L’état du cycle de vie (0600), les domaines servis et le verrou que détient quiconque les modifie.

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

Le document d’état public (0644).

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

Les clés privées retirées, avec PUBLISH_RETIRED_KEYS (0644) ; pepsi-httpd(1) les sert à /.well-known/pepsi-dkim-retired/<domain>/<selector>.pem.

/run/pepsi-dkim/sign.sock

La socket de signature (0660, groupe pepsi ; le répertoire appartient au démon, 0711).

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

TSIG_SECRET, lisible par pepsi-dkim seul.

95.1.9.1.9. Code de sortie

0 en cas de succès ; 1 lorsque la configuration ne peut pas être lue, que la socket ne peut pas être liée, que le répertoire d’état est inutilisable, ou qu’une commande échoue.

95.1.9.1.10. Voir aussi

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