feat: end-to-end DKIM check through a real Postfix, docs and example config

- Check that every message the list delivered through Postfix is signed with the list domain and still verifies, and that edits break it
- Run dkim keygen, record and the no-overwrite rule inside the read-only container
- Document DKIM, SPF and DMARC in the README and show the dkim block in the example config
This commit is contained in:
tgiachi 2026-11-09 20:04:32 +01:00
commit 849a85ec7d
3 changed files with 119 additions and 1 deletions

View file

@ -5,6 +5,7 @@ A modern, single-binary mailing list manager: an evolution of Mailman.
- Postfix delivers to parsimony over LMTP; parsimony relays through SMTP.
- Discussion lists with member-only posting, `List-*` headers, one-click unsubscribe
and DMARC-safe `From` rewriting.
- DKIM signing of outgoing mail with one key per list domain, so DMARC holds after the From rewrite.
- Durable outbound queue: a post is accepted once it is stored, one delivery per recipient,
and a background worker sends it with retries (1m, 5m, 15m, 1h, 3h, then every 6h, for up to
3 days). Relay outages and restarts lose nothing.
@ -89,6 +90,39 @@ of the messages. Messages that cannot be read are listed and counted, and the ex
It works whatever the list's archive policy is (the policy only governs live mail). The admin UI has the same import on
the Archive tab. Search is accent-insensitive: `caffe` finds "Caffè".
## Outgoing mail: DKIM, SPF and DMARC
Parsimony rewrites `From` to the list address, so a signature of the original author's domain is of no use and
receivers that enforce DMARC need a signature of the **list domain**.
```
parsimony dkim keygen lists.example.org --selector mail --out /etc/parsimony/dkim-lists.pem
```
prints the DNS TXT record to publish and the config to add (the private key is written with mode 0600 and the
command never overwrites an existing key without `--force`):
```yaml
dkim:
- domain: lists.example.org
selector: mail
key_file: /etc/parsimony/dkim-lists.pem
```
Once the record is in DNS, `parsimony dkim check lists.example.org --key FILE --selector mail` looks it up and compares it
with the key. Both commands work offline of the API and need no token.
- A message is signed with the key of the domain in its From address (exact match, else a parent domain), at send time, so
the per-recipient `List-Unsubscribe` headers are covered. Relaxed/relaxed, SHA-256, no body length limit.
Signed: From, To, Cc, Subject, Date, Message-ID, In-Reply-To, References, Reply-To, MIME-Version, Content-Type,
Content-Transfer-Encoding and the `List-*` headers. A relay may add `Received` or rewrite other headers.
- A list on a domain without a key is sent unsigned. A broken key file stops the daemon at startup. If signing fails at
send time the error is logged and the message goes out unsigned: not delivering is worse than a missed signature.
- RSA (2048 bits recommended; PKCS#1 or PKCS#8 PEM) and Ed25519 keys are supported. Some receivers do not verify Ed25519 yet.
- Also publish SPF for the machine that relays your mail (for example `v=spf1 ip4:203.0.113.10 -all` on the list domain)
and a DMARC record (start with `_dmarc.lists.example.org TXT "v=DMARC1; p=none; rua=mailto:postmaster@example.org"`,
then tighten the policy once the reports look clean).
## Docker
The image runs as an unprivileged user (uid 65532) and works with a read-only root filesystem.

View file

@ -11,7 +11,12 @@
package e2e
import (
"crypto/rand"
"crypto/rsa"
"crypto/x509"
"encoding/base64"
"encoding/json"
"encoding/pem"
"fmt"
"io"
"net"
@ -24,6 +29,8 @@ import (
"strings"
"testing"
"time"
"github.com/emersion/go-msgauth/dkim"
)
const (
@ -37,6 +44,7 @@ var (
postfixC = "pm-e2e-postfix-" + suffix
parsimonyC = "pm-e2e-parsimony-" + suffix
smtpAddr string
dkimPub *rsa.PublicKey // the list domain's signing key
apiBase string
webBase string
)
@ -84,6 +92,16 @@ func TestMain(m *testing.M) {
apiBase = fmt.Sprintf("http://127.0.0.1:%d", apiPort)
webBase = fmt.Sprintf("http://127.0.0.1:%d", webPort)
// A DKIM key for the list domain, mounted read-only into the container.
key, err := rsa.GenerateKey(rand.Reader, 2048)
if err != nil {
panic(err)
}
dkimPub = &key.PublicKey
keyFile := filepath.Join(os.TempDir(), "pm-e2e-dkim-"+suffix+".pem")
os.WriteFile(keyFile, pem.EncodeToMemory(&pem.Block{Type: "RSA PRIVATE KEY", Bytes: x509.MarshalPKCS1PrivateKey(key)}), 0o644)
defer os.Remove(keyFile)
cfg := filepath.Join(os.TempDir(), "pm-e2e-"+suffix+".yaml")
os.WriteFile(cfg, []byte(fmt.Sprintf(`db: /data/parsimony.db
base_url: %s
@ -97,6 +115,10 @@ api:
listen: 0.0.0.0:8080
web:
listen: 0.0.0.0:8081
dkim:
- domain: lists.example.test
selector: e2e
key_file: /etc/parsimony/dkim.pem
`, webBase)), 0o644)
defer os.Remove(cfg)
@ -104,7 +126,7 @@ web:
"-p", "127.0.0.1::25", "parsimony-e2e-postfix")
mustDocker("run", "-d", "--name", parsimonyC, "--network", network, "--network-alias", "parsimony",
"--read-only", "--cap-drop", "ALL", "-e", "PARSIMONY_API_TOKEN="+token,
"-v", cfg+":/etc/parsimony/parsimony.yaml:ro",
"-v", cfg+":/etc/parsimony/parsimony.yaml:ro", "-v", keyFile+":/etc/parsimony/dkim.pem:ro",
"-p", fmt.Sprintf("127.0.0.1:%d:8080", apiPort), "-p", fmt.Sprintf("127.0.0.1:%d:8081", webPort), image)
smtpAddr = mustDocker("port", postfixC, "25/tcp")
smtpAddr = strings.Split(strings.Split(smtpAddr, "\n")[0], " ")[0] // "127.0.0.1:49153"
@ -263,6 +285,24 @@ func waitMail(t *testing.T, user, contains string) string {
return found
}
// verifyDKIM checks the signatures of a delivered message against the test key.
func verifyDKIM(t *testing.T, raw string) []*dkim.Verification {
t.Helper()
der, _ := x509.MarshalPKIXPublicKey(dkimPub)
vs, err := dkim.VerifyWithOptions(strings.NewReader(raw), &dkim.VerifyOptions{
LookupTXT: func(name string) ([]string, error) {
if name == "e2e._domainkey."+domain {
return []string{"v=DKIM1; k=rsa; p=" + base64.StdEncoding.EncodeToString(der)}, nil
}
return nil, fmt.Errorf("no record %s", name)
},
})
if err != nil {
t.Fatalf("verify: %v", err)
}
return vs
}
func header(msg, name string) string {
re := regexp.MustCompile(`(?im)^` + regexp.QuoteMeta(name) + `:[ \t]*(.*(?:\r?\n[ \t]+.*)*)`)
if m := re.FindStringSubmatch(msg); m != nil {
@ -608,6 +648,44 @@ func TestWholePath(t *testing.T) {
}
})
t.Run("everything the list delivered is DKIM-signed and still verifies after Postfix", func(t *testing.T) {
checked := 0
for _, user := range []string{"alice", "bob", "carol"} {
for _, m := range mailbox(user) {
vs := verifyDKIM(t, m)
if len(vs) != 1 || vs[0].Err != nil || vs[0].Domain != domain {
t.Fatalf("%s: message %q is not validly signed by %s: %+v", user, header(m, "Subject"), domain, vs)
}
if from := header(m, "From"); !strings.Contains(from, "@"+domain) {
t.Fatalf("a signature for the list domain only makes sense when From is on it: %q", from)
}
checked++
}
}
if checked < 8 {
t.Fatalf("expected posts, confirmations and approved mail, checked only %d", checked)
}
// A copy changed after delivery must fail verification.
m := mailbox("bob")[0]
tampered := strings.Replace(m, "Subject: ", "Subject: [edited] ", 1)
if vs := verifyDKIM(t, tampered); len(vs) != 1 || vs[0].Err == nil {
t.Fatalf("a modified message must not verify: %+v", vs)
}
})
t.Run("dkim keygen works in the read-only container", func(t *testing.T) {
out, err := docker("exec", parsimonyC, "/parsimony", "dkim", "keygen", "keys.example.test", "--out", "/data/e2e-key.pem")
if err != nil || !strings.Contains(out, "mail._domainkey.keys.example.test.") || !strings.Contains(out, "v=DKIM1; k=rsa; p=") {
t.Fatalf("keygen: %v\n%s", err, out)
}
if out, err := docker("exec", parsimonyC, "/parsimony", "dkim", "keygen", "keys.example.test", "--out", "/data/e2e-key.pem"); err == nil || !strings.Contains(out, "already exists") {
t.Fatalf("must not overwrite: %v %s", err, out)
}
if out, err := docker("exec", parsimonyC, "/parsimony", "dkim", "record", "keys.example.test", "--key", "/data/e2e-key.pem"); err != nil || !strings.Contains(out, "v=DKIM1") {
t.Fatalf("record: %v %s", err, out)
}
})
t.Run("the queue ends empty", func(t *testing.T) {
waitQueueEmpty(t)
})

View file

@ -11,3 +11,9 @@ web:
api:
listen: 0.0.0.0:8080
# The API token is read from the PARSIMONY_API_TOKEN environment variable.
# Sign outgoing mail with DKIM, one key per domain. The private key stays in a file
# (create it with: parsimony dkim keygen lists.example.org --selector mail).
# dkim:
# - domain: lists.example.org
# selector: mail
# key_file: /etc/parsimony/dkim-lists.pem