.. This file is part of PEPSI. Copyright (C) 2026 GNUnet e.V. PEPSI is free software; you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version. ========== pepsi-dkim ========== *Hold the DKIM and ARC signing keys, sign for the pipeline, rotate the keys and say which DNS records they need.* 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``. :doc:`pepsi-stage-dkim-sign` and :doc:`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: :manpage:`pepsi-dkim(1)`. 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. :ref:`tm-adv-component` states the residual, and :ref:`dkim-signing-daemon` describes the mechanism. 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.** ``-YYYYMM`` (RSA, ``RSA_BITS`` 2048, 3072 or 4096) and ``-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 :doc:`pepsi-status`, :doc:`pepsi-setup` (``run``, ``check``), the admin API (``GET /api/v1/keys/dkim``) and the console's DKIM page. Operating it ============ :ref:`dkim-key-rotation` in :doc:`../operations` is the operator's guide: publishing the records, turning rotation on, emergency rotation, RFC 2136, and why the keys are left out of backups. See also ======== :doc:`pepsi-stage-dkim-sign`, :doc:`pepsi-stage-arc`, :doc:`pepsi-setup`, :doc:`../security`, :manpage:`pepsi-dkim(1)`.