SMOKER Documentation

• 1: Overview
• 2: Concepts
• 2.1: Authentication
• 2.2: Authorization
• 2.3: Cryptography
• 3: Specification
• 3.1: Contract
• 3.2: Broker
• 3.3: Client
• 4: References

1 - Overview

The SMOKER protocol describes two independent security processes for MQTT 5.0: Anonymous authentication based on Zero-Knowledge Proofs as well as client-managed authorization. It provides an enhanced authentication scheme based on the Schnorr Non-Interactive Zero-Knowledge Proof over an elliptic curve. Therefore, no sensitive data has to be transmitted, nor stored on the broker. In case the broker gets compromised, no valuable data can be extracted (e.g. password hashes). Furthermore, SMOKER provides a client-managed authorization mechanism usable for authenticated parties. Both authentication and authorization pursue the goal of not having a central authority and delegating the data sovereignty to the clients.

The first proof-of-concept of the SMOKER protocol was elaborated in a bachelor thesis at the Bern University of Applied Sciences. Some parts of the thesis were extracted to a paper that was published to arxiv. Arxiv is a free distribution service and an open-access archive for scholarly articles. More papers, such as one for the authorization part, will follow. SMOKER is now further developed by the microfast GmbH in Switzerland.

MQTT

If you are new to MQTT take a look at the introduction, which describes the basic idea and functionality of the MQTT protocol. For more details, please consult the official documentation from Oasis, which describes the MQTT protocol in full detail. Make sure to consult the MQTT version 5 of the protocol documentation as SMOKER relies on features, such as enhanced authentication, released in this version.

Implementations

Brokers

Clients

Where should I go next?

• Concepts: Understanding the main concepts of SMOKER
• Specification: Checkout the detailed specification

2 - Concepts

The main goal of SMOKER is it, to provide an easy and anonymous way for clients to authenticate themselves at a broker and provide a possibility to set up authorization rules at topic level. The claims are managed exclusively by the clients by claiming/unclaiming them. The broker only has to take care of the secure storage of claims and the enforcement of their rules for MQTT publish/subscribe activities.

2.1 - Authentication

SMOKER authentication completely voids session hijacking for the MQTT protocol and provides authenticity without the need for any network security nor channel security. The broker does not require to keep any secrets for session handling. Moreover, it allows the clientID, which represents the identification for a session, to be publicly known. The presented approach allows completely anonymous but authentic sessions, hence the broker does not need any priory knowledge of the client party. As it is especially targeted for applications within the world of IoT, SMOKER is designed to require only the minimum in extra power in terms of energy and space. SMOKER does not define any new concept, but simply combines a state of the art cryptographic signature scheme with the existing MQTT 5.0 specification. Thus, no protocol extension is required in order to provide the targeted security properties. The described approach is completely agnostic to the application layer at the client side and is only required during MQTT session establishment.

MQTT Enhanced Authentication

The MQTT CONNECT packet supports basic authentication of a network connection using the username and password fields. While these fields are named for a simple password authentication, they can be used to carry other forms of authentication such as passing a token as the password.

Enhanced authentication extends this basic authentication to include challenge / response style authentication. It might involve the exchange of AUTH packets between the Client and the Server after the CONNECT and before the CONNACK packets.

SMOKER uses this challenge / response authentication flow as the client needs to be able to retrieve authentication data from the broker while connection establishment.

Client ID

As the SMOKER protocol uses a (base32 encoded) representation of a EdDSA public key for the MQTT client ID, this key-pair must be generated before the connection can be established. Depending on the use case, the client could also generate a new key-pair for every connection. Base32 is used to fit the public key into the allowed character set specified by the MQTT protocol itself.

An example how a valid client ID looks like:

T5LKBKSPOWU43HVKN7ZCB54VQB2ZVR3ZOQRV6EZSDDF5JX4HX4SQ====

Note that the clientId must be encoded with padding.

Client ID collisions

It is possible that clients, even without SMOKER authentication, connect with a client ID that is already used by an authenticated client. The default behavior of most brokers is that the already connected client is disconnected, and the new client is accepted. In such a case, when implementing a SMOKER extension for a broker, it is mandatory to ensure that the already connected client does not get disconnected. One of the following treatments should be implemented:

1. The broker accepts the connection but assigns a new unique clientId to the connecting client.
2. The broker denies the connection with a 0x85 Client Identifier not valid or 0x87 Not authorized reason code and a corresponding message.

If a client connects with a clientId already assigned by the broker but can prove its authenticity using the SMOKER protocol, the client should be accepted and for the already connected client the default behavior of the broker should be applied.

Establish a connection

The following figure shows a successful and unsuccessful MQTT session establishment using the SMOKER authentication method:

1. The client starts the connection establishment by sending a CONNECT packet with 'SMOKER' set as authentication method and the base32 (incl. padding) encoded public key.
2. The broker responds with a AUTH packet containing a unique 32 byte nonce.
3. The client must sign this message with his already generated private key which is the counter part of the public key used as client id in the MQTT session. The signed message is sent back to the broker within a AUTH packet.
4. The broker verifies the received signature and responds with a CONNACK packet which accepts or denies the connection.

2.2 - Authorization

Authenticated parties are allowed to claim topics and authorize other clients to subscribe or publish on the claimed resource. Such a claim is fully client-managed – only the initiator can ever change or delete the claim again. If an authenticated client wants to subscribe or publish on a claimed topic, the broker must decide whether this is permitted or not on the basis of the available claims made by the clients.

Security considerations

An attacker could manipulate the data source of the broker where claims are stored. Therefore, several precautions must be taken in order to ensure the attacker is not able to manipulate data to its favor.

Client-side signature of claims

The broker must have the possibility to verify that a claim was not modified since creation. Therefore, the client must provide a signature of the given claim at creation time. The signature must be created with the secret counterpart of the clients public key that acts as clientID in the authenticated MQTT session. This allows the broker to verify a claim is valid when it evaluates it for further processing. If verification fails, the claim record must be considered compromised and may not further be used.

Restricted area

The restricted area is a dedicated branch within the tree of topics. The topic to be claimed, must start with a predefined segment followed by the clientID and the effective topic name (e.g. restricted/{clientID}/temperature). This implicitly creates a dedicated client space, which can only be managed by the clientID present in the topic name.

Topic must contain the client ID

Any user with access to the claim store could possibly modify an existing claim, and enter itself as the owner and use its self-calculated valid signature. The steal of the claim would allow it to listen to the communication on the topic without anyone ever noticing it. In order to prevent this, the clientID must be present in the topic name which has to be claimed. If this is not the case, the claim has to be considered to be invalid by the broker. This ensures that the relationship between signature, the owners’ clientID and the topic name, is always upright.

Claim flooding

Any authenticated client is allowed to claim topics. A client can theoretically claim topics for itself at arbitrary intervals. Fortunately, MQTT does not allow to publish on wildcard topics. This prevents claiming wide topic ranges within one claim.

If the implementation of the persistence logic within the broker includes direct I/O access, it can lead to enormous loss of performance or even end up in a server crash. This problem is not solved by the SMOKER protocol and must be solved when implementing the claim store.

Client

A client can basically use the following SMOKER interactions:

• Claim a topic
• Unclaim a topic
• Publish & Subscribe claimed topics

Claiming

The following figure visualizes a successful sequence of a topic claim. This example is used for the subsequent definitions on client and broker side.

The client initiates a topic claim by publishing a claim to a predefined system topic. This message must be published with QoS 1 as the broker submits feedback information within the PUBACK packet.

The claiming payload sent by the client, is classified as a whitelist or blacklist and contains a restriction. A restriction must contain at least one or more authorization rules consisting of the targeting topic, and a set of rules for read (subscribe) and write (publish) actions. All containing rules are implicitly interpreted with the allow (whitelist) or deny (blacklist) operator based on the classification. Rules can be defined for all (wildcard *) or specific clientID’s. If a client gets whitelisted on a topic, all other clients automatically get blacklisted and vice versa. The only exception is the owner itself, which is always guaranteed to have full access to all topics owned by it. In case a client only wants to authorize specific clients, it must know their clientID’s.

Further, the client must provide a signature of the restriction within the claim. As the client is fully responsible for his claims it needs to make sure that claims can not be manipulated by anyone else. Therefore, it’s evident that the restriction which is provided to the broker must be signed with the clients private key. Thus, the broker is able to verify that the restriction it is looking up is not compromised.

The fully detailed structure of claims is described in the API docs.

Update a claim

Updates of claims are only accepted by the owner itself. An update can be triggered by publishing a new version of the claim on the same topic. The broker must then completely replace the previous claim with the new one.

Unclaim

Deletions of claims are only accepted by the owner itself. If a client wants to unclaim a topic, this must be achieved by publishing the concerned topic name within the payload of the message on a specific unclaim topic.

Publish & Subscribe

A client can publish and subscribe to any topic he wants to. If the topic is within the restricted area, the SMOKER topic validation on the broker must kick in and decide whether the client is allowed to perform the activity or not.

Subscribing wildcard topics

A client is basically allowed to subscribe any wildcard topic. Such subscriptions may also include resources where access to the subscribing client is not granted by the claim owner. However, the client may only receive messages it is allowed to.

Broker

Receive a claim

For each incoming claim configuration, the broker must perform various validations to complete the topic claim. If the validation fails, the broker returns a 0x99 Payload format invalid reason code within the PUBACK packet. This can happen if at least one following cases occur:

• If the provided signature can not be verified successfully
• If the given topic contains MQTT specific wildcard characters (e.g. + or #)
• If the given topic is empty or contains only whitespaces

If the validation succeeds, the broker must store the claim and its corresponding signature. This store must be accessible throughout different sessions.

Handling publish and subscribe messages

The broker must check for each incoming publish or subscribe activity whether the underlying client has permission to do so or not. This decision must be based on the persisted claims already submitted by other clients or the requesting client itself. A successful subscription is visualized in the figure below:

Before the broker can evaluate a specific claim, it needs to check its integrity with various validation rules. If one of the validation rules fails it must be assumed that the claim is compromised and can not be used for further evaluation. In this case the broker must return the 0x83 Implementation specific error reason code. The following rules must be validated:

• Verify the owners’ signature to ensure the claim was not modified
• Check if the topic name contains the owners clientID

If the integrity check succeeds, the requested action will be allowed or denied based on the given claim permission. For allowed subscriptions, no further work is necessary on the broker side. An allowed publish messages gets enqueued on the broker to be delivered to authorized clients.

Because of the following reasons it may be mandatory to perform further security checks for any outbound message.

• The topic matches due a wildcard subscription of a client
• An existing topic subscription became invalid due to a claim update

The broker must accept wildcard subscriptions by clients without considering any permissions. If a publish message, matches a clients’ wildcard subscription, the broker must evaluate whether the client is allowed to receive this message or not. If it’s not, the message delivery must be discarded. Otherwise, the message is delivered as usual.

As claims are client-managed, they can be updated at any time. This may cause an authorized subscription, to become deprecated. It is a decision of the broker implementation whether permissions have to be enforced immediately or not – with the acceptance of the respective consequences.

2.3 - Cryptography

Cryptography & signature scheme

Every cryptographic operation of SMOKER is using the Edwards-curve Digital Signature Algorithm (EdDSA). EdDSA is a digital signature scheme using a variant of Schnorr signature based on Twisted Edwards curves. It is designed to be faster than existing digital signature schemes without sacrificing security.

3 - Specification

3.1 - Contract

The following object descriptions must be considered on the client and broker side.

Claim

To claim a topic, the claim must be published to the claim-topic (default: access/claim) with the JSON representation within the payload. The following JSON structure represents a valid claim.

{
  "restriction": {
    "topicName": "restricted/4Z6BOASZMWKO6YP4BALMNRZ4EBDWIOVXVVJBZ647WASYOEA7AUJQ====/temperature",
    "permissions": [
      {
      "clientId": "T5LKBKSPOWU43HVKN7ZCB54VQB2ZVR3ZOQRV6EZSDDF5JX4HX4SQ====",
      "activity": "PUBLISH"
      }
    ],
    "restrictionType": "WHITELIST"
  },
  "signature": "c/p7jJevMaXIImzBfE4+r5xAYQZt0ukiuICeIpJNjxZ6FYWUESO/2lO1Bs5ZX5+sDr44nyjyisEo8trPlHkfAHsicGVybWlzc2lvbnMiOlt7ImFjdGl2aXR5IjoiUFVCTElTSCIsImNsaWVudElkIjoiVDVMS0JLU1BPV1U0M0hWS043WkNCNTRWUUIyWlZSM1pPUVJWNkVaU0RERjVKWDRIWDRTUT09PT0ifV0sInJlc3RyaWN0aW9uVHlwZSI6IldISVRFTElTVCIsInRvcGljTmFtZSI6InJlc3RyaWN0ZWQvNFo2Qk9BU1pNV0tPNllQNEJBTE1OUlo0RUJEV0lPVlhWVkpCWjY0N1dBU1lPRUE3QVVKUT09PT0vdGVtcGVyYXR1cmUifQ=="
}

Signature

Every Claim needs to be signed by the client and verified by the broker. To make sure that signatures are consistent over all platforms the signature payload is specified as follows:

• JSON representation of the Restriction Object
  • lowerCamelCase
  • Alphabetically sorted properties
  • Oneliner (no spaces, no pagebreaks)

This payload must be signed with a valid ED25519 key-pair which was generated when the client connected to the broker. The signature must then be set on the claim in a Base64 representation.

Claim properties

Restriction properties

Permission properties

Claim Request / Response

The client can request all his claims from the broker. For more details about this request-response implementation see broker specification.

The broker must publish the following information in JSON format to the response topic:

• clientId The clientId which is involved
• ownedClaims All claims which are owned by the requesting client
• involvedClaims All claims where the client is allowed to publish or subscribe. Claims which deny the client to act on explicitly or via wildcard must be ignored.

{
  "clientId": "SBVEUXVOPGSL6EDRBKI6ZZKGSJJVIL4W2GFEPFHON4QCZMFHVCJQ====",
  "involvedClaims": [
    {
      "restriction": {
        "permissions": [
          {
            "activity": "PUBLISH",
            "clientId": "*"
          }
        ],
        "restrictionType": "WHITELIST",
        "topicName": "restricted/47VQEWGOFI2BWEZFTGSUQVUKNX3JJDGYNDOFTQELD5LLCOYK366Q====/asdasd"
      },
      "signature": "bM28F8Hpne6iwH0X/VA7i38qW44oCEXTwn1JajFuNA2wTsYNt6oxNYl2W2qGUSWhKWmWVp7ntYsScDkSNjmAD3sicGVybWlzc2lvbnMiOlt7ImFjdGl2aXR5IjoiUFVCTElTSCIsImNsaWVudElkIjoiKiJ9XSwicmVzdHJpY3Rpb25UeXBlIjoiV0hJVEVMSVNUIiwidG9waWNOYW1lIjoicmVzdHJpY3RlZC80N1ZRRVdHT0ZJMkJXRVpGVEdTVVFWVUtOWDNKSkRHWU5ET0ZUUUVMRDVMTENPWUszNjZRPT09PS9hc2Rhc2QifQ=="
    },
    {
      "restriction": {
        "permissions": [
          {
            "activity": "ALL",
            "clientId": "*"
          }
        ],
        "restrictionType": "WHITELIST",
        "topicName": "restricted/2WACA536Y65V2D6HYJO67DRDZDRQLSM53XHEAAQHDDSA2JMDQUNQ====/claims"
      },
      "signature": "CDbCDfmGy8nVXPNkSkllieLE1NRiHQoWhoKYA/0l5R0V5ipV3crHmfV/fp65HVu65Ze0A2cFt5SpwBmkgICrA3sicGVybWlzc2lvbnMiOlt7ImFjdGl2aXR5IjoiQUxMIiwiY2xpZW50SWQiOiIqIn1dLCJyZXN0cmljdGlvblR5cGUiOiJXSElURUxJU1QiLCJ0b3BpY05hbWUiOiJyZXN0cmljdGVkLzJXQUNBNTM2WTY1VjJENkhZSk82N0RSRFpEUlFMU001M1hIRUFBUUhERFNBMkpNRFFVTlE9PT09L2NsYWltcyJ9"
    },
  ],
  "ownedClaims": [
    {
      "restriction": {
        "permissions": [],
        "restrictionType": "WHITELIST",
        "topicName": "restricted/SBVEUXVOPGSL6EDRBKI6ZZKGSJJVIL4W2GFEPFHON4QCZMFHVCJQ====/claims"
      },
      "signature": "gdQgtW4XSq4oBu7kjMfEicxql4+zrQoSJU2hlPJRghc087i0Qa57tAWW5SscMLm7a2Te7c9skAXzvXLNYrCeC3sicGVybWlzc2lvbnMiOltdLCJyZXN0cmljdGlvblR5cGUiOiJXSElURUxJU1QiLCJ0b3BpY05hbWUiOiJyZXN0cmljdGVkL1NCVkVVWFZPUEdTTDZFRFJCS0k2WlpLR1NKSlZJTDRXMkdGRVBGSE9ONFFDWk1GSFZDSlE9PT09L2NsYWltcyJ9"
    }
  ]
}

3.2 - Broker

Connection establishment

According to the authentication concepts, the broker must proceed the following steps to be able to accept SMOKER connections:

1. Check the authentication method property of incoming connections
2. Generate a unique nonce and send it back to the client
3. Verify the signed nonce of the client and accept or deny the connection

Check authentication method

On every incoming connection the broker needs to check if the client connects with the SMOKER authentication method. If so, the broker must initialize the SMOKER authentication flow.

The broker may only accept SMOKER connections. In this case the broker must deny all connections except the ones with SMOKER set as authentication method. Otherwise, it must be made sure, that non-SMOKER clientId’s don’t collide with already connected SMOKER clients. This could be achieved by letting the broker generate/override clientId’s for non-SMOKER clients or denying the connection with a CONACK packet and a 0x87 Not authorized reason code.

Generate a unique nonce

If a SMOKER client is connecting, the broker needs to respond with an AUTH packet with a unique nonce in the authentication data, and a reason code 0x18 Continue authentication. It is recommended to provide at least a nonce of 128 bit (16 bytes) in length.

Verify the signed nonce

If the signed nonce is received with another AUTH packet sent from the client, the broker must verify this signature using the clientId and check if the nonce matches. If so, the broker must accept the connection with a 0x00 Success reason code. Otherwise, the connection must be denied with a 0x87 Not authorized reason code.

Admin topics

Claim

To receive claims and unclaims, the broker must provide and reserve the follwing topics:

• access/claim
• access/unclaim

These topics must not be subscribed by any client and must be treated as system topics.

Claim Requests

The client can request all claims that it either owns or is authorized to perform any MQTT activity. Therefore, the client can publish to the following admin topic using the request-response pattern, which was introduced in MQTT 5.0:

• access/claims/{clientId}/request

Process incoming claim

If the broker receives a claim, meaning a message is published on the topic access/claim, the broker must expect a valid claim within the payload of this message.

If the client is not authenticated, the broker must reject this message with a 0x87 Not authorized reason code.

If the client is authenticated, the broker must try to process the claim with the following steps:

• Parse the claim (JSON) from the payload of the message
• Validate the claim.
  • Mandatory fields (see contracts)
  • Verify the given signature (see signature)
• Persist the claim. It is up to the implementation, which type of storage is used.
• Returing a result
  • Success: Return 0x00 Success if validation, signature verification and the claim could be persisted
  • Fail: Otherwise return a reason code (such as 0x99 Payload format invalid or 0x80 Unspecified error) and a meaningful error message

Process incoming unclaim

If the broker receives an unclaim, meaning a message is published on the topic access/unclaim, the broker must expect a valid SMOKER topic name within the payload of this message.

If the client is not authenticated, the broker must reject this message with a 0x87 Not authorized reason code.

If the client is authenticated the broker must try to process the unclaim with the following steps:

• Search the claim-store for topic names that match the topic from the message payload. The broker must only search topic of the client that sent the unclaim message. Only the owner can ever perform the unclaim a claimed topic.
• If a topic was found, remove the claim from the claim-store.
• Returing a result
  • Success: Return 0x00 Success if the unclaim could be performed (or no claim was found)
  • Fail: Otherwise return a reason code (such as 0x99 Payload format invalid or 0x80 Unspecified error) and a meaningful error message

Process Claim Request

According to the MQTT request-response specification, the client must provide a response topic where the opposite party can publish the response to. For SMOKER implementations, the broker must reject the publish message with a 0x83 Implementation specific error reason code if no response topic is present. Usually another client responds to the clients request - in this case the broker himself must respond the client requests directly.

The response topic must match the following pattern:

• restricted/{clientId}/claims

This requires the client to claim this response topic before requesting the claims to be able to subscribe to the response topic and receive the claim information. As this is the default claiming behaviour, the client is free to permit subscriptions to any other clients on his response topic.

The broker must publish the following information to the response topic:

• clientId The clientId which is involved
• ownedClaims All claims which are owned by the requesting client
• involvedClaims All claims where the client is allowed to publish or subscribe. Claims which deny the client to act on explicitly or via wildcard must be ignored.

3.3 - Client

Connection establishment

According to the authentication concepts, the client must proceed the following steps to be able to accept SMOKER connections:

1. Generate or read a valid ED25519 key-pair
2. Send a CONNECT packet with SMOKER as authentication method
3. If the nonce is received by the broker, the client must respond with another AUTH packet with the signed nonce within the authentication data

Generate or read key-pair

The client needs a ED25519 key-pair (see cryptography concepts) to authenticate himself to the broker. The client can either generate a new key-pair or use an existing one. The client is responsible for the key-management for himself. It is recommended to use implementations of libsodium for cryptographic operations.

Send CONNECT packet

To start the authentication flow, the client needs to send a CONNECT packet with the following properties set:

• Authentication method: SMOKER
• ClientId: Base32 (padded) representation of the public-key
• Protocol version: 5

Send AUTH packet

If the client receives the AUTH packet with the nonce from the broker, the client needs to sign it with its key-pair. This signature then needs to be sent back with another AUTH packet with the following properties set:

• Authentication data: the signature
• Reason code: 0x18 Continue authentication

Send a claim

To claim a topic the client needs to process the following steps:

• Setup a valid claim according to the contracts
  • Set up a valid restriction
  • Sign the created restriction and set up a valid claim
• Send the created claim to the broker by publishing a message to the access/claim topic with the JSON serialized claim in the message payload.

Note: It is highly recommended to publish claim messages with QoS 1 to be able to receive a PUBACK packet which contains further information about success or failures of the operation.

Send a unclaim

To unclaim a topic, the client needs to process the following steps:

• Send the unclaim by publishing a message to the access/unclaim topic with the topic name within the message payload.

Note: It is highly recommended to publish unclaim messages with QoS 1 to be able to receive a PUBACK packet which contains further information about success or failures of the operation.

Publish / Subscribe claimed topics

Claimed topics can simply be subscribed/published by the client using the standard MQTT procedures. The topic name must always be fully qualified (see restricted area). The broker must decide if a incoming MQTT operation is permitted or not, based on the claims it is holding from clients.

4 - References

[1] SMOKER - Client-managed anonymous authentication and authorization for MQTT, Lukas Läderach & Cédric von Allmen, January 2020

[2] SMOKER - How to Authenticate MQTT Sessions Without Channel- and Broker Security, Reto Koenig & Lukas Läderach & Cédric von Allmen, January 2020

[3] MQTT Version 5.0 Specification, Oasis, March 2019