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.