MQTT Interface

TLS/SSL support

Secure MQTT connections support the following TLS/SSL versions:

• SSL 3.0

• TLS 1.0, 1.1 & 1.2

The TLS/SSL ciphers supported are:

• TLS_RSA_WITH_RC4_128_SHA

• TLS_RSA_WITH_3DES_EDE_CBC_SHA

• TLS_RSA_WITH_AES_128_CBC_SHA

• TLS_RSA_WITH_AES_256_CBC_SHA

• TLS_RSA_WITH_AES_128_GCM_SHA256

• TLS_RSA_WITH_AES_256_GCM_SHA384

• TLS_ECDHE_ECDSA_WITH_RC4_128_SHA

• TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA

• TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

• TLS_ECDHE_RSA_WITH_RC4_128_SHA

• TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA

• TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

• TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA

• TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

• TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

• TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

• TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

TLS Certificate signature validation (beta)

You can optionally perform a signature verification to verify the certificate presented by the MQTT client as follows:

1. Modify the thing definition for the thing and add an attribute with key tlssignature.

2. To find the signature of the certificate, use the following openssl command:

   
                                    
   > openssl x509 -in client.pem -text -noout
   ...
       Signature Algorithm: sha1WithRSAEncryption
            65:9c:41:b4:68:6e:23:ea:b0:b8:4f:cc:fe:c7:00:08:39:49:
            54:4d:bf:d9:fb:2e:a4:08:db:9f:d8:e3:ec:3b:0a:68:18:e8:
            05:41:b0:95:02:36:0f:d3:f2:f6:8f:14:99:19:07:44:27:a1:
            34:59:7f:5b:27:e2:3d:72:f9:5f:b4:3d:63:09:3a:1d:1f:fa:
            29:86:1b:88:5d:ba:fd:cd:92:ef:e5:14:55:f5:8f:05:ca:fc:
            c4:cd:a8:e3:57:a5:0c:50:a3:04:7f:26:cf:18:60:59:5d:99:
            1b:06:bc:de:c9:c6:64:22:aa:aa:d1:43:90:e5:83:b1:06:f8:
            5b:d6:86:38:71:2f:5c:89:17:06:bb:a9:a8:d8:8b:3a:cf:53:
            0f:75:d8:cf:d9:ea:37:cf:38:1f:69:15:fb:e8:30:7c:86:56:
            45:e9:18:8d:37:b7:4e:3c:2d:f0:3b:0a:2c:ee:35:29:1a:d8:
            14:68:ea:cc:09:1d:2d:99:8f:66:c0:e2:6d:49:f4:c4:73:f3:
            e1:03:98:c3:6d:b8:e0:23:71:a2:78:53:f3:36:b3:b1:3c:00:
            04:32:28:61:b4:9b:42:43:dc:44:b3:eb:4e:0e:90:ed:7e:18:
            bd:f3:de:bf:7a:9d:82:3f:ba:f2:7b:c1:a6:0e:95:6d:f6:1e:
            8f:b6:c3:ba
               

3. Set the tlssignature attribute on the thing on which you want to enable certificate validation to the signature returned in the previous step.

   Note:

   Enter the value as a hex string with no space or newline characters. Colons are acceptable between bytes.

4. Connect the device. If the signatures do not match, you receive an authentication error.

   Note:

   The validation occurs during the MQTT authentication, not during the TLS negotiation, so the TLS connection is successfully established, but you may receive a failed mqtt connection if the certificate cannot be validated.

MQTT Authentication

Authentication with MQTT uses the standard MQTT v3.1.1 authentication capabilities of the Client_ID, Username, and Password.

• User Authentication

  • Client_ID - Must be a unique string for different connections established by the same user.

  • Username - The email address for the user account.

  • Password - The password for the user account.

• Application Authentication

  • Client_ID - The application ID for the device that is connecting.

  • Username - The thing key for the application connecting. Must be globally unique for the organization.

  • Password - The application token for the device that is connecting.

TR50 Interface

Using MQTT as the transport for TR50 provides a reliable transport to send TR50 commands asynchronously within a single TCP session.

• Basic use

  • Send commands on topic api" in the following format:

    {
      "1" : {
        "command" : "command1",
        "params" : {
          command1Param
        }
      },
      "2" : {
        "command" : "command2",
        "params" : {
          command2Param1,
          command2Param2
        }
      }
    }

  • Receive replies on topic reply in the following format:

    {
      "1" : {
        "success" : true
      },
      "2" : {
        "success" : false,
        "errorCodes" : [-22],
        "errorMessages" : ["Device not found"]
      }
    }

• Send compressed JSON

  • To reduce data usage, you can send commands on special topics that expect a compressed payload.  Compression is performed using the standard zlib algorithm.  

  • Send commands on topic apiz.

  • Receive replies on topic reply.

• Using topic correlation Ids

  • Depending on your implementation, it may be easier to handle correlation Ids using the topic name for message routing rather than in the TR50 command.  To enable this functionality, the API allows a correlation Id to be specified after the api or apiz topics, and the Id is appended to the reply topic when the command completes.

  • Send commands on a topic such as api/123 and the reply is returned on reply/123.

    Note:

    Do not use mqtt.receive Event to listen to reserved topics api and apiz.

Server Topic Interface

While it is possible to leverage the full capability of the platform through the TR50 interface, it is easier to execute the majority of APIs using the server topics. The server topics enable you to develop applications that use the MQTT publish/subscribe interface to send and receive data regarding properties, alarms, and attributes on things.

• In any topic that specifies a thingKey, self can be used to indicate to the server to use the thingKey that is associated with your MQTT session.

• Wildcards plus (+) and hash (#) are supported. For example, subscribe to thing/+/property/temp to receive notifications when property temp on any thing in the organization changes.

For more information, see Server Topics API.