95.1.5. pepsi-stage-srs

rewrite the envelope sender with the Sender Rewriting Scheme

Manual section:

1

95.1.5.1.1. Name

pepsi-stage-srs - SRS envelope-sender rewriting stage of the Pepsi pipeline.

95.1.5.1.2. Synopsis

pepsi-stage-srs [GLOBAL-OPTIONS] worker

pepsi-stage-srs [GLOBAL-OPTIONS] forward ADDRESS

pepsi-stage-srs [GLOBAL-OPTIONS] reverse ADDRESS

95.1.5.1.3. Description

This stage defaults to FUSION = yes: when stage fusion is enabled ([pepsi] ALLOW_FUSION, the default) and this stage is folded into the unified pepsi binary, a predecessor may run it in its own worker process instead of dispatching it separately. See pepsi-dispatch(1) and pepsi.conf(5).

pepsi-stage-srs is a stage program run by pepsi-dispatch(1) as a persistent worker reading message ids on standard input. It implements the Sender Rewriting Scheme (SRS).

When Pepsi forwards a message it keeps the body intact but relays it from its own IP addresses. The next hop’s SPF check then sees Pepsi sending mail whose envelope sender is still the original sender’s domain, which does not authorise Pepsi’s IPs, and the check fails. SRS solves this by rewriting the envelope sender (MAIL FROM) into a local address of a Pepsi-controlled domain (SRS_DOMAIN) that encodes the original sender and signs it with an HMAC:

SRS0=HHHH=TT=origin.example=alice@srs.example.net

SPF at the next hop now checks srs.example.net, which legitimately sends from Pepsi’s IPs. The body and its DKIM signatures are untouched. The stage then advances the message to its NEXT_STAGE (the delivery stage). Besides the envelope sender, it changes only state.srs.original, where it records the original sender. The rest of the row’s state, including any RFC 3461 state.dsn parameters, stays untouched for later stages to honour.

The null sender (<>, i.e. a returning bounce) is never rewritten, and a sender already in SRS_DOMAIN is left unchanged (rewriting is idempotent). A sender that is already an SRS address, because the message reached Pepsi through another forwarder, is re-signed in the compact SRS1 form rather than being nested, so that a bounce hops back one forwarder at a time.

95.1.5.1.3.1. A dedicated domain

SRS_DOMAIN must be a domain of its own, not DMARC-aligned with any domain that this host serves. The rewrite runs for every forwarded message, whatever its DMARC result on arrival, and the SPF pass that it gains at the next hop is a pass for SRS_DOMAIN. If that domain aligns with the message’s From: domain, because it is the served domain itself, a subdomain or a parent of it, the pass is an aligned one, and DMARC passes on it alone. Consider a message forged as a served domain, received from outside (where it failed DMARC) and sent to an address that forwards. It would then leave this host passing DMARC: forwarding launders the forgery. With a dedicated domain SPF still passes, but it does not align with the From:, so DMARC at the next hop has to rest on the author’s own DKIM signature, which a faithful forward keeps and a forgery never had. (The signature that pepsi-stage-dkim-sign(1) may add to forwarded mail is withheld for a message that failed DMARC on arrival, so it cannot launder one either.)

pepsi-setup(1) therefore refuses an SRS_DOMAIN aligned with an ACCEPTED_DOMAINS entry or another sending identity, unless [pepsi-srs] ALLOW_ALIGNED_DOMAIN = yes accepts it. It then warns and names what closes the route (aspf=s in the served domain’s DMARC record for a subdomain, or an enforcing p= with [pepsi-ingress] DMARC_ENFORCE = yes), and pepsi-setup check verifies that against live DNS. The wizard asks for a dedicated domain instead of defaulting to the primary one. The operator publishes the domain’s DNS: an MX record pointing at this host (see below), and the SPF record that pepsi-setup(1) prints for it, as for every sending identity. Nobody writes mail from this domain, so its DMARC record may say p=reject. When the wizard imports an existing mail server and a postsrsd beside it already rewrites into a domain, that domain is offered as the default (bounces of mail forwarded before the migration are addressed to it); an aligned one is refused there too. The reasoning is set out under “Forwarded forgeries of our own domain” in the security chapter of the Pepsi manual.

95.1.5.1.3.2. Reverse direction

pepsi-ingress(1) performs the other half of SRS at RCPT time, not this program: it recognises a bounce returned to an SRS address, verifies its signature and timestamp, decodes the original sender and relays the bounce there. A recipient in SRS_DOMAIN whose local-part is a valid SRS token is accepted and rewritten back to the original sender (even though that sender’s domain is not one that Pepsi serves: the valid signature authorises the relay); a forged or expired token is rejected with 550. Both directions read the same shared [pepsi-srs] configuration, so the secret and domain match.

This half is what makes SRS_DOMAIN a domain that must receive mail, not merely one that this host sends as. Rewriting the envelope sender makes Pepsi the bounce destination for a message that it did not write; if the domain publishes no MX and no address record, the returning bounce is discarded by the MTA that tried to send it and the original author is never told. pepsi-setup(1) checks for this on every run, under its DNS cross-checks, because the domain’s SPF and DMARC records look complete without it.

95.1.5.1.3.3. Forwarded copies

A copy that an alias (pepsi-stage-aliases(1)) or a ~/.forward (pepsi-stage-dot-forward(1)) sends off-site does not get an SRS address. Such a recipient carries state.dsn.rcpt[].expanded_from (the address that the sender used), and the row leaves with a forward return address instead:

fwd+<sealed record>=<tag>@srs.example.net

The record is encrypted and authenticated with keys derived from the SRS secret (HMAC-SHA256 in the SIV pattern, an 80-bit tag; the address is lower-case base32). It holds the original envelope sender, the address that the sender used, whether the message arrived encrypted, whether the sender was authenticated, the sender’s NOTIFY for that recipient and the day it was minted; none of it is readable in the address. A report that a remote host sends about the copy comes back to pepsi-ingress(1). Ingress accepts it only from the null sender and only while the record verifies and is younger than MAX_AGE_DAYS, and answers with a DSN of this host’s own about the address that the sender used. The remote report is logged and dropped: it would reveal the forwarding target, the reply of the host behind it and, for a message that arrived encrypted, the decrypted content. An SRS address would have relayed that report to the sender unchanged.

The address is stateless (nothing is stored) and therefore long: two addresses do not fit the 64 octets that RFC 5321 gives a local part, and a typical one is 80 to 120 characters, like the SRS address of a long sender. Its length is not capped: a next hop that refuses a long envelope sender fails the delivery, and the DSN that this host then writes names the address that the sender used, like any other DSN. An SRS address in its place would let anybody who chooses a long envelope sender reopen the path that the forward return address closes. Only a sender that cannot be sealed at all (longer than 254 octets) makes the copy leave with the null sender, with a warning in the log. The null sender itself is never rewritten, so a bounce that is forwarded keeps <>; a sender already in SRS_DOMAIN is left alone.

The envelope sender is one per row. A row whose recipients would need different senders, such as a forwarded copy and an ordinary relay, or copies for two different aliases, is therefore first split into one row per recipient, each of which comes back to this stage on its own.

95.1.5.1.4. Configuration

The stage needs only a NEXT_STAGE in its own [stage-<name>] section (PROGRAM = pepsi-stage-srs); the SRS parameters (SRS_DOMAIN, SECRET/SECRET_FILE, PREVIOUS_SECRET_FILE, MAX_AGE_DAYS, ALLOW_ALIGNED_DOMAIN) live in the [pepsi-srs] section, which the stage shares with pepsi-ingress(1). All are documented in pepsi.conf(5). Omitting [pepsi-srs] disables SRS: a worker of this stage then refuses to start (as it does when the secret cannot be read), so the dispatcher holds the messages queued for it until the configuration is fixed rather than failing them, and pepsi-ingress(1) treats SRS-looking recipients as ordinary addresses. The secret is re-read for every message, so a rotated secret needs no restart; if it becomes unreadable while a worker runs, the message is retried with back-off (see pepsi-dispatch(1)). The stage signs with SECRET alone; PREVIOUS_SECRET_FILE names retired secrets that pepsi-ingress(1) still accepts on returning addresses, so the secret can be replaced without breaking the addresses already in circulation.

95.1.5.1.5. State

Inputs: the mail_from column; state.dsn.rcpt[].expanded_from and .notify (which recipients are forwarded copies), state.crypto.in and the authentication record state.auth / state.local_origin (sealed into a forward return address).

Outputs: state.srs.original, the envelope sender the rewrite replaced. Nothing else in state is touched; state.dsn and the rest are preserved unchanged. The state layout is described in pepsi.state(7).

That one key exists for a DSN that Pepsi originates after this stage has run, which is every DSN on a relaying path: this stage necessarily precedes the delivery stage, so pepsi-stage-bounce(1) would otherwise address the report to our own SRS alias and make it take a round trip out to the next hop and back in through our MX to be decoded. The bounce stage reads this instead of reversing the alias, which keeps the SRS secret out of a stage that only composes mail. It is written only when absent, so a message rewritten twice keeps the address that names a real correspondent rather than the intermediate alias.

Transitions: advances to NEXT_STAGE, whether the envelope sender was rewritten or passed through unchanged (a null sender, or one already in SRS_DOMAIN). A row whose recipients need different envelope senders is split to one recipient per row and requeued at this stage. The stage never pauses, fails, reroutes or finishes.

95.1.5.1.6. Commands

Run as a worker, the program rewrites each message’s envelope sender and advances it. The subcommands are operator tools:

forward ADDRESS

Print the SRS rewrite of ADDRESS (the forward direction) and exit. Useful for inspecting what a given sender becomes.

reverse ADDRESS

Decode and verify ADDRESS (an SRS address or bare local-part) and print the original sender, or fail if it is not a valid SRS address.

95.1.5.1.7. Global Options

-c FILE, –config FILE

Read the configuration from FILE instead of the default search path.

-L LOGLEVEL, –log LOGLEVEL

Set the logging verbosity (error, warn, info, debug, trace; default [pepsi] LOG, else info).

-h, –help

Print a usage summary and exit.

-V, –version

Print the version and exit.

95.1.5.1.8. Exit Status

The outcome of each message is reported to pepsi-dispatch(1) on the worker’s status line, not as the exit status.

0

The worker ran until its standard input was closed, or the forward / reverse subcommand succeeded.

1

A fatal error occurred (unreadable configuration, the database could not be opened, standard input/output failed, or reverse was given an address that is not a valid SRS address). The reason is written to the log.

78

The worker refused to start: [pepsi-srs] is missing, does not parse or its secret cannot be read (or the database schema does not match this binary). The dispatcher requeues what it handed over and retries the stage later.

95.1.5.1.9. Examples

Show what a sender is rewritten to:

pepsi-stage-srs -c /etc/pepsi/pepsi.conf forward alice@origin.example

Decode a returned bounce address:

pepsi-stage-srs -c /etc/pepsi/pepsi.conf reverse 'SRS0=HHHH=TT=origin.example=alice@srs.example.org'

95.1.5.1.10. See Also

pepsi-config(1), pepsi-stage-relay-to-smarthost(1), pepsi-stage-relay-to-internet(1), pepsi-stage-bounce(1), pepsi-stage-dkim-sign(1), pepsi-dispatch(1), pepsi-ingress(1), pepsi.conf(5), pepsi.state(7), pepsi-setup(1)

95.1.5.1.11. Bugs

Report bugs to the Pepsi issue tracker.