Last updated: 2026-06-25

OpenSMTPD TLS/SSL Configuration Guide

This guide provides recommended TLS/SSL settings for OpenSMTPD, the SMTP server from the OpenBSD project. OpenSMTPD takes a deliberately minimal approach to TLS configuration: instead of exposing dozens of tuning knobs, it relies on the secure defaults of the underlying TLS library (LibreSSL on OpenBSD, OpenSSL on most portable builds). Like any SMTP server, it has two TLS roles: receiving mail on the public MX (port 25) and accepting authenticated submission (ports 587 and 465). These call for different policies, which is reflected in the listener configuration below.

Prerequisites#

• OpenSMTPD 6.6 or later (the tls / tls-require listener syntax shown here; current stable is 7.8.0p1)
• LibreSSL (OpenBSD base) or OpenSSL 1.1.1 or later (portable builds on Linux, FreeBSD, etc.)
• A valid SSL/TLS certificate from a trusted CA

OpenSMTPD links against LibreSSL when built on OpenBSD, and usually against OpenSSL on Linux and other portable platforms. The TLS knobs described here are the same in both cases; the secure defaults they rely on come from whichever library is linked. The cipher and protocol keyword formats (secure, tlsv1.2, and so on) are provided by LibreSSL's libtls, which the portable build bundles or shims.

A note on OpenSMTPD's minimal TLS surface#

Compared to Postfix, OpenSMTPD exposes far fewer TLS options on purpose. There is no per-server session cache database to configure, no separate mandatory-versus-opportunistic cipher grade, and no long list of smtpd_tls_* parameters. TLS is configured entirely on the listen on line and through pki blocks. The library defaults are chosen to be safe, so the recommended configuration is short. Where this guide tightens a default, it does so with the two options OpenSMTPD actually provides for this purpose: protocols and ciphers.

Certificate Configuration#

Certificates are declared with pki blocks. Each block is named, and the name is referenced later by listeners. Provide the full certificate chain and the private key:

pki mail.example.com cert "/etc/ssl/mail.example.com/fullchain.pem"
pki mail.example.com key "/etc/ssl/mail.example.com/privkey.pem"

The pki name is an arbitrary label. Using the server's hostname is a common convention and makes SNI configuration clearer when you serve more than one certificate. To present different certificates for different hostnames, declare multiple pki blocks and list multiple pki options on the listener; OpenSMTPD selects the matching one by SNI.

Listener Configuration#

OpenSMTPD configures TLS on the listen on line. The interface argument can be a specific interface, an interface group, an IP address, or a hostname. The all interface group listens on every interface and covers both IPv4 and IPv6:

listen on all tls pki mail.example.com

To bind explicit addresses instead, or to split IPv4 and IPv6, repeat the line. You can also restrict a listener to one address family with inet4 or inet6:

listen on 192.0.2.25 tls pki mail.example.com
listen on 2001:db8::25 tls pki mail.example.com

Inbound MX (port 25): opportunistic STARTTLS#

For the public-facing MX that receives mail from other servers, use opportunistic TLS. The tls option advertises STARTTLS and uses it when the sending server supports it, but still accepts plaintext from servers that do not:

listen on all tls pki mail.example.com

On a public MX, use tls, not tls-require. Requiring encryption on port 25 would reject mail from any sending server that does not offer STARTTLS, bouncing legitimate email. Opportunistic TLS is the correct policy for inbound MX traffic.

Submission (port 587): mandatory STARTTLS#

Authenticated submission from mail clients should require encryption, since credentials are sent over the connection. Use tls-require to force a successful STARTTLS handshake before OpenSMTPD will accept the SMTP transaction:

listen on all port 587 tls-require pki mail.example.com auth

The auth option enables SASL authentication on the submission listener. With tls-require, the client cannot authenticate or send mail until TLS is established.

Submission over implicit TLS (port 465): smtps#

Port 465 uses implicit TLS: the connection is encrypted from the first byte, with no plaintext STARTTLS preamble. Enable it with smtps:

listen on all smtps pki mail.example.com auth

The smtps option defaults to port 465 and is mutually exclusive with tls on the same listener. Implicit TLS is preferred over STARTTLS for submission because there is no plaintext negotiation that a network attacker could strip or intercept.

Protocol Versions#

Restrict TLS to version 1.2 and above with the protocols option. The value is parsed by LibreSSL's tls_config_parse_protocols, which accepts the keywords tlsv1.2, tlsv1.3, all, legacy, and secure (an alias for default, currently TLSv1.2 and TLSv1.3). The secure keyword already means "TLS 1.2 and 1.3 only," which is the recommended baseline, so the library default is safe out of the box:

listen on all tls pki mail.example.com protocols "secure"

Setting protocols "secure" is equivalent to the default on current LibreSSL and OpenSSL builds; include it to make the policy explicit and to stay safe on any build whose default differs. You can also name versions directly, for example protocols "tlsv1.2,tlsv1.3", or remove an unwanted version with a leading exclamation mark, for example protocols "all,!tlsv1.0,!tlsv1.1".

Cipher Selection#

The ciphers option sets the TLS 1.2 cipher list. It accepts the LibreSSL keyword sets secure (alias default), compat, legacy, and insecure (alias all), or an OpenSSL-style cipher string. The default keyword, secure, already restricts the server to strong AEAD suites with forward secrecy:

listen on all tls pki mail.example.com protocols "secure" ciphers "secure"

If you want to pin an explicit list rather than rely on the keyword, OpenSMTPD passes an OpenSSL-style cipher string through to the TLS library. The site-standard AEAD-only, forward-secret list is:

listen on all tls pki mail.example.com protocols "secure" \
    ciphers "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305"

TLS 1.3 cipher suites are fixed by the protocol specification and are not selected through the ciphers option. OpenSMTPD does not expose a separate TLS 1.3 cipher knob; the three standard TLS 1.3 suites are always available when TLS 1.3 is negotiated.

For most deployments, ciphers "secure" (or simply omitting the option to take the default) is sufficient and is what the OpenBSD project recommends. The explicit list is shown for operators who must document an exact, audited cipher set.

Mutual TLS (mTLS)#

Standard TLS in SMTP encrypts the connection but does not verify the identity of the connecting client. Mutual TLS adds client authentication: OpenSMTPD requires the connecting party to present a valid certificate signed by a configured CA. This is an uncommon requirement for public mail and is most useful for private relays or server-to-server links between hosts you control on both sides. Do not require client certificates on a public MX, since other mail servers will not present one.

Declare the CA that signs your client certificates with a ca block, then reference it on the listener together with the verify keyword. Adding verify to tls-require (or to smtps) makes a valid client certificate mandatory:

ca partner-ca cert "/etc/ssl/partner-ca.pem"

listen on 192.0.2.25 port 587 tls-require verify pki mail.example.com ca partner-ca auth

• ca caname cert "file" - Declares the CA certificate used to verify client certificates.
• ca caname (on the listener) - Selects which declared CA verifies presented client certificates.
• verify - Requires a valid client certificate; connections without one are rejected. Used as tls-require verify or smtps verify.

See RFC 8446 §4.3.2 for the TLS Certificate Request specification, and Wikipedia: Mutual authentication for a general overview.

Complete Configuration#

A full /etc/mail/smtpd.conf with opportunistic TLS on the MX and mandatory TLS on submission:

# Certificate (full chain) and private key
pki mail.example.com cert "/etc/ssl/mail.example.com/fullchain.pem"
pki mail.example.com key "/etc/ssl/mail.example.com/privkey.pem"

# Inbound MX: opportunistic STARTTLS on port 25.
# Use tls (not tls-require) so mail from servers without STARTTLS is not bounced.
# "secure" pins TLS 1.2 and 1.3; the ciphers keyword keeps the AEAD/forward-secret default.
listen on all tls pki mail.example.com protocols "secure" ciphers "secure"

# Submission: mandatory STARTTLS on port 587 with SASL auth.
listen on all port 587 tls-require pki mail.example.com protocols "secure" ciphers "secure" auth

# Submission: implicit TLS on port 465 with SASL auth.
listen on all smtps pki mail.example.com protocols "secure" ciphers "secure" auth

# Local delivery and relay rules follow your site policy, for example:
action "local" mbox
action "relay" relay

match for local action "local"
match from any for domain "example.com" action "local"
match from local for any action "relay"

To pin an explicit, audited cipher list instead of the secure keyword, replace ciphers "secure" with the OpenSSL-style string shown in the Cipher Selection section. Both produce an AEAD-only, forward-secret cipher set.

Security Notes#

OpenSMTPD relies on the LibreSSL or OpenSSL defaults, tightened by the protocols and ciphers options above. With TLS 1.2 as the minimum and an AEAD-only, forward-secret cipher set, the configuration in this guide addresses the following known TLS vulnerabilities:

• POODLE (CVE-2014-3566, 2014): SSL 3.0 is disabled. The LibreSSL/libtls defaults do not offer SSL 3.0, and protocols "secure" permits only TLS 1.2 and 1.3.
• BEAST (CVE-2011-3389, 2011): Mitigated by requiring TLS 1.2 as the minimum; AEAD-only ciphers eliminate the CBC padding oracle.
• CRIME (CVE-2012-4929, 2012): TLS compression is not enabled by the LibreSSL/libtls or OpenSSL defaults; do not enable it.
• Lucky13 (2013): AEAD-only cipher list eliminates CBC padding timing side-channels entirely.
• FREAK (CVE-2015-0204, 2015): EXPORT-grade ciphers are excluded; the LibreSSL/libtls defaults and the recommended cipher string contain no EXPORT suites.
• LOGJAM (CVE-2015-4000, 2015): Short-key DHE is excluded; only ECDHE key exchange is recommended.
• Sweet32 (CVE-2016-2183, 2016): 3DES is excluded from the recommended cipher string (AEAD suites only), so it is never negotiated.
• ROBOT (2017): Static RSA key exchange is excluded; only ECDHE is recommended.
• Downgrade attacks: TLS_FALLBACK_SCSV prevents protocol version rollback; it is enabled by default in modern LibreSSL and OpenSSL.
• Renegotiation injection (CVE-2009-3555, 2009): Secure renegotiation is enforced by default in modern LibreSSL and OpenSSL; TLS 1.3 removes renegotiation entirely.

The following are not addressable through TLS configuration alone:

• Heartbleed (CVE-2014-0160, 2014): A memory disclosure bug in OpenSSL 1.0.1 through 1.0.1f. Fixed in OpenSSL 1.0.1g (April 7, 2014); LibreSSL was forked partly in response to it and was never affected. Addressed by patching the TLS library, not by TLS configuration.
• BREACH (CVE-2013-3587, 2013): Not applicable. BREACH targets HTTP-level response compression; SMTP does not involve HTTP.
• DROWN (CVE-2016-0800, 2016): Requires SSLv2 to be enabled on any server sharing the same private key. Ensure SSLv2 is disabled on all services that use the same certificate and key pair; LibreSSL/libtls does not support SSLv2 at all.

Verification#

Check the configuration syntax and reload OpenSMTPD:

smtpd -n
rcctl reload smtpd

On systemd-based portable installs, use systemctl reload opensmtpd instead of rcctl.

Test submission over implicit TLS (port 465):

openssl s_client -connect mail.example.com:465

Test inbound STARTTLS on port 25 and submission STARTTLS on port 587:

openssl s_client -connect mail.example.com:25 -starttls smtp
openssl s_client -connect mail.example.com:587 -starttls smtp

Check OpenSMTPD's log for TLS connection details:

grep smtpd /var/log/maillog

On OpenBSD the mail log is /var/log/maillog; many Linux distributions write it to /var/log/mail.log instead.

Test your MX and submission certificates externally with the Mr.DNS SSL/TLS Certificate Check (port 25 for inbound STARTTLS, 465 for implicit TLS).

Verify SPF, DKIM, and DMARC alignment for the sending domain with the Mr.DNS Email Authentication Health Check.