# 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:

```text
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`.