Overview

Mail clients send passwords and messages to the server, and other mail servers deliver messages to it. TLS encrypts these connections, so that nobody on the network path can read or alter them, and lets the client verify that it is talking to the right server. Stalwart encrypts connections with TLS on every listener that has TLS enabled.

Two things are needed for that. The first is a certificate for each name that clients connect to, which proves the server’s identity. The second is the TLS settings of each listener, which determine whether a connection starts with TLS and which protocol versions and cipher suites the listener accepts.

Certificates

Certificates are obtained in one of two ways:

• ACME obtains and renews certificates automatically from a certificate authority such as Let’s Encrypt. It is enabled per domain.
• Certificates issued by another authority, including an internal one, are installed by hand, as described in Certificates.

Both kinds are stored as Certificate objects. For each connection, the server chooses among them from the name that the client requests.

Scope of this section

This section covers the server side of TLS, which means the connections that clients and other servers open to Stalwart. TLS for the deliveries that Stalwart itself makes over SMTP is configured separately, including DANE and MTA-STS enforcement. Outbound TLS, DANE and MTA-STS describe it.

Listener settings

TLS is configured per listener, on the NetworkListener object (found in the WebUI under Settings › Network › Listeners). Each listener makes a few decisions about TLS.

The first decision is whether the listener uses TLS at all, and when the connection becomes encrypted:

• useTls enables TLS on the listener. STARTTLS not offered or TLS handshake fails lists the usual causes of TLS failures on a listener.
• implicitTls starts every connection with a TLS handshake. Without it, the mail protocols begin in plain text and offer STARTTLS, a command with which the client upgrades the connection to TLS. Listeners explains the two modes.
• tlsTimeout limits the time a client has to complete the handshake.

The second decision is which parts of TLS the listener accepts:

• tlsDisableProtocols lists the TLS versions to refuse, tls12 or tls13. When the list is empty, both are accepted. Disabling both has the same effect as disabling none: both remain enabled.
• tlsDisableCipherSuites lists the cipher suites to refuse. It does not affect key exchange groups.
• tlsIgnoreClientOrder decides whose preference counts when the client and the server both support several cipher suites. When it is enabled, the server chooses in its own order of preference. When it is disabled, the client’s order is used. It is enabled unless changed.

The certificate is not a listener setting. Clients that do not send a server name receive the certificate selected by SystemSettings.defaultCertificateId, and Certificates describes the full selection.

Protocol versions

TLS 1.2 and TLS 1.3 are supported. Earlier versions, including TLS 1.1 and 1.0, are not offered.

Cipher suites

A cipher suite is the combination of algorithms that protects a connection once the handshake is complete. The server offers the following nine cipher suites, in this order of preference. The names are the values that tlsDisableCipherSuites accepts, and a listener offers all of them except the ones it disables.

Version	Cipher suite
TLS 1.3	tls13-aes-256-gcm-sha384
TLS 1.3	tls13-aes-128-gcm-sha256
TLS 1.3	tls13-chacha20-poly1305-sha256
TLS 1.2	tls-ecdhe-ecdsa-with-aes-256-gcm-sha384
TLS 1.2	tls-ecdhe-ecdsa-with-aes-128-gcm-sha256
TLS 1.2	tls-ecdhe-ecdsa-with-chacha20-poly1305-sha256
TLS 1.2	tls-ecdhe-rsa-with-aes-256-gcm-sha384
TLS 1.2	tls-ecdhe-rsa-with-aes-128-gcm-sha256
TLS 1.2	tls-ecdhe-rsa-with-chacha20-poly1305-sha256

The TLS 1.2 suites depend on the type of the certificate’s key. The suites with ECDSA work only with an ECDSA certificate, and those with RSA only with an RSA certificate. Certificates issued through ACME use ECDSA keys.

Key exchange groups

A key exchange group is the algorithm with which the client and the server agree on the keys for the connection. The server offers a fixed set of groups, which cannot be configured:

• X25519MLKEM768, a hybrid of X25519 and the post-quantum ML-KEM-768. It is used with TLS 1.3 by clients that support it, including current web browsers.
• X25519
• SECP256R1
• SECP384R1

The client’s order of preference decides which group is used, because tlsIgnoreClientOrder applies to cipher suites only.

Example

The following listener accepts submission with STARTTLS on port 587. It accepts TLS 1.3 only, and refuses the AES-256 suite:

{
  "name": "submission",
  "protocol": "smtp",
  "bind": {"[::]:587": true},
  "useTls": true,
  "implicitTls": false,
  "tlsDisableProtocols": {"tls12": true},
  "tlsDisableCipherSuites": {"tls13-aes-256-gcm-sha384": true}
}

The same restriction on port 25 is not advisable. Many sending servers still use TLS 1.2, and a sender that cannot negotiate TLS either delivers in plain text or fails, depending on its policy.