Securing EMQ Connections with SSL

EMQ Security

Dec 15, 2017 · 4 min read

SSL is cryptographic protocol that provides the communications security over a computer network. As expected, it can be used also in MQTT message exchange.

SSL brings many security benefits, like:

  • Strong Authentication: When a SSL connection is creating, the communication parties can check the identity of their partner and decide if it is trustworthy. Usually, in this phase, X.509 certificates can be used to assure the identity of certificate holder.
  • Privacy: When the protocol being initiated, a unique session key is also generated by the effort of both sides. The communication is encrypted by this session key. The messages exchanged can not be viewed by any unauthorized parties.
  • Integrity: It is impossible to tamper the communication over SSL.

EMQ and EMQ X support SSL. In this article we will show you how to enable the SSL on EMQ.


The SSL protocol is a combination of SSL record protocol and SSL handshake protocol.

The record protocol is very similar to any other data carrying protocol, a record message includes the content type, version, length and a message payload, which carries the encrypted data. Sometimes a record message also has a message authentication code and/or a padding.

The handshake protocol is used when a SSLconnection starts, it controls the way of the communication. The handshake itself is also carried in a SSL record (content type 22).

A typical SSL handshake:

SSL Handshake

the purpose of a handshake is to create the communication channel, to identify the identity of each other and to negotiate a cipher specification. Handshake starts with “hello” message and finishes with “finished” message.

Preparation for Using SSL in EMQ

Usually we will use certificate for SSL communication. Thus, before we start SSL, we will need some certificates. They are: the CA certificate, the certificate for EMQ. Optionally, if we want enable two-way authentication, we will also need certificates for clients.

In demonstration or in lab environment, it is common that we generate the certificates and sign them by ourselves rather than to get them from a trusted third part.

Here we will use the tool comes with OpenSSL to generate the certificates we need.

Firstly, we will need a key for our self-signed CA Root Certificate, the following cli generate a RSA private key with key length of 2048 and save it in the file ‘MyRootCA.key’:

openssl genrsa -out MyRootCA.key 2048

The next step is generate the Root Cert using the key we just got:

openssl req -x509 -new -nodes -key MyRootCA.key -sha256 -days 3650 -out MyRootCA.pem

The root cert is the start of a trust chain, we assume that the a cert on the chain is trustworthy if all the nodes from its issuer up to the root cert on the chain are trustworthy.

After having a self-signed Root CA Certificate, we can use it to issue certificates for other identities, like the EMQ server. Similarly, we will need a private key first:

openssl genrsa -out MyEMQ1.key 2048

Then the certificate request for EMQ1:

openssl req -new -key ./MyEMQ1.key -out MyEMQ1.csr

Then use the Root CA to issue the certificate for EMQ1:

openssl x509 -req -in ./MyEMQ1.csr -CA MyRootCA.pem -CAkey MyRootCA.key -CAcreateserial -out MyEMQ1.pem -days 3650 -sha256

Now we can start using SSL on EMQ.

Enabling SSL on EMQ

It is quite straightforward to enable the SSL on EMQ, what we need is to modify a few directives in ‘emq.conf’. Fit them for you environment.

The default listening port is 8883:

listener.ssl.external = 8883

The location of key and certs file:

#private key for emq cert:
listener.ssl.external.keyfile = etc/certs/MyEMQ1.key
#emq cert:
listener.ssl.external.certfile = etc/certs/MyEMQ1.pem
#CA cert:
listener.ssl.external.cacertfile = etc/certs/MyRootCA.pem

Restart the EMQ after modifying the conf, and test it with mosquitto_sub:

mosquitto_sub -t abc -h emq1 -p 8883 -d --cafile ~/test_certs/MyRootCA.pem  --insecure
Client mosqsub|10617-Zhengyus- sending CONNECT
Client mosqsub|10617-Zhengyus- received CONNACK
Client mosqsub|10617-Zhengyus- sending SUBSCRIBE (Mid: 1, Topic: abc, QoS: 0)
Client mosqsub|10617-Zhengyus- received SUBACK
Subscribed (mid: 1): 0

Above shows that the protocol runs as expetect. Also, we can check it on the EMQ Dashboard:

1 SSL connection

Enabling Client Side Certificate

In some scenarios, it is necessary to assure the client identities by checking their certificate. This can be easily done by enabling the following directive:

#enable the client side certificates
listener.ssl.external.verify = verify_peer

To make the client side certificate mandatory:

#set it to 'true' to allow the ssl with client side certificate only 
listener.ssl.external.fail_if_no_peer_cert = true

After applying the above changes and we test it with the same sub command again, we will get an TLS error:

mosquitto_sub -t abc -h emq1 -p 8883 -d --cafile ~/test_certs/MyRootCA.pem  --insecure
Client mosqsub|10738-Zhengyus- sending CONNECT
Error: A TLS error occurred.

We will need the client certificate, we generate it by the same way of server side certificate:

openssl genrsa -out MyClient1.key 2048openssl req -new -key ./MyClient1.key -out MyClient1.csropenssl x509 -req -in ./MyClient1.csr -CA MyRootCA.pem -CAkey MyRootCA.key -CAcreateserial -out MyClient1.pem -days 3650 -sha256

We modify the sub command to include the newly generated client certificate:

mosquitto_sub -t abc -h emq1 -p 8883 -d --key ~/test_certs/MyClient1.key --cert ~/test_certs/MyClient1.pem --cafile ~/test_certs/MyRootCA.pem  --insecure
Client mosqsub|10796-Zhengyus- sending CONNECT
Client mosqsub|10796-Zhengyus- received CONNACK
Client mosqsub|10796-Zhengyus- sending SUBSCRIBE (Mid: 1, Topic: abc, QoS: 0)
Client mosqsub|10796-Zhengyus- received SUBACK
Subscribed (mid: 1): 0

Everything runs as expected:)

We hope you enjoy our little article.


Written by


Scalable and Reliable Real-time MQTT Messaging Engine for IoT in 5G Era

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade