58. pepsi-stage-secretary¶
Hold mail from unknown senders until they confirm by replying.
58.1. Role¶
pepsi-stage-secretary is confirm-to-send, after qmail’s qsecretary. Mail from a
sender that no whitelist knows is held, and the sender is asked, in their own
language, to reply once. The reply whitelists them and releases everything held for them;
later mail from them passes pepsi-stage-check-whitelist and is never held
again. Without a reply by HOLD_TIME the held mail takes the timeout path
(BOUNCE_STAGE if one is wired, else it is deleted). Reference:
pepsi-stage-secretary(1).
It is weaker than pay-to-send (pepsi-stage-anti-spam): a spammer with a
working mailbox can reply, and the declaration that the sender agrees to
(PENALTY) is a legal deterrent rather than an economic one. It is still worth
having, because most bulk mail comes from addresses that cannot receive, and a
real correspondent only has to reply once. Supported Features compares the two.
58.2. What is challenged¶
Locally submitted mail and a whitelisted sender (state.spam = false) pass
untouched; state.spam = true takes the timeout path. A null-sender message
cannot be challenged, so it passes only with a proof that it answers mail that
this host sent: a Pepsi-Origin field that verifies and whose nonce is still
tracked. Without that proof it is unchallengeable, so a forged bounce cannot
carry a stranger’s mail past the gate (with [pepsi-origin] ENABLED = no
nothing can be proven and every bounce passes). Everything else is challenged,
except in the cases below, where the message goes to UNCHALLENGEABLE_STAGE
(or takes the timeout path when that is unset):
RFC 3834 says do not answer it (lists,
Precedence: bulk,Auto-Submitted:, service senders, delivery reports), or the sender failed SPF or DMARC outright (afailverdict;softfail,neutralandnonedo not count); these are the shared rules for automatic replies, which pepsi-stage-vacation also applies;the sender is also one of the recipients;
its
From:is not exactly the envelope sender (the challenge goes to MAIL FROM and the whitelist matchesFrom:, so they must be one address);REQUIRE_AUTHENTICATED(default on) is set and neither SPF nor DMARC passed, which guards against backscatter;the sender has had
MAX_CHALLENGES_PER_SENDER(default 5) challenges in the last 24 hours, across every whitelist;WHITELIST_NAMEdoes not expand for the recipients, or there is no served domain to put the reply address at.
One challenge covers every message from one sender to one whitelist: a second
message joins the open challenge and inherits its deadline. A message whose
recipients expand WHITELIST_NAME to different lists is split one row per list.
58.3. The challenge and the reply¶
The challenge is a null-sender text/plain message with Auto-Submitted:
auto-replied, injected at RESPONSE_STAGE. Its From: and Reply-To: are
the reply address <CONTROL_LOCAL_PART>-<cookie>@<domain> (default
secretary-…), whose cookie is a random 128-bit identifier. It never quotes the
held message, since a challenge to a forged sender would otherwise deliver the
spam for the spammer. It shows only an 8-character hint of the subject
(SUBJECT_HINT_LENGTH) and the sender’s display name, and not even those to a
sender that did not pass SPF or DMARC (challenged only under
REQUIRE_AUTHENTICATED = no).
The text comes from MESSAGE_<LANG> in the stage’s own section (a user’s own,
through the settings layer) or the secretary-challenge.<lang>.body template,
per language, with a built-in English fallback; the fields are SENDER_NAME,
RECIPIENT, SUBJECT_HINT, ORIGINAL_DATE, DEADLINE,
REPLY_ADDRESS and PENALTY. The language is chosen, and the two-space rule
applied, as in pepsi-stage-vacation. The challenge and the confirmation
notice ship in the same ten languages as every other notice (English, German, Spanish, French,
Hungarian, Italian, Russian, Swedish, Turkish and Ukrainian), and so do their
subject lines: a SUBJECT_<LANG> option wins, then the shipped subject for
the language the text was chosen in, then SUBJECT. An explicit
SUBJECT switches the shipped translations off, because an operator who
wrote their own subject wants it in every language for which they did not also
write a SUBJECT_<LANG>.
A reply to the address confirms when it comes from the challenged address (its
envelope sender or From:). A null-sender reply means the challenge bounced, and
releases the held mail to the timeout path at once; a reply marked as automatic
(an out-of-office) is ignored. A reply after the deadline has no effect: the
challenge is gone. The reply itself is always consumed.
58.4. Placement¶
After pepsi-stage-detect-language and pepsi-stage-check-whitelist,
before pepsi-stage-aliases, the list router and local delivery. Run
pepsi-stage-auto-whitelist into the same WHITELIST_NAME on the outbound
path so the people your users write to are never challenged. pepsi-setup’s
wizard wires all of it when asked “Ask unknown senders to confirm by reply”.
58.5. Configuration¶
[stage-<name>]: PROGRAM = pepsi-stage-secretary, NEXT_STAGE and
RESPONSE_STAGE (mandatory), WHITELIST_NAME (mandatory, one name or a
{login}/{localpart} template; the operator may name any whitelist, a
shared one included, while a value that an account owner sets by mail must stay
in their <login>/... namespace or be the operator’s;
pepsi-stage-edit-settings enforces this when it stores the value),
BOUNCE_STAGE, UNCHALLENGEABLE_STAGE,
CONTROL_LOCAL_PART, HOLD_TIME, REQUIRE_AUTHENTICATED,
MAX_CHALLENGES_PER_SENDER, DKIM_REQUIRED, CONFIRM_NOTICE, PENALTY,
SUBJECT_HINT_LENGTH, TEMPLATE, SUBJECT, DEFAULT_LANGUAGE, the
MESSAGE_<LANG>/SUBJECT_<LANG>/CONFIRM_MESSAGE_<LANG> overrides and the
locality options. pepsi-setup rejects unresolvable targets and a
DEFAULT_LANGUAGE with no text, and warns when no check-whitelist consults the
whitelist, no auto-whitelist writes it, CONTROL_LOCAL_PART is a login or an
alias, or proof-of-origin is switched off. See pepsi-stage-secretary(1) and Configuration.
58.6. State¶
Inputs:
state.spam,state.local_origin,state.auth(SPF, DMARC, DKIM, ARC),state.language; the whole message of a null-sender row, for itsPepsi-Originproof.Outputs:
state.secretaryon a held row (challenge,deadline,whitelist; thenconfirmedorabandoned),state.secretary.unchallengeableon mail routed toUNCHALLENGEABLE_STAGE, andstate.spam = falseon released mail. The timeout path removesstate.secretary.state.dsnis preserved.Transitions: advance to
NEXT_STAGE; pause while held; reroute toUNCHALLENGEABLE_STAGEorBOUNCE_STAGE; delete a reply, or timed-out mail when there is noBOUNCE_STAGE.
58.7. Database¶
pepsi.secretary_challenge (one open challenge per whitelist and sender, deleted
when it is answered, bounces or expires) and pepsi.secretary_sent (when each
challenge was sent, without its cookie, for the daily cap). A confirmation writes an
ordinary pepsi.whitelist row, escaped and anchored exactly as
pepsi-stage-auto-whitelist writes one. Under DKIM_REQUIRED = auto (the
default) the row demands dkim_required when a held message passed DKIM, and
otherwise dmarc_required when one passed DMARC (an aligned SPF pass
suffices), recorded per challenge in dkim_seen / dmarc_seen; only when
neither passed is it written without a requirement.
58.8. Security¶
A challenge goes to an envelope sender that nobody has verified, so the stage
must meet the backscatter claims of A remote sender and the per-sender
rate of Availability (MAX_CHALLENGES_PER_SENDER). Against
backscatter it relies on the RFC 3834 and authentication-failure rules,
REQUIRE_AUTHENTICATED and quoting nothing of the held message. Every option but NEXT_STAGE and
BOUNCE_STAGE is per-address overridable; what a user may set by e-mail is
bounded as Per-address settings are a trust boundary describes, WHITELIST_NAME additionally to their
own namespace.
58.9. See also¶
pepsi-stage-check-whitelist, pepsi-stage-auto-whitelist, pepsi-stage-anti-spam, pepsi-whitelist, pepsi-settings, Supported Features, pepsi-stage-secretary(1).