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 FROM becomes SRS0=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 SRS1 form 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_DOMAIN is 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 ~/.forward produced (state.dsn.rcpt[].expanded_from) leaves with fwd+<sealed>=<tag>@srs instead, sealing the original sender, the address the sender used, the encrypted-arrival flag, the sender’s authentication and NOTIFY, 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/reverse subcommands 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_from column; state.dsn.rcpt[].expanded_from and .notify, state.crypto.in and 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, SRS1 pass 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 in state, including state.dsn, is preserved.

36.5. See also

pepsi-ingress, pepsi-stage-relay-to-internet, Supported Features, pepsi-stage-srs(1).