bongo/docs/mail-authentication.md

Mail authentication

Bongo 0.7 uses separate, established libraries for each mail-authentication job:

• libspf2 checks the SMTP client and envelope identity on incoming mail.
• OpenDKIM verifies incoming signatures and signs outgoing mail.
• OpenDMARC evaluates SPF and all DKIM results against the single RFC5322 From domain.
• GNU Mailutils parses the RFC5322 From field; it is not an SPF, DKIM or DMARC engine.
• libsrs2 rewrites the envelope sender when mail is forwarded and reverses the resulting SRS recipient when a bounce returns.

Incoming checks run on unauthenticated external SMTP sessions. Authenticated submission and the restricted internal-relay listener are not rejected by DMARC. Bongo writes the local SPF, DKIM and DMARC decisions into one Authentication-Results field before handing the message to the queue. At that trust boundary, all incoming Authentication-Results fields are removed because an unauthenticated sender can forge them. Bongo then adds one fresh local result field after verification.

The relevant smtp configuration keys are:

• spf_verify, dkim_verify, and dmarc_verify enable the incoming checks.
• dmarc_enforce defers temporary lookup failures and rejects messages when a sampled p=reject policy applies. A p=quarantine result remains accepted and is recorded for later filtering; it is never treated as reject.
• dkim_sign_outgoing, dkim_key_directory, dkim_selector, and dkim_signing_domain control outgoing DKIM signatures.
• srs_forward, srs_reverse, srs_domain, and srs_secret_file control SRS forwarding and bounce reversal.

Every delivery which leaves Bongo for an external SMTP peer is authenticated before transmission. Local, authenticated, trusted-internal-relay and Bongo-generated bounce traffic receives a Bongo DKIM signature. This includes mail returned by Mailman over the restricted internal SMTP listener and mail sent through a system or per-user relayhost. An unauthenticated incoming message forwarded to another external domain receives an SRS envelope sender instead; Bongo defers that delivery if SRS is disabled or unusable rather than leaking the original sender unchanged. Internal Store delivery and configured LMTP delivery do not add DKIM or SRS.

The SRS secret and DKIM private keys must not be readable by other users. SRS addresses are envelope addresses such as SRS0=...@example.org; SRS is not a message-header format.

SPF and DMARC are DNS policies rather than per-message signatures. The setup wizard validates their DNS records, while the SMTP agents only evaluate them at delivery time. It writes public-key hints below /etc/bongo/dkim.d/DOMAIN and suffixless per-domain check state below /etc/bongo/dmarc.d.

The generated starting policy is deliberately conservative:

DOMAIN                              TXT  v=spf1 ip4:PUBLIC_IPV4 -all
SELECTOR._domainkey.DOMAIN          TXT  v=DKIM1; k=rsa; p=PUBLIC_KEY
_dmarc.DOMAIN                       TXT  v=DMARC1; p=none; rua=mailto:dmarc-reports@DOMAIN

If no public outbound IPv4 address is supplied, the SPF suggestion uses mx and is marked for review. Bongo follows SPF RFC 7208, DKIM RFC 6376, current DMARC RFC 9989, and aggregate-report RFC 9990. RFC 9989 removed the historical pct tag; use t=y while testing a stricter policy. Start with p=none, review reports, then deliberately progress to quarantine or reject.