TLS Ciphers and protocols

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.1.9.1 and later looks like this:

set {
    tls {
        protocols "TLSv1.2,+TLSv1.3";
        ciphers "ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-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 Ubuntu 24.04 LTS with standard OpenSSL 3.0.13 on the server side, this results in the following testssl output:

ECC

If you use an ECC server certificate:

Hexcode  Cipher Suite Name (OpenSSL)       KeyExch.   Encryption  Bits     Cipher Suite Name (IANA/RFC)
-----------------------------------------------------------------------------------------------------------------------------
TLSv1.2 (server order)
 xcca9   ECDHE-ECDSA-CHACHA20-POLY1305     ECDH 253   ChaCha20    256      TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256      
 xc02c   ECDHE-ECDSA-AES256-GCM-SHA384     ECDH 253   AESGCM      256      TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384            
 xc02b   ECDHE-ECDSA-AES128-GCM-SHA256     ECDH 253   AESGCM      128      TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256            
TLSv1.3 (server order)
 x1303   TLS_CHACHA20_POLY1305_SHA256      ECDH 253   ChaCha20    256      TLS_CHACHA20_POLY1305_SHA256                       
 x1302   TLS_AES_256_GCM_SHA384            ECDH 253   AESGCM      256      TLS_AES_256_GCM_SHA384                             
 x1301   TLS_AES_128_GCM_SHA256            ECDH 253   AESGCM      128      TLS_AES_128_GCM_SHA256                             

 Has server cipher order?     yes (OK) -- TLS 1.3 and below
 FS is offered (OK)           TLS_AES_256_GCM_SHA384 TLS_CHACHA20_POLY1305_SHA256 ECDHE-ECDSA-AES256-GCM-SHA384 ECDHE-ECDSA-CHACHA20-POLY1305 TLS_AES_128_GCM_SHA256
                              ECDHE-ECDSA-AES128-GCM-SHA256 
 Elliptic curves offered:     prime256v1 secp384r1 secp521r1 X25519 

RSA

If you use an RSA server certificate:

Hexcode  Cipher Suite Name (OpenSSL)       KeyExch.   Encryption  Bits     Cipher Suite Name (IANA/RFC)
-----------------------------------------------------------------------------------------------------------------------------
TLSv1.2 (server order)
 xcca8   ECDHE-RSA-CHACHA20-POLY1305       ECDH 253   ChaCha20    256      TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256        
 xc030   ECDHE-RSA-AES256-GCM-SHA384       ECDH 253   AESGCM      256      TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384              
 xc02f   ECDHE-RSA-AES128-GCM-SHA256       ECDH 253   AESGCM      128      TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256              
TLSv1.3 (server order)
 x1303   TLS_CHACHA20_POLY1305_SHA256      ECDH 253   ChaCha20    256      TLS_CHACHA20_POLY1305_SHA256                       
 x1302   TLS_AES_256_GCM_SHA384            ECDH 253   AESGCM      256      TLS_AES_256_GCM_SHA384                             
 x1301   TLS_AES_128_GCM_SHA256            ECDH 253   AESGCM      128      TLS_AES_128_GCM_SHA256

 Has server cipher order?     yes (OK) -- TLS 1.3 and below
 FS is offered (OK)           TLS_AES_256_GCM_SHA384 TLS_CHACHA20_POLY1305_SHA256 ECDHE-RSA-AES256-GCM-SHA384 ECDHE-RSA-CHACHA20-POLY1305 TLS_AES_128_GCM_SHA256 ECDHE-RSA-AES128-GCM-SHA256 
 Elliptic curves offered:     prime256v1 secp384r1 secp521r1 X25519 

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

In UnrealIRCd 6.1.9.1 and later the setting works with OpenSSL 1.0.2 and higher (released in 2015), because AES in CBC mode is disabled (only GCM is allowed). If you need to downgrade to before that, read on...

6.0.5 - 6.1.8.1

In UnrealIRCd 6.0.5 - 6.1.8.1 we used:

set { tls { ciphers "EECDH+CHACHA20 EECDH+AESGCM EECDH+AES+SHA384 EECDH+AES+SHA256"; } }

This allows AES in CBC mode.

Before 6.0.5

In UnrealIRCd 6.0.5 we disabled things like TLSv1.0/TSLv1.1 and ciphers without forward secrecy. This works 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 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";
    };
};

NOTE: The above settings do not work on Windows because we use LibreSSL, which disables TLSv1.0 and TLSv1.1 for security. Which is sensible, but it means you can no longer enable these on Windows even if you wanted to.

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 in sep 2023 listed curve x25519, but as we later found out in 2024 this wasn't actually effectively enabled.
• Windows build only: Since UnrealIRCd 6.1.7 you can no longer enable TLSv1.0 or TLSv1.1 even if you wanted to (as mentioned earlier, TLSv1.0 and TLSv1.1 are already off since UnrealIRCd 6.0.5 by default). This is because LibreSSL dropped support for these TLS protocols.
• Windows build only: UnrealIRCd up to and including 6.1.8.1 are missing ecdh-curve secp521r1 (a rarely used curve) and did not support setting set::tls::ecdh-curves.
• In UnrealIRCd 6.1.9 (2024-11-XX) a bug was fixed that prevented ecdh-curve X25519 from being added.
• In UnrealIRcd 6.1.9 (2024-11-XX) we dropped support for AES in CBC mode and only allow it in GCM mode. This means the TLSv1.2 ciphers were set to ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256