39. pepsi-stage-dkim-sign¶
Prepend DKIM signatures before delivery.
39.1. Role¶
pepsi-stage-dkim-sign DKIM-signs the message and advances it to a delivery
stage. Separating signing from message construction lets
pepsi-stage-bounce build an unsigned DSN and point its NEXT_STAGE
here, so a generated bounce is signed before it is sent. Reference:
pepsi-stage-dkim-sign(1).
39.2. Features¶
Dual-signature DKIM (RFC 6376): prepends both an RSA-2048 and an Ed25519 (RFC 8463)
DKIM-Signatureheader by default;[pepsi] DKIM_ALGORITHMSnarrows that to one (the largest receivers do not verify Ed25519 and report it asfailin DMARC aggregate reports).Signing domain selection:
SIGNING_DOMAINif set, otherwise the domain of the message’sFrom:header.Full body coverage, always: RFC 6376’s
l=body-length tag is never emitted and cannot be configured. Strict verifiers (mail-auth, Stalwart, and Pepsi’s own) reject anl > 0signature outright, and RFC 6376 §8.2 warns that appended content can replace the original in the reader’s eyes.Prepend-only / single write: signatures are added at the top, so existing signatures lower in the message are undisturbed; only the
headerscolumn is rewritten, unless the body was converted (next item).7-bit before signing (RFC 6376 section 5.3): an 8-bit body is re-encoded as quoted-printable or base64 before the signature is computed, so a next hop without
8BITMIMEdoes not make the relay re-encode it afterwards and break the signature. Not done when another signature already covers the 8-bit bytes (aDKIM-SignatureorARC-Message-Signatureon the message, amultipart/signedpart), nor when the message headers needSMTPUTF8.No signature for a forgery of our domain: a message is advanced unsigned if it arrived from outside, its
From:aligns with the signing domain, and ingress authenticated it neither by DMARC nor by an aligned DKIM signature. So forwarding it does not make it pass DMARC at the next hop. Mail submitted here and mail Pepsi composes (DSNs, notices, list copies) are signed as usual. WithSIGNING_DOMAIN, mail received from outside whoseFrom:is not of that domain’s organisation (forwarded mail of a foreign author) is advanced unsigned as well. The dedicated SRS domain of pepsi-stage-srs covers the SPF half of this rule; see Forwarded forgeries of our own domain (A remote sender).Strict ``From:`` reading: the signing domain is taken from a
From:only when every mailbox in it parses strictly (CERT/CC VU#517845), so a field that clients resolve to different addresses is never signed as the domain a lenient reader would pick.Fail-closed: apart from that rule, a message is never advanced unsigned. A message cannot be signed when no signing domain can be determined (no
SIGNING_DOMAINand noFrom:that reads one way only), when pepsi-dkim(1) does not sign for that domain, or when theFrom:of a message submitted or composed here is not of the organisation of a configuredSIGNING_DOMAIN. Such a message is split into one row per recipient and rerouted to the stage’sBOUNCE_STAGEwith a DSN reason (5.6.0or5.7.1). Without aBOUNCE_STAGE, or for a null-sender message, it is failed (terminalfailed, with the reason instate.last_error), and pepsi-failure-bouncer or the operator decides what happens to it. If the signing daemon cannot be reached or refuses for another reason, the host is at fault: the message is paused and retried, with the reason instate.last_error, until the stage’sMAX_LIFETIME(default 120 hours). Startpepsi-dkim.service, and the queue drains by itself.
39.3. Configuration¶
[stage-<name>]: PROGRAM = pepsi-stage-dkim-sign, NEXT_STAGE
(required) and SIGNING_DOMAIN, plus the signature parameters
HEADER_CANONICALIZATION / BODY_CANONICALIZATION
(relaxed, the default, or simple, choosable independently),
SIGNED_HEADERS (the h= set; must include From; the default covers
List-Unsubscribe and List-Unsubscribe-Post, as RFC 8058 requires, and
over-signs every field it names, so a prepended second To: or Reply-To:
breaks the signature) and
SIGNATURE_EXPIRATION_DAYS (the x= tag, seven days after signing by
default; 0 emits none, see The lifetime of our DKIM signatures). [pepsi]
DKIM_ALGORITHMS decides which signatures are made. See
pepsi-stage-dkim-sign(1).
The stage holds no key: pepsi-dkim(1) does, under its own account, and
signs the header block that the stage builds and sends to its socket. The selectors
are the daemon’s (<DKIM_SELECTOR>-YYYYMM and the same with -ed25519),
and change when it rotates. A compromised stage therefore cannot copy a key,
but it can still have mail of a served domain signed through the socket while
it runs, so a signature is only as strong as the pepsi role
(A compromised component). 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).
39.4. State¶
Inputs:
state.local_originand the ingress verdictsstate.auth.dmarc/state.auth.dkim, which decide whether a message whoseFrom:aligns with the signing domain is signed; the domain comes fromSIGNING_DOMAINor thefrom_headercolumn, the body hash from the loaded message.Outputs: on the signing path only
state.origin.body_8bit, cleared when the body was converted to 7-bit; the rest ofstate, includingstate.dsn, is preserved. Otherwise only a refusal or a retry writes anything (state.last_error;state.bouncewhen rerouted toBOUNCE_STAGE;state.temporary_failuresfor a retry).
39.5. See also¶
pepsi-stage-bounce, pepsi-stage-relay-to-internet, Supported Features, pepsi-stage-dkim-sign(1).