From ce5eca25c9d731222be6aba63167694c4fc1a32e 2025-01-20 21:44:07 From: Branko Majic Date: 2025-01-20 21:44:07 Subject: [PATCH] MAR-230: Updated documentation, inline comments, and some tests related to TLS configuration: - Documentation and comments should be a bit more consistent across the roles now. - Try to follow same rule for inclusion of singular TLSv1.2 cipher across the board in affected tests. --- diff --git a/docs/releasenotes.rst b/docs/releasenotes.rst index 0baed8431f38095df8770a8a4964306c6aea90d0..4d2d41b5720dbd23bbe26d264b7b9d98ad756e9c 100644 --- a/docs/releasenotes.rst +++ b/docs/releasenotes.rst @@ -46,23 +46,23 @@ Upgraded to Ansible 10.4.x. Dropped support for Debian 11 * ``ldap_server`` role - * TLSv1.3 is now enabled by default (in addition to TLSv1.2), - alongside the mandatory ciphers. + * TLSv1.3 is now enabled by default (with RFC-defined mandatory + ciphers), in addition to TLSv1.2. * ``mail_server`` role - * TLSv1.3 is now enabled by default (in addition to TLSv1.2), - alongside the mandatory ciphers. + * TLSv1.3 is now enabled by default (with RFC-defined mandatory + ciphers), in addition to TLSv1.2, for IMAP and SMTP submission. * ``web_server`` role - * TLSv1.3 is now enabled by default (in addition to TLSv1.2), - alongside the mandatory ciphers. + * TLSv1.3 is now enabled by default (with RFC-defined mandatory + ciphers), in addition to TLSv1.2. * ``xmpp_server`` role - * TLSv1.3 is now enabled by default (in addition to TLSv1.2), - alongside the mandatory ciphers, for client-to-server + * TLSv1.3 is now enabled by default (with RFC-defined mandatory + ciphers), in addition to TLSv1.2, for client-to-server communications. **Bug fixes:** diff --git a/docs/rolereference.rst b/docs/rolereference.rst index decf74ffa8b9b1160cf491918c0d67ec61cd7116..eee6a68a2d2d1c9112443ec53e3c2316d521491d 100644 --- a/docs/rolereference.rst +++ b/docs/rolereference.rst @@ -964,28 +964,42 @@ Parameters `_ configuration option ``archive_expires_after``. -**xmpp_server_tls_ciphers** (string, optional ``DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:!aNULL:!MD5:!EXPORT``) +**xmpp_server_tls_ciphers** (string, optional, ``DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:!aNULL:!MD5:!EXPORT``) TLS ciphers to enable on the XMPP server. This should be an OpenSSL-compatible cipher specification. Value should be compatible with Prosody's option ``ciphers`` normally defined within the ``ssl`` section of configuration file (see `official documentation `_ for details). - Default value allows TLSv1.2 with strong PFS ciphers and RSA - private keys. Ciphers listed for use with TLSv1.3 (``TLS_*`` ones) - are mandated by relevant standards, and cannot be disabled if - TLSv1.3 is enabled. The TLSv1.3 ciphers are included in this list - for completeness' sake. + Default value enables TLSv1.2-compatible strong PFS ciphers and RSA + private keys. TLSv1.3-specific ciphers (``TLS_*``) + are not configurable due to OpenSSL TLS context initialisation + specifics/implementation details. They are included here for + documentation/reference purposes only. + + .. warning:: + If the mail server minimum TLS version is set to TLSv1.3, it is + still necessary to include at least one TLSv1.2-compatible cipher + in the list in order to ensure TLSv1.3 initialisation. This is + due to specifics of OpenSSL context initialisation/internals. + + The server-to-server communications are not affected by this + configuration in order to ensure the widest possible compatibility + with 3rd-party servers. **xmpp_server_tls_protocol** (string, optional, ``tlsv1_2+``) - TLS protocol versions the XMPP server should support for client + TLS protocol versions the XMPP server should enable for client connections. The value specified should be compatible with Prosody's ``protocol`` option normally defined within the ``ssl`` section of configuration file (see `official documentation `__ for details). Older versions of TLS protocol (TLSv1.1 and lower) are not fully supported by the role, and additional configuration is - required on the server to weaken the OpenSSL security policies to - make them usable. + required on the server that weakens the OpenSSL security policies in + order to enable them. + + The server-to-server communications are not affected by this + configuration in order to ensure the widest possible compatibility + with 3rd-party servers. **xmpp_tls_certificate** (string, mandatory) X.509 certificate used for TLS for XMPP service. The file will be stored in @@ -1178,24 +1192,38 @@ Parameters ``ssl_protocols`` and ``smtpd_tls_mandatory_protocols`` configuration options. Older versions of TLS protocol (TLSv1.1 and lower) are not fully supported by the role, and additional - configuration is required on the server to weaken the OpenSSL - security policies. + configuration is required on the server that weakens the OpenSSL + security policies in order to enable them. + + The SMTP port (TCP\:25) is not affected by this configuration in + order to ensure the widest possible compatibility with 3rd-party + servers. **mail_server_smtp_additional_configuration** (string, optional, ``""``)) Additional configuration directives to include in SMTP server main configuration file. Directives must be specifically compatible with Postfix, and are treated verbatim (multi-line string will suffice). -**mail_server_tls_ciphers** (string, optional ``DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:!aNULL:!MD5:!EXPORT``) +**mail_server_tls_ciphers** (string, optional, ``DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:!aNULL:!MD5:!EXPORT``) TLS ciphers to enable on the mail server (for IMAP and SMTP submission). This should be an OpenSSL-compatible cipher specification. Value should be compatible with Postfix configuration option ``tls_high_cipherlist`` and Dovecot configuration option - ``ssl_cipher_list``. Default value allows TLSv1.2 with strong PFS - ciphers and RSA private keys. Ciphers listed for use with TLSv1.3 - (``TLS_*`` ones) are mandated by relevant standards, and cannot be - disabled if TLSv1.3 is enabled. The TLSv1.3 ciphers are included in - this list for completeness' sake. + ``ssl_cipher_list``. Default value enables TLSv1.2 strong PFS + ciphers and RSA private keys. TLSv1.3-specific ciphers (``TLS_*``) + are not configurable due to OpenSSL TLS context initialisation + specifics/implementation details. They are included here for + documentation/reference purposes only. + + .. warning:: + If the mail server minimum TLS version is set to TLSv1.3, it is + still necessary to include at least one TLSv1.2-compatible cipher + in the list in order to ensure TLSv1.3 initialisation. This is + due to specifics of OpenSSL context initialisation/internals. + + The SMTP port (TCP\:25) is not affected by this configuration in + order to ensure the widest possible compatibility with 3rd-party + servers. **mail_user** (string, optional, ``vmail``) Name of the user that owns all the mail files. @@ -1501,22 +1529,29 @@ Parameters matched). **web_server_tls_protocols** (list, optional, ``[ "TLSv1.2", "TLSv1.3" ]``) - List of TLS protocols the web server should support. Each value - specified should be compatible with Nginx configuration option + + List of TLS protocol versions to enabled on the web server. Each + value specified should be compatible with Nginx configuration option ``ssl_protocols``. Older versions of TLS protocol (TLSv1.1 and lower) are not fully supported by the role, and additional - configuration is required on the server to weaken the OpenSSL - security policies. + configuration is required on the server that weakens the OpenSSL + security policies in order to enable them. **web_server_tls_ciphers** (string, optional, ``DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:!aNULL:!MD5:!EXPORT``) TLS ciphers to enable on the web server. This should be an OpenSSL-compatible cipher specification. Value should be compatible with Nginx configuration option ``ssl_ciphers``. Default value - allows TLSv1.2 with strong PFS ciphers and RSA private keys. Ciphers - listed for use with TLSv1.3 (``TLS_*`` ones) are mandated by - relevant standards, and cannot be disabled if TLSv1.3 is - enabled. The TLSv1.3 ciphers are included in this list for - completeness' sake. + enables TLSv1.2-compatible strong PFS ciphers and RSA private + keys. TLSv1.3-specific ciphers (``TLS_*``) are not configurable due + to OpenSSL TLS context initialisation specifics/implementation + details. They are included here for documentation/reference purposes + only. + + .. warning:: + If the web server TLS version is set to TLSv1.3 only, it is still + necessary to include at least one TLSv1.2-compatible cipher in + the list in order to ensure TLSv1.3 initialisation. This is due + to specifics of OpenSSL context initialisation/internals. Distribution compatibility diff --git a/docs/usage.rst b/docs/usage.rst index a38d3a0fbb4aed7280278bbe201a1441384e6b72..3545f29d7138b9265d660bf86d9ca4eeebd19fe1 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -972,7 +972,7 @@ role. you can also use alternative ports 26 (redirected to port 587) and 27 (redirected to port 25). - TLS has also been hardened on port 587 to allow only TLSv1.2 and PFS ciphers + TLS has also been hardened on port 587 to allow only TLSv1.2+ and PFS ciphers (you can override TLS versions/ciphers via role configuration). TLS configuration on port 25 has been left unchanged for maximum interoperability with other servers. diff --git a/roles/mail_server/defaults/main.yml b/roles/mail_server/defaults/main.yml index f7d166c807aa89b062c3995acefd7127370b0052..d4ce0028efe9ea5615f9159975623cf9c6eef378 100644 --- a/roles/mail_server/defaults/main.yml +++ b/roles/mail_server/defaults/main.yml @@ -10,8 +10,10 @@ local_mail_aliases: {} imap_max_user_connections_per_ip: 10 mail_server_minimum_tls_protocol: "TLSv1.2" -# TLS_* ciphers are mandated by the TLSv1.3-related standards and -# cannot be disabled when TLSv1.3 is enabled on the server. +# TLS ciphers for TLSv1.3 (when enabled) are not configurable due to +# OpenSSL internals around context initialisation. The three ciphers +# included in this list (TLS_* ones) are included for +# completeness/documentation purposes only. mail_server_tls_ciphers: "\ DHE-RSA-AES128-GCM-SHA256:\ DHE-RSA-AES256-GCM-SHA384:\ diff --git a/roles/mail_server/molecule/default/group_vars/parameters-optional.yml b/roles/mail_server/molecule/default/group_vars/parameters-optional.yml index b472237f5d066940b900d80a9d4f77fedef568a5..3005395f48a769e03aca749797662f76d9cf3082 100644 --- a/roles/mail_server/molecule/default/group_vars/parameters-optional.yml +++ b/roles/mail_server/molecule/default/group_vars/parameters-optional.yml @@ -6,9 +6,10 @@ mail_ldap_tls_truststore: "{{ lookup('file', 'tests/data/x509/ca/chain-full.cert mail_ldap_postfix_password: postfixpassword mail_ldap_dovecot_password: dovecotpassword mail_server_minimum_tls_protocol: TLSv1.3 +# At least one non-TLSv1.3 cipher has to be included in order to +# ensure TLSv1.3 gets initialised. TLSv1.3 ciphers (TLS_*) are not +# configurable and listed for documentation/reference purposes. mail_server_tls_ciphers: "\ -ECDHE-RSA-AES128-GCM-SHA256:\ -ECDHE-RSA-AES256-GCM-SHA384:\ ECDHE-RSA-CHACHA20-POLY1305:\ TLS_AES_128_GCM_SHA256:\ TLS_AES_256_GCM_SHA384:\ diff --git a/roles/web_server/defaults/main.yml b/roles/web_server/defaults/main.yml index ecf1e1f316f00d156fb2f549524a67a42ecee6a1..be86b62df9e2db3bed98c112b8c31554f9f4ee47 100644 --- a/roles/web_server/defaults/main.yml +++ b/roles/web_server/defaults/main.yml @@ -8,8 +8,10 @@ web_server_tls_protocols: - "TLSv1.2" - "TLSv1.3" -# TLS_* ciphers are mandated by the TLSv1.3-related standards and -# cannot be disabled when TLSv1.3 is enabled on the server. +# TLS ciphers for TLSv1.3 (when enabled) are not configurable due to +# OpenSSL internals around context initialisation. The three ciphers +# included in this list (TLS_* ones) are included for +# completeness/documentation purposes only. web_server_tls_ciphers: "\ DHE-RSA-AES128-GCM-SHA256:\ DHE-RSA-AES256-GCM-SHA384:\ diff --git a/roles/xmpp_server/molecule/default/group_vars/parameters-optional.yml b/roles/xmpp_server/molecule/default/group_vars/parameters-optional.yml index 870edd3f47f9adfe62862c97841a633e9d1610de..fa23af5d9f8c7482d6fb1ec3a1878de9dae1983b 100644 --- a/roles/xmpp_server/molecule/default/group_vars/parameters-optional.yml +++ b/roles/xmpp_server/molecule/default/group_vars/parameters-optional.yml @@ -14,8 +14,14 @@ xmpp_tls_certificate: "{{ lookup('file', 'tests/data/x509/server/{{ inventory_ho xmpp_tls_key: "{{ lookup('file', 'tests/data/x509/server/{{ inventory_hostname }}_xmpp.key.pem') }}" xmpp_server_tls_protocol: "tlsv1_3+" # At least one non-TLSv1.3 cipher has to be included in order to -# ensure TLSv1.3 gets initialised. -xmpp_server_tls_ciphers: "ECDHE-RSA-CHACHA20-POLY1305:!aNULL:!MD5:!EXPORT" +# ensure TLSv1.3 gets initialised. TLSv1.3 ciphers (TLS_*) are not +# configurable and listed for documentation/reference purposes. +xmpp_server_tls_ciphers: "\ +ECDHE-RSA-CHACHA20-POLY1305:\ +TLS_AES_128_GCM_SHA256:\ +TLS_AES_256_GCM_SHA384:\ +TLS_CHACHA20_POLY1305_SHA256:\ +!aNULL:!MD5:!EXPORT" # common ca_certificates: