Kaspersky IoT Secure Gateway 100
2.0
English

Contents

Configuring a connection over the MQTT protocol

Kaspersky IoT Secure Gateway 100 forwards data to the

MQTT broker
over the
MQTT
protocol. You can read the MQTT protocol specification on the developer's website. Kaspersky IoT Secure Gateway 100 version 2.0 supports MQTT protocol version 3.1.1.

In this Help section

Securing a connection over the MQTT protocol

Configuring data transmission over the MQTT protocol

Parameters description in the MqttPublisherSettings-0.json configuration file

Special considerations when generating names of MQTT topics

Required actions when an MQTT broker certificate is revoked
Page top
[Topic 224293]

Securing a connection over the MQTT protocol

To securely transmit data over the MQTT protocol:

  1. Copy the file containing the
    certificate chain
    of the MQTT client (a chain can consist of one leaf
    certificate
    of the client) to the directory /app/Core/pki/certs/transfer/mqtt/publisher on the HW-IDS partition of the microSD card.
  2. Copy the file containing the certificate chain that was used to form the
    digital signature
    to the directory /app/Core/pki/certs/transfer/mqtt/publisher on the HW-IDS partition of the microSD card.
  3. Copy the file of the private
    encryption key
    of the MQTT client to the directory /app/Core/pki/private/transfer/mqtt/publisher on the HW-IDS partition of the microSD card.

The certificates and encryption keys used by the MQTT client must be in PEM format. The key length of the client certificate must be at least 2048 bits.

Page top
[Topic 240937]

Configuring data transmission over the MQTT protocol

To configure data transmission over the MQTT protocol:

  1. Create the MqttPublisherSettings-0.json file.
  2. In the MqttPublisherSettings-0.json file, specify the MQTT settings and their values in accordance with JSON syntax.
  3. Put the configuration file into the directory /app/Core/config/transfer/mqtt/publisher on the HW-IDS partition of the microSD card.

Sample configuration file:

MqttPublisherSettings-0.json

{

"id": 0,

"name": "Kaspersky IoT Secure Gateway 100 MQTT Publisher",

"description": "Transfer data to MQTT Broker by Kaspersky IoT Secure Gateway 100",

"clientId": "KISG100",

"serverUri": "ssl://192.168.188.8:8883",

"security": {

"clientPkiData": {

"certificate": "mqtt-publisher.crt",

"privateKey": "mqtt-publisher.key"

},

"trustStore": ["ca-bundle.crt"]

},

"userCredentials":{

"username": "KISG100",

"password": "4vRXE84zsCy8bLQcZi2HH82TmC"

},

"lastWill": {

"topicName": "LastWill",

"message": "LastMessage"

},

"keepAlive": 800,

"qualityOfService": 1,

"topics": [

{

"id": 0,

"name": "Heartbeat",

"topicName": "Heartbeat"

},

{

"id": 1,

"name": "Temperature",

"topicName": "Temperature"

},

{

"id": 2,

"name": "Speed",

"topicName": "Speed"

}

]

}

To edit files in JSON format, we recommend using a text editor that supports JSON syntax highlight. This will help avoid potential errors (for example, unbalanced braces).

Page top

[Topic 240939]

Parameters description in the MqttPublisherSettings-0.json configuration file

The required parameters should be explicitly defined. The other parameters are optional. For optional parameters that are not included in the configuration file, the default value prescribed by the MQTT protocol may be used.

Parameters in the MqttPublisherSettings-0.json file

Parameter name

Required parameter

Description

Possible values and notes

id

Yes

ID of the MQTT client that will send data to the MQTT broker.

0.

The value of this parameter must match the value of the sendingHubId parameter in the GuideSettings-0.json configuration file.

name

Yes

Name of the MQTT client that will send data to the MQTT broker.

<MQTT Publisher name>.

Example: Kaspersky IoT Secure Gateway 100 MQTT Publisher.

description

No

Description of the MQTT client that will send data to the MQTT broker.

<MQTT Publisher description>.

Example: Transfer data to MQTT Broker by Kaspersky IoT Secure Gateway 100.

clientId

No

Unique identifier of the MQTT client.

1.

The internal architecture of Kaspersky IoT Secure Gateway 100 involves interaction between a receiving hub and a sending hub. The id parameter is linked to the sending hub. The clientId parameter is linked to the MQTT protocol requirements and determines the ID of the MQTT client within this protocol.

The clientId value must be unique among all clients connected to the MQTT broker.

serverUri

Yes

Address of the server that the MQTT client will connect to.

<scheme>://<host>:<port>.

Example: ssl://192.168.188.8:8883.

ssl is an architecture-prescribed scheme for querying a resource.

8883 is the default port.

security

Yes

Parameter block for configuring a secure connection. Contains the clientPkiData and trustStore parameter blocks.

{clientPkiData, trustStore} parameter block.

The security parameter block is used to configure the certificates and encryption keys for the digital signature and data

encryption
.

clientPkiData

Yes

Parameter block containing the names of the certificate and private encryption key files of the MQTT client for an encrypted connection.

{certificate, privateKey} parameter block.

certificate

Yes

Name of the file containing the certificate chain to the MQTT client certificate.

mqtt-publisher.crt.

privateKey

Yes

Private encryption key file name.

mqtt-publisher.key.

The key length must be at least 2048 bits.

trustStore

Yes

Array that includes the name of the file containing the certificate chain to the MQTT broker certificate.

ca-bundle.crt.

Name of the file containing the certificate chain to the certificate of the Certification Authority that signed the MQTT broker certificate.

userCredentials

Yes

Parameter block responsible for authentication of the MQTT client on the server.
  • {username, password} parameter block containing the user account credentials.
  • null is indicated if you want to allow an anonymous connection of the MQTT client to the MQTT broker. In this case, you do not need to fill in the username and password fields.

username

No

Name of the user account for authorization on the MQTT server.

<username>.

password

No

Password of the user account for authorization on the MQTT server.

<password>.

lastWill

No

Parameter block for configuring a message informing that the client was improperly disconnected (LWT message).

{topicName, message} parameter block.

The client can specify the LWT message when connecting to the MQTT broker for the first time. The MQTT broker will store this message until it detects an improper disconnection of the client. Upon detection of an improper connection, it will send the LWT message to all clients that have subscribed to this type of message. The MQTT broker does not send this message when the client is properly disconnected.

topicName

No

Name of the

MQTT topic
that determines the information channel where the LWT message will be published.

<topicName>.

Example: LastWill.

message

No

Contents of the LWT message.

<message>.

Example: LastMessage.

keepAlive

No

Period of time that the MQTT broker can wait to receive a message from the MQTT client before terminating the connection due to inactivity.

800.

The default value is 120.

Available values: 0–65535.

If the keepAlive value is equal to zero, the server will not be obligated to disconnect a client based on inactivity of the client.

If the server deems a client to be inactive or if the client is not responding to queries, the server can disconnect the client at any time, irrespective of the keepAlive value provided by the client.

qualityOfService

No

Parameter defining a guarantee to send messages.

1.

Agreement between the message sender (publisher) and message recipient (subscriber) that defines a guarantee to deliver a specific message. The MQTT specification defines the following three levels of qualityOfService:

  • 0 is no more than one time: the client publishes messages without verifying whether they are delivered to the broker. Messages may be lost or duplicated.
  • 1 is at least one time: the broker confirms delivery. Messages may be duplicated, but delivery is guaranteed.
  • 2 is exactly one time: message delivery is guaranteed, and any potential duplication is eliminated.

The default value is 1.

topics

Yes

Array from the parameter blocks of MQTT topics.

Array of [{id, name, topicName}] parameter blocks.

A separate parameter block in the array is completed for each MQTT topic.

id

Yes

ID of the destination port.

<id>.

Example: 0.

name

Yes

Name of the destination port. This name must match the outbound port name of one of the

OPC UA
server data nodes indicated in the nodes parameter block in the OpcUaClientSettings-0.json configuration file.

<name>.

Example: Temperature.

To correctly transfer data from the OPC UA server to the MQTT broker, you need to map the MQTT topics to their corresponding OPC UA

data nodes
. The name value is used for mapping.

topicName

Yes

Name of the MQTT topic.

<topicName>.

Example: Heartbeat.

See also: Special considerations when generating names of MQTT topics.

Page top

[Topic 240940]

Special considerations when generating names of MQTT topics

When filling in the values for topicName, please adhere to the following guidelines:

  • Wildcard characters cannot be used in the names of MQTT topics. We also do not recommend using the $ character in the names of MQTT topics.
  • The name of an MQTT topic cannot be blank (it must contain at least one character).
  • The names of MQTT topics are case sensitive.
  • The names of MQTT topics can contain a blank space character.
  • MQTT topics that are separated by only a / character at the beginning or end of the name are considered to be different MQTT topics.
  • An MQTT topic name consisting of only a / character is permitted.
  • The name of an MQTT topic must not contain the null character (NUL).
  • Names of MQTT topics are UTF-8 strings of size that does not exceed 65535 bytes.
Page top
[Topic 240941]

Required actions when an MQTT broker certificate is revoked

When an MQTT broker certificate is revoked, you will need to obtain a new certificate from the MQTT broker administrator and replace the revoked certificate. If you do not do this, Kaspersky IoT Secure Gateway 100 will trust both the revoked certificate and the new certificate until the revoked certificate expires. This could lead to a situation in which a connection established over a secure channel is not actually secure.

To use a new MQTT broker certificate instead of a revoked certificate:

  1. In the /app/Core/pki/certs/transfer/mqtt/publisher directory on the HW-IDS partition of the microSD card, delete the file indicated in the trustStore parameter of the MqttPublisherSettings-0.json configuration file.
  2. In the trustStore parameter of the MqttPublisherSettings-0.json configuration file, specify the name of the new certificate file.
  3. Copy the new certificate file to the /app/Core/pki/certs/transfer/mqtt/publisher directory on the HW-IDS partition.

Page top

[Topic 246545]