Changeset - ce5eca25c9d7
Parent rev.
Child rev.
[Not reviewed]
0 7 0
Branko Majic (branko) - 2 months ago 2025-01-20 21:44:07
branko@majic.rs
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.
7 files changed with 89 insertions and 43 deletions:
docs/releasenotes.rst
8
8
docs/rolereference.rst
61
26
docs/usage.rst
1
1
roles/mail_server/defaults/main.yml
4
2
roles/mail_server/molecule/default/group_vars/parameters-optional.yml
3
2
roles/web_server/defaults/main.yml
4
2
roles/xmpp_server/molecule/default/group_vars/parameters-optional.yml
8
2
0 comments (0 inline, 0 general) First comment
docs/releasenotes.rst
➞
Show inline comments
 
@@ -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:**

			




        

    


    
    

    

        

                

                    docs/rolereference.rst
                

                

                  
                      
                        

                      ➞

                      
                        
                  

                  
                      
                  
                      
                  
                      
                  
                      
                  
                  
                

                

                    Show inline comments
                    
                

        

        

            



	
	
		
 
@@ -964,28 +964,42 @@ Parameters

			




	
	
	
		
 
  <https://prosody.im/doc/modules/mod_mam>`_ 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

			




	
	
	
		
 
  <https://prosody.im/doc/advanced_ssl_config#ciphers>`_ 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

			




	
	
	
		
 
  <https://prosody.im/doc/advanced_ssl_config#protocol>`__ 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

			




        

    


    
    

    

        

                

                    docs/usage.rst
                

                

                  
                      
                        

                      ➞

                      
                        
                  

                  
                      
                  
                      
                  
                      
                  
                      
                  
                  
                

                

                    Show inline comments
                    
                

        

        

            



	
	
		
 
@@ -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.

			




        

    


    
    

    

        

                

                    roles/mail_server/defaults/main.yml
                

                

                  
                      
                        

                      ➞

                      
                        
                  

                  
                      
                  
                      
                  
                      
                  
                      
                  
                  
                

                

                    Show inline comments
                    
                

        

        

            



	
	
		
 
@@ -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:\

			




        

    


    
    

    

        

                

                    roles/mail_server/molecule/default/group_vars/parameters-optional.yml
                

                

                  
                      
                        

                      ➞

                      
                        
                  

                  
                      
                  
                      
                  
                      
                  
                      
                  
                  
                

                

                    Show inline comments
                    
                

        

        

            



	
	
		
 
@@ -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:\

			




        

    


    
    

    

        

                

                    roles/web_server/defaults/main.yml
                

                

                  
                      
                        

                      ➞

                      
                        
                  

                  
                      
                  
                      
                  
                      
                  
                      
                  
                  
                

                

                    Show inline comments
                    
                

        

        

            



	
	
		
 
@@ -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:\

			




        

    


    
    

    

        

                

                    roles/xmpp_server/molecule/default/group_vars/parameters-optional.yml
                

                

                  
                      
                        

                      ➞

                      
                        
                  

                  
                      
                  
                      
                  
                      
                  
                      
                  
                  
                

                

                    Show inline comments
                    
                

        

        

            



	
	
		
 
@@ -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:

			




        

    



    


    



    



      

      





    
    0 comments (0 inline, 0 general)
    First comment





    


  

  

      

      

          

            You need to be logged in to comment. Login now
          

      

      

      
      

      

  







  


    




    








    
        
    
    
        This site is powered by
            Kallithea 0.7.99,
        which is
        © 2010–2024 by various authors & licensed under GPLv3.