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-Signature header by default; [pepsi] DKIM_ALGORITHMS narrows that to one (the largest receivers do not verify Ed25519 and report it as fail in DMARC aggregate reports).

  • Signing domain selection: SIGNING_DOMAIN if set, otherwise the domain of the message’s From: 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 an l > 0 signature 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 headers column 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 8BITMIME does not make the relay re-encode it afterwards and break the signature. Not done when another signature already covers the 8-bit bytes (a DKIM-Signature or ARC-Message-Signature on the message, a multipart/signed part), nor when the message headers need SMTPUTF8.

  • 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. With SIGNING_DOMAIN, mail received from outside whose From: 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_DOMAIN and no From: that reads one way only), when pepsi-dkim(1) does not sign for that domain, or when the From: of a message submitted or composed here is not of the organisation of a configured SIGNING_DOMAIN. Such a message is split into one row per recipient and rerouted to the stage’s BOUNCE_STAGE with a DSN reason (5.6.0 or 5.7.1). Without a BOUNCE_STAGE, or for a null-sender message, it is failed (terminal failed, with the reason in state.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 in state.last_error, until the stage’s MAX_LIFETIME (default 120 hours). Start pepsi-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_origin and the ingress verdicts state.auth.dmarc/state.auth.dkim, which decide whether a message whose From: aligns with the signing domain is signed; the domain comes from SIGNING_DOMAIN or the from_header column, 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 of state, including state.dsn, is preserved. Otherwise only a refusal or a retry writes anything (state.last_error; state.bounce when rerouted to BOUNCE_STAGE; state.temporary_failures for a retry).

39.5. See also

pepsi-stage-bounce, pepsi-stage-relay-to-internet, Supported Features, pepsi-stage-dkim-sign(1).