Securing ejabberd with TLS encryption

In recent years security and privacy become central focus of users and system administrators. Here is brief guide on securing ejabberd connections and keep them private.

ejabberd have number of options that control security:

certfile: Full path to a file containing the default SSL certificate
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 TLS compression.
s2s_use_starttls: This option defines if s2s connections are encrypted
s2s_certfile: Full path to a file containing a SSL certificate
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 TLS compression

For more configuration options and description refer to ejabberd documentation.

Settings: Recommended vs Compatibility

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:

Option Legacy Recommended
certfile path: /etc/ssl/ejabberd/domain.pem path: /etc/ssl/ejabberd/domain.pem
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 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
protocol_options no_sslv2, no_sslv3 no_sslv2, no_sslv3, no_tlsv1,no_tlsv1_1
dhfile path: /etc/ssl/ejabberd/dh1024.pem path: /etc/ssl/ejabberd/dh2048.pem
starttls TRUE TRUE
starttls_required FALSE TRUE
tls FALSE FALSE
tls_compression FALSE FALSE
s2s_use_starttls OPTIONAL REQUIRED
s2s_certfile path: /etc/ssl/ejabberd/domain.pem path: /etc/ssl/ejabberd/domain.pem
s2s_dhfile path: /etc/ssl/ejabberd/dh1024.pem path: /etc/ssl/ejabberd/dh2048.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 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
s2s_protocol_options no_sslv2, no_sslv3 no_sslv2, no_sslv3, no_tlsv1,no_tlsv1_1
s2s_tls_compression FALSE FALSE

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.

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
    certfile: "/etc/ssl/ejabberd/domain.pem"
    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_sslv2"
      - "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
    certfile: "/etc/ssl/ejabberd/domain.pem"
    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:

s2s_use_starttls: required
s2s_certfile: /etc/ssl/ejabberd/domain.pem
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:

s2s_use_starttls: optional
s2s_certfile: /etc/ssl/ejabberd/domain.pem
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 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 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 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:

cat xmpp_example_com.crt > xmpp_example_com.pem (create PEM file with certificate)
cat ca_intermediate_certificate.crt >> xmpp_example_com.pem (add intermediate CA certificate to PEM)
cat xmpp_example_com.key >> xmpp_example_com.pem (finally add private key to file)

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-----

5 thoughts on “Securing ejabberd with TLS encryption

  1. I followed this guide and everything seems OK, but

    Tested my ejabberd on xmpp.net and saw following

    SASL
    Pre-TLS

    PLAIN <———————–
    SCRAM-SHA-1
    X-OAUTH2

    server must not offer this pre-tls
    Seems to be some misconfiguration from my side. Any ideas?

  2. If I’m using a self signed certificate, in the last step to create the PEM file, is it ok to only do the following 2 steps?

    cat xmpp_example_com.crt > xmpp_example_com.pem (create PEM file with certificate)
    cat xmpp_example_com.key >> xmpp_example_com.pem (finally add private key to file)

    Thanks

    • Yes, should be working this way, however I strongly recommend using trusted certificates – like https://letsencrypt.org – they are free and now ejabberd can handle automatically renewal process. See latest ejabberd release.

  3. Hi
    In my case I need to append first the private key, then the certificate and at last the chain file (all from letsencrypt).
    Then everything works fine. If the pem file is in any other order, either the chain certificate is not found or the clients cannot connect.

Leave a Comment