bongo/docs/tls.md

# TLS policy

Bongo offers TLS 1.3 and TLS 1.2 by default. Older protocol versions are only
available on listeners whose explicit legacy-TLS option is enabled. Keep those
listeners restricted to trusted legacy networks; do not expose them directly
to the Internet.

The SMTP delivery agent uses opportunistic STARTTLS. When a peer offers
STARTTLS, it encrypts the connection. `outbound_tls_verify` additionally
verifies the certificate chain against the system trust store and verifies the
connected MX or configured LMTP host name. It defaults to `false`, because
public Internet MX servers cannot universally be assumed to have a usable
public-PKI certificate. Enable it for a closed set of known destinations.

`outbound_tls_ca_file` may name an additional PEM trust file. The system trust
store remains active; this option is intended for a private relay CA or an
isolated integration fixture, not for disabling public WebPKI validation.

`outbound_tls_required` defaults to `false`, so delivery remains possible to
SMTP servers which do not offer STARTTLS. Enabling it defers mail instead of
sending plaintext. It is a global policy and should only be enabled when every
configured destination is known to support TLS.

When `use_relay_host` is enabled, Bongo sends remote mail to the configured
next hop instead of performing an MX lookup. `relay_host` is a DNS hostname or
IPv4 address and `relay_port` accepts non-standard submission ports. The
relay-specific TLS policy follows the familiar Postfix client levels:

- `none` disables TLS;
- `may` prefers STARTTLS but permits plaintext;
- `encrypt` requires encryption without authenticating the certificate; and
- `verify` requires encryption, a trusted chain, and a matching relay hostname.

Set `relay_tls_wrapper_mode` only with `encrypt` or `verify` for implicit TLS
(normally port 465). `relay_tls_ca_file` adds a private CA for `verify`.
Relayhost authentication is disabled when `relay_username` and
`relay_password_file` are empty. Configure both to authenticate to an ISP or
hosted smarthost. A rejected login remains a temporary delivery failure, so the
message stays in the Queue and can be retried after credentials are repaired.
The password file contains only the password on its first line. For the
unprivileged SMTP delivery agent, use ownership `root:bongo` and mode `0640`;
symbolic links, non-regular files, group-writable files and files accessible
to other users are rejected.

Per-message RFC 8689 REQUIRETLS is stronger than merely requiring encryption.
As in Postfix, Bongo requires the next hop to advertise REQUIRETLS and requires
an authenticated delivery policy: usable DANE, enforcing MTA-STS, or a
DNSSEC-authenticated MX/address lookup combined with explicitly enabled Web
PKI verification. DANE-EE and DANE-TA authentication do not also require an
unrelated public-CA validation.

`outbound_dane_enabled` defaults to `true`. RFC 7672 DANE is activated only
when both the MX and the address used for the connection were authenticated by
DNSSEC. Bongo independently validates the complete TLSA response or
authenticated denial with libunbound before passing a secure RRset to
GnuTLS/libdane for certificate matching. This separation is important because
libdane alone does not retain DNSSEC status for an empty TLSA response. A
secure usable DANE-EE(3) or DANE-TA(2) record makes STARTTLS and DANE
authentication mandatory; DANE-TA also checks the MX and original next-hop
names. PKIX-TA(0) and PKIX-EE(1) records do not become SMTP DANE trust anchors.
A secure TLSA RRset containing no usable SMTP records still makes TLS
mandatory. Bogus or indeterminate DNSSEC results defer delivery. An insecure
TLSA response or securely proven TLSA absence leaves the existing
opportunistic STARTTLS policy in place.

For the deployed but non-conforming MX-to-CNAME case, Bongo follows Postfix's
RFC 7672 handling: it tries TLSA at the DNSSEC-authenticated canonical address
name first and falls back to the original MX owner only when no authenticated
policy was found there. The selected TLSA base domain is used for SNI and
DANE-TA reference-name checks. MTA-STS matching and Web PKI verification
continue to use the actual MX hostname.

`outbound_mta_sts_enabled` also defaults to `true`. When no authenticating
DANE policy is active, Bongo discovers the RFC 8461 policy at
`_mta-sts.<domain>`, downloads it only over certificate-validated HTTPS, and
keeps the validated policy in
`outbound_mta_sts_cache_directory`. An `enforce` policy permits only listed
MX hosts and requires authenticated TLS 1.2 or newer; policy, certificate,
STARTTLS, and handshake failures defer delivery without a plaintext retry. A
`testing` policy records the same failures without changing delivery. A valid
cached policy remains authoritative through its `max_age` when DNS discovery
or HTTPS refresh temporarily fails. A usable authenticating DANE policy takes
precedence over MTA-STS; an all-unusable TLSA set may still be strengthened by
an enforcing MTA-STS policy.

When outbound TLS reporting is enabled, the SMTP delivery agent records one
final TLS policy result for each attempted destination. The worker aggregates
completed UTC days into RFC 8460 JSON reports without losing late events or
double-counting retries. It preserves the exact DNS TLSRPT policy that was
used for delivery, waits a randomized interval of up to four hours, and sends
one durable delivery to every `mailto:` and `https:` reporting URI. Reports
are gzip-compressed; mail reports use `multipart/report` with an
`application/tlsrpt+gzip` attachment, while HTTPS reports use a validated
HTTPS POST. Temporary failures are retried with persisted exponential backoff
for 24 hours after the initial attempt.

TLS report messages carry `TLS-Required: No` and bypass outbound DANE,
MTA-STS, and TLSRPT accounting so a receiver's TLS failure cannot create a
report loop. They still prefer STARTTLS. RFC 8460 requires email reports to be
DKIM-signed, so `mailto:` delivery remains pending unless outbound DKIM is
enabled and the configured key for the reporting domain is readable. The
submitter defaults to the DKIM signing domain, or otherwise to the configured
Bongo host name. HTTPS report delivery does not depend on DKIM.

The resolver named in `resolv.conf` must therefore be a trusted validating
resolver reached over a trusted local path; Bongo must not trust an AD bit
received from an untrusted network resolver. GnuTLS/libdane also needs its
DNSSEC root trust anchor installed by the operating system.

External-account collection and submission use libcurl and independently
verify certificates and host names by default. See `external-accounts.md` for
the credential and provider policy.

Initial setup stores the default certificate and key as
`/etc/bongo/ssl.d/server.crt` and `/etc/bongo/ssl.d/server.key`. The key is
root-owned, group-readable by Bongo, and never world-readable. Setup creates a
3072-bit RSA self-signed certificate only when no pair exists. A complete
existing pair is parsed and checked for a matching key before reuse; unsafe,
invalid, or incomplete material fails closed.

The `bongoworker` ACME job implements RFC 8555 directly. It honors CA
`Retry-After` limits and renewal information, writes candidate material first,
validates the complete certificate/key pair, then deploys it atomically and
signals the manager to reload TLS listeners. HTTP-01 is the default. DNS-01
publishes `base64url(SHA-256(keyAuthorization))`, waits for the exact TXT value
through ldns, and removes only the value created for that authorization.

For DNS-01, `/etc/bongo/acme.d/providers` selects the longest matching zone.
Use `type: "nsupdate"` for the native RFC 2136 adapter; `rfc2136` is an alias.
No external `nsupdate` process is used. The adapter supports SOA-primary
discovery, explicit IPv4/IPv6 or host-name servers, non-default ports, and
TSIG HMAC algorithms. Delegated CNAME challenges use `match_zone`,
`challenge_alias`, and the provider's target `zone`. Installed examples are
in `/usr/share/bongo/examples/acme`.

`bongo-admin migrate` moves the historical `osslcert.pem` and `osslpriv.pem`
pair from the state database directory into `ssl.d` only when both files are
present and the destination is empty. ACME deployments should atomically
install a complete pair and reload or restart the affected Bongo agents.