Securing ejabberd with TLS encryption

ProcessOne
· 6 min read
Send by email

In recent years security and privacy become central focus of users and system administrators. Here is brief guide on setting up secure ejabberd TLS connections and keeping them private.

ejabberd have number of options that control security:

  • certfiles: List of full paths to files containing SSL certificates (available since ejabberd 17.11)
  • ciphers: OpenSSL ciphers list in the same format accepted by ‘openssl ciphers’ command
  • protocol_options: List of supported SSL protocols
  • dhfile: Full path to a file containing custom parameters for Diffie-Hellman key exchange
  • starttls: This option specifies that STARTTLS encryption is available on connections to the port
  • starttls_required: This option specifies that STARTTLS encryption is required on connections to the port.
  • tls: This option specifies that traffic on the port will be encrypted using SSL immediately after connecting. This method is nowadays deprecated and not recommended
  • tls_compression: Whether to enable or disable ejabberd TLS compression.
  • s2s_use_starttls: This option defines if s2s connections are encrypted
  • s2s_dhfile: Full path to a file containing custom DH parameters
  • s2s_ciphers: OpenSSL ciphers list in the same format accepted by ‘openssl ciphers’ command
  • s2s_protocol_options: List of supported SSL protocols
  • s2s_tls_compression: Whether to enable or disable ejabberd TLS s2s compression

For more configuration options and description refer to ejabberd documentation.

Looking for even more enterprise-grade security advice on ejabberd?
Contact our experts »

For many years security was something that was not primary concern in many cases in internet standards. ProcessOne team stands on the point that security is one of the primary factors thus we will recommend strong settings but also provide compatibility for reference only for those who want and need to retain support for insecure, legacy clients and servers but understand that this settings may jeopardize security and privacy. In below table you can find defaults for legacy and recommended settings:

ejabberd TLS configuration examples

Example 1 – Strong settings for c2s settings

This config disables protocols from SSLv2 up to TLSv1.1 and allows only “modern” (as of 2016) protocol TLSv1.2 and related ciphers.

certfiles:
  - /etc/ssl/ejabberd/domain.pem

listen:
  -
    port: 5222
    module: ejabberd_c2s
    protocol_options:
      - no_sslv2
      - no_sslv3
      - no_tlsv1
      - no_tlsv1_1
    ciphers: "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256"
    shaper: c2s_shaper
    access: c2s
    starttls: true
    starttls_required: true
    tls_compression: false
    dhfile: /etc/ssl/ejabberd/dh2048.pem

Note: Clients that do not support TLS1.2 will not be allowed to connect to c2s port.

Example 2 – Compatible settings for c2s

listen:
  -
    port: 5222
    module: ejabberd_c2s
    protocol_options:
      - no_sslv
      - no_sslv3
    ciphers: "ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS"
    shaper: c2s_shaper
    access: c2s
    starttls: true
    starttls_required: false
    tls_compression: false
    dhfile: /etc/ssl/ejabberd/dh1024.pem

Note: Clients that can connect to c2s ports need support at last TLS1.0. SSLv2 and SSLv3 have serious security flaws and have to be disabled. Also DH parameter is lowered here to 1024 bit as some older Java do not support higher grades.

Server-to-Server connections

s2s connections are more complex then client connections. If we want to federate with broad spectrum of XMPP servers, we have to allow unencrypted connections to that port. There are still lot of servers that do not support encryption. On the other hand, we have 2016 and it is hard to believe that there are still servers that sends data using plain-text. Choice is always up to server administrators, but ProcessOne strongly recommend to allow only secure, encrypted connections to port s2s:

Example 1 – Strong settings for s2s connections

Global section:

certfiles:
  - /etc/ssl/ejabberd/domain.pem
s2s_use_starttls: required
s2s_dhfile: /etc/ssl/ejabberd/dh2048.pem
s2s_ciphers: "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256"

Listening ports:

listen:
  -
    port: 5269
    module: ejabberd_s2s_in
    protocol_options:
      - no_sslv2
      - no_sslv3
      - no_tlsv1
      - no_tlsv1_1

Note: Only TLSv1.2 connections are allowed and all s2s connections are required to be encrypted

Example 2 – Legacy and unsafe s2s settings

Global section:

certfiles:
  - /etc/ssl/ejabberd/domain.pem
s2s_use_starttls: optional
s2s_dhfile: /etc/ssl/ejabberd/dh1024.pem
s2s_ciphers: "ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS"

Listening ports:

listen:
  -
    port: 5269
    module: ejabberd_s2s_in
    protocol_options:
      - no_sslv2
      - no_sslv3

Note: Allow unencrypted connections for servers that do not require it. If connections are encrypted – allow only protocol up from TLSv1. Also DH is lowered to 1024 bits.

Appendix: Create PEM files and DH paramerers

ejabberd TLS supports certificates in PEM format. Certificate should also contain certificate-chain that comes from certificate provider. Here is how certificates in PEM file should stack-up:

——— Main Certificate (xmpp.example.com)    ———
——— Intermediate certificate, chain certs  ———
——— Private Key for Main Certificate       ———

PEM file should be only readable by process running ejabberd.

ejabberd TLS configuration allow to use custom DH parameters, this is important as recent research revealed weakness of widely and common used DH files (see https://weakdh.org). We are recommending to use at last 2048-bit DH parameters. To generate DH use openssl command, for example:

openssl dhparam -out /etc/ssl/ejabberd/dh2048.pem 2048

and add proper ejabberd TLS config option (see previous section). If you need to support some old software like Java7, set DH size to 1024.

Appendix: Generating private key and certificate requests

You can generate self-signed certificates for your connections, however nowadays we strongly recommend that anyone use signed certificates by trusted and known Certificate Authority (CA). You can easily find commercial CA with pricing starting as low as $15 per year. There is also option of using free certificates from https://letsencrypt.org – see their docs for automated process of issuing certificates.

Generate Private Key (PK):

openssl genrsa -out xmpp_example_com.key 2048

this will generate PK – keep it safe, do not share. It is 2048 bit long, if you need bigger key, go for 4096 bits. Now you need to generate Certificate Signing Request (CSR) – that need to be send (usually copy&paste) to CA to generate certificate for you:

openssl req -out xmpp_example_com.csr -key xmpp_example_com.key -new -sha256

you will have to answer range of questions, and most important is: “Common Name (e.g. server FQDN or YOUR name)” this is where you place your domain name, like: xmpp.example.com , you can use wildcard names as well if you use certificate for other sub-domains.
After submitting CSR to CA you will get CRT – file that is actually public part of your key pair. Usually with your CRT, CA also provides certificate chain that need to be included in PEM file (see appendix about creating PEM files).

If you want to generate a self-signed certificate and not yet ask a certificate to a CA, you can use the following command. It is not recommended for production, but can be helpful for testing:

openssl x509 -req -days 365 -in xmpp_example_com.csr -signkey xmpp_example_com.key -out xmpp_example_com.crt

Then, all what you need to do is to combine files into single PEM file. Using names from above examples, that can be done using cat command (step-by-step):

Let’s assume that CA sent you xmpp_example_com.crt and ca_intermediate_certificate.crt:

# create PEM file with certificate
cat xmpp_example_com.crt > xmpp_example_com.pem

# add intermediate CA certificate to PEM
cat ca_intermediate_certificate.crt >> xmpp_example_com.pem

# finally add private key to file
cat xmpp_example_com.key >> xmpp_example_com.pem

Ensure that PEM file do not have any garbage, it should be nice and smooth text file like:

-----BEGIN CERTIFICATE-----
MIIHEjCCBfqgAwIBAgIQCI9arD288vK6p24B8dArzjANBgkqhkiG9w0BAQUFADBm
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3
....
....
XJqV43tRs8oaymPzU9NVbLutjva+ln/ml2IcEoE7a8x0UbdcYfQKpFI9cjr9yIki
sn5Y+o5sMjse8gXZtFMttmE3yypBt5BR4yLoQB2BSocmZkhWGjQ=
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIGWDCCBUCgAwIBAgIQCl8RTQNbF5EX0u/UA4w/OzANBgkqhkiG9w0BAQUFADBs
....
....
Ib4p1I5eFdZCSucyb6Sxa1GDWL4/bcf72gMhy2oWGU4K8K2Eyl2Us1p292E=
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
MIIEpQIyyiKCA35wtuube64IQM5hYnSzNL8HLJLYVfEl5vSrDO5KwLZ/P71BPrhx
....
....
hddA/p+zRteyTvBJaXAJwrreSjeJL4HGyf0E9z4TLE5qNMF81bXFso0+2FGDrh0t
-----END RSA PRIVATE KEY-----
Securing ejabberd with TLS encryption

Photo by Markus Spiske on Unsplash

Written by ProcessOne