The "ssl_openssl" Module (v3)

This module depends on a third-party library (OpenSSL) and must be manually enabled at compile time.

Once you have installed the dependency you can enable this module using the following command:

./configure --enable-extras ssl_openssl

Description

This module allows TLS (SSL) encrypted connections using the OpenSSL library.

Configuration

To load this module use the following <module> tag:

<module name="ssl_openssl">

<bind>

This module extends the core <bind> tags with the following fields:

Name Type Default Value Description
sslprofile (since 3.10.0)
ssl (3.0.0 to 3.9.0) 		Text None This MUST be set to the name of an OpenSSL TLS (SSL) profile to listen for secure connections with OpenSSL.
Example Usage

Listens for OpenSSL encrypted IRC connections on the *:6697 endpoint with an TLS (SSL) profile named "Clients":

<bind address="*"
      port="6697"
      ...
      sslprofile="Clients"
      type="clients">

Listens for OpenSSL encrypted server connections on the *:7000 endpoint with an TLS (SSL) profile named "Servers":

<bind address="*"
      port="7000"
      ...
      sslprofile="Servers"
      type="servers">

<openssl>

The <openssl> tag defines settings about how the ssl_openssl module should behave. This tag can only be defined once.

Name Type Default Value Description
onrehash Boolean No Whether TLS (SSL) profiles (see below) should be reloaded as part of a normal rehash.
Example Usage
<openssl onrehash="yes">

<sslprofile>

The <sslprofile> tag defines a TLS (SSL) profile for sockets to use. This tag can be defined as many times as required.

If no <sslprofile> tags are defined, including tags for other TLS (SSL) modules, a default profile named openssl will be created. This profile will use the contents of the deprecated <openssl> tag if one has been defined. It is strongly recommended that you do not use this as it will be removed in a future release.

Name Type Default Value Description
name Text None Required! The name of this TLS (SSL) profile. This is used in <bind:ssl> for incoming connections and <link:ssl> for outgoing server connections.
provider Text None Required! This MUST be set to "openssl" to use the OpenSSL library.
cafile Text ca.pem The path to the CA in PEM format.
certfile Text cert.pem The path to the certificate in PEM format.
ciphers Text None If defined then an OpenSSL cipher string.
clientclearoptions Number 0 Raw integer value of options to clear on the client context. Don't change this unless you know what you are doing.
clientsetoptions Number 0 Raw integer value of options to set on the client context. Don't change this unless you know what you are doing.
compression Boolean No Whether insecure TLS (SSL) compression is enabled.
crlfile Text None If defined then the path to the CRL file in PEM format.
crlmode Text chain The mode to use when checking for certificate revocations.
crlpath Text None If defined then the path to the CRL directory.
dhfile Text dhparams.pem The path to the DH parameters in PEM format. Since InspIRCd v3.13.0 this does nothing on OpenSSL 3.0.0+.
ecdhcurve Text prime256v1 The ECDH curve.
hash Text md5 The hash algorithm used for TLS (SSL) client fingerprints.
keyfile Text key.pem The path to the private key in PEM format.
renegotiation Boolean No Whether insecure TLS (SSL) renegotiation is enabled.
requestclientcert Boolean Yes Whether to request a TLS (SSL) certificate from clients.
serverclearoptions Number 0 Raw integer value of options to clear on the server context. Don't change this unless you know what you are doing.
serversetoptions Number 0 Raw integer value of options to set on the server context. Don't change this unless you know what you are doing.
tlsv1 Boolean No Whether the insecure TLSv1.0 protocol is enabled.
tlsv11 Boolean Yes New in v3.2.0! Whether the TLSv1.1 protocol is enabled.
tlsv12 Boolean Yes New in v3.2.0! Whether the TLSv1.2 protocol is enabled.
tlsv13 Boolean Yes New in v3.15.0! Whether the TLSv1.3 protocol is enabled.

The crlmode field should be set to one of the following values:

Value Description
chain Check if any certificate in the chain has been revoked.
leaf Only check if the leaf certificate has been revoked.

The hash field should be set to one of the values shown in openssl list --digest-commands.

Example Usage
<sslprofile name="Clients"
            provider="openssl"
            cafile="ca.pem"
            certfile="cert.pem"
            crlfile=""
            ciphers="DEFAULT"
            compression="no"
            dhfile="dhparams.pem"
            ecdhcurve="prime256v1"
            hash="sha256"
            keyfile="key.pem"
            renegotiation="no"
            requestclientcert="yes"
            tlsv1="no"
            tlsv11="no"
            tlsv12="yes"
            tlsv13="yes">

Special Notes

If you are using a version of OpenSSL older than 3.0 you will also need to provide a DH parameters file. This file can be generated using openssl dhparam -out dhparams.pem 2048 and then be placed in your config directory.

Mozilla publish documentation on how to configure server-side TLS which can be used for selecting a secure OpenSSL configuration. We recommend using the intermediate profile to allow compatibility with as many clients as possible whilst maintaining a decent level of security.

TLS (SSL) profiles are not reloaded as part of a normal rehash. If you wish to reload TLS (SSL) profiles you should enable <openssl:onrehash>, use /REHASH -ssl, or load the sslrehashsignal to allow you to reload TLS (SSL) profiles by sending SIGUSR1 to the InspIRCd process.

If you are having trouble getting InspIRCd to read your .pem files then check that it has read access to the full path up to the location of them. If you are using a system that uses AppArmor you may need to edit the AppArmor profile to allow InspIRCd to read them too.

If you are using Let's Encrypt and are having problems with missing intermediate certificates then make sure you are using fullchain.pem from Certbot/Dehydrated/etc in <sslprofile:certfile> instead of cert.pem as the latter does not contain intermediate certificates.