..
  This file is part of PEPSI.
  Copyright (C) 2026 Pepsi contributors

  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-stage-dkim-sign
=====================

*Prepend DKIM signatures before delivery.*

Role
====

``pepsi-stage-dkim-sign`` DKIM-signs the message and advances it to a delivery
stage. Separating signing from message construction lets
:doc:`pepsi-stage-bounce` build an *unsigned* DSN and point its ``NEXT_STAGE``
here, so a generated bounce is signed before it is sent. Reference:
:manpage:`pepsi-stage-dkim-sign(1)`.

Features
========

* **Dual-signature DKIM** (RFC 6376): prepends both an **RSA-2048** and an
  **Ed25519** (RFC 8463) ``DKIM-Signature`` header.
* **Signing domain selection:** ``SIGNING_DOMAIN`` if set, otherwise the domain of
  the message's ``From:`` header.
* **Body-length tag (optional):** ``COVER_BODY = no`` adds an ``l=`` tag fixed to
  the body as signed, so a downstream hop may append a footer without breaking the
  signature; the signed portion is still fully covered. Default ``yes`` (no ``l=``).
* **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.
* **Fail-open:** if no signing domain can be determined or the keys are missing or
  signing errors, the message is advanced **unsigned** with a warning.

Configuration
=============

``[stage-<name>]``: ``PROGRAM = pepsi-stage-dkim-sign``, ``NEXT_STAGE``
*(required)*, ``COVER_BODY`` and ``SIGNING_DOMAIN``. Key material and selectors
come from the shared ``[pepsi]`` section (``KEY_DIR``, ``DKIM_SELECTOR``). See
:manpage:`pepsi-stage-dkim-sign(1)`.

State
=====

* **Inputs:** none from ``state`` (domain from ``SIGNING_DOMAIN`` or the
  ``from_header`` column; body hash from the loaded message).
* **Outputs:** none added; the whole ``state``, including ``state.dsn``, is
  preserved.

See also
========

:doc:`pepsi-stage-bounce`, :doc:`pepsi-stage-relay-to-internet`,
:doc:`../features`, :manpage:`pepsi-stage-dkim-sign(1)`.