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=noneNo ARC chain was present: this ADMD is the first to seal the message.
cv=passA chain was present and every set validated.
cv=failA 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, elseinfo).- -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.