doc/SSL.md

   1 # [ngIRCd](https://ngircd.barton.de) - SSL/TLS Encrypted Connections
   2
   3 ngIRCd supports SSL/TLS encrypted connections using the *OpenSSL* or *GnuTLS*
   4 libraries. Both encrypted server-server links as well as client-server links
   5 are supported.
   6
   7 SSL is a compile-time option which is disabled by default. Use one of these
   8 options of the ./configure script to enable it:
   9
  10 - `--with-openssl`: enable SSL support using OpenSSL.
  11 - `--with-gnutls`: enable SSL support using GnuTLS.
  12
  13 You can check the output of `ngircd --version` to validate if your executable
  14 includes support for SSL or not: "+SSL" must be listed in the feature flags.
  15
  16 You also need a SSL key and certificate, for example using Let's Encrypt, which
  17 is out of the scope of this document.
  18
  19 From a feature point of view, ngIRCds support for both libraries is
  20 comparable. The only major difference (at this time) is that ngIRCd with GnuTLS
  21 does not support password protected private keys.
  22
  23 ## Configuration
  24
  25 SSL-encrypted connections and plain-text connects can't run on the same network
  26 port (which is a limitation of the IRC protocol); therefore you have to define
  27 separate port(s) in your `[SSL]` block in the configuration file.
  28
  29 A minimal configuration for *accepting* SSL-encrypted client & server
  30 connections looks like this:
  31
  32 ``` ini
  33 [SSL]
  34 CertFile = /etc/ssl/certs/my-fullchain.pem
  35 KeyFile = /etc/ssl/certs/my-privkey.pem
  36 Ports = 6697, 6698
  37 ```
  38
  39 In this case, the server only deals with *incoming* connections and never has to
  40 validate SSL certificates itself, and therefore no "Certificate Authorities" are
  41 needed.
  42
  43 If you want to use *outgoing* SSL-connections to other servers, you need to add:
  44
  45 ``` ini
  46 [SSL]
  47 ...
  48 CAFile = /etc/ssl/certs/ca-certificates.crt
  49 DHFile = /etc/ngircd/dhparams.pem
  50
  51 [SERVER]
  52 ...
  53 SSLConnect = yes
  54 ```
  55
  56 The `CAFile` option configures a file listing all the certificates of the
  57 trusted Certificate Authorities.
  58
  59 The Diffie-Hellman parameters file `dhparams.pem` can be created like this:
  60
  61 - OpenSSL: `openssl dhparam -2 -out /etc/ngircd/dhparams.pem 4096`
  62 - GnuTLS: `certtool --generate-dh-params --bits 4096 --outfile /etc/ngircd/dhparams.pem`
  63
  64 Note that enabling `SSLConnect` not only enforces SSL-encrypted links for
  65 *outgoing* connections to other servers, but for *incoming* connections as well:
  66 If a server configured with `SSLConnect = yes` tries to connect on a plain-text
  67 connection, it won't be accepted to prevent data leakage! Therefore you should
  68 set this for *all* servers you expect to use SSL-encrypted connections!
  69
  70 ## Accepting untrusted Remote Certificates
  71
  72 If you are using self-signed certificates or otherwise invalid certificates,
  73 which ngIRCd would reject by default, you can force ngIRCd to skip certificate
  74 validation on a per-server basis and continue establishing outgoing connections
  75 to the respective peer by setting `SSLVerify = no` in the `[SERVER]` block of
  76 this remote server in your configuration.
  77
  78 But please think twice before doing so: the established connection is still
  79 encrypted but the remote site is *not verified at all* and man-in-the-middle
  80 attacks are possible!