Specification

• 1: Contract
• 2: Broker
• 3: Client

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"
    }
  ]
}

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 - 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.