From 8461468bfd9f4303c4276a3ae4a607792d208ced Mon Sep 17 00:00:00 2001 From: Brennan Kinney <5098581+polarathene@users.noreply.github.com> Date: Thu, 25 Sep 2025 20:43:32 +1200 Subject: [PATCH] docs(tls): Revise customization section - Better document cipher suite support. - Custom DH params revised. - Additional note about impact of disabling DH params and how to exclude DHE cipher suites. --- docs/content/config/security/ssl.md | 171 +++++++++++++++++++++++++++- 1 file changed, 166 insertions(+), 5 deletions(-) diff --git a/docs/content/config/security/ssl.md b/docs/content/config/security/ssl.md index 46f12182..e6013004 100644 --- a/docs/content/config/security/ssl.md +++ b/docs/content/config/security/ssl.md @@ -906,17 +906,172 @@ if [ "$certcheck_2weeks" = "Certificate will not expire" ]; then fi ``` -## Custom DH Parameters +## DMS - TLS (technical details) -TODO +### Cipher suite support by `TLS_LEVEL` -By default DMS uses [`ffdhe4096`][ffdhe4096-src] from [IETF RFC 7919][ietf::rfc::ffdhe]. These are standardized pre-defined DH groups and the only available DH groups for TLS 1.3. It is [discouraged to generate your own DH parameters][dh-avoid-selfgenerated] as it is often less secure. +Both Postfix and Dovecot are configured with the following cipher lists depending on the [`TLS_LEVEL` ENV][docs-env::tls-level], which only affects the authenticated ports (_**SMTP:** 587 + 465 / **POP3:** 110 + 995 / **IMAP:** 143 + 993_): -Despite this, if you must use non-standard DH parameters or you would like to swap `ffdhe4096` for a different group (eg `ffdhe2048`); Add your own PEM encoded DH params file via a volume to `/tmp/docker-mailserver/dhparams.pem`. This will replace DH params for both Dovecot and Postfix services during container startup. +```sh +# TLS_LEVEL=modern +ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384 + +# TLS_LEVEL=intermediate +ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA256 +``` + +For clarity, the permitted [cipher suites][wikipedia::cipher-suites] are comprised of the components: + +- **Key-Exchange:** ECDHE + DHE +- **Authentication:** RSA + ECDSA (_depending on the key type of your TLS certificate(s)_) +- **Encryption:** AES-GCM + CHACHA20-POLY1305 + AES-CBC + +The default `TLS_LEVEL=modern` includes: `DHE-RSA-AES128-GCM-SHA256` + `DHE-RSA-AES256-GCM-SHA384` + +`TLS_LEVEL=intermediate` includes 6 additional cipher suites that leverage the AES-CBC encryption cipher. While the AES-CBC cipher in TLS 1.2 should be generally considered secure, it is [not AEAD][tls::cbc-not-aead] (_hence their exclusion from `TLS_LEVEL=modern`_). + +These are the additional cipher suites supported via `TLS_LEVEL=intermediate`, they use the `ECDHE` / `DHE` key-exchange algorithms (_which provide [perfect forward secrecy][tls::pfs]_): + +- **ECDHE:** + - **ECDSA:** `ECDHE-ECDSA-AES128-SHA256` + `ECDHE-ECDSA-AES256-SHA384` + - **RSA:** `ECDHE-RSA-AES128-SHA256` + `ECDHE-RSA-AES256-SHA384` +- **DHE:** + - **RSA:** `DHE-RSA-AES128-SHA256` + `DHE-RSA-AES256-SHA256` + +??? info "Cipher suite negotiation is via server preference" + + The client sends a list of cipher suites it can support negotiating, and the server will compare that with it's own to decide which one to use. Choosing the first compatible cipher suite from the two lists can be configured to prefer the server or the clients cipher list. + + --- + + DMS defaults to server preference when negotiating TLS 1.2 (or lower when configured): + + - **Postfix:** `tls_preempt_cipherlist = yes` + - **Dovecot:** `ssl_server_prefer_ciphers = server` (_Prior to DMS v16, the equialent setting for Dovecot 2.3 was `ssl_prefer_server_ciphers = yes`_) + + Server preference prioritizes cipher suites by these factors: + + - Key-Exchange: ECDHE before an equivalent DHE cipher suite. + - Cipher: AEAD ciphers sorted by those most commonly supported, with their lower security level variant first (_128-bit symmetric security is incredibly secure already_). Any non-AEAD cipher suites would be appended to the list with the same sorting rules. + + --- + + Client preference should be ok to enable with the cipher lists configured by DMS. + + - `TLS_LEVEL=modern` only offers cipher suites that use AEAD ciphers. + - `TLS_LEVEL=intermediate` additionally includes AES-CBC ciphers (non-AEAD) that are known to be secure (_but have historically had related cipher suites with a variety of vulnerabilities_). + - Port 25 has an even broader cipher list configured than `TLS_LEVEL=intermediate`, but have likewise been filtered to cipher suites that should be safe. As this port for public ingress is expected to not enforce TLS, there is less value controlling the cipherlist. + + The main benefit from client preference is that the client can choose which cipher suite is most optimal / efficient for it to use (_Most commonly this would be for devices that would prefer a `CHACHA20-POLY1305` or `CCM` cipher_). + + --- + + Client preference should be ok to enable with the cipher lists configured by DMS. + + - `TLS_LEVEL=modern` only offers cipher suites that use AEAD ciphers. + - `TLS_LEVEL=intermediate` additionally includes AES-CBC ciphers that are known to be secure, but have historically had a variety of vulnerabilities. + - Port 25 has an even broader cipher list configured than `TLS_LEVEL=intermediate`, but likewise should be fairly secure to permit client preference. + + The main benefit from client preference is that the client can choose which cipher suite is most optimal / efficient for it to use (_Most commonly this would be for devices that would prefer a `CHACHA20-POLY1305` or `CCM` cipher_). + +### Using custom DH parameters + +It is possible to configure the DH parameters for TLS 1.2 and below. + +- By default DMS uses [`ffdhe4096`][ffdhe4096-src] from [IETF RFC 7919][ietf::rfc::ffdhe] (_Standardized pre-defined DH groups and the only available DH groups for use in TLS 1.3_). +- It is however [discouraged to generate your own DH parameters][dh-avoid-selfgenerated] as it is often less secure. Instead you should prefer to use one of the standard parameter groups from RFC 7919 (eg: `ffdhe2048`). + +??? example "Custom DH params with `compose.yaml`" + + 1. Add your own PEM encoded DH parameters file via a volume into the DMS container at any path you prefer (eg: `/tmp/docker-mailserver/dh-params.pem`). + 2. Update one or both service configs via our config override support ([Dovecot][docs::dms-override-config::dovecot], [Postfix][docs::dms-override-config::postfix]). + + This example uses the Docker Compose `configs` feature, but you could also use standard `volumes` with separate files if you prefer. + + ```yaml + services: + mailserver: + image: mailserver/docker-mailserver:latest + configs: + # During the first run of the DMS container instance, these overrides will update the internal `/etc/postfix/main.cf` and copy to `/etc/dovecot/local.cf`: + - source: postfix-overrides + target: /tmp/docker-mailserver/postfix-main.cf + - source: dovecot-overrides + target: /tmp/docker-mailserver/dovecot.cf + - source: dh-params-2048 + target: /tmp/docker-mailserver/dh-params.pem + + configs: + # NOTE: Postfix plans to remove support in future for setting custom DH parameters. + postfix-overrides: + content: | + smtpd_tls_dh1024_param_file = /tmp/docker-mailserver/dh-params.pem + + # NOTE: The setting `ssl_server_dh_file` is for Dovecot 2.4 (DMS v16), it previously named `ssl_dh`. + dovecot-overrides: + content: | + ssl_server_dh_file =