Kura Adapter

The Kura protocol adapter exposes an MQTT topic hierarchy allowing Eclipse Kura™ based gateways to publish control and data messages to Eclipse Hono™’s Telemetry and Event endpoints.

Authentication

The Kura adapter by default requires devices (gateways) to authenticate during connection establishment. The adapter supports both the authentication based on the username/password provided in an MQTT CONNECT packet as well as client certificate based authentication as part of a TLS handshake for that purpose.

The adapter tries to authenticate the device using these mechanisms in the following order

Client Certificate

The MQTT adapter supports authenticating clients based on TLS cipher suites using a digital signature based key exchange algorithm as described in RFC 5246 (TLS 1.2) and RFC 8446 (TLS 1.3). This requires a client to provide an X.509 certificate containing a public key that can be used for digital signature. The adapter uses the information in the client certificate to verify the device’s identity as described in Client Certificate based Authentication.

Username/Password

The MQTT adapter supports authenticating clients based on credentials provided during MQTT connection establishment. This means that clients need to provide a user and a password field in their MQTT CONNECT packet as defined in MQTT Version 3.1.1, Section 3.1 when connecting to the MQTT adapter. The username provided in the user field must match the pattern auth-id@tenant, e.g. sensor1@DEFAULT_TENANT.

The adapter extracts the auth-id, tenant and password from the CONNECT packet and verifies them using the credentials that the configured Credentials service has on record for the client as described in Username/Password based Authentication. If the credentials match, the client has been authenticated successfully and the connection is being established.

Resource Limit Checks

The adapter performs additional checks regarding resource limits when a client tries to connect and/or send a message to the adapter.

Connection Limits

The adapter rejects a client’s connection attempt with return code 0x05, indicating Connection Refused: not authorized, if

• the maximum number of connections per protocol adapter instance is reached, or
• if the maximum number of simultaneously connected devices for the tenant is reached.

Please refer to resource-limits for details.

Connection Duration Limits

The adapter rejects a client’s connection attempt with return code 0x05, indicating Connection Refused: not authorized, if the connection duration limit that has been configured for the client’s tenant is exceeded.

Message Limits

The adapter

• discards any MQTT PUBLISH packet containing telemetry data or an event that is sent by a client and
• rejects any AMQP 1.0 message containing a command sent by a north bound application

if the message limit that has been configured for the device’s tenant is exceeded.

Connection Events

The adapter can emit Connection Events for client connections being established and/or terminated. Please refer to the common configuration options for details regarding how to enable this behavior.

The adapter includes the client identifier from the client’s MQTT CONNECT packet as the Connection Event’s remote-id.

Publishing Data

Once the gateway has established a connection to the Kura adapter, all control and data messages published by applications running on the gateway are sent to the adapter and mapped to Hono’s Telemetry and Event API endpoints as follows:

1. The adapter treats all messages that are published to a topic starting with the configured HONO_KURA_CONTROL_PREFIX as control messages. All other messages are considered to be data messages.
2. control messages with QoS 0 are forwarded to Hono’s telemetry endpoint whereas messages with QoS 1 are forwarded to the event endpoint. The corresponding messages that are sent downstream have a content type of application/vnd.eclipse.kura-control.
3. data messages with QoS 0 are forwarded to the telemetry endpoint whereas messages with QoS 1 are forwarded to the event endpoint. The corresponding messages that are sent downstream have a content type of application/vnd.eclipse.kura-data.

Downstream Meta Data

The adapter includes the following meta data in messages being sent downstream:

The adapter also considers defaults registered for the device at either the tenant or the device level. The values of the default properties are determined as follows:

1. If the message already contains a non-empty property of the same name, the value if unchanged.
2. Otherwise, if a default property of the same name is defined in the device’s registration information, that value is used.
3. Otherwise, if a default property of the same name is defined for the tenant that the device belongs to, that value is used.

Note that of the standard AMQP 1.0 message properties only the content-type and ttl can be set this way to a default value.

Event Message Time-to-live

Events published by devices will usually be persisted by the messaging infrastructure in order to support deferred delivery to downstream consumers.

In most cases, the messaging infrastructure can be configured with a maximum time-to-live to apply to the events so that the events will be removed from the persistent store if no consumer has attached to receive the event before the message expires.

In order to support environments where the messaging infrastructure cannot be configured accordingly, the protocol adapter supports setting a downstream event message’s ttl property based on the default ttl and max-ttl values configured for a tenant/device as described in the Tenant API.

Tenant specific Configuration

The adapter uses the Tenant API to retrieve tenant specific configuration for adapter type hono-kura-mqtt. The following properties are (currently) supported: