HiveMQ Edge Security

HiveMQ Edge is designed from the ground up with maximum security in mind. Secure, encrypted end-to-end communication and advanced authentication and authorization features are mission-critical for most IoT and M2M production deployments. HiveMQ Edge gives you the flexibility to enable specific security features to suit your business needs.

If you are unfamiliar with MQTT security concepts, we recommend reading our MQTT Security Fundamentals series.

What is TLS?

Transport Layer Security (TLS) is a cryptographic protocol that allows a secure and encrypted communication at transport layer between a client application and a server. If a TLS listener is enabled in HiveMQ, each client connection for that listener is encrypted and secured by TLS.

Multiple listeners
You can configure HiveMQ with multiple listeners so HiveMQ can handle secure and insecure connections simultaneously. For more information, see HiveMQ Edge Listeners.

For usage scenarios where sensitive information is published via MQTT , we strongly recommend that you enable TLS. When configured correctly, it is very difficult for an attacker to break the encryption and read the packets on the wire. Since TLS is a proven technology and the whole transport is encrypted, TLS could be a better choice than a hand-rolled payload encryption when security is more important for your scenario than package overhead. See the infobox below for more details.

As in most cases, added security comes with some disadvantages. The most important disadvantage is, that SSL/TLS comes with a significant increase in used bandwidth. While we are talking of tens of bytes here, it can make a huge difference in scenarios where small bandwidth usage is key. Please note that the SSL handshake that takes place when a connection is established adds additional overhead in terms of bandwidth and CPU. The increased overhead is an important consideration if your deployment relies on unreliable connections that frequently drop.

Encryption at Transport Layer vs Encryption at Application Layer

Encryption at transport layer has the advantage that the whole connection is encrypted, including all MQTT messages sent from the client to the server and from the server to the client. This ensures that nobody but the client which is connected to HiveMQ can read any message of the communication. Since the payload of the MQTT messages remain unencrypted raw bytes in this case, fully interoperability with other MQTT clients (even if they do not use TLS) is ensured. All MQTT messages (not only PUBLISHes) are secured with this technique.

Encryption at application layer means that the payload of a MQTT PUBLISH message is encrypted with an application specific encryption and only clients who know how to encrypt the payload can read the original message. When not used together with TLS the transport is unencrypted and attackers could read the raw message on the wire. If the attacker does not know how to decrypt the payload, the payload of the MQTT PUBLISH message is secure. It is important to understand that only the payload of a MQTT PUBLISH can be encrypted, all other information like the topic of the message is unencrypted. Only PUBLISH payloads can be encrypted, all other MQTT messages like CONNECT cannot be secured with this technique.

If desired, the two encryption techniques can be used together. When it is important that only a few trusted clients can decrypt the content of specific MQTT publishes, and you want to secure your complete communication, the combination can be beneficial.

Java Key- and Trust Store

Java key stores and Java trust stores are containers that contain information needed for SSL like X.509 certificates and keys. Typically, each trust store and each key store is persisted in one single file, and they are protected by a master password.

Key stores and trust stores are conceptually similar but there is a difference in function. In an SSL context, key stores provide credentials and trust stores verify credentials. That means, a key store contains a public key certificate and the corresponding private key.

If you are unfamiliar with the topic, we strongly recommend that you refresh your knowledge about private and public key cryptography.

Servers such as HiveMQ typically use key stores to protect the private key for their SSL connections.

Trust stores contain trusted certificates or certificates signed by a CA in order to identify the partner of the SSL connection. Typically, clients which want to connect to a server have to store the certificate of the server (or the trusted CA when the server certificate was signed by a CA) to identify the server as a trusted server.

It is possible to use the same file as key store and trust store. We strongly recommend separating them to ensure the security of the private key.

For information on how to create a key store, see HiveMQ Edge How-Tos.

Autoreload
Key and trust stores are reloaded during runtime. You can add or remove client certificates from the trust store or change the server certificate in the key store without downtime. Even the replacing of the key and trust store file is possible if the same master password is used.

Communication Protocol

If no explicit SSL/TLS version is set, TLS (which is the same as TLSv1) is used to secure the communication between HiveMQ and the clients. If possible, it is recommended to use TLSv1.1 or TLSv1.2 since these protocols tend to be more secure.

By default, HiveMQ Edge enables the following TLS protocols:

Default TLS protocols
TLSv1.3
TLSv1.2

To enable only specific protocols, you can use an explicit TLS configuration that is similar to the following example. If necessary, you can also use such an explicit configuration to enable legacy protocols such as TLSv1 and TLSv1.1:

Example configuration to set a specific TLS version
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    ...
    <listeners>
        ...
        <tls-tcp-listener>
            <tls>
                ...
                <!-- Enable specific TLS versions manually -->
                <protocols>
                    <protocol>TLSv1.2</protocol>
                </protocols>
                ...
            </tls>
        </tls-tcp-listener>
    </listeners>
    ...
</hivemq>

Cipher Suites

TLS can only be as secure as the used cipher suites. Usually, JVM vendors make sure that only secure ciphers are activated by default. However, in some cases, you may want to limit HiveMQ to use specific cipher suites you are comfortable with.

By default, HiveMQ Edge enables the following cipher suites:

Default cipher suites
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
TLS_RSA_WITH_AES_128_GCM_SHA256
TLS_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_256_CBC_SHA
AES256 requires JCE unlimited strength jurisdiction policy files.

If none of the HiveMQ default cipher suites are supported, the cipher suites your JVM enables are used.

List of cipher suites
You can see a list of available cipher suites for the Oracle JVM here: Oracle JCA documentation.

The list of cipher suites that are enabled by default can change with any release. If you depend on specific cipher suites, specify the cipher suites explicitly.

Example configuration to set cipher suites for listeners explicitly
<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    ...
    <tls>
        ...
        <!-- Only allow specific cipher suites -->
        <cipher-suites>
            <cipher-suite>TLS_RSA_WITH_AES_128_CBC_SHA</cipher-suite>
            <cipher-suite>TLS_RSA_WITH_AES_256_CBC_SHA256</cipher-suite>
            <cipher-suite>SSL_RSA_WITH_3DES_EDE_CBC_SHA</cipher-suite>
        </cipher-suites>
        ...
    </tls>
    ...
</hivemq>

Each TLS listener can be configured to have its own list of enabled cipher suites.

Randomness

If it is available, HiveMQ Edge uses /dev/urandom as the default source of cryptographically secure randomness. /dev/urandom is generally considered secure enough for almost all purposes [1] and has a significantly better performance than /dev/random.

If desired, you can revert to /dev/random for your random number generation:

  • Delete the line that starts with the following information from your $HIVEMQ_HOME/bin/run.sh file if you start HiveMQ manually or the -Djava.security.egd=file:/dev/./urandom option from the configuration file of the init service of your choice.

     	    JAVA_OPTS="$JAVA_OPTS -Djava.security.egd=file:/dev/./urandom"