95.1.4. pepsi-stage-arc

ARC-verify, sign and seal in the Pepsi pipeline

Manual section:

1

95.1.4.1.1. Name

pepsi-stage-arc - the ARC verification and sealing stage of the Pepsi pipeline.

95.1.4.1.2. Synopsis

pepsi-stage-arc [GLOBAL-OPTIONS] worker

95.1.4.1.3. Description

pepsi-stage-arc is a stage program run by pepsi-dispatch(1) as a persistent worker that reads message ids on standard input. It implements ARC (RFC 8617): it verifies any existing inbound ARC chain and records the resulting verdict in the row’s state.auth.arc. When an ARC signing identity is configured, it also seals the message as our ADMD by prepending a fresh ARC set: ARC-Authentication-Results (AAR), ARC-Message-Signature (AMS) and ARC-Seal (AS). Sealing only prepends header lines, so existing signatures lower in the message are undisturbed; the one content change this stage makes is the MIME rewrite described below. The row then advances to its NEXT_STAGE. The rest of the row’s state, including any RFC 3461 state.dsn parameters, is left untouched for later stages to honour.

ARC signing is a stage rather than part of pepsi-ingress(1), so ingress does not hold the ARC signing keys. Ingress verifies SPF, DKIM and DMARC, writes the standalone Authentication-Results header, and records the rendered result text under state.origin.ar_results; this stage adds only the ARC set. The AAR (which, per RFC 8617, should mirror the receiver’s full assessment) is built from that stored fragment as it is. SPF, DKIM and DMARC are therefore not verified again here, and the work that needs many DNS lookups is done exactly once. This stage verifies only the inbound ARC chain, which ingress does not assess, in order to compute the chain-validation (cv=) value and to append its own arc= line to the AAR.

One rewrite is done here rather than in ingress. A message whose MIME structure has a soft-class anomaly (pepsi-ingress(1), “Ambiguous MIME structure”) is normally rewritten to its RFC reading by ingress before it is stored. A message that arrived with an ARC chain is stored as received and marked state.mime_normalise instead: the chain has to be verified over the bytes that its sealers signed, while our seal has to cover what is stored from here on. This stage verifies the chain over the message as received, rewrites it (pepsi_common::mime_anomaly), and seals the rewritten message, so cv= reflects the chain as it arrived and the ARC-Message-Signature covers the stored bytes. For such a message both the headers and the body column are rewritten, state.mime_normalise is set to false and state.mime_normalised to pepsi-stage-arc. The rewrite is applied on every advancing path, sealed or not; a DNS temperror pause leaves the row as it was.

95.1.4.1.4. Who sealed the chain: state.auth.arc_sealers

Besides the verdict, the stage records the d= of the ARC-Seal fields that the message carried when it arrived. It stores them as a JSON array under state.auth.arc_sealers: lower-cased, stripped of any trailing root dot, de-duplicated, and ordered by instance, so that the ADMD closest to the originator comes first. Our own ARC_DOMAIN never appears: the list is read from the message before this stage’s own set is rendered, so a seal that we added cannot satisfy a rule about intermediaries.

This exists because state.auth.arc cannot answer the question that a receiver actually has. RFC 8617 §8.4 is explicit that a valid chain conveys no trustworthiness: it establishes only that the ADMDs named in it handled the message, and deliberately leaves to local policy the question of whether those ADMDs are honest. A receiver that wants to excuse a forwarding hop’s broken SPF or DKIM therefore has to name the hops that it accepts, and it needs a place from which to read the hops. This key is that place; the sealer_domain rows of pepsi-stage-check-whitelist(1) are the policy written against it.

For a chain that validated, the array holds only the sealers whose own ARC-Message-Signature still verifies over the message as it arrived. RFC 8617 section 5.2 checks only the newest AMS; the older sets are held in place by the seals, and a seal signs the ARC header fields, not the message. So anybody can copy a genuine set off a real posting from lists.example.org, put it over content of their own and seal the result with their own key: the chain validates and names lists.example.org, which never saw these bytes. Checking each sealer’s AMS is what makes the list mean “signed this content” rather than “appears in a valid chain”. The cost is that a later hop that rewrites the message (a subject tag, a footer) drops the earlier sealers from the list, which is right: that hop could have rewritten anything.

For a chain that did not validate, the array holds every claimed sealer. An unvalidated d= is a claim, and an operator who diagnoses a rejected message needs the record of what was claimed. Anything that consumes the array must therefore first require state.auth.arc = pass. check-whitelist does so and discards the whole list otherwise, so a chain that anybody minted cannot name a trusted sealer.

95.1.4.1.5. Chain validation and cv=

RFC 8617 §5.2 defines three chain-validation outcomes, and the cv= tag of the ARC-Seal this stage adds reports which one applies to the message as it arrived:

cv=none

No ARC chain was present: this ADMD is the first to seal the message.

cv=pass

A chain was present and every set validated.

cv=fail

A chain was present and did not validate.

cv=none is an assertion about provenance rather than an absence: it tells the next receiver that nothing upstream had already vouched for this message. Emitting it over a chain that was present but broken would launder that chain: the downstream validator would see an apparently pristine i=1 set and no evidence that anything had been tampered with.

Pepsi therefore seals cv=fail for every inbound chain that fails to validate, including the cases where the chain cannot be read at all: an ARC-Seal/ARC-Message-Signature/ARC-Authentication-Results header that does not parse, a chain longer than the 50 sets that RFC 8617 permits, and a chain with unequal numbers of the three header types. A set sealed or signed with rsa-sha1 does not validate either: RFC 8301 makes that algorithm a permerror for DKIM, and ARC seals and message signatures use the DKIM algorithms. The new set continues the chain’s instance numbering rather than restarting it at i=1.

The one exception is a chain whose most recent ARC-Seal already says cv=fail. Per RFC 8617 §5.1.1 a failed chain cannot be repaired and that seal is the last one, so this stage adds no set at all and the message is forwarded with the chain as it stands.

A chain that could not be validated only because a key lookup failed (a DNS temperror) is not sealed at once: that cv=fail would be wrong about a chain that may be sound, and a seal cannot be taken back. The message is paused for five minutes and tried again, up to three times (about a quarter of an hour, counted in state.arc_temperrors); if the lookups still fail it is then sealed cv=fail like any other chain that does not validate.

The seal needs some context from the SMTP session: the authserv-id, the rendered Authentication-Results fragment and the IP address of the connecting client. The stage reads it from the SMTP-origin metadata that ingress recorded under the row’s state.origin. This is how information is passed from ingress to this stage.

The ARC set is signed with the key of the [pepsi] ARC_DOMAIN domain, for the single algorithm that [pepsi] ARC_ALGORITHM names (ARC permits one signature per hop). The stage holds no key: the signing daemon pepsi-dkim(1) does, under its own account. The stage builds the ARC-Message-Signature and ARC-Seal fields and sends each canonicalised header block to the daemon’s socket ([pepsi-dkim] SOCKET), which signs only for ARC_DOMAIN. A compromised stage therefore cannot copy the key, but every process of group pepsi can ask the socket, so a seal is only as strong as that role (see the manual’s Threat model chapter). The stage protects the domain’s reputation, not a user’s preference, so do not list it in the EDITABLE_STAGES of pepsi-stage-edit-settings(1).

ARC applies only to mail we receive and forward: it preserves an upstream ADMD’s authentication across our hop. It must therefore never touch mail that we originate, that is, our own authenticated submissions (state.local_origin); pepsi-stage-dkim-sign(1) authenticates those as the author domain instead. Sealing such a message would only publish the submission’s own SPF/DKIM/DMARC verdicts (typically an SPF fail for a roaming client that is not listed in our SPF record) inside the ARC set. The stage therefore skips any state.local_origin message that it is handed, and advances it unsealed; this makes the stage safe wherever it is placed. On a host that both receives and submits, place it on the inbound branch only, after the state.local_origin split, so that it sees only received mail, and ahead of SRS envelope rewriting and any other transformation. On a receive-only host it is naturally the initial stage ([stage-init]).

Sealing is fail-open where there is nothing to seal with: if the origin context is missing, the [pepsi] configuration cannot be read, no ARC_DOMAIN is set, pepsi-dkim(1) does not sign for it or holds no key of ARC_ALGORITHM, or the resolver cannot be set up, the message is advanced unsealed with a warning rather than being held up (the ARC verdict is still recorded whenever it could be computed). A signing daemon that cannot be reached is different: that is the host’s fault, and the message is paused and retried like any stage error until the stage’s MAX_LIFETIME, never advanced unsealed for it. The stage’s own section is the other exception: it is checked when the worker starts, and a section that does not parse makes the worker refuse to start (exit 78), so the dispatcher holds the queue until the section is fixed instead of letting every message through unsealed.

95.1.4.1.6. Configuration

The stage is wired and configured through its own [stage-<name>] section (PROGRAM = pepsi-stage-arc, a required NEXT_STAGE). Its options are the DNS settings (DNS_SERVERS, DNS_TIMEOUT) and the signature parameters of the ARC set: HEADER_CANONICALIZATION, BODY_CANONICALIZATION, SIGNATURE_EXPIRATION_DAYS and SIGNED_HEADERS, whose default adds DKIM-Signature to the DKIM stage’s set and leaves out the List-Unsubscribe pair. pepsi.conf(5) documents them together with the shared [pepsi] signing identity (ARC_DOMAIN, ARC_ALGORITHM). The key and its selector belong to pepsi-dkim(1).

95.1.4.1.7. State

Inputs: state.local_origin: when it is true, the message is one of our own submissions and is advanced untouched (no ARC). Otherwise state.origin, the SMTP-origin metadata that ingress recorded. The authserv_id is required to reproduce the AAR identity (without it the stage advances unsealed, fail-open); ar_results carries ingress’s rendered Authentication-Results fragment, reused verbatim in the AAR so SPF/DKIM/DMARC need not be re-checked; remote_ip is needed for the AAR’s own arc= result, which is left out when it is absent (local injection). helo is read but does not change the set.

Outputs: the stage overwrites state.auth.arc with the re-evaluated chain verdict (replacing the none that ingress puts there), writes state.auth.arc_sealers (see above) and prepends the ARC set to the headers column; the rest of state, including the other state.auth verdicts and state.dsn, is preserved unchanged. While it waits out a DNS temperror it counts the attempts in state.arc_temperrors. The state layout is described in pepsi.state(7).

Transitions: advances to NEXT_STAGE: after prepending the ARC set, after merely recording the verdict in state.auth.arc when no signing identity is configured, or immediately (untouched) for a state.local_origin message, which is never ARC-processed. The one other outcome is a pause of five minutes, at most three times, for an inbound chain whose validation hit a DNS temperror (see above). There is no branch; the stage never fails, reroutes or finishes a message.

95.1.4.1.8. Commands

Run as a worker, the program verifies and seals each message and advances it.

95.1.4.1.9. Global Options

-c FILE, –config FILE

Read the configuration from FILE instead of the default search path.

-L LOGLEVEL, –log LOGLEVEL

Set the logging verbosity (error, warn, info, debug, trace; default [pepsi] LOG, else info).

-h, –help

Print a usage summary and exit.

-V, –version

Print the version and exit.

95.1.4.1.10. Exit Status

The outcome of each message is reported to pepsi-dispatch(1) on the worker’s status line, not as the exit status.

0

The worker ran until its standard input was closed.

1

A fatal error occurred (unreadable configuration, the database could not be opened, or standard input/output failed). The reason is written to the log.

78

The worker refused to start: its section does not parse. The dispatcher requeues what it handed over and retries the stage later.

95.1.4.1.11. See Also

pepsi-config(1), pepsi-ingress(1), pepsi-stage-srs(1), pepsi-stage-dkim-sign(1), pepsi-dispatch(1), pepsi.conf(5), pepsi.state(7), pepsi-setup(1), pepsi-dkim(1)

95.1.4.1.12. Bugs

Report bugs to the Pepsi issue tracker.