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.