From b826fad15871f73435328b1d77fd364838389adb Mon Sep 17 00:00:00 2001 From: Alexander Barton Date: Mon, 8 Jan 2024 18:31:30 +0100 Subject: [PATCH] S2S-TLS: Convert SSL.txt to Markdown and update information given No longer describe creating self-signed certificates or using "stunnel", as both is not recommended. --- INSTALL.md | 2 +- doc/Makefile.am | 2 +- doc/QuickStart.md | 4 ++ doc/SSL.md | 80 ++++++++++++++++++++++++++++++++++ doc/SSL.txt | 108 ---------------------------------------------- 5 files changed, 86 insertions(+), 110 deletions(-) create mode 100644 doc/SSL.md delete mode 100644 doc/SSL.txt diff --git a/INSTALL.md b/INSTALL.md index faf8812e..544c92d4 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -386,7 +386,7 @@ standard locations. - `--with-gnutls[=]` Enable support for SSL/TLS using OpenSSL or GnuTLS libraries. - See `doc/SSL.txt` for details. + See `doc/SSL.md` for details. - IPv6 (autodetected by default): diff --git a/doc/Makefile.am b/doc/Makefile.am index a7e01999..d37c9b38 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -34,7 +34,7 @@ static_docs = \ README-Interix.txt \ RFC.txt \ Services.txt \ - SSL.txt + SSL.md doc_templates = sample-ngircd.conf.tmpl diff --git a/doc/QuickStart.md b/doc/QuickStart.md index 96f57bd9..abea9cd4 100644 --- a/doc/QuickStart.md +++ b/doc/QuickStart.md @@ -120,3 +120,7 @@ with the `;` character), but it is a good idea to enable it whenever possible! And you can have as many *Operator blocks* as you like, configuring multiple different IRC Operators. + +## Configuring SSL/TLS Encryption + +Please see the file `SSL.md` for details. diff --git a/doc/SSL.md b/doc/SSL.md new file mode 100644 index 00000000..a2e029b2 --- /dev/null +++ b/doc/SSL.md @@ -0,0 +1,80 @@ +# [ngIRCd](https://ngircd.barton.de) - SSL/TLS Encrypted Connections + +ngIRCd supports SSL/TLS encrypted connections using the *OpenSSL* or *GnuTLS* +libraries. Both encrypted server-server links as well as client-server links +are supported. + +SSL is a compile-time option which is disabled by default. Use one of these +options of the ./configure script to enable it: + +- `--with-openssl`: enable SSL support using OpenSSL. +- `--with-gnutls`: enable SSL support using GnuTLS. + +You can check the output of `ngircd --version` to validate if your executable +includes support for SSL or not: "+SSL" must be listed in the feature flags. + +You also need a SSL key and certificate, for example using Let's Encrypt, which +is out of the scope of this document. + +From a feature point of view, ngIRCds support for both libraries is +comparable. The only major difference (at this time) is that ngIRCd with GnuTLS +does not support password protected private keys. + +## Configuration + +SSL-encrypted connections and plain-text connects can't run on the same network +port (which is a limitation of the IRC protocol); therefore you have to define +separate port(s) in your `[SSL]` block in the configuration file. + +A minimal configuration for *accepting* SSL-encrypted client & server +connections looks like this: + +``` ini +[SSL] +CertFile = /etc/ssl/certs/my-fullchain.pem +KeyFile = /etc/ssl/certs/my-privkey.pem +Ports = 6697, 6698 +``` + +In this case, the server only deals with *incoming* connections and never has to +validate SSL certificates itself, and therefore no "Certificate Authorities" are +needed. + +If you want to use *outgoing* SSL-connections to other servers, you need to add: + +``` ini +[SSL] +... +CAFile = /etc/ssl/certs/ca-certificates.crt +DHFile = /etc/ngircd/dhparams.pem + +[SERVER] +... +SSLConnect = yes +``` + +The `CAFile` option configures a file listing all the certificates of the +trusted Certificate Authorities. + +The Diffie-Hellman parameters file `dhparams.pem` can be created like this: + +- OpenSSL: `openssl dhparam -2 -out /etc/ngircd/dhparams.pem 4096` +- GnuTLS: `certtool --generate-dh-params --bits 4096 --outfile /etc/ngircd/dhparams.pem` + +Note that enabling `SSLConnect` not only enforces SSL-encrypted links for +*outgoing* connections to other servers, but for *incoming* connections as well: +If a server configured with `SSLConnect = yes` tries to connect on a plain-text +connection, it won't be accepted to prevent data leakage! Therefore you should +set this for *all* servers you expect to use SSL-encrypted connections! + +## Accepting untrusted Remote Certificates + +If you are using self-signed certificates or otherwise invalid certificates, +which ngIRCd would reject by default, you can force ngIRCd to skip certificate +validation on a per-server basis and continue establishing outgoing connections +to the respective peer by setting `SSLVerify = no` in the `[SERVER]` block of +this remote server in your configuration. + +But please think twice before doing so: the established connection is still +encrypted but the remote site is *not verified at all* and man-in-the-middle +attacks are possible! diff --git a/doc/SSL.txt b/doc/SSL.txt deleted file mode 100644 index 28ea2cd9..00000000 --- a/doc/SSL.txt +++ /dev/null @@ -1,108 +0,0 @@ - - ngIRCd - Next Generation IRC Server - - (c)2001-2008 Alexander Barton, - alex@barton.de, http://www.barton.de/ - - ngIRCd is free software and published under the - terms of the GNU General Public License. - - -- SSL.txt -- - - -ngIRCd supports SSL/TLSv1 encrypted connections using the OpenSSL or GnuTLS -libraries. Both encrypted server-server links as well as client-server links -are supported. - -SSL is a compile-time option which is disabled by default. Use one of these -options of the ./configure script to enable it: - - --with-openssl enable SSL support using OpenSSL - --with-gnutls enable SSL support using GnuTLS - -You also need a key/certificate, see below for how to create a self-signed one. - -From a feature point of view, ngIRCds support for both libraries is -comparable. The only major difference (at this time) is that ngircd with gnutls -does not support password protected private keys. - -Configuration -~~~~~~~~~~~~~ - -To enable SSL connections a separate port must be configured: it is NOT -possible to handle unencrypted and encrypted connections on the same port! -This is a limitation of the IRC protocol ... - -You have to set (at least) the following configuration variables in the -[SSL] section of ngircd.conf(5): Ports, KeyFile, and CertFile. - -Now IRC clients are able to connect using SSL on the configured port(s). -(Using port 6697 for encrypted connections is common.) - -To enable encrypted server-server links, you have to additionally set -SSLConnect to "yes" in the corresponding [SERVER] section. - - -Creating a self-signed certificate -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -OpenSSL: - -Creating a self-signed certificate and key: - $ openssl req -newkey rsa:2048 -x509 -keyout server-key.pem -out server-cert.pem -days 1461 -Create DH parameters (optional): - $ openssl dhparam -2 -out dhparams.pem 4096 - -GnuTLS: - -Creating a self-signed certificate and key: - $ certtool --generate-privkey --bits 2048 --outfile server-key.pem - $ certtool --generate-self-signed --load-privkey server-key.pem --outfile server-cert.pem -Create DH parameters (optional): - $ certtool --generate-dh-params --bits 4096 --outfile dhparams.pem - - -Alternate approach using stunnel(1) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Alternatively (or if you are using ngIRCd compiled without support -for GnuTLS/OpenSSL), you can use external programs/tools like stunnel(1) to -get SSL encrypted connections: - - - - -Stefan Sperling (stefan at binarchy dot net) mailed the following text as a -short "how-to", thanks Stefan! - -=== snip === - ! This guide applies to stunnel 4.x ! - - Put this in your stunnel.conf: - - [ircs] - accept = 6667 - connect = 6668 - - This makes stunnel listen for incoming connections - on port 6667 and forward decrypted data to port 6668. - We call the connection 'ircs'. Stunnel will use this - name when logging connection attempts via syslog. - You can also use the name in /etc/hosts.{allow,deny} - if you run tcp-wrappers. - - To make sure ngircd is listening on the port where - the decrypted data arrives, set - - Ports = 6668 - - in your ngircd.conf. - - Start stunnel and restart ngircd. - - That's it. - Don't forget to activate ssl support in your irc client ;) - The main drawback of this approach compared to using builtin ssl - is that from ngIRCds point of view, all ssl-enabled client connections will - originate from the host running stunnel. -=== snip === -- 2.39.2