42. pepsi-stage-relay-to-internet

Direct-to-MX delivery with MTA-STS.

42.1. Role

pepsi-stage-relay-to-internet delivers a message directly to the recipient domain’s mail exchangers, doing its own MX discovery and TLS policy enforcement. It is one of the two interchangeable delivery stages. Reference: pepsi-stage-relay-to-internet(1).

42.2. Features

42.2.1. MX discovery (RFC 5321 / RFC 7505)

  • The stage does its own MX lookup and tries the hosts in ascending preference (equal preference in random order); a domain with no MX falls back to its address records (implicit MX, RFC 5321 §5.1).

  • Null MX (RFC 7505, 0 .) and a non-existent domain are permanent failures, never retries.

  • Happy-Eyeballs address selection across A/AAAA, intersected with ADDRESS_FAMILY; resolved addresses are cached per address (with connect health) in the pepsi.dns_address table, so a working address is preferred until its DNS TTL elapses.

42.2.2. Transport security (RFC 8461 / RFC 6125)

  • MTA-STS (RFC 8461) discovery and enforcement (unless MTA_STS = no): an enforce policy restricts delivery to listed MX hosts over STARTTLS with a certificate that validates for the host (RFC 6125). A testing policy is validated the same way and the outcome recorded for TLS Reporting, but a failure falls back to opportunistic STARTTLS over all MX hosts; with no policy, delivery uses opportunistic STARTTLS. Policy lookups fail open only when nothing is cached, and such a failed fetch is reported through TLSRPT (sts-policy-fetch-error, or sts-webpki-invalid for a certificate failure). The policy is fetched only from a public address (a policy host resolving to loopback or a private range is not contacted, which counts as a failed fetch). Fetched policies are cached for their max_age (capped at a week) in the pepsi.mta_sts_policy table, so they survive worker recycling and restarts (RFC 8461 section 5.1); pepsi-queue gc deletes expired ones. A cached policy is fetched again on use once less than half of that lifetime remains, whatever the _mta-sts record says (RFC 8461 section 10.2). A successful fetch stores the policy for its full lifetime again. A failed one keeps the cached policy; it is retried after five minutes and logged as a warning once less than a quarter of the lifetime remains. The hourly pepsi-queue gc refreshes every stored policy under the same rules without waiting for a message (section 10.2), so a rarely mailed domain does not lapse back to first contact. The mta-sts subcommand prints the applicable policy as a fresh fetch finds it, ignoring the cache.

  • DANE/TLSA (RFC 7672), per MX host: DANE = off | warn | strict, default strict (warn is an explicit opt-out from RFC 7672’s refusal). When usable TLSA records exist and the MX RRset is DNSSEC-secure, they take precedence over MTA-STS for that connection, except that warn mode never replaces an enforce MTA-STS policy’s PKIX validation. Pepsi reads the resolver’s AD bit and does not validate DNSSEC itself; a worker started with DANE on warns when that resolver is neither on loopback nor reached over DNS over TLS or HTTPS, or does not set the AD bit on a signed probe answer. A mismatch with usable records defers delivery under strict and only warns under warn (delivery then uses the certificate check that applies without DANE, and TLSRPT records the session as tlsa-invalid). Any secure TLSA RRset, usable or not, makes STARTTLS mandatory in both modes (RFC 7672 section 2.2): when a host does not offer it, the message is deferred instead of being sent in cleartext. Where one usage and selector are published under both SHA-256 and SHA-512, only the SHA-512 records are matched (RFC 7671 section 9).

  • Stapled OCSP (RFC 6960): on a PKIX-validated hop, and under a DANE-TA match, an OCSP response that the MX staples is verified and a revoked answer refuses the session (a DANE-EE match is not asked); nothing is queried, and a hop that staples nothing is not checked.

  • Require TLS (RFC 8689): a message tagged state.tls_required = "required" by ingress (the REQUIRETLS parameter) goes only to an MX host whose name is validated by DNSSEC or an MTA-STS policy, over mandatory STARTTLS with the certificate authenticated by DANE or PKIX, and only if the host then advertises REQUIRETLS; the parameter is passed on. Each MX host is tried in turn. When none qualifies, the message bounces with 5.7.30 or 5.7.10; this bounce is itself tagged and returns headers only. A message tagged "no" (TLS-Required: No) is delivered opportunistically to every MX host, with the domain’s policy treated as advisory, and is not reported through TLSRPT.

42.2.3. Delivery, retry and bounce

  • Sends with the message’s own envelope sender (null sender for bounces), one recipient per attempt: a multi-recipient row is first split into one row per recipient.

  • On success, finishes the row (or advances to NEXT_STAGE).

  • Exponential backoff on transient failure (RETRY_INITIAL/RETRY_MAX_INTERVAL/RETRY_FACTOR); past MAX_LIFETIME a transient failure becomes permanent.

  • Loop detection via MAX_HOP_COUNT Received: headers.

  • A permanent failure of an ordinary message routes to BOUNCE_STAGE (or marks the row failed). A permanent failure of a bounce is never re-bounced: a copy goes to POSTMASTER if that is set, and otherwise it is discarded.

42.2.4. DSN propagation and origination (RFC 3461)

  • Propagates RET/ENVID/NOTIFY/ORCPT to the MX only when it advertises DSN.

  • On permanent failure, hands the recipient’s NOTIFY/ORCPT/ENVID to the bounce stage so a failure DSN is generated only when requested.

  • Success DSN (Action: delivered) when ORIGINATE_SUCCESS_DSN + NOTIFY=SUCCESS; delay DSN (Action: delayed, once) when DELAY_DSN_AFTER elapses and NOTIFY=DELAY.

  • RRVS (RFC 7293): a recipient’s RRVS= parameter is passed on when the MX advertises RRVS; otherwise the default action R fails that recipient with 5.7.19 and C writes the request as a Require-Recipient-Valid-Since: field naming only that recipient.

42.2.5. Proof of origin

  • With [pepsi-origin] configured (the default), every outbound message is stamped with an unsigned Pepsi-Origin header (an HMAC over the sender account, a nonce recorded in pepsi.origin_nonce, a timestamp and the host name), so pepsi-stage-anti-spam can recognise a returning bounce as a reply to mail Pepsi sent. A nonce that cannot be recorded holds the message back for a retry rather than sending an unverifiable stamp.

42.2.6. Content adaptation (RFC 6152 / RFC 6531)

  • Matches the message to the extensions the MX advertises: re-advertises BODY=8BITMIME / SMTPUTF8 when supported, otherwise downgrades the body (RFC 2045) and UTF-8 headers (RFC 2047). A non-ASCII address that cannot be represented to a non-SMTPUTF8 hop is bounced, and so is a body that is still 8-bit after the downgrade, because RFC 6152 §3 permits no attempt to send it.

42.3. Configuration

[stage-<name>] with PROGRAM = pepsi-stage-relay-to-internet: SERVER_NAME (required), NEXT_STAGE/BOUNCE_STAGE, POSTMASTER, the timeouts (CONNECT_TIMEOUT/COMMAND_TIMEOUT/DATA_TIMEOUT), the retry policy (RETRY_INITIAL/RETRY_MAX_INTERVAL/RETRY_FACTOR/MAX_LIFETIME/ DELAY_DSN_AFTER), MAX_HOP_COUNT, DNS (DNS_SERVERS/DNS_TIMEOUT), MTA-STS (MTA_STS/MTA_STS_TIMEOUT), DANE and ADDRESS_FAMILY. Durations must use h/m/s units. Full reference: pepsi-stage-relay-to-internet(1).

42.4. State

  • Inputs: state.dsn (propagation + report gating), state.origin (8BITMIME/SMTPUTF8 hints) and state.tls_required (RFC 8689).

  • Outputs: attempts/last_error/delay_sent on pause; a state.bounce object (permanent/success/delay) when routing to or enqueuing for the bounce stage; last_error on terminal fail. state.dsn and state.origin are preserved.

42.5. Security

An active network attacker and The network adversary state the transport-security guarantees and their limits: what an active network attacker gets with and without MTA-STS enforce or DANE records, and why the resolver must validate DNSSEC on loopback or over an authenticated channel. The MTA-STS policy fetch shares the public-address check described under “Key-discovery SSRF” in Security model.

42.6. See also

pepsi-stage-relay-to-smarthost, pepsi-stage-bounce, Supported Features, pepsi-stage-relay-to-internet(1).