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 DKIM From: aligned with d= and named in h=, 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_BITS 2048, 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 for RETIRE_AFTER_DAYS (14), longer than any signature’s x=; then its private keys are deleted, or published with PUBLISH_RETIRED_KEYS once DNS no longer serves their records.

  • Optional rotation (ROTATION_DAYS, off by default), with the next generation made ROTATION_LEAD_DAYS (28) ahead and, with WAIT_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).