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; and

  • the 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

v

Format version; a verifier accepts only 1.

host

The originating deployment’s hostname ([pepsi-ingress] HOSTNAME), in the clear.

sender

The authorised envelope-sender account that the message originated from.

for

Only on mail that Pepsi injected itself (see below): the message’s envelope recipients, lower-cased, sorted and comma-separated.

nonce

A random 128-bit nonce, base64url-encoded (RFC 4648, no padding).

ts

The Unix timestamp (seconds) at which the header was minted.

mac

HMAC-SHA256 over the preceding fields, base64url-encoded.

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::origin engine, and record the freshly minted nonce in the pepsi.origin_nonce table 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_nonce lookup 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’s BOUNCE_TARGET_STAGE when one is wired (the wizard wires the discard-rejected sink, so such a bounce is dropped; a quarantine stage keeps it for review), and otherwise forwarded to NEXT_STAGE unchanged. 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 for form 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, carries for naming every envelope recipient of the row, and has a tracked nonce. The ordinary form, which every recipient of our mail holds, never exempts; the for form 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.