95.1.8. pepsi-stage-dkim-sign¶
DKIM-sign a message in the Pepsi pipeline
- Manual section:
1
95.1.8.1.1. Name¶
pepsi-stage-dkim-sign - DKIM-signing stage of the Pepsi pipeline.
95.1.8.1.2. Synopsis¶
pepsi-stage-dkim-sign [GLOBAL-OPTIONS] worker
95.1.8.1.3. Description¶
pepsi-stage-dkim-sign is a stage program run by pepsi-dispatch(1)
as a persistent worker reading message ids on standard input. It prepends one
DKIM-Signature header per algorithm in [pepsi] DKIM_ALGORITHMS (by
default two: one RSA, one Ed25519) to the message’s raw bytes and advances the
row to its NEXT_STAGE (a delivery stage). Signing only prepends header lines, so any
existing signatures lower in the message are undisturbed. It does not touch the
row’s state (beyond the one flag described below), so any RFC 3461
state.dsn parameters are preserved for later stages to honour.
A message whose body carries 8-bit octets is first converted to a 7-bit
content-transfer-encoding (RFC 6376 section 5.3): every 8-bit MIME leaf part is
re-encoded as quoted-printable (text/*) or base64, and a non-ASCII parameter
in a part’s own header (an attachment’s file name) takes the RFC 2231 form.
Otherwise a relay stage would apply this conversion after signing, towards a
next hop that does not advertise 8BITMIME, and would invalidate the
signature. When the body is converted beforehand, the relay finds nothing left
to change. The converted body is stored in place of the original, and
state.origin.body_8bit is cleared so that the relay no longer announces
BODY=8BITMIME. The message is instead signed unchanged in these cases:
when its own header block holds non-ASCII octets (it needs SMTPUTF8
regardless); when it already carries a DKIM-Signature or
ARC-Message-Signature, such as an author’s signature on a forwarded message
or Pepsi’s own ARC seal, since both cover the 8-bit body and would break on
every hop; when one of its parts is a multipart/signed, whose OpenPGP or
S/MIME signature covers the encoded octets beneath it; or when the conversion
cannot make the body 7-bit (a MIME tree nested too deeply).
The signing domain (d=) is SIGNING_DOMAIN if configured, otherwise the
domain of the first mailbox of the message’s From: header. That header is
read strictly: unless every mailbox in it parses as an RFC 5322 mailbox, the
message counts as having no usable From:. Mail clients resolve some fields
to different addresses (<me@example.org>:<ceo@example.com>, a second
<...> address, group syntax, an encoded-word inside the address; CERT/CC
VU#517845). Such a field is never signed as the domain that a lenient reader
would pick.
The stage holds no key. The per-domain DKIM keys belong to the signing daemon
pepsi-dkim(1), which runs as its own account. The stage computes the
body hash, builds the DKIM-Signature field (one per algorithm of [pepsi]
DKIM_ALGORITHMS, with the selectors that the daemon names as current) and
sends the canonicalised header block to the daemon’s socket ([pepsi-dkim]
SOCKET, default /run/pepsi-dkim/sign.sock). The daemon checks the block
against its policy and returns the signature. It signs only for a domain that it
serves, and a DKIM signature only when every mailbox of the From: is of
the d= domain’s organisation and h= names From. When a key switch
happens between choosing a selector and signing, the stage asks for the
current selectors once more.
This stage exists so that message construction and DKIM signing are separate
steps. In particular pepsi-stage-bounce(1) builds an unsigned DSN and
points its NEXT_STAGE here, so a generated bounce is signed as its
postmaster’s domain before delivery.
A message that arrived from outside is advanced unsigned when a domain of
its From: aligns with the signing domain (the same domain, a parent or
subdomain of it, or one sharing its last two labels) and ingress authenticated
it neither by DMARC (state.auth.dmarc) nor by a DKIM signature aligned with
the From: (state.auth.dkim). Our signature would be exactly the aligned
one that DMARC looks for, so signing such a message would let a forgery of our
own domain pass DMARC at the next hop. Such a forgery may be received from
anywhere and forwarded on (by an alias expanding off-site, a ~/.forward, or
the relay signer that the wizard’s SIGN_RELAYED inserts). The message leaves
as any forwarder without our key would send it, and the decision is logged. A
From: that cannot be read strictly counts as aligned. Mail submitted here
(state.local_origin) is always signed, and so is mail that Pepsi composes
itself, which carries no ingress
verdicts: DSNs, automatic replies and notices, and mailing-list copies (the
list software is their author and applies its own posting policy). With
SIGNING_DOMAIN, mail received from outside whose From: is of another
organisation (forwarded mail of a foreign author) advances unsigned: the
signing daemon signs only a From: aligned with d=, and the message keeps
its author’s own signatures. Mail submitted or composed here with such a
From: is refused with a 5.7.1 DSN instead. The SPF half of the same
rule is the dedicated SRS domain (see pepsi-stage-srs(1)); both are set out under
“Forwarded forgeries of our own domain” in the security chapter of the Pepsi
manual.
The daemon keeps the keys out of every stage’s reach, so a compromised stage
cannot copy them. It cannot keep such a stage from using them: the socket
answers every process of group pepsi, so a DKIM signature is only as strong
as the pepsi role. Any compromised stage can have mail of a served domain
signed while it runs, and can rewrite a queued message’s From: before this
stage sees it. The manual’s Threat model chapter records this as a documented
residual. 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).
Apart from these deliberate cases, signing is fail-closed: a message that cannot be signed is never advanced unsigned. What happens instead depends on whose fault it is:
The message reached
dkim-signfor a domain that nobody here signs for: no signing domain can be determined (noSIGNING_DOMAINand no usableFrom:header), pepsi-dkim(1) answers that it does not sign for the domain, or, withSIGNING_DOMAIN, theFrom:is not of that domain’s organisation (which the daemon would refuse on every retry). With a BOUNCE_STAGE, the message is first split into one row per recipient, so that each recipient’sNOTIFYis honoured, and rerouted there with a DSN reason instate.bounce. The status is5.7.1for a domain that the daemon does not sign for or aFrom:outsideSIGNING_DOMAIN, and5.6.0for a message without a usableFrom:; the diagnostic names the domain. Without a BOUNCE_STAGE, the message is moved to the terminalfailedstate, with the reason instate.last_error. A null-sender message (itself a DSN or an auto-reply) is always failed rather than rerouted: a bounce is never bounced, and as a failed row it stays visible to the operator.The daemon cannot be reached (
pepsi-dkim.servicestopped or restarting), or it refuses for any other reason: the host is at fault, not the message. The error is retried (see pepsi-dispatch(1)): the message stayspausedat this stage with the reason instate.last_errorand is retried, after one minute and then at doubling intervals up to an hour, until it has been queued longer than the stage’s MAX_LIFETIME (default120 h); only then is it given up. Failing it at once would bounce every outbound message, and the bounces, which are signed here too, would then be dropped without anybody hearing.
The stage’s own section, [pepsi] and [pepsi-dkim] SOCKET are checked
when the worker starts: a configuration that does not parse makes the worker refuse to start (exit
78), and the dispatcher holds the queue until it is fixed.
95.1.8.1.3.1. Body coverage¶
The signature always covers the whole body strictly: any change to the body in
transit invalidates it. Pepsi never emits RFC 6376’s body-length (l=) tag,
and there is no option to make it.
The tag exists so that a signature can survive a mailing list that appends a
footer, but no operator can usefully make that trade. Pepsi’s own verifier and
every mail-auth/Stalwart deployment use mail-auth’s strict parser, which
rejects any signature with l > 0 outright rather than merely tolerating
less coverage. The tag therefore turns a signature that would have passed into
one that fails. The case it exists for is also the case where the list’s rewrite has
already broken SPF, so under a DMARC p=reject policy that DKIM failure is the
difference between delivered and rejected. RFC 6376 §8.2 separately warns that
appended content can replace the original in the reader’s eyes through MIME
restructuring or lax HTML parsing, and that “signers should be extremely wary of
using this tag”.
95.1.8.1.3.2. Header coverage¶
The headers covered by the signature (the h= tag) are the SIGNED_HEADERS
list (default: the common originator/MIME headers). Every header of the default
list is named twice so that it is over-signed (RFC 6376 §8.15). A header
that is named once more often than it actually occurs is signed one extra
(empty) time. An attacker who prepends a second From:, To:,
Reply-To:, Date:, Content-Type: or any other listed field therefore
produces an occurrence that the signature does not cover, which breaks
verification. Each of these fields occurs at most
once in a well-formed message, so the second entry never leaves a legitimate
occurrence unsigned. Listing any header in SIGNED_HEADERS that is absent from
the message likewise over-signs it (it cannot later be added).
The default list also covers List-Unsubscribe and List-Unsubscribe-Post,
over-signed like the rest. RFC 8058 section 4 allows a receiver to offer one-click
unsubscription only when a valid DKIM signature covers both fields; otherwise
anybody who can relay a copy of the message could choose the URI the receiver
posts to.
95.1.8.1.4. Configuration¶
The stage is wired and configured through its own [stage-<name>] section
(PROGRAM = pepsi-stage-dkim-sign, a required NEXT_STAGE, an optional
BOUNCE_STAGE for the refusals described above). pepsi.conf(5)
documents its options, HEADER_CANONICALIZATION/BODY_CANONICALIZATION
(chosen independently), SIGNATURE_EXPIRATION_DAYS, SIGNED_HEADERS and
SIGNING_DOMAIN, together with the shared [pepsi] options
(DKIM_SELECTOR, DKIM_ALGORITHMS). The keys, their selectors and their
rotation belong to pepsi-dkim(1). The daemon’s [pepsi-dkim]
RETIRE_AFTER_DAYS must exceed SIGNATURE_EXPIRATION_DAYS, so that a key’s
record outlives every signature made with it; pepsi-setup
validate checks this.
The hash is always SHA-256; by default both an RSA and an Ed25519 signature are
emitted, each with an x= expiration seven days after signing
(SIGNATURE_EXPIRATION_DAYS, 0 for none), so a replayed copy or a
signature made with a stolen key stops verifying after a week.
95.1.8.1.5. State¶
Inputs: state.local_origin and the ingress verdicts
state.auth.dmarc and state.auth.dkim, which decide whether a message
whose From: aligns with the signing domain is signed (see above). The
signing domain comes from SIGNING_DOMAIN or the from_header column, and
the body hash from the loaded message.
Outputs: on the signing path, state.origin.body_8bit is cleared when
the body was converted to 7-bit; nothing else is added. The signatures are
prepended to the headers column (and the converted body, if any, replaces
the body); the rest of state, including state.dsn, is preserved
unchanged. A refused message gets state.last_error and, when rerouted,
state.bounce; a retried one gets state.last_error and
state.temporary_failures. The state layout is described in
pepsi.state(7).
Transitions: on success advances to NEXT_STAGE (the delivery stage),
having prepended the DKIM-Signature header(s). If the signing domain cannot be
determined or has no keys here, the message is rerouted to BOUNCE_STAGE
(one row per recipient, state.bounce set) or, without one or for a
null-sender message, moved to the terminal failed state; if its keys cannot
be used, it is paused for a retry until MAX_LIFETIME (fail-closed; see
above). The stage never finishes a message.
95.1.8.1.6. Commands¶
Run as a worker, the program signs each message and advances it.
95.1.8.1.7. 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.8.1.8. 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 or
[pepsi]does not parse. The dispatcher requeues what it handed over and retries the stage later.
95.1.8.1.9. See Also¶
pepsi-config(1), pepsi-stage-bounce(1), pepsi-stage-relay-to-internet(1), pepsi-stage-relay-to-smarthost(1), pepsi-dispatch(1), pepsi-ingress(1), pepsi.conf(5), pepsi.state(7), pepsi-setup(1), pepsi-dkim(1)
95.1.8.1.10. Bugs¶
Report bugs to the Pepsi issue tracker.