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