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, elseinfo).- -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.