From UnrealIRCd documentation wiki
Jump to navigation Jump to search
This page contains changes which are not marked for translation.

Other languages:
English • ‎français

SSL stands for Secure Socket Layer. Later this has been renamed to TLS (Transport Layer Security) but most people still call it SSL.

Why use SSL

When you use SSL for a connection then all the traffic between the two endpoints is encrypted. Nobody can see/sniff/snoop the data (theoretically, anyway). This is important as IRC traffic often includes things like passwords and other sensitive information.

You probably see https:// sites on the internet all the time. HTTPS is simply HTTP with SSL and it's used for banking, e-commerce sites and nowadays a lot of regular sites as well. The same technology (SSL) can be used for IRC.

How to use SSL

First of all, you need an SSL-capable client. Fortunately such clients are widespread nowadays: mIRC, XChat and irssi all support SSL.

Second, an SSL port needs to be opened up on the server. Chances are high you have this already as the example configuration file opens up port 6697 for this (in the Listen block with listen::options::ssl) and UnrealIRCd will complain on boot if you don't have opened up an SSL port.

Now you need to connect to the SSL-only port in a special way. For example with mIRC you use: /server +6697. The + (plus) instructs mIRC to use SSL/TLS on an SSL-only port.

Final remarks

  • The UnrealIRCd team recommends to use SSL/TLS as much as possible. At the very least, use it to secure server to server traffic and for IRCOp client connections.
  • For real security you should validate certificates when you connect to servers and not blindly accept any SSL ceritificate. If you don't check them then you are still vulnerable to MitM attacks. That is, however, too off-topic to discuss here. See Wikipedia: Man-in-the-middle-attack for more background information. Clients like mIRC and XChat will show a popup prompt when a new (unknown) SSL certificate is detected.


Global settings

Global SSL/TLS settings can be configured via set::ssl. For most users the defaults are fine.

Per-port settings

If you want port-specific SSL setting then these can be configured in the Listen block.
NOTE: Doing so is very rare, most people would not change these at all or change the global ssl options in set::ssl instead.


UnrealIRCd also support SNI, multiple certificates with different names, which you configure using the Sni block.

Strict Transport Security

UnrealIRCd 4.0.13 and later come with a feature called "Strict Transport Security". This is an advanced feature that:

  1. Will send users with capable clients to the appropriate SSL/TLS port automatically
  2. Ensures that these users won't use insecure connections for a specified period of time

For full details see the specification.

To enable this you need to configure two important things:

Step 1: Get a real certificate

You need a 'real' SSL/TLS certificate, not the default / self-signed certificate that many people use. So: either buy one or get one via Let's Encrypt (tutorial).

IMPORTANT: Your users must connect to the server with the same hostname as the hostname in the certificate. So if users use /server then your server shouldn't serve a certificate for See Sni block for more information on this (possible solutions are: wildcard certificates or multiple certificates).

It is important to configure the certificate (and naming) correctly. Without STS such a misconfiguration will 'only' trigger a certificate warning on the client but with STS the clients will be unable to connect. It is a hard error.

Step 2: Configure the set::ssl::sts-policy block

The following will configure a STS policy, redirecting capable clients to port 6697 (which must be SSL):

set {
    ssl {
        sts-policy {
            port 6697;
            duration 5m; /* you can always increase this later */

Note that while you can remove the set::ssl::sts-policy block at any time, clients will cache the setting for up to set::ssl::sts-policy::duration time. So when deploying sts-policy, and when picking a (final) setting, be sure to provide SSL/TLS support for an extended amount of time. This shouldn't be any problem with UnrealIRCd but just to reiterate: only deploy STS if you are serious about offering SSL/TLS to your clients!

You should gradually raise the set::ssl::sts-policy::duration time. This to prevent you inadvertently locking users out due to a misconfiguration:

  • Begin with 5 minutes (5m) during testing.
  • After a week, consider raising it to a day (1d).
  • After a month, consider raising it to it's final setting, such as half a year (180d)

You will want to enforce the STS policy on all servers on your network

Side note: UnrealIRCd 4.0.13-4.0.15 will announce the capability as 'draft/sts'. UnrealIRCd 4.0.16 onwards will announce it as 'sts'. This shouldn't be an issue since clients should support both for the time being.