Contract

The description of the contract objects which must be used by the broker and the client.

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

Property	Type	Description	Mandatory
`signature`	`string`	A Base64 representation of the signed `Restriction`	Y
`restriction`	`Restriction`	The `Restriction`-Object which holds all relevant information about the topic that will be claimed	Y

`Restriction` properties

Property	Type	Description	Mandatory
`topicName`	`string`	The name of the topic that will be claimed. This topic must be prefixed with: `restricted/{clientId}/`	Y
`permissions`	`Permission[]`	A list of `Permission`-Objects. If no permissions are set, only the owner can interact on this topic.	N
`restrictionType`	`string`	The type of the restriction and how the permissions should be interpreted. Allowed values are: `WHITELIST` or `BLACKLIST`	Y

`Permission` properties

Property	Type	Description	Mandatory
`clientId`	`string`	A Base32 representation of a client ID of any other SMOKER client. A `*` can be used to include all clients.	Y
`activity`	`string`	The MQTT-Activity which this rule is activated on. Allowed values are: `PUBLISH`, `SUBSCRIBE` or `ALL`	Y

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