12. SMTP Protocol Extensions¶
Pepsi advertises these standard ESMTP service extensions in its EHLO
response (pepsi-ingress; the governing standards are in
RFC Index): SIZE (RFC 1870), 8BITMIME (RFC 6152), SMTPUTF8
(RFC 6531), PIPELINING (RFC 2920), CHUNKING (RFC 3030, without
BINARYMIME), DSN (RFC 3461), ENHANCEDSTATUSCODES (RFC 2034) and
RRVS (RFC 7293) always; STARTTLS (RFC 3207) while a starttls
listener’s session is still cleartext; and REQUIRETLS (RFC 8689) and
AUTH (RFC 4954) only once the session is TLS-protected. The outbound
client honours the same set at the next hop: DSN, 8BITMIME,
SMTPUTF8, RRVS and REQUIRETLS parameters are sent only to a hop
that advertises them, and content or requests are downgraded or refused as
each standard says when it does not (Supported Features).
Beyond those, Pepsi defines two message header fields of its own:
the
Pepsi-Origin:proof-of-origin header, stamped on outbound mail; andthe
Taler:payment header, which advertises a pay-to-send payment request to a wallet.
Neither is registered with IANA under RFC 3864. Both are private extensions that only a Pepsi deployment (and, for the payment header, a GNU-Taler-aware wallet) interprets, and both are optional fields in the sense of RFC 5322 §3.6.8: a field name of printable US-ASCII followed by an unstructured value, which every conforming MTA relays untouched and every conforming reader ignores if it does not recognise it.
Pepsi names its header fields by what they are for. The two protocol fields
above travel between deployments and carry no X- prefix: RFC 6648 deprecates
X- because a field that succeeds has to be renamed, breaking every
implementation that adopted it early.
The fields that only annotate a message for its local recipient, or carry a
request from a local mail client, share the X-Pepsi-* namespace, which is
never meant to reach another deployment: X-Pepsi-Crypto,
X-Pepsi-Detected-Languages, X-Pepsi-Sign and the rest.
pepsi-stage-decrypt
strips that whole namespace off inbound mail except ingress’s own
X-Pepsi-Warning, and ingress removes an inbound X-Pepsi-Warning before
it adds its own, so no remote sender can forge a
local verdict (see GnuPG status-line and output injection fools front ends; what each
indicator promises is stated in What a security indicator means). The same rule is
why Pepsi-Origin: must stay outside it: a proof of origin in the namespace
would be stripped exactly on the returning bounce where it is needed. The local
fields are documented with the stage that writes or reads them, not here.
12.1. The Pepsi-Origin: proof-of-origin header¶
When Pepsi relays an outbound message off-site it stamps it with a
Pepsi-Origin: header that cryptographically proves this deployment
originated the message and records which of its authorised senders did. That
lets a returning bounce be trusted. A DSN that comes back days later carries the
original message, or a copy of it, inside its report body, and with it the
Pepsi-Origin: header. pepsi-stage-anti-spam can therefore
recover that header and confirm that the bounce is a reply to mail that Pepsi
really sent, rather than backscatter or a forged bounce aimed at the
pay-to-send gate.
12.1.1. Field syntax¶
The header value is a list of key=value fields separated by ;:
Pepsi-Origin: v=1; host=mail.example.org; sender=alice@example.org;
nonce=<base64url>; ts=<epoch-seconds>; mac=<base64url>
Pepsi-Origin: v=1; host=mail.example.org; sender=alice@example.org;
for=bob@example.com; nonce=<base64url>; ts=<epoch-seconds>; mac=<base64url>
Field |
Meaning |
|---|---|
|
Format version; a verifier accepts only |
|
The originating deployment’s hostname ( |
|
The authorised envelope-sender account that the message originated from. |
|
Only on mail that Pepsi injected itself (see below): the message’s envelope recipients, lower-cased, sorted and comma-separated. |
|
A random 128-bit nonce, base64url-encoded (RFC 4648, no padding). |
|
The Unix timestamp (seconds) at which the header was minted. |
|
|
The MAC covers the version, hostname, sender account, nonce and timestamp, each
field length-prefixed with its big-endian u32 length and concatenated, so no
field boundary can be shifted. A header with for appends two more fields, the
literal for and the recipient list, so the field can be neither added to an
ordinary header nor removed from, or changed on, one that has it. The hostname
is both carried in the clear and folded into the MAC: the clear copy lets a
verifier reject a bounce minted for a different Pepsi deployment cheaply,
before any database lookup, while binding it into the MAC means a captured
header cannot be replayed against a sibling deployment that happens to share a
secret. Because only Pepsi ever generates or verifies these headers, the wire
format does not need to interoperate with anything.
12.1.2. Minting and verification¶
Stamping. Whichever outbound path a message takes, the relay stage prepends the header: pepsi-stage-relay-to-internet and pepsi-stage-relay-to-smarthost both call the shared
pepsi-common::originengine, and record the freshly minted nonce in thepepsi.origin_noncetable with a two-week expiry. If the feature is off the message is unchanged; a nonce that cannot be recorded makes the stage retry the message rather than send a stamp that it would later refuse to recognise.Verification. pepsi-stage-anti-spam, on a returning bounce, scans the whole message (the header sits inside the DSN body, not the bounce’s own header block), unfolds any continuation lines, and accepts the first header whose version and hostname match and whose MAC verifies under the secret. Only if the cheap cryptographic check passes is the (slower)
pepsi.origin_noncelookup consulted; a bounce verifies only if its nonce is still tracked. A bounce does not verify if its header is missing, forged or expired, and no bounce verifies when proof-of-origin is not configured. Such a bounce is routed to the stage’sBOUNCE_TARGET_STAGEwhen one is wired (the wizard wires thediscard-rejectedsink, so such a bounce is dropped; a quarantine stage keeps it for review), and otherwise forwarded toNEXT_STAGEunchanged. A genuine bounce is always forwarded normally. A bounce is never gated on payment.Mail that Pepsi injected itself. The secure-link portal’s link and PIN notifications are messages that the deployment composes on its own behalf with a human envelope sender. Such a message is stamped with the
forform when it is injected, bound to its envelope recipients, and its nonce is recorded. When such a message comes back in through this deployment’s MX to a gated mailbox, pepsi-stage-anti-spam forwards it without a payment gate if a header in the message’s own header block verifies, carriesfornaming every envelope recipient of the row, and has a tracked nonce. The ordinary form, which every recipient of our mail holds, never exempts; theforform can only be replayed by its recipients, on mail to themselves. The adversary that this answers is the remote sender of A remote sender.
12.1.3. Configuration¶
Keying lives in the shared [pepsi-origin] section (SECRET / SECRET_FILE,
plus the required [pepsi-ingress] HOSTNAME that is bound into every MAC). The
feature is on by default: when no secret is configured, pepsi-setup
provisions a random one on first run. The secret must stay stable over time (a
bounce returned days later must still verify) and be identical across all
instances of a deployment.
To switch the feature off, set ENABLED = no in [pepsi-origin]. Outbound
mail is then unstamped, every bounce is unverifiable (routed per the anti-spam
stage’s BOUNCE_TARGET_STAGE, else forwarded), and pepsi-setup mints no
secret; an existing secrets.d/pepsi-origin.secret is left in place, so
switching it back on resumes with the same key. Removing the section is not an
off switch: the next pepsi-setup run would find no secret and provision a new
one. See pepsi-stage-anti-spam and pepsi.conf(5).
12.2. The Taler: payment header¶
When pepsi-stage-anti-spam holds a message for payment it
originates a payment-request auto-reply to the sender (Auto-Submitted:
auto-replied per RFC 3834, null envelope sender). That reply carries the GNU
Taler payment URI
Taler: taler://pay/<backend>/<order-id>/
as a header field, and in its body as a clickable link and an inline cid:
PNG QR code (RFC 2392 for the cid: reference), together with a pointer to
https://wallet.taler.net/ for senders without a wallet. The header is added
alongside the body copy, never instead of it, so a human reader and a non-Taler
client are wholly unaffected.
The value is exactly the URI that the stage mints, with order_id == token, so a
wallet resolves the order against the merchant backend just as it would from the
body link. taler:// is not an IANA-registered URI scheme (RFC 7595 sets the
procedure); it is GNU Taler’s own, and the wire form is documented by that
project rather than here.
12.2.1. Why a header and not only the body¶
The header is what makes the demand machine-detectable, and Pepsi is itself
the machine that reads it. pepsi-stage-auto-pay is the
sending-side counterpart and runs on the inbound path. It recognises a returning
payment demand by this field: it unfolds continuation lines, accepts several
URIs in one field and several ``Taler:`` fields (a message to a list can draw
more than one demand), and ignores taler:// URIs of any other kind, so that
only genuine pay demands are ever settled.
Detection alone is not authorisation. The stage pays only for mail that this
deployment provably originated. It establishes this with the Pepsi-Origin:
header described above, which it recovers from the returned message and checks
against pepsi.origin_nonce. The budget is booked against that origin nonce,
so a single original message cannot be charged twice.
The reply also copies the original message’s Pepsi-Origin: header verbatim,
which is what lets the correlation survive the round trip.
12.2.2. Interaction with DKIM and ARC¶
The auto-reply is injected at BLOCK_RESPONSE_STAGE, so it is DKIM-signed on
the way out like any other message. Whether the Taler: field is covered by
that signature follows the stage’s ordinary h= configuration
(SIGNED_HEADERS, see pepsi-stage-dkim-sign), whose default
does not include it; it is not special-cased. Because
DKIM header selection is bottom-up (RFC 6376 §5.4.2), adding the field does not
disturb any signature already present.
12.3. See also¶
pepsi-stage-anti-spam, pepsi-stage-auto-pay, pepsi-stage-relay-to-internet, pepsi-stage-relay-to-smarthost, Supported Features, RFC Index.