Tip of the day: The blacklist { } block can be used to ban known troublemakers that are listed in blacklists like EfnetRBL and DroneBL.

TLS Ciphers and protocols

From UnrealIRCd documentation wiki
Jump to navigation Jump to search

You can configure the permitted SSL/TLS protocols and ciphers using set::tls::protocols, set::tls::ciphers and set::tls::options::ciphersuites. Or, if you want to override these global options, then you can use listen::tls-options or link::tls-options for listen- and link-specific configuration.

We do our best to ship with secure defaults for these settings. More important for a server is to actually use a real certificate, like from Let's Encrypt.

Default configuration

The default configuration in UnrealIRCd 6.0.5 and later looks like this:

set {
    tls {
        protocols "TLSv1.2,TLSv1.3";
        ciphers "EECDH+CHACHA20 EECDH+AESGCM EECDH+AES+SHA384 EECDH+AES+SHA256";
        ciphersuites "TLS_CHACHA20_POLY1305_SHA256:TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256:TLS_AES_128_CCM_8_SHA256:TLS_AES_128_CCM_SHA256";
        ecdh-curves "x25519:secp521r1:secp384r1:prime256v1";
    }
}

NOTE: There is no need to copy-paste this to your config file as this is already the default!

Result

With OpenSSL 3.0.7 on the server side, this results in the following testssl output:

 Testing server preferences 

 Has server cipher order?     yes (OK) -- TLS 1.3 and below
 Negotiated protocol          TLSv1.3
 Negotiated cipher            TLS_CHACHA20_POLY1305_SHA256, 253 bit ECDH (X25519)
 Cipher order
    TLSv1.2:   ECDHE-ECDSA-CHACHA20-POLY1305 ECDHE-ECDSA-AES256-GCM-SHA384
               ECDHE-ECDSA-AES128-GCM-SHA256 ECDHE-ECDSA-AES256-SHA384 ECDHE-ECDSA-AES128-SHA256 
    TLSv1.3:   TLS_CHACHA20_POLY1305_SHA256 TLS_AES_256_GCM_SHA384 TLS_AES_128_GCM_SHA256
[..]
 Elliptic curves offered:     prime256v1 secp384r1 secp521r1 X25519 
[..]
 Testing 370 ciphers via OpenSSL plus sockets against the server, ordered by encryption strength 

Hexcode  Cipher Suite Name (OpenSSL)       KeyExch.   Encryption  Bits     Cipher Suite Name (IANA/RFC)
-----------------------------------------------------------------------------------------------------------------------------
 x1302   TLS_AES_256_GCM_SHA384            ECDH 253   AESGCM      256      TLS_AES_256_GCM_SHA384                             
 x1303   TLS_CHACHA20_POLY1305_SHA256      ECDH 253   ChaCha20    256      TLS_CHACHA20_POLY1305_SHA256                       
 xc02c   ECDHE-ECDSA-AES256-GCM-SHA384     ECDH 521   AESGCM      256      TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384            
 xc024   ECDHE-ECDSA-AES256-SHA384         ECDH 521   AES         256      TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384            
 xcca9   ECDHE-ECDSA-CHACHA20-POLY1305     ECDH 253   ChaCha20    256      TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256      
 x1301   TLS_AES_128_GCM_SHA256            ECDH 253   AESGCM      128      TLS_AES_128_GCM_SHA256                             
 xc02b   ECDHE-ECDSA-AES128-GCM-SHA256     ECDH 521   AESGCM      128      TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256            
 xc023   ECDHE-ECDSA-AES128-SHA256         ECDH 521   AES         128      TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256            

Rationale

By default we:

  • Require protocol TLSv1.2 or higher
  • Only allows ciphers with Forward Secrecy
  • Use secure and randomly chosen ECDH curves

These minimum requirements can be met by these TLS client libraries:

  • OpenSSL 1.0.1 (released in 2012): for example first used in Fedora 18 (2013), Debian 7 (2013), Ubuntu 14.04 (2014)
  • GnuTLS 3.2.6 (2013): for example used in Ubuntu 16.0.4 (2016)
  • Android 4.4.2 (2013)

Previous less secure setting

The default settings as of UnrealIRCd 6.0.5+ work with these minimum versions of popular TLS client libraries: OpenSSL 1.0.1 (released in 2012), GnuTLS 3.2.6 (2013), Android 4.4.2 (2013).

If you need to permit clients that use an TLS library that is more than 10+ years old, then you have to downgrade the security a bit and revert to these old settings:

set {
    tls {
        protocols "All"; /* TLSv1.0 or later */
        ciphers "EECDH+CHACHA20 EECDH+AESGCM EECDH+AES AES256-GCM-SHA384 AES128-GCM-SHA256 AES256-SHA256 AES128-SHA256 AES256-SHA AES128-SHA";
    };
};

History

See also: Moving users to TLS

  • Prior to UnrealIRCd 4.0.7 (2016-10-09) if you did not have a cipher setting it was left up to your OS/Distro (and ultimately OpenSSL/LibreSSL build parameters) as to which algorithms were enabled. In practice this could easily mean that ciphers such as RC4 and 3DES were enabled which is discouraged.
  • In UnrealIRCd 4.0.14 (2017-09-15) the cipher list was updated to include TLSv1.3 ciphers. This means as soon as you upgrade your OpenSSL to a version which supports TLSv1.3, UnrealIRCd will be able to use it.
  • In UnrealIRCd 4.0.18 (2018-06-23) support was added of setting the ECDH(E) curves via the ecdh-curves option and a default was set. Previously this was left over to the SSL library with a fallback to P-256.
  • In UnrealIRCd 4.2.0 (2018-09-30) support for cipher setting for TLSv1.3 was changed to match OpenSSL specifics.
  • In UnrealIRCd 4.2.2 (2019-03-01) we reordered AES-128 and AES-256. In practice, most clients (by far) already negotiated either CHACHA20 or AES-256, but now in the remaining case (non-PFS) we prefer AES-256 as well.
  • In UnrealIRCd 5.0.0 (2019-12-13) there were no changes in the chipers but we did change the default generated certificate from RSA-4096 to secp384r1. On a side note, we do not recommend using a self-signed certificate. Instead, you should use a real certificate like from Let's Encrypt.
  • In UnrealIRCd 6.0.5 (2022-12-29) the requirements changed to TLSv1.2 or later and a cipher with Forward Secrecy (ECDHE). This was previously in a section called A more secure setting but is now the default. The old default is now documented under Previous less secure setting.
  • Doc update: curve x25519 is actually added as well since Apr 2018, if OpenSSL supports is (1.1.0+), just was not documented here.