35. pepsi-stage-arc

ARC verification, signing and sealing — the entry stage on the inbound path.

35.1. Role

pepsi-stage-arc implements ARC (RFC 8617). It verifies any existing inbound ARC chain and, when an ARC_DOMAIN and its keys are configured, seals the message as our ADMD so the boundary authentication verdict survives Pepsi’s forwarding hop. Because it applies only to mail we receive and forward, it must never touch our own submissions (state.local_origin). pepsi-stage-dkim-sign signs those as the author domain instead, and this stage skips any such message. On a host that both receives and submits, place it on the inbound branch only, after the state.local_origin split (ahead of SRS); on a receive-only host it is the [stage-init] stage. Reference: pepsi-stage-arc(1).

35.2. Features

  • ARC verification of any inbound chain; the verdict is recorded under state.auth.arc.

  • ARC sealing: prepends a fresh ARC set — ARC-Authentication-Results (AAR), ARC-Message-Signature (AMS) and ARC-Seal (AS) — as the ARC_DOMAIN identity, signed with the single ARC_ALGORITHM (rsa or ed25519; ARC permits one signature per hop).

  • AAR from the boundary verdict: the AAR reuses the Authentication-Results fragment that ingress stored under state.origin.ar_results, so SPF/DKIM/DMARC are verified exactly once, at ingress. Only the inbound ARC chain is verified here, to compute the chain-validation (cv=) value and the AAR’s arc= line.

  • Prepend-only: the seal is added at the top, so existing lower signatures and the ingress Received: header are undisturbed; only the headers column is rewritten, never the body, except for the one rewrite described below.

  • The deferred MIME rewrite: a message that ingress marked with state.mime_normalise (ambiguous MIME that arrived with an ARC chain) is rewritten here to its RFC reading. The rewrite comes after the chain is verified over the bytes as received and before the seal, so cv= reflects the chain as it arrived and the seal covers what is stored (Ambiguous MIME is settled at the boundary). It is applied on every advancing path, sealed or not.

  • Fail-open: if the origin context, [pepsi] config or keys are missing, or sealing errors, the message is advanced unsealed with a warning (the verdict is still recorded when computable); only a signing daemon that cannot be reached makes it wait and retry.

  • cv=fail for every broken chain (RFC 8617 section 5.2), including one that does not parse or whose sets are signed with rsa-sha1 (RFC 8301), so a broken chain is never laundered into a fresh i=1; cv=none set. A chain whose last seal already says cv=fail gets no further set.

  • DNS temperror is waited out: a chain that could not be validated only because a key lookup failed is paused five minutes and retried, at most three times (counted in state.arc_temperrors), before it is sealed cv=fail.

35.3. Configuration

[stage-<name>]: PROGRAM = pepsi-stage-arc, NEXT_STAGE (required: the stage always hands the message on, so a missing one fails every message), the DNS settings DNS_SERVERS (empty = [pepsi] DNS_SERVERS, else the system resolver; plain, tls:// or https:// entries) / DNS_TIMEOUT, and the shared signature parameters HEADER_CANONICALIZATION / BODY_CANONICALIZATION (relaxed by default, or simple), SIGNED_HEADERS (which must include From; the default covers DKIM-Signature when the message carries one) and SIGNATURE_EXPIRATION_DAYS (no x= by default) applied to the AMS (the ARC-Seal is always relaxed-canonicalized over its fixed header set and carries no x=, per RFC 8617). The signing identity and algorithm come from the shared [pepsi] section (ARC_DOMAIN, ARC_ALGORITHM). See pepsi-stage-arc(1).

The seal is made with the key for ARC_DOMAIN and ARC_ALGORITHM, which pepsi-dkim(1) holds and signs with; the stage builds the ARC-Message-Signature and ARC-Seal and sends the header block to the daemon’s socket. Without an ARC_DOMAIN, or when the daemon does not sign for it, the message is advanced unsealed; when the daemon cannot be reached it is retried. A compromised stage cannot copy the key but can have seals made while it runs, so a seal is only as strong as the pepsi role (A compromised component). A valid chain conveys no trust by itself (RFC 8617 §8.4): a local policy, such as the sealer_domain rows of pepsi-stage-check-whitelist, is written against state.auth.arc_sealers. The stage protects the domain’s reputation, not a user’s preference; never list it in EDITABLE_STAGES (Per-address settings are a trust boundary).

35.4. State

  • Inputs: state.local_origin: when true, the message is advanced untouched (no ARC on mail we originate). Otherwise state.origin, with the authserv_id (required to reproduce the AAR identity; without it the stage advances unsealed), ar_results (reused in the AAR) and remote_ip (without it the AAR carries no arc= result). state.mime_normalise: when true, the message’s soft-class MIME anomalies are rewritten here.

  • Outputs: overwrites state.auth.arc with the re-evaluated chain verdict and records the chain’s sealer domains under state.auth.arc_sealers (the rest of state, including the other state.auth siblings and state.dsn, is preserved). For a chain that validated, arc_sealers lists only the sealers whose own ARC-Message-Signature still verifies over the message (chain validation checks only the newest one, so a set copied from another message would otherwise name a sealer that never saw these bytes); for one that did not, it lists every claimed sealer, so any reader must first require state.auth.arc == "pass". While a DNS temperror is waited out, state.arc_temperrors counts the pauses. After the deferred MIME rewrite, state.mime_normalise is false and state.mime_normalised is pepsi-stage-arc.

35.5. See also

pepsi-ingress, pepsi-stage-dkim-sign, Supported Features, pepsi-stage-arc(1).