73. pepsi-dkim¶
Hold the DKIM and ARC signing keys, sign for the pipeline, rotate the keys and say which DNS records they need.
73.1. Role¶
pepsi-dkim serve is a long-lived service (pepsi-dkim.service) running
as its own account, pepsi-dkim. It alone holds the private keys of every
signing domain, as 0600 files in its 0700 state directory
/var/lib/pepsi-dkim. pepsi-stage-dkim-sign and
pepsi-stage-arc hash the body and build the signature fields themselves,
send the canonicalised header block over the socket
/run/pepsi-dkim/sign.sock (group pepsi) and put the signature value that
the daemon returns into the field. Reference: pepsi-dkim(1).
73.2. Why a daemon¶
The stages run as pepsi, the account that every ordinary stage shares. If
those stages could read a key, an attacker who compromised any one of them could
take the key away and go on signing for the domain after the hole was fixed.
Behind the daemon, a compromised stage can still have messages signed while it
runs, because every pepsi process can reach key use: through the socket, or
by rewriting a queued From: that the signing stage then signs. It cannot copy
a key, though.
A compromised component states the residual, and
The DKIM signing daemon describes the mechanism.
73.3. Features¶
Signing. One JSON request per line; the daemon checks the header block against its policy (a served
d=, a DKIMFrom:aligned withd=and named inh=, ARC only for[pepsi] ARC_DOMAIN) and signs with the current key. A daemon that cannot be reached makes the signing stage’s error temporary: the message is retried, never sent unsigned.Selectors per generation.
<DKIM_SELECTOR>-YYYYMM(RSA,RSA_BITS2048, 3072 or 4096) and<DKIM_SELECTOR>-YYYYMM-ed25519, so every key has a record name of its own.Lifecycle
next->current->retiring->retired. A domain without keys gets a current generation at once. The records of a retiring generation stay forRETIRE_AFTER_DAYS(14), longer than any signature’sx=; then its private keys are deleted, or published withPUBLISH_RETIRED_KEYSonce DNS no longer serves their records.Optional rotation (
ROTATION_DAYS, off by default), with the next generation madeROTATION_LEAD_DAYS(28) ahead and, withWAIT_FOR_DNS, the switch held until every authoritative server serves its records.pepsi-dkim rotate [--hard]and the console’s rotate now switch on demand.DNS checks of every authoritative server, hourly by default; optional RFC 2136 updates with TSIG (
DNS_UPDATE = rfc2136).Postmaster notices by mail when a record must be added or may be removed, a rotation waits for DNS, or a DNS update was refused.
A public status document,
/var/lib/pepsi-dkim-public/status.json, read by pepsi-status, pepsi-setup (run,check), the admin API (GET /api/v1/keys/dkim) and the console’s DKIM page.
73.4. Operating it¶
Rotating DKIM keys in Operating Pepsi is the operator’s guide: publishing the records, turning rotation on, emergency rotation, RFC 2136, and why the keys are left out of backups.
73.5. See also¶
pepsi-stage-dkim-sign, pepsi-stage-arc, pepsi-setup, Security model, pepsi-dkim(1).