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.