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) andARC-Seal(AS) — as theARC_DOMAINidentity, signed with the singleARC_ALGORITHM(rsaored25519; ARC permits one signature per hop).AAR from the boundary verdict: the AAR reuses the
Authentication-Resultsfragment that ingress stored understate.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’sarc=line.Prepend-only: the seal is added at the top, so existing lower signatures and the ingress
Received:header are undisturbed; only theheaderscolumn 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, socv=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 freshi=1; cv=noneset. A chain whose last seal already sayscv=failgets 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 sealedcv=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). Otherwisestate.origin, with theauthserv_id(required to reproduce the AAR identity; without it the stage advances unsealed),ar_results(reused in the AAR) andremote_ip(without it the AAR carries noarc=result).state.mime_normalise: when true, the message’s soft-class MIME anomalies are rewritten here.Outputs: overwrites
state.auth.arcwith the re-evaluated chain verdict and records the chain’s sealer domains understate.auth.arc_sealers(the rest ofstate, including the otherstate.authsiblings andstate.dsn, is preserved). For a chain that validated,arc_sealerslists 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 requirestate.auth.arc == "pass". While a DNStemperroris waited out,state.arc_temperrorscounts the pauses. After the deferred MIME rewrite,state.mime_normaliseisfalseandstate.mime_normalisedispepsi-stage-arc.
35.5. See also¶
pepsi-ingress, pepsi-stage-dkim-sign, Supported Features, pepsi-stage-arc(1).