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

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