50. pepsi-stage-check-whitelist¶
Mark mail from trusted senders as non-spam.
50.1. Role¶
pepsi-stage-check-whitelist consults a named whitelist of trusted senders and,
when the message’s From: header matches, records state.spam = false so a
later pepsi-stage-anti-spam lets the message through without payment. Place
it ahead of the anti-spam stage. It only annotates the state and advances; it
never drops, bounces or pauses a message. Reference:
pepsi-stage-check-whitelist(1).
50.2. Features¶
Database-backed whitelists: the
pepsi.whitelisttable groups rows under awhitelist_name.WHITELIST_NAMEis a comma-separated list of the groups to consult, and an entry may be a template containing{localpart}or{login}, expanded per envelope recipient.WHITELIST_NAME = correspondents, {localpart}/correspondentsthus consults the operator’s shared list and each recipient’s own list, in the namespace that pepsi-whitelist lets that user manage. Only a recipient at a local domain may name a whitelist (otherwise an attacker-chosen co-recipient would expand to any local user’s list), and{login}additionally needs the address to resolve to a passwd account, so place the stage after pepsi-stage-aliases when using it. Every applicable name is checked in one query.POSIX ERE matching: each
whitelist_regexis an extended POSIX regular expression, matched case-insensitively against the field that the row’smatch_fieldnames. The match uses PostgreSQL’s~*operator in a single round-trip and is cancelled after five seconds; a cancelled match counts as no match, so a pathological pattern cannot tie up a database backend. The fields are:from(the default) — the addr-spec parsed out of theFrom:header, never the raw header value: otherwise a whitelisted address sitting in the display-name position would spoof a match. RFC 5322 comments and CFWS are removed, and aFrom:naming more than one mailbox matches nothing (the DKIM/DMARC verdict is computed for the first address, so matching a later one would answer two questions about two senders).list-id— the RFC 2919 identifier of the message’sList-Id:header. A mailing list’s postings carry arbitraryFrom:addresses, so nofrompattern can say “anything that came through this list”.
The expression itself is unanchored; anchor it with
^/$to match a whole address (which is what pepsi-stage-auto-whitelist writes).A row whose expression is one exact address or list identifier, or any mailbox at one domain (the shapes pepsi-whitelist and pepsi-stage-auto-whitelist write, when the text is ASCII), is found through an index rather than by evaluating the expression. The result is the same; only the other rows are evaluated one by one, so the cost of the check does not grow with the number of learnt correspondents.
Optional conditions per row:
dkim_required→ matches only if theFrom:domain is authenticated:state.auth.dkim = pass, or an ARC pass that DMARC also confirms (state.auth.arc = passandstate.auth.dmarc = pass). ARC pass alone is only chain integrity (a one-hop chain can be self-minted over a forgedFrom:), so it does not satisfy the row by itself. The column defaults to true, aspepsi-whitelist adddoes.dmarc_required→ matches only if the message passed DMARC at ingress on either aligned identifier, an aligned DKIM signature or an aligned SPF pass (state.auth.dmarc = pass), or a trusted ARC sealer let it through a DMARC failure (state.auth.arc_override). This is the level for a correspondent whose domain does not DKIM-sign; an unaligned SPF pass does not count, and everydkim_requiredpass satisfies it. When a row sets several conditions, all of them must hold.signature_required→ matches only ifstate.signature_verifiedistrue, which pepsi-stage-decrypt sets for a message whose end-to-end signature verified against a trusted key. Avalid-untrustedverdict deliberately does not set it, so such a row is a genuine “this correspondent signs, verifiably” gate rather than a “someone signed this” one. Place a decrypt stage before this one, or the row never matches. A signature from an S/MIMEEnvelopedData(AES-CBC) does not count: whether a modified CBC ciphertext still verifies depends on its padding, and the verdict decides whether the sender is asked to pay or to confirm (CBC padding and format oracles against unauthenticated S/MIME).sealer_domain→ matches only if the message arrived with an ARC chain that validated and the named ADMD is among its sealers (state.auth.arc = passand the domain instate.auth.arc_sealers). This is what makes alist-idrow safe:List-Id:is unauthenticated text that anyone can copy, and a valid ARC chain conveys no trust by itself (RFC 8617 §8.4). Naming the sealer is what turns the pair into evidence.
Expiring list rows: a
list-idrow learnt by pepsi-stage-auto-whitelist matches only untillast_seen + max_idle; each authenticated posting it matches moveslast_seenforward (at most daily), andpepsi-queue gcdeletes it once it lapses.Recording confirmation requests: with
RECORD_LIST_CONFIRMATIONS, a message that looks like a list’s subscription confirmation request (a singleMessage-ID:,confirmin theSubject:, a-request/-confirm/-join/-subscribesender orReply-To:) is recorded per local recipient forLIST_CONFIRMATION_DAYS(7), so the auto-whitelist stage can learn the list from that recipient’s reply. Recording trusts nothing.Non-destructive: on a match it merges
spam: falseand advances toNEXT_STAGE; on no match it advances unchanged. A message with noFrom:header, and one to which no configured whitelist name applies, match nothing.
50.3. Configuration¶
[stage-<name>]: PROGRAM = pepsi-stage-check-whitelist, WHITELIST_NAME
(required; the comma-separated list of whitelist_name groups, literal or
templated), NEXT_STAGE (required, because the stage always hands the message on),
and the shared locality options LOCAL_DOMAINS (defaulting to
[pepsi-ingress] ACCEPTED_DOMAINS), TARGETS and RECIPIENT_DELIMITER,
which are used to expand the placeholders and to keep confirmation requests
to local recipients, and RECORD_LIST_CONFIRMATIONS (default no) /
LIST_CONFIRMATION_DAYS (default 7). See
pepsi-stage-check-whitelist(1).
50.4. State¶
Inputs:
state.auth.dkim/state.auth.arc/state.auth.dmarc(fordkim_requiredrows),state.auth.dmarc/state.auth.arc_override(fordmarc_requiredrows),state.auth.arc_sealers(forsealer_domainrows) andstate.signature_verified(forsignature_requiredrows; written by pepsi-stage-decrypt). TheFrom:header comes from thefrom_headercolumn;List-Id:is read from the header block, which is why this stage loads the headers (but never the body).Outputs: on a match,
spam: falsemerged intostate; otherwisestateis unchanged. Side effects: a matched learnt list row’slast_seenis refreshed, and withRECORD_LIST_CONFIRMATIONSa confirmation request is written topepsi.list_confirmation.
50.5. See also¶
pepsi-stage-anti-spam, pepsi-stage-arc, Supported Features,
pepsi-stage-check-whitelist(1). Security: the forged mail a
whitelist must not admit (A remote sender), the bound on user-written
patterns (Availability), why the stage should not be listed in
EDITABLE_STAGES when filtering is mandatory (Per-address settings are a trust boundary), and who
may write the table (The privilege split).