36. pepsi-stage-srs¶
Sender Rewriting Scheme — make SPF pass at the next hop.
36.1. Role¶
pepsi-stage-srs rewrites the envelope sender into a local address of a
Pepsi-controlled SRS_DOMAIN so the next hop’s SPF check passes. The reverse
direction (decoding bounces returned to an SRS address) is done by
pepsi-ingress at RCPT time. Both read the shared [pepsi-srs]
section. Reference: pepsi-stage-srs(1).
36.2. Features¶
Forward rewrite:
MAIL FROMbecomesSRS0=HHHH=TT=domain=local@srs, HMAC-signing the original sender and stamping a day-granular timestamp; the truncated MAC is base32-encoded (RFC 4648).Compact re-signing: an address that is already SRS (mail reached Pepsi through another forwarder) is re-signed in the
SRS1form rather than nested, so a bounce hops back one forwarder at a time.Idempotent / safe: the null sender (a returning bounce) is never rewritten, and a sender already in
SRS_DOMAINis left unchanged.Reverse decode (in ingress): a recipient that is a valid SRS token is verified (signature + timestamp) and relayed to the decoded original sender, even outside served domains; a forged/expired token is rejected
550.Forward return address for forwarded copies: a recipient that an alias or a
~/.forwardproduced (state.dsn.rcpt[].expanded_from) leaves withfwd+<sealed>=<tag>@srsinstead, sealing the original sender, the address the sender used, the encrypted-arrival flag, the sender’s authentication andNOTIFY, and the day. A remote report about the copy is then answered by pepsi-ingress with this host’s own DSN about the address the sender used, never relayed (Forwarding addresses in delivery reports). A row whose recipients need different envelope senders is split to one recipient per row first.Body untouched: only the envelope sender changes; DKIM body hashes survive.
Operator tools:
forward/reversesubcommands compute a rewrite or decode an address by hand.
36.3. Configuration¶
[stage-<name>]: PROGRAM = pepsi-stage-srs and NEXT_STAGE. The SRS
parameters are shared in [pepsi-srs]: SRS_DOMAIN,
SECRET/SECRET_FILE (the HMAC key; must stay stable and identical across
instances), PREVIOUS_SECRET_FILE (retired keys that still verify returning
addresses but sign nothing, so the key can be rotated: Rotating the SRS key in
Operating Pepsi), MAX_AGE_DAYS (validity window, default 21) and
ALLOW_ALIGNED_DOMAIN. SRS_DOMAIN must be a dedicated domain that is not
DMARC-aligned with any served domain. The SPF pass that a forward earns at the
next hop is a pass for this domain, and an aligned domain would let a forged
message of a served domain pass DMARC once it is forwarded from here. pepsi-setup refuses an aligned
domain unless ALLOW_ALIGNED_DOMAIN = yes (see Forwarded forgeries of our
own domain in Security model, upholding A remote sender); when the
wizard imports a server with a postsrsd, its SRS domain becomes the default.
Omitting [pepsi-srs] disables SRS: the worker then refuses to start and the
dispatcher holds its messages. Never list the stage in EDITABLE_STAGES: it
protects the domain’s reputation, not a user’s preference (Per-address settings are a trust boundary).
See pepsi-stage-srs(1).
36.4. State¶
Inputs: the
mail_fromcolumn;state.dsn.rcpt[].expanded_fromand.notify,state.crypto.inand the authentication record (state.auth,state.local_origin), which a forward return address seals.Outputs:
state.srs.original— the envelope sender as it was before the rewrite, written only when a rewrite happened and only if the key is not already there (so a second,SRS1pass keeps the earliest real correspondent). When this deployment originates a DSN, pepsi-stage-bounce addresses it to this sender rather than to our own SRS alias. Everything else instate, includingstate.dsn, is preserved.
36.5. See also¶
pepsi-ingress, pepsi-stage-relay-to-internet, Supported Features, pepsi-stage-srs(1).