MQTT security

Three concepts are fundamental to MQTT security: identity, authentication, and authorization. Identity is about naming the client that is being authorized and given authority. Authentication is about proving the identity of the client, and authorization is about managing the rights that are given the client.

Try the security samples

Identity

Identify an MQTT client by its client identifier, user ID, or public digital certificate. One or other of these attributes defines the client identity. An MQTT server authenticates the certificate sent by the client with the SSL protocol, or the client identity with a password set by the client. The server controls which resources the client can access, based on the client identity.

The MQTT server identifies itself to the client with its IP address and its digital certificate. The MQTT client uses the SSL protocol to authenticate the certificate sent by the server. In some cases, it uses the DNS name of the server to verify the server that sent it the certificate is registered as the certificate holder.

Set the identity of the client in one of the following ways:

Client identifier
The MqttClient class (MQTTClient_create or MQTTAsync_create in C) sets the client identifier. Call the class constructor to set the client identifier as a parameter, or return a randomly generated client identifier. The client identifier must be unique across all clients that connect to the server, and must not be the same as the queue manager name on the server. All clients must have a client identifier, even if it is not used for identity checking. See Client identifier.
User ID
The MqttClient class (MQTTClient_create or MQTTAsync_create in C) sets the client user ID as an attribute of MqttConnectOptions (MqttClient_ConnectOptions in C). The user ID does not need to be unique to a client.
Client digital certificate
The client digital certificate is stored in the client keystore. The keystore location depends on the client:

  • Java

    Set the location and properties of the client keystore by calling the setSSLProperties method of MqttConnectOptions and passing the keystore properties. See SSL Modifications to Example.java. The keytool tool manages Java keys and keystores.

  • C

    MQTTClient_create or MQTTAsync_create sets the keystore properties as attributes of MQTTClient_SSLOptions ssl_opts. The openSSL tool creates and manages the keys and keystores that are accessed by the MQTT client for C.

  • Android

    Manage an Android device keystore from the Settings > Security menu. Load new certificates from the SD card.

Set the identity of the server by storing its private key in the server keystore:

IBM WebSphere MQ
The MQTT server keystore is an attribute of the telemetry channel the client is connected to.

Set the keystore location and attributes with IBM WebSphere MQ Explorer, or with the DEFINE CHANNEL command; see DEFINE CHANNEL (MQTT). Multiple channels can share a keystore.

Authentication

An MQTT client can authenticate the MQTT server that it connects to, and the server can authenticate the client that is connecting to it.

A client authenticates a server with the SSL protocol. An MQTT server authenticates a client with the SSL protocol, or with a password, or both.

If the client authenticates the server, but the server does not authenticate the client, the client is often known as an anonymous client. It is common to establish an anonymous client connection over SSL, and then authenticate the client with a password encrypted by the SSL session. It is much more common to authenticate a client with a password than with a client certificate, because of the certificate distribution and management problem. You are likely to find client certificates used in high value devices such as ATMs and chip-and-pin machines, and in custom devices, such as smart electricity meters.

Server authentication by a client
An MQTT client verifies that it is connected to the correct server by authenticating the server certificate with the SSL protocol. This form of verification is familiar to you, when you browse a website over the HTTPS protocol.

The server sends its public certificate, signed by a certificate authority, to the client. The client uses the public key of the certificate authority to verify the signature of the certificate authority on the server certificate. It also checks the certificate is current. Those checks establish that the certificate is valid.

Certificate authority certificates, often termed root certificates, are stored in the client truststore:

  • Java

    Call the setSSLProperties method of MqttConnectOptions and pass the truststore properties to set the location and properties of the client truststore. See SSL Modifications to Example.java. Manage certificates and truststores with the keytool tool.

  • C

    MQTTClient_create or MQTTAsync_create set the truststore properties as attributes of MQTTClient_SSLOptions ssl_opts. Manage certificates and truststores with the openSSL tool.

  • Android

    Manage an Android device truststore from the Settings > Security menu. Load new root certificates from the SD card.

Client authentication by a server

An MQTT server verifies that it is connected to the correct client by authenticating the client certificate with the SSL protocol, or by authenticating the client identity with a password.

It authenticates the client with the password that is sent by the client to the server in an MQTT protocol header. The server might choose to authenticate the client identifier, user ID, or certificate with the password. It depends on the server. Usually, the server authenticates the user ID. Verify passwords over an SSL connection that has been secured by verifying the server, to avoid sending passwords in the clear.

  • IBM WebSphere MQ

    IBM WebSphere MQ authenticates a client certificate with the SSL protocol. Store root certificates in the IBM WebSphere MQ Telemetry keystore. You can only authenticate a client certificate as part of mutual SSL authentication. That is, you must provide the client with the server public certificate as well as providing the server with the client public certificate.

    IBM WebSphere MQ Telemetry uses the same store for both its own private and public certificate, and other public certificates, such as the root certificates provided by certificate authorities.

    Set the keystore location and attributes with IBM WebSphere MQ Explorer, or with the DEFINE CHANNEL command; see DEFINE CHANNEL (MQTT). Multiple channels can share a keystore.

    IBM WebSphere MQ authenticates the client user ID, or the client identifier, by calling the Java authentication and authorization service (JAAS).

    Configure JAAS in an MQXRConfig configuration stanza that is stored in the jaas.config file. The file is stored in the qmgrs\QmgrName\mqxr directory in the IBM WebSphere MQ data path.

    Check the authenticity of the client by writing a login method for the JAASLoginModule. See Telemetry channel JAAS configuration.

    IBM WebSphere MQ Telemetry passes the JAASLoginModule.login method the following parameters:
    • User ID
    • Password
    • Client identifier
    • Network identifier
    • Channel name
    • ValidPrompts

Authorization

Authorization is not part of the MQTT protocol. It is provided by MQTT servers. What is authorized depends on what the server does. MQTT servers are publish/subscribe brokers, and useful MQTT authorization rules control which clients can connect to the server, and which topics a client can publish or subscribe to. If an MQTT client can administer the server, more authorization rules control which clients can administer different aspects of the server.

The number of possible clients is huge, so it is not feasible to authorize each client separately. An MQTT server will have a means to group clients by profiles, or groups.

The identity of a client, from the point of view of access and authorization, is not something that is unique to an MQTT client. Do not equate the identity of a client, with the client identifier. They might be the same, but are commonly different. For example, you probably have a user name that is common across a number of services, and some of these services co-operate in single sign-on. An enterprise scale MQTT server is likely to call an authorization service that offers common identities and authorities for different applications.

IBM WebSphere MQ

IBM WebSphere MQ has a pluggable authorization service. The default authorization service that is provided on Windows and Linux® is the object authority manager (OAM). See Controlling access to objects by using the OAM on UNIX, Linux and Windows systems. It associates operating system user IDs and groups with operations on IBM WebSphere MQ objects, such as topics and queues.

You can configure a telemetry channel to access IBM WebSphere MQ with a fixed user ID. This is how the sample channel is set up. Or you can access IBM WebSphere MQ with the user ID set by the MQTT client. Authorizing MQTT clients to access WebSphere MQ objects describes ways of setting up IBM WebSphere MQ Telemetry to achieve coarse, medium, and fined grained client access control.