95.1.8. pepsi-stage-dkim-sign¶
DKIM-sign a message in the Pepsi pipeline
- Section du manuel:
1
95.1.8.1.1. Nom¶
pepsi-stage-dkim-sign - l’étape de signature DKIM du pipeline Pepsi.
95.1.8.1.2. Synopsis¶
pepsi-stage-dkim-sign [GLOBAL-OPTIONS] worker
95.1.8.1.3. Description¶
pepsi-stage-dkim-sign est un programme d’étape exécuté par pepsi-dispatch(1) comme un worker persistant lisant les identifiants de message sur l’entrée standard. Il ajoute en tête un en-tête DKIM-Signature par algorithme de [pepsi] DKIM_ALGORITHMS (par défaut deux : un RSA, un Ed25519) aux octets bruts du message et fait avancer la ligne vers son NEXT_STAGE (une étape de remise). La signature ne fait qu”ajouter en tête des lignes d’en-tête, de sorte que les signatures existantes plus bas dans le message ne sont pas perturbées. Il ne touche pas au state de la ligne (hormis l’unique indicateur décrit ci-dessous), de sorte que d’éventuels paramètres state.dsn RFC 3461 sont préservés pour que les étapes ultérieures les honorent.
Un message dont le corps porte des octets 8 bits est d’abord converti vers un encodage de transfert 7 bits (RFC 6376 section 5.3) : chaque partie MIME feuille 8 bits est réencodée en quoted-printable (text/*) ou en base64, et un paramètre non ASCII dans l’en-tête propre d’une partie (le nom de fichier d’une pièce jointe) prend la forme RFC 2231. Sinon, une étape de relais appliquerait cette conversion après la signature, vers un prochain saut qui n’annonce pas 8BITMIME, et invaliderait la signature. Lorsque le corps est converti au préalable, le relais ne trouve plus rien à changer. Le corps converti est stocké à la place de l’original, et state.origin.body_8bit est effacé afin que le relais n’annonce plus BODY=8BITMIME. Le message est au contraire signé sans modification dans les cas suivants : lorsque son propre bloc d’en-têtes contient des octets non ASCII (il a de toute façon besoin de SMTPUTF8) ; lorsqu’il porte déjà un DKIM-Signature ou un ARC-Message-Signature, comme la signature d’un auteur sur un message réexpédié ou le propre sceau ARC de Pepsi, car tous deux couvrent le corps 8 bits et casseraient à chaque saut ; lorsque l’une de ses parties est un multipart/signed, dont la signature OpenPGP ou S/MIME couvre les octets encodés en dessous ; ou lorsque la conversion ne peut pas rendre le corps 7 bits (une arborescence MIME imbriquée trop profondément).
Le domaine de signature (d=) est SIGNING_DOMAIN s’il est configuré, sinon le domaine de la première boîte aux lettres de l’en-tête From: du message. Cet en-tête est lu strictement : à moins que chaque boîte aux lettres qu’il contient s’analyse comme une boîte aux lettres RFC 5322, le message est considéré comme sans From: utilisable. Les clients de messagerie résolvent certains champs en adresses différentes (<me@example.org>:<ceo@example.com>, une seconde adresse <...>, une syntaxe de groupe, un encoded-word à l’intérieur de l’adresse ; CERT/CC VU#517845). Un tel champ n’est jamais signé au nom du domaine qu’un lecteur indulgent choisirait.
L’étape ne détient aucune clé. Les clés DKIM par domaine appartiennent au démon de signature pepsi-dkim(1), qui s’exécute sous son propre compte. L’étape calcule l’empreinte du corps, construit le champ DKIM-Signature (un par algorithme de [pepsi] DKIM_ALGORITHMS, avec les sélecteurs que le démon désigne comme courants) et envoie le bloc d’en-têtes canonisé à la socket du démon ([pepsi-dkim] SOCKET, par défaut /run/pepsi-dkim/sign.sock). Le démon confronte ce bloc à sa politique et renvoie la signature. Il ne signe que pour un domaine qu’il sert, et une signature DKIM seulement lorsque chaque boîte aux lettres du From: relève de l’organisation du domaine d= et que h= nomme From. Lorsqu’une bascule de clé survient entre le choix d’un sélecteur et la signature, l’étape redemande une fois les sélecteurs courants.
Cette étape existe afin que la construction du message et la signature DKIM soient des étapes séparées. En particulier, pepsi-stage-bounce(1) construit un DSN non signé et pointe son NEXT_STAGE ici, de sorte qu’un rebond généré soit signé au nom du domaine de son postmaster avant la remise.
Un message arrivé de l’extérieur est avancé non signé lorsqu’un domaine de son From: s’aligne avec le domaine de signature (le même domaine, un domaine parent ou un sous-domaine de celui-ci, ou un domaine partageant ses deux derniers labels) et que l’ingress ne l’a authentifié ni par DMARC (state.auth.dmarc) ni par une signature DKIM alignée avec le From: (state.auth.dkim). Notre signature serait exactement la signature alignée que DMARC recherche ; signer un tel message permettrait donc à une contrefaçon de notre propre domaine de réussir DMARC au saut suivant. Une telle contrefaçon peut être reçue de n’importe où puis réexpédiée (par un alias qui se développe hors site, un ~/.forward ou le signataire de relais qu’insère le SIGN_RELAYED de l’assistant). Le message part comme l’enverrait tout réexpéditeur dépourvu de notre clé, et la décision est journalisée. Un From: qui ne peut pas être lu strictement compte comme aligné. Le courrier soumis ici (state.local_origin) est toujours signé, de même que le courrier que Pepsi compose lui-même, qui ne porte aucun verdict d’ingress : DSN, réponses automatiques et avis, et copies de listes de diffusion (le logiciel de liste en est l’auteur et applique sa propre politique de publication). Avec SIGNING_DOMAIN, le courrier reçu de l’extérieur dont le From: relève d’une autre organisation (courrier réexpédié d’un auteur étranger) avance non signé : le démon de signature ne signe qu’un From: aligné avec d=, et le message garde les propres signatures de son auteur. Le courrier soumis ou composé ici avec un tel From: est au contraire refusé avec un DSN 5.7.1. La moitié SPF de la même règle est le domaine SRS dédié (voir pepsi-stage-srs(1)) ; les deux sont exposées sous « Forwarded forgeries of our own domain » dans le chapitre sécurité du manuel de Pepsi.
Le démon garde les clés hors de portée de toute étape, de sorte qu’une étape compromise ne peut pas les copier. Il ne peut pas empêcher une telle étape de les utiliser : la socket répond à tout processus du groupe pepsi, de sorte qu’une signature DKIM ne vaut que ce que vaut le rôle pepsi. Toute étape compromise peut faire signer du courrier d’un domaine servi tant qu’elle s’exécute, et peut réécrire le From: d’un message en file avant que cette étape ne le voie. Le chapitre Modèle de menace du manuel consigne cela comme un risque résiduel documenté. L’étape protège la réputation du domaine, pas une préférence d’utilisateur ; ne l’inscrivez donc pas dans les EDITABLE_STAGES de pepsi-stage-edit-settings(1).
Hormis ces cas voulus, la signature est fail-closed : un message qui ne peut pas être signé n’est jamais avancé non signé. Ce qui se passe à la place dépend de la partie en cause :
Le message a atteint
dkim-signpour un domaine pour lequel personne ici ne signe : aucun domaine de signature ne peut être déterminé (pas deSIGNING_DOMAINet pas d’en-têteFrom:utilisable), pepsi-dkim(1) répond qu’il ne signe pas pour le domaine, ou, avecSIGNING_DOMAIN, leFrom:ne relève pas de l’organisation de ce domaine (ce que le démon refuserait à chaque nouvelle tentative). Avec un BOUNCE_STAGE, le message est d’abord scindé en une ligne par destinataire, afin que leNOTIFYde chaque destinataire soit respecté, puis réacheminé vers cette étape avec une raison de DSN dansstate.bounce. Le statut est5.7.1pour un domaine pour lequel le démon ne signe pas ou unFrom:hors deSIGNING_DOMAIN, et5.6.0pour un message sansFrom:utilisable ; le diagnostic nomme le domaine. Sans BOUNCE_STAGE, le message est déplacé vers l’état terminalfailed, avec la raison dansstate.last_error. Un message à expéditeur nul (lui-même un DSN ou une réponse automatique) est toujours mis en échec plutôt que réacheminé : on ne fait jamais rebondir un rebond, et une ligne en échec reste visible pour l’opérateur.Le démon est injoignable (
pepsi-dkim.servicearrêté ou en cours de redémarrage), ou il refuse pour toute autre raison : c’est l’hôte qui est en cause, non le message. L’erreur est réessayée (voir pepsi-dispatch(1)) : le message restepausedà cette étape avec la raison dansstate.last_erroret est réessayé, après une minute puis à des intervalles qui doublent jusqu’à une heure, jusqu’à ce qu’il soit resté en file plus longtemps que le MAX_LIFETIME de l’étape (par défaut120 h) ; ce n’est qu’alors qu’il est abandonné. Le faire échouer immédiatement ferait rebondir chaque message sortant, et les rebonds, qui sont eux aussi signés ici, seraient alors abandonnés sans que personne n’en soit averti.
La section propre de l’étape, [pepsi] et [pepsi-dkim] SOCKET sont vérifiées au démarrage du worker : une configuration qui ne s’analyse pas fait refuser au worker de démarrer (sortie 78), et le dispatcher retient la file jusqu’à sa correction.
95.1.8.1.3.1. Couverture du corps¶
La signature couvre toujours strictement l’intégralité du corps : tout changement du corps en transit l’invalide. Pepsi n’émet jamais le tag de longueur de corps (l=) de la RFC 6376, et aucune option ne permet de le lui faire émettre.
Le tag existe pour qu’une signature survive à une liste de diffusion qui ajoute un pied de page, mais aucun opérateur ne peut faire utilement ce compromis. Le vérificateur de Pepsi et tout déploiement mail-auth/Stalwart utilisent l’analyseur strict de mail-auth, qui rejette purement et simplement toute signature portant l > 0, au lieu de se contenter de tolérer une couverture moindre. Le tag transforme donc une signature qui serait passée en une signature qui échoue. Le cas pour lequel il existe est aussi celui où la réécriture de la liste a déjà cassé SPF, si bien que sous une politique DMARC p=reject cet échec DKIM fait la différence entre remis et rejeté. La RFC 6376 §8.2 avertit par ailleurs que le contenu ajouté peut remplacer l’original aux yeux du lecteur, par restructuration MIME ou analyse HTML laxiste, et que « les signataires devraient être extrêmement circonspects quant à l’usage de ce tag ».
95.1.8.1.3.2. Couverture des en-têtes¶
Les en-têtes couverts par la signature (le tag h=) sont la liste SIGNED_HEADERS (par défaut : les en-têtes courants d’origine/MIME). Chaque en-tête de la liste par défaut est nommé deux fois afin d’être sur-signé (RFC 6376 §8.15). Un en-tête nommé une fois de plus qu’il n’apparaît réellement est signé une fois de plus (à vide). Un attaquant qui ajoute en tête un second From:, To:, Reply-To:, Date:, Content-Type: ou tout autre champ listé produit donc une occurrence que la signature ne couvre pas, ce qui casse la vérification. Chacun de ces champs apparaît au plus une fois dans un message bien formé, de sorte que la seconde entrée ne laisse jamais une occurrence légitime non signée. Lister dans SIGNED_HEADERS un en-tête absent du message le sur-signe de même (il ne pourra pas être ajouté ultérieurement).
La liste par défaut couvre aussi List-Unsubscribe et List-Unsubscribe-Post, sur-signés comme les autres. La RFC 8058 section 4 n’autorise un destinataire à proposer le désabonnement en un clic que lorsqu’une signature DKIM valide couvre les deux champs ; sinon, quiconque peut relayer une copie du message pourrait choisir l’URI à laquelle le destinataire envoie sa requête POST.
95.1.8.1.4. Configuration¶
L’étape est câblée et configurée via sa propre section [stage-<name>] (PROGRAM = pepsi-stage-dkim-sign, un NEXT_STAGE obligatoire, un BOUNCE_STAGE facultatif pour les refus décrits ci-dessus). pepsi.conf(5) documente ses options, HEADER_CANONICALIZATION/BODY_CANONICALIZATION (choisies indépendamment), SIGNATURE_EXPIRATION_DAYS, SIGNED_HEADERS et SIGNING_DOMAIN, ainsi que les options partagées de [pepsi] (DKIM_SELECTOR, DKIM_ALGORITHMS). Les clés, leurs sélecteurs et leur renouvellement relèvent de pepsi-dkim(1). Le [pepsi-dkim] RETIRE_AFTER_DAYS du démon doit dépasser SIGNATURE_EXPIRATION_DAYS, afin que l’enregistrement d’une clé survive à chaque signature faite avec elle ; pepsi-setup validate le vérifie. Le hachage est toujours SHA-256 ; par défaut, une signature RSA et une signature Ed25519 sont toutes deux émises, chacune avec une expiration x= sept jours après la signature (SIGNATURE_EXPIRATION_DAYS, 0 pour aucune), de sorte qu’une copie rejouée ou une signature faite avec une clé volée cesse de se vérifier au bout d’une semaine.
95.1.8.1.5. État¶
Entrées : state.local_origin et les verdicts d’ingress state.auth.dmarc et state.auth.dkim, qui décident si un message dont le From: s’aligne avec le domaine de signature est signé (voir ci-dessus). Le domaine de signature provient de SIGNING_DOMAIN ou de la colonne from_header, et l’empreinte du corps, du message chargé.
Sorties : sur le chemin de signature, state.origin.body_8bit est effacé lorsque le corps a été converti en 7 bits ; rien d’autre n’est ajouté. Les signatures sont ajoutées en tête de la colonne headers (et le corps converti, s’il y en a un, remplace le body) ; le reste de state, y compris state.dsn, est préservé tel quel. Un message refusé reçoit state.last_error et, lorsqu’il est réacheminé, state.bounce ; un message réessayé reçoit state.last_error et state.temporary_failures. La disposition de l’état est décrite dans pepsi.state(7).
Transitions : en cas de succès, avance vers NEXT_STAGE (l’étape de remise), après avoir ajouté en tête le ou les en-têtes DKIM-Signature. Si le domaine de signature ne peut être déterminé ou n’a pas de clés ici, le message est réacheminé vers BOUNCE_STAGE (une ligne par destinataire, state.bounce défini) ou, sans lui ou pour un message à expéditeur nul, déplacé vers l’état terminal failed ; si ses clés ne peuvent être utilisées, il est mis en pause pour réessai jusqu’à MAX_LIFETIME (fail-closed ; voir ci-dessus). L’étape ne termine jamais un message.
95.1.8.1.6. Commandes¶
Exécuté comme worker, le programme signe chaque message et le fait avancer.
95.1.8.1.7. Options globales¶
- -c FILE, –config FILE
Lit la configuration depuis FILE au lieu du chemin de recherche par défaut.
- -L LOGLEVEL, –log LOGLEVEL
Règle la verbosité de journalisation (
error,warn,info,debug,trace; par défaut[pepsi] LOG, sinoninfo).- -h, –help
Affiche un résumé d’utilisation et quitte.
- -V, –version
Affiche la version et quitte.
95.1.8.1.8. Code de sortie¶
Le résultat de chaque message est rapporté à pepsi-dispatch(1) sur la ligne de statut du worker, et non par le code de sortie.
- 0
Le worker s’est exécuté jusqu’à la fermeture de son entrée standard.
- 1
Une erreur fatale s’est produite (configuration illisible, base de données impossible à ouvrir, ou échec de l’entrée/sortie standard). La raison est écrite dans le journal.
- 78
Le worker a refusé de démarrer : sa section ou
[pepsi]ne s’analyse pas. Le dispatcher remet en file ce qu’il lui avait confié et réessaie l’étape plus tard.
95.1.8.1.9. Voir aussi¶
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. Bogues¶
Signalez les bogues au gestionnaire de tickets de Pepsi.