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

@@ -386,7 +386,7 @@ standard locations.
   - `--with-gnutls[=<path>]`
 
   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):
 

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
 

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.

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!

doc/SSL.txt

@@ -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:
-
-  <http://stunnel.mirt.net/>
-  <http://www.stunnel.org/>
-
-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 ===