95.1.25. pepsi-stage-check-whitelist¶
mark trusted senders” mail as non-spam
- Section du manuel:
1
95.1.25.1.1. Nom¶
pepsi-stage-check-whitelist - l’étape de liste blanche d’expéditeurs du pipeline Pepsi.
95.1.25.1.2. Synopsis¶
pepsi-stage-check-whitelist [GLOBAL-OPTIONS] worker
95.1.25.1.3. Description¶
Cette étape a FUSION = yes par défaut : lorsque la fusion d’étapes est activée ([pepsi] ALLOW_FUSION, la valeur par défaut) et que cette étape est pliée dans le binaire pepsi unifié, un prédécesseur peut l’exécuter dans son propre processus worker plutôt que de la dispatcher séparément. Comme cette étape a besoin du bloc d’en-têtes du message (pour List-Id:), seul un prédécesseur ayant chargé les en-têtes ou le message entier peut la fusionner ; un prédécesseur n’ayant chargé que les métadonnées d’enveloppe la dispatche normalement. Voir pepsi-dispatch(1) et pepsi.conf(5).
pepsi-stage-check-whitelist est un programme d’étape que pepsi-dispatch(1) exécute comme un worker persistant ; ce worker lit les identifiants de message sur l’entrée standard. Pour chaque identifiant, il charge la ligne pepsi.workqueue (il refuse d’agir si son status n’est pas running), lit sa section [stage-<stage>], et consulte une liste blanche nommée d’expéditeurs de confiance. Si le message correspond à la liste blanche, l’étape note state.spam = false afin qu’une pepsi-stage-anti-spam(1) ultérieure le laisse passer sans paiement. Dans les deux cas, le message avance ensuite vers NEXT_STAGE : cette étape ne supprime, ne fait rebondir ni ne met jamais un message en pause.
La liste blanche réside dans la table pepsi.whitelist, peuplée hors bande par l’opérateur (pepsi-whitelist(1)), par le pepsi-stage-auto-whitelist(1) sortant, ou par un utilisateur important sa propre boîte aux lettres (pepsi-whitelist import). Chaque ligne associe un whitelist_name (un label de groupe) à un whitelist_regex, à un match_field qui nomme ce à quoi l’expression est comparée, et aux conditions qui encadrent la correspondance. L’option WHITELIST_NAME de l’étape sélectionne le groupe ou les groupes. PostgreSQL décide en une seule requête si l’une de leurs lignes correspond, sous réserve des conditions de la ligne. Le whitelist_regex est une expression régulière étendue POSIX, comparée sans tenir compte de la casse (elle est évaluée par l’opérateur ~* de PostgreSQL, donc le dialecte est exactement l’ERE POSIX). L’expression n’est pas ancrée ; ancrez-la avec ^/$ pour correspondre au sujet entier. Le sujet d’une ligne from est l’addr-spec du From: sous forme canonique (Unicode NFC, partie locale ramenée à la casse, domaine sous forme de A-label). pepsi-whitelist et pepsi-stage-auto-whitelist(1) construisent leurs motifs à partir de la même forme, de sorte qu’une ligne correspond à toutes les graphies de son adresse.
Une ligne dont l’expression désigne une adresse ou un identifiant de liste exact, ou toute boîte d’un domaine (les formes qu’écrivent pepsi-whitelist et pepsi-stage-auto-whitelist(1) lorsque le texte est en ASCII), est trouvée par un index au lieu d’évaluer l’expression. Le résultat est le même ; seules les autres lignes sont évaluées une à une, de sorte que le coût de la vérification ne croît pas avec le nombre de correspondants appris.
Une ligne dont l’expression ne se compile pas ne correspond à rien ; elle ne fait pas échouer la vérification. Chaque outil qui écrit la table valide d’abord une expression, mais une ligne entrée malgré tout (un INSERT écrit à la main) ferait sinon refuser à PostgreSQL la requête entière. Comme chaque nom applicable est vérifié dans cette unique requête, la mauvaise ligne d’un utilisateur retiendrait alors le courrier de tous ceux qui partagent avec lui un nom de liste blanche. L’étape journalise un avertissement nommant les listes blanches concernées ; pepsi-whitelist list trouve la ligne.
La requête s’exécute sous un statement_timeout de cinq secondes. Une expression que PostgreSQL doit parcourir avec retour arrière, comme la référence arrière ^(.*)\1\1$, peut prendre des secondes face à un long From: et monopoliserait une connexion à la base de données pendant tout ce temps. Lorsque la limite se déclenche, le message est traité comme non inscrit en liste blanche (le même résultat qu’une absence de correspondance) et l’étape journalise un avertissement nommant les listes blanches concernées.
95.1.25.1.3.1. Ce qui est comparé¶
match_field sélectionne le sujet de la comparaison :
from(la valeur par défaut) : l’addr-spec analysée depuis l’en-têteFrom:du message, et non la valeur brute de l’en-tête. Une adresse en liste blanche écrite à la place du nom d’affichage ne peut donc pas simuler une correspondance, et les commentaires RFC 5322 ainsi que les espaces de repliement sont retirés. Un message sans en-têteFrom:ne correspond à rien, et il en va de même d’un message dont leFrom:nomme plus d’une boîte aux lettres. (Le verdict DKIM/DMARC que consultedkim_requireda été calculé pour la première adresse, de sorte que faire correspondre une autre trancherait deux questions portant sur deux expéditeurs différents.)list-id: l’identifiant de liste RFC 2919 issu de l’en-têteList-Id:du message, réduit au jeton entre chevrons, rogné et mis en minuscules (List-Id: Rust users <users.rust-lang.org>est comparé àusers.rust-lang.org). Un message sansList-Id:ne correspond à rien.
Une ligne list-id existe parce que les messages d’une liste de diffusion portent des adresses From: arbitraires. Aucun motif sur From: ne peut dire « tout ce qui est passé par cette liste », de sorte qu’un abonné devrait sinon mettre en liste blanche chaque contributeur individuel, ou payer la barrière pour chaque message que la liste relaie. Comparer List-Id: le dit une fois. Comme cet en-tête est un texte non authentifié que n’importe qui peut recopier, associez une telle ligne à sealer_domain (ci-dessous).
95.1.25.1.3.2. Plusieurs groupes, et listes blanches par utilisateur¶
WHITELIST_NAME est une liste séparée par des virgules, et une entrée peut être un modèle contenant {localpart} ou {login}, qui est développé par destinataire d’enveloppe
WHITELIST_NAME = correspondents, {localpart}/correspondents
Cela consulte la liste partagée de l’opérateur et celle propre à chaque destinataire. L’espace de noms <login>/... est celui que pepsi-whitelist(1) permet à un utilisateur ordinaire de gérer et de semer depuis sa boîte aux lettres ; c’est donc un modèle qui rend effective une liste blanche par utilisateur. Sans modèle, un tel nom n’est atteignable que par une redéfinition pepsi.settings par adresse (pepsi-settings(1)).
{localpart} se développe en la partie locale du destinataire, toute sous-adresse retirée (alice+lists@ → alice). {login} résout d’abord le destinataire en un login passwd, ce qui s’aligne sur l’espace de noms lorsque l’adresse n’est pas elle-même un login (first.last@ → alice) ; il faut donc que le destinataire se résolve localement. Placez par conséquent l’étape après pepsi-stage-aliases(1) lorsque vous l’utilisez. Un destinataire pour lequel un modèle ne peut pas être développé est ignoré, de même que tout développement sortant de la grammaire des noms de liste blanche (lettres, chiffres, _, . et - par segment séparé par /, et aucun segment composé uniquement de points).
Seul un destinataire à un domaine servi nomme une liste blanche. Les deux marqueurs ne sont développés que pour les destinataires dont le domaine figure dans LOCAL_DOMAINS (par défaut [pepsi-ingress] ACCEPTED_DOMAINS) ; un destinataire situé ailleurs est ignoré. Cela compte parce qu’une correspondance dans n’importe quelle liste consultée dédouane le message entier : la partie locale d’une adresse étrangère est choisie par qui a écrit l’enveloppe, de sorte que sans ce test un expéditeur déjà présent dans la liste blanche d’un utilisateur pourrait ajouter RCPT TO:<thatuser@anything.invalid> à un message destiné à quelqu’un d’autre et le faire dédouaner.
Tous les noms applicables sont vérifiés en une seule requête, et une correspondance dans l’un quelconque d’entre eux marque le message comme non-spam : le verdict est par message, et une ligne de la file d’attente est un message. Notez que cela met la confiance en commun entre les destinataires servis d’un même message : un message adressé à deux de vos utilisateurs est non-spam s’il correspond à la liste de l’un ou l’autre. Les options de localité LOCAL_DOMAINS, TARGETS et RECIPIENT_DELIMITER ne sont lues que pour développer ces marqueurs.
Une ligne peut en outre restreindre les cas où elle compte comme une correspondance :
dkim_required: la ligne ne correspond que si le domaineFrom:du message est authentifié, c’est-à-dire si l’ingress a notéstate.auth.dkim = pass, ou si pepsi-stage-arc(1) a notéstate.auth.arc = passet que DMARC a aussi réussi (state.auth.dmarc = pass). Un succès ARC seul ne montre que l’intégrité de la chaîne : un expéditeur qui contrôle un seul domaine quelconque peut frapper une chaîne ARC valide d’un seul saut sur unFrom:falsifié. Il n’est donc accepté que lorsque DMARC confirme l’alignement duFrom:.dmarc_required: la ligne ne correspond que si le message a réussi DMARC à l’ingress sur l’un ou l’autre identifiant aligné, une signature DKIM alignée ou une réussite SPF alignée (state.auth.dmarc = pass), ou si un scelleur ARC de confiance l’a laissé passer malgré un échec DMARC (state.auth.arc_override). C’est le niveau qui convient à un correspondant dont le domaine ne s’authentifie que par SPF, ce quedkim_requiredn’accepte pas ; une réussite SPF non alignée ne compte pas. Tout message qui satisfaitdkim_requiredle satisfait aussi.signature_required: la ligne ne correspond que sistate.signature_verifiedvauttrueet si la signature n’est pas issue d’un texte chiffré sans protection d’intégrité (unEnvelopedDataS/MIME, AES-CBC). pepsi-stage-decrypt(1) positionnestate.signature_verifiedpour un message qui porte une signature qu’il a vérifiée contre une clé de confiance. Qu’un tel texte chiffré, modifié par son expéditeur, produise encore une signature valide dépend de son remplissage, et le verdict décide si c’est le paiement pour envoyer ou la confirmation pour envoyer qui répond à l’expéditeur ; le prendre en compte ferait de cette réponse un oracle de remplissage.sealer_domain: la ligne ne correspond que si le message est arrivé porteur d’une chaîne ARC qui a validé (state.auth.arc = pass) et si l’ADMD nommé est l’un des scelleurs de cette chaîne (state.auth.arc_sealers, noté par pepsi-stage-arc(1)).
Lorsqu’une ligne fixe plusieurs conditions, toutes doivent être remplies.
sealer_domain est ce qui rend sûre l’écriture d’une règle portant sur un intermédiaire, et aucune des deux moitiés ne suffit seule. List-Id: ne prouve rien : c’est du texte qu’un expéditeur recopie d’un message authentique. Une chaîne ARC valide ne prouve rien non plus. La RFC 8617 §8.4 est explicite : elle ne transmet aucune confiance, seulement le fait que les ADMD qui y sont nommés ont réellement manipulé ces octets, et c’est exactement pourquoi n’importe qui peut en frapper une sur un message falsifié. Nommer le scelleur est la politique locale que le protocole laisse délibérément au destinataire : l’opérateur (ou l’utilisateur) énonce quel intermédiaire il accepte, et la chaîne prouve alors que cet intermédiaire a manipulé le message. Cela vaut aussi pour les lignes from, où cela restreint un motif d’expéditeur au courrier relayé par un redirecteur connu.
Notez que les domaines de state.auth.arc_sealers sont notés que la chaîne ait validé ou non, car ils sont la trace de ce qui a été prétendu ; l’étape les écarte tous à moins que state.auth.arc ne vaille pass, de sorte qu’une chaîne falsifiée ne peut jamais satisfaire une ligne sealer_domain. Pour une chaîne validée, la liste ne contient que les scelleurs dont le propre ARC-Message-Signature se vérifie encore sur le message, de sorte qu’un jeu authentique copié d’un autre message sur un contenu falsifié, et scellé par le faussaire, ne nomme pas non plus le scelleur copié.
Une ligne que pepsi-stage-auto-whitelist(1) a apprise à partir d’une réponse de confirmation d’abonnement porte aussi last_seen et max_idle. Elle ne correspond que jusqu’à last_seen + max_idle. Chaque fois qu’elle correspond à une contribution authentifiée, l’étape avance last_seen, au plus une fois par jour. (Authentifiée signifie : les mêmes conditions que pour la correspondance elle-même, de sorte qu’une contribution falsifiée qui échoue à dkim_required ne peut pas maintenir la ligne en vie.) Quitter une liste n’envoie aucun signal ; c’est cette expiration qui retire la ligne d’une liste où plus personne ne publie. Les lignes écrites à la main ou lors d’une invite d’import n’ont pas de last_seen et n’expirent jamais.
Si une ligne correspond (sous réserve de ses conditions), l’étape fusionne spam: false dans le state du message et avance. Sinon elle fait avancer le message inchangé.
95.1.25.1.3.3. Demandes de confirmation de listes de diffusion¶
Avec RECORD_LIST_CONFIRMATIONS (par défaut no), l’étape consigne aussi, dans pepsi.list_confirmation, chaque message qui ressemble à une demande de confirmation d’abonnement d’une liste de diffusion adressée à un destinataire local, afin que pepsi-stage-auto-whitelist(1) (son LIST_WHITELIST_NAME) puisse mettre la liste en liste blanche lorsque ce destinataire y répond. L’étape reconnaît une telle demande à partir du seul bloc d’en-têtes, et de façon délibérément étroite ; toutes ces conditions doivent être remplies :
exactement un identifiant
Message-ID:;un
Subject:contenantconfirmdans une casse quelconque (leconfirm <cookie>de Mailman 2, le « Your confirmation is needed to join … » de Mailman 3 et les propres avis de listes de Pepsi le contiennent tous) ;une adresse
From:,Reply-To:ouSender:dont la partie locale, sans son+detail, se termine par-request,-confirm,-joinou-subscribe(une adresse de contrôle de liste) ;un identifiant de liste : le
List-Id:si le message en a un valide, sinon le<name>.<domain>qu’implique l’adresse de contrôle (users-confirm+tok@lists.example.orgdonneusers.lists.example.org, l’identifiant par défaut de Mailman et des propres listes de Pepsi ; les demandes de Mailman ne portent pas deList-Id:).
Une ligne est écrite par destinataire d’enveloppe local (un destinataire hors de LOCAL_DOMAINS est ignoré), valable pendant LIST_CONFIRMATION_DAYS (7 par défaut) puis supprimée par pepsi-queue gc. Le premier enregistrement d’une demande l’emporte, de sorte qu’une copie remise à nouveau ne peut ni changer sa liste ni prolonger sa fenêtre. L’enregistrement est fail-open et le message n’est affecté d’aucune manière. N’importe qui peut envoyer un message qui passe ce test ; le consigner n’est pas lui faire confiance. Rien n’est mis en liste blanche tant que la propre réponse sortante du destinataire ne nomme pas la demande dans In-Reply-To: et ne part pas vers son adresse de contrôle, et la ligne apprise exige encore une contribution authentifiée.
95.1.25.1.4. Configuration¶
Les options résident dans la propre section [stage-<name>] de l’étape (PROGRAM = pepsi-stage-check-whitelist) : la liste WHITELIST_NAME obligatoire des groupes à consulter ; un NEXT_STAGE, obligatoire lui aussi (l’étape passe toujours le message plus loin, donc pepsi-setup rejette une section qui n’en a pas) ; les options de localité LOCAL_DOMAINS / TARGETS / RECIPIENT_DELIMITER ; et les options de listes de diffusion RECORD_LIST_CONFIRMATIONS (par défaut no) et LIST_CONFIRMATION_DAYS (par défaut 7, de 1 à 90). Les options de localité servent à développer un marqueur dans une entrée de WHITELIST_NAME, et LOCAL_DOMAINS décide en outre pour quels destinataires une demande de confirmation est consignée. LIST_CONFIRMATION_DAYS ne compte que lorsque RECORD_LIST_CONFIRMATIONS est activé. L’étape vérifie toutes ces options à son démarrage, qu’elle s’en serve ou non. Toutes ces options sont documentées dans pepsi.conf(5) ; les lignes de liste blanche elles-mêmes sont gérées avec pepsi-whitelist(1).
95.1.25.1.5. État¶
Entrées : state.auth.dkim / state.auth.arc / state.auth.dmarc (pour les lignes dkim_required), state.auth.dmarc / state.auth.arc_override / state.auth.dkim (pour les lignes dmarc_required), state.signature_verified (pour les lignes signature_required), que pepsi-stage-decrypt(1) ne positionne que pour son verdict de signature valid (une signature saine faite avec une clé qui n’a pu être ancrée, valid-untrusted, n’ouvre donc pas la barrière), ainsi que state.auth.arc / state.auth.arc_sealers (pour les lignes sealer_domain), tous deux écrits par pepsi-stage-arc(1). L’en-tête From: provient de la colonne from_header, non de state ; List-Id: est lu dans le bloc d’en-têtes du message, raison pour laquelle cette étape le charge (le corps n’est jamais chargé).
Sorties : en cas de correspondance, l’étape fusionne spam: false dans state (la clé que pepsi-stage-anti-spam(1) lit pour sauter la barrière de paiement) et avance ; sans correspondance, state est laissé intact. Effets de bord : le last_seen d’une ligne de liste apprise qui correspond est rafraîchi, et avec RECORD_LIST_CONFIRMATIONS une demande de confirmation est consignée dans pepsi.list_confirmation. La disposition de l’état est décrite dans pepsi.state(7).
Transitions : avance toujours vers NEXT_STAGE, que l’expéditeur ait ou non correspondu à la liste blanche. Une correspondance est validée avec le helper reroute, qui fusionne spam: false et déplace l’étape dans le même et unique UPDATE ; une non-correspondance est une simple avancée. Il n’y a pas de branche ; l’étape ne met jamais en pause, n’échoue, ne réachemine ni ne termine. La décision réelle de paiement/abandon est laissée à une étape ultérieure (pepsi-stage-anti-spam(1)).
95.1.25.1.6. Commandes¶
- worker
Exécuté comme un worker persistant de pepsi-dispatch(1), lisant les identifiants de message sur l’entrée standard.
95.1.25.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 (par défaut
[pepsi] LOG, sinoninfo).- -v, –verbose
Affiche les messages de journal de toutes les sources.
- -h, –help ; -V, –version
Affiche un résumé d’utilisation / la version et quitte.
95.1.25.1.8. Code de sortie¶
Le résultat de chaque message est rapporté à pepsi-dispatch(1) sur la ligne d’état du worker, et non comme code de sortie. Un message qui ne peut pas être vérifié (une erreur de base de données, un développement de {login} qui n’a pas pu interroger la base passwd) est mis en pause et réessayé, comme pour toute étape ; un whitelist_regex mal formé ou trop coûteux n’est pas du tout une erreur : cette ligne ne correspond à rien (voir ci-dessus).
- 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 : une section
[stage-*]qu’il sert ne s’analyse pas (par exemple un WHITELIST_NAME manquant, ou un LIST_CONFIRMATION_DAYS hors de l’intervalle 1 à 90). Le dispatcher remet en file ce qu’il lui avait confié et réessaie l’étape plus tard.
95.1.25.1.9. Exemples¶
Vérifier le message 42 par rapport à la liste blanche (il doit être running ; son résultat est affiché comme ligne d’état)
echo 42 | pepsi-stage-check-whitelist -c /etc/pepsi/pepsi.conf worker
Une section de pipeline qui met en liste blanche les expéditeurs de confiance avant la barrière de paiement
[stage-check-whitelist]
PROGRAM = pepsi-stage-check-whitelist
NEXT_STAGE = anti-spam
WHITELIST_NAME = trusted-senders
Consulter la liste partagée ainsi que celle propre à chaque destinataire, afin qu’une liste blanche qu’un utilisateur a semée avec pepsi-whitelist import soit honorée
[stage-check-whitelist]
PROGRAM = pepsi-stage-check-whitelist
NEXT_STAGE = anti-spam
WHITELIST_NAME = trusted-senders, {localpart}/correspondents
Mettre en liste blanche un domaine partenaire, mais seulement lorsque son courrier est signé en DKIM/ARC
INSERT INTO pepsi.whitelist (whitelist_name, whitelist_regex, dkim_required)
VALUES ('trusted-senders', '@partner\.example\.org$', TRUE);
dkim_required vaut par défaut TRUE lorsqu’un INSERT l’omet, comme le fait pepsi-whitelist add ; une ligne qui fait confiance au courrier non signé doit indiquer dkim_required = FALSE explicitement. Il vaut mieux soumettre un partenaire dont le domaine ne signe pas mais publie DMARC et SPF à dmarc_required
pepsi-whitelist add trusted-senders --no-dkim-required --dmarc-required '@partner\.example\.org$'
Laisser passer une liste de diffusion au-delà de la barrière de paiement, quel qu’en soit le contributeur, mais seulement lorsque l’ADMD propre à la liste a scellé la chaîne ARC du message
pepsi-whitelist add-list alice/lists users.rust-lang.org \
--sealer mail.rust-lang.org
Apprendre, en direct, les listes auxquelles les utilisateurs s’abonnent en répondant à une demande de confirmation. Cette étape consigne la demande, pepsi-stage-auto-whitelist(1) apprend la liste sur le chemin sortant dans le <login>/lists de chaque utilisateur, et cette étape le consulte
[stage-check-whitelist]
PROGRAM = pepsi-stage-check-whitelist
NEXT_STAGE = anti-spam
WHITELIST_NAME = trusted-senders, {login}/correspondents, {login}/lists
RECORD_LIST_CONFIRMATIONS = yes
[stage-auto-whitelist]
PROGRAM = pepsi-stage-auto-whitelist
NEXT_STAGE = dkim-sign
WHITELIST_NAME = trusted-senders
LIST_WHITELIST_NAME = {login}/lists
Faire délibérément confiance au seul en-tête, pour une liste qui ne scelle pas en ARC. Un attaquant n’a qu’à recopier un List-Id: pour satisfaire une telle ligne : limitez-en donc la portée à la liste blanche propre d’un utilisateur plutôt qu’à une liste partagée
pepsi-whitelist add-list alice/lists announce.example.org --no-dkim-required
95.1.25.1.10. Voir aussi¶
pepsi-config(1), pepsi-whitelist(1), pepsi-stage-anti-spam(1), pepsi-stage-arc(1), pepsi-settings(1), pepsi-dispatch(1), pepsi.conf(5), pepsi.state(7), pepsi-setup(1)
95.1.25.1.11. Bogues¶
Signalez les bogues au gestionnaire de tickets de Pepsi.