selfpost/docs/plans/panel-dkim-signing.md

# Plan: panel-dkim-signing

**Status:** agreed, 2026-10-15 - the row is agreed (owner, 2026-10-15, the
order port25-bare-newline -> base-trixie -> panel-dkim-signing); three
questions below were settled one at a time the same day.  
**Date:** 2026-10-15  
**Version:** `2.8.0` MINOR (after base-trixie, shipped `2.7.0`). No migration;
nothing for an operator to do.

---

## Goal

The panel signs outgoing mail itself, in its own milter, and OpenDKIM
leaves the image. The analysis ([own-mta-builds](../own-mta-builds-2026-10-15.md)
§ 3 E) and the roadmap section give the reasons: OpenDKIM is a 2018 beta
with three open 2026 CVEs and nobody upstream; every OpenDKIM limit
SelfPost works around goes with it (the syslog relay, the From: parser
port and its 256-byte refusal, the tables reloaded by a cross-uid signal
and `CAP_KILL`, keys shared through a group).

What stays the same for an operator: the keys, the selectors, the DNS
records, the panel's pages (one label on Health excepted, Q3).

## What the signer does

- **Library:** `github.com/emersion/go-msgauth/dkim` v0.7.0 (MIT; the
  author of the go-milter v0.4.1 we run; the e2e suite verifies with its
  v0.6.8 today). Read for this plan, `dkim/sign.go`: `NewSigner` hashes the
  body as it is written (an `io.Pipe` into a goroutine), so a message is
  not buffered; `HeaderKeys` is written to `h=` in the order given, each
  name picked last instance first (`header.go`, `newHeaderPicker`), and a
  name listed once more than it occurs is kept in `h=` with nothing hashed
  for it - the over-signing RFC 6376 § 5.4.2 describes; RSA-SHA256; the
  signature is the caller's to insert.
- **What is signed:** `relaxed/simple`, as `build/opendkim.conf` signs
  today. `h=`: every header of the message whose name is in OpenDKIM's
  `dkim_should_signhdrs[]` (`libopendkim/dkim.c:223-246`: from, reply-to,
  subject, date, to, cc, the five resent-*, in-reply-to, references, the
  seven list-*), each occurrence, in message order, plus `From` once more
  (`OversignHeaders From` today). Absent names are not listed, as
  OpenDKIM does not list them.
- **Which key:** on 465/587 the key of the domain the SASL login belongs
  to - `{auth_authen}`, then `Bindings.DomainOf(login)`, the table the
  sender check already reads (`internal/milter/sender.go:262-269`). For the
  panel's own notifications (`sendmail(1)`, `non_smtpd_milters`) the key of
  the server's name, as `EnsureServerSigned` provides it today. The sender
  check has already held `From:` to that same domain, so the signature's
  `d=` is the `From:` domain DMARC aligns on.
- **What Postfix hands a milter,** read in Postfix 3.10.13,
  `src/milter/milter8.c:2329-2400`, `milter8_header()`: Postfix's own
  `Received:` is not shown (and an inserted header at index 0 lands above
  it, "relative to the message as delivered"); a multi-line header comes
  as text separated by `\n`; one space after the colon is eaten unless the
  milter asks for `SMFIP_HDR_LEADSPC` (`OptHeaderLeadingSpace`, which the
  sender check already asks for); body records end in `\r\n`
  (`milter8_body()`, :2470-2500). The signer rebuilds each header as
  `Name:` + value with `\n` made `\r\n` - go-msgauth's own
  `cmd/dkim-milter` writes `name + ": " + value + "\r\n"` and would sign a
  folded header wrongly. A unit test signs folded, tab-led and
  space-free headers and an independent verifier checks them.
- **When it cannot sign** (no key file, a login with no domain, a read
  error): temporary failure, `default_action=tempfail`, as OpenDKIM is
  attached today. A message is never sent unsigned by accident.
- **8-bit mail:** `disable_mime_output_conversion=yes`. Postfix converts an
  8-bit message to 7-bit for a server that does not announce 8BITMIME
  (default `no`, `src/global/mail_params.h:3088`), which breaks any body
  hash - OpenDKIM's today as well. Not set until now; set with this row.

## Decisions settled before this plan

From the roadmap section and the analysis, agreed with the row: the
library; `relaxed/simple`; the header set and `From` over-signed; the key
by the login's domain and by the server's name for local mail; strict;
the removals below; keys, selectors and records unchanged; the e2e oracle
an independent verifier; a message to a real mailbox before the cut.

Decided here (technical, the owner may overrule):

- **The oracle is dkimpy** (`python3-dkim` 1.1.8-2 in trixie,
  `/usr/bin/dkimverify`, seen in `debian:trixie` 2026-10-15) - a separate
  implementation in another language, maintained, packaged by Debian; not
  OpenDKIM's `opendkim-testmsg` (the code this row removes) and not
  go-msgauth (the signer's own library). It runs in the e2e sink's
  network against the stand's CoreDNS.
- **A cross-check before OpenDKIM goes:** on the stand of stage 1 both
  sign the same messages for a while (OpenDKIM after the panel in the
  chain) and the two signatures' `bh=` and `h=` are compared on every
  e2e message; they must agree before stage 2 removes OpenDKIM.
- **The From: parser port goes.** It exists so that the sender check
  judges the address OpenDKIM chooses the key by. With the key chosen by
  the login, the check keeps `net/mail` (one RFC 5322 address at an
  allowed domain) and the 256-byte refusal goes; the refusal texts that
  name OpenDKIM are rewritten.

## Open questions (to the owner, one at a time)

- **Q1. Where the signer runs.** (a) Its own role in the panel process on
  two sockets of its own: `sign.sock` for 465/587 (the key by the login)
  and `sign-local.sock` for local submission (the server's key only), in
  the chain where OpenDKIM is now: sender check, signer, journal. (b)
  Inside the sender check's milter: one socket fewer, but the check would
  receive every body, and local mail - which has no login - would need the
  same milter to tell "no login" from "local", deciding a key by the
  absence of something. **Recommended: (a)** - the socket a message comes
  through, not a missing login, decides that the server's key may sign
  it; the sender check stays a header-only milter; and moving the signer
  into a process of its own later is a change of where it is started.
  **Decided (owner, 2026-10-15): (a).**
- **Q2. The key directory's name.** `/data/opendkim/keys/<domain>/<sel>.private`
  stays as it is, or becomes `/data/dkim/...` (the entrypoint moves the
  tree once; KeyTable and SigningTable are deleted). A backup restores
  only into the image of its own version, so no older archive meets the
  new name. **Recommended: rename** - the cost is the entrypoint's move,
  the paths in the code and the backup tests; a directory named after a
  program the image no longer has would mislead whoever reads `/data`.
  **Decided (owner, 2026-10-15): rename to `/data/dkim`.**
- **Q3. Health.** The Overview's socket check and the process list name
  OpenDKIM and the syslog relay. **Recommended:** the socket row becomes
  "DKIM signer" (the panel's `sign.sock`, checked the same way), the two
  programs leave the process list. A mockup first, as for any page
  change.
  **Settled 2026-10-15:** shown to the owner as a picture; it follows from
  the card's own rule (a row per milter socket Postfix needs, and the
  signer is strict), so it is not his choice - the two rows as drawn.

## Stages

### Stage 1 - the signer, beside OpenDKIM (no release)

- [ ] `internal/milter/sign.go`: the session (Connect, MailFrom with
  `{auth_authen}`, Header, Headers, BodyChunk, Body), `OptHeaderLeadingSpace`,
  `InsertHeader(0, "DKIM-Signature", ...)` (the server's `Actions` gain
  add-header), the key read per message from the key file (a small cache
  keyed by path and mtime), the selector from the store as `Record` reads
  it.
- [ ] Unit tests: sign and verify with go-msgauth; folded and tab-led
  headers; a header absent and present twice; an empty body; a body
  without a final newline; a login with no domain and a missing key file
  answer tempfail; the server's socket never signs with a domain's key.
- [ ] `cmd/panel`: the role, its two sockets (`listenMilter`, group
  selfpost, 0660), the wrapper waits for them.
- [ ] `build/postfix-config.sh`: `smtpd_milters` = sender, sign, OpenDKIM,
  journal (OpenDKIM kept for the cross-check); `non_smtpd_milters` =
  sign-local, OpenDKIM; `disable_mime_output_conversion=yes`.
- [ ] e2e: dkimpy in the stand; every positive send and the notification
  verified by dkimpy against the panel's signature; the panel's and
  OpenDKIM's `bh=`/`h=` compared.

### Stage 2 - OpenDKIM removed (no release)

- [ ] Chain: OpenDKIM out of both milter lists.
- [ ] Go: `internal/domain/opendkim.go` reduced to key storage (tables,
  `Rebuild`, `assertConfigSafe`, the USR1 reload go), `internal/supervisor`
  (its only caller is the reload), `internal/syslogrelay`,
  `internal/milter/mailparse.go` and its tests and testdata, the
  sender-check texts; Resync's "OpenDKIM's tables" step; Health's
  liveness set and socket row (Q3); `OPENDKIM_SOCKET`/`OPENDKIM_DIR`.
- [ ] Image: the `opendkim` package, `opendkim.conf`, the two supervisord
  programs, the `/dev/log` link and `/run/opendkim`, `usermod -aG selfpost
  opendkim`, crashexit's spared list; `deploy/docker-compose.yml`'s `KILL`
  capability (its only use was the reload).
- [ ] Keys: `/data/opendkim/keys` -> `/data/dkim/keys` (Q2): the entrypoint
  copies the tree once and leaves the old one for a rollback to 2.7.x until
  the next release; KeyTable and SigningTable go with the new layout.
- [ ] Tests: `test/upstream/*.sh`, e2e's OpenDKIM log and process checks,
  the 256-byte test rewritten for the new rule.

### Stage 3 - documents, the canary, the cut

- [ ] architecture § OpenDKIM -> § DKIM signing; security.md (the
  mail-path bullets, the accepted risks that were OpenDKIM's); guide;
  development's cited-package table (opendkim and libopendkim11 leave);
  the assumptions register's header notes what left; help (design commit
  first) and Health's label (Q3, mockup first).
- [ ] Reviews: technical and security.
- [ ] On the test server: a day of the owner's mail; one message from an
  application through 465 and one notification to a real mailbox, the
  headers read (dkim=pass with the panel's `d=`).
- [ ] Cut `2.8.0`.

## Risks

- **A signing defect fails DMARC for every tenant at once.** The answer is
  the oracle (another implementation), the cross-check against OpenDKIM on
  the same messages before it goes, and the canary before the cut.
- **go-msgauth is small and released slowly.** It can be vendored if it
  ever matters; the signing path is about 300 lines of it.
- **Rollback:** until stage 2 ships, the chain change is one line; after
  the cut, the previous image (2.7.x) still has OpenDKIM and reads the same
  keys - under Q2's rename, from the old path, which the move leaves as a
  copy until the next release.