# 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, `outbound_tls_verify` verifies its certificate chain against the
system trust store and verifies the connected MX or configured LMTP host name.
It defaults to `true`. Set it to `false` only for a peer whose certificate
cannot yet be repaired.

`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. A later policy layer may apply
per-domain DANE or MTA-STS requirements.

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.