Overview

Transport Layer Security (TLS) encrypts data in transit between Stalwart and its peers, keeping mail and management traffic confidential and tamper-evident. TLS is the usual answer to eavesdropping and machine-in-the-middle attacks against mail transport.

Stalwart supports two ways of obtaining certificates. Manually provided certificates fit organisations with their own certificate authority or strict procurement policies: the certificate and private key are imported into the server and used directly. For operators who prefer automation, Stalwart also implements the ACME protocol and can integrate with ACME-compliant providers such as Let’s Encrypt to issue and renew certificates without manual intervention.

Settings

TLS is configured per listener: each NetworkListener (found in the WebUI under Settings › Network › Listeners) carries its own TLS fields, and the relevant ones are:

• useTls: whether TLS is available on this listener. Default true.
• tlsImplicit: whether the listener uses implicit TLS (encrypted from the first byte) rather than explicit TLS (upgrade via STARTTLS). Default false.
• tlsTimeout: how long to wait for the client to complete the TLS handshake. Default "1m".
• tlsDisableProtocols: TLS versions to refuse on this listener. When empty, both TLS 1.2 and TLS 1.3 are offered.
• tlsDisableCipherSuites: cipher suites to refuse. When empty, the full set built into the TLS library is offered.
• tlsIgnoreClientOrder: whether the server uses its own cipher order. When false, the client’s preferred order is honoured. Default true.

The default certificate used when a client connects without sending an SNI value is selected globally through defaultCertificateId on the SystemSettings singleton.

Supported TLS versions

The following TLS versions are supported:

• TLSv1.3
• TLSv1.2

TLS 1.1 is not supported; it has known security weaknesses and has been deprecated by the major standards bodies and browser vendors.

Supported cipher suites

The following TLS 1.3 cipher suites are supported:

• tls13-aes-256-gcm-sha384
• tls13-aes-128-gcm-sha256
• tls13-chacha20-poly1305-sha256

The following TLS 1.2 cipher suites are supported:

• tls-ecdhe-ecdsa-with-aes-256-gcm-sha384
• tls-ecdhe-ecdsa-with-aes-128-gcm-sha256
• tls-ecdhe-ecdsa-with-chacha20-poly1305-sha256
• tls-ecdhe-rsa-with-aes-256-gcm-sha384
• tls-ecdhe-rsa-with-aes-128-gcm-sha256
• tls-ecdhe-rsa-with-chacha20-poly1305-sha256

Supported exchange groups

The following exchange groups are supported:

• X25519
• SECP256R1
• SECP384R1

Example

The following listener disables TLS 1.2 and two cipher suites, keeping implicit TLS off and the server cipher order preferred:

{
  "name": "submission",
  "protocol": "smtp",
  "bind": ["[::]:587"],
  "useTls": true,
  "tlsImplicit": false,
  "tlsTimeout": "1m",
  "tlsDisableProtocols": ["tls12"],
  "tlsDisableCipherSuites": [
    "tls13-aes-256-gcm-sha384",
    "tls-ecdhe-rsa-with-chacha20-poly1305-sha256"
  ],
  "tlsIgnoreClientOrder": true
}