broker is a MQTT broker.

broker has Boost.ProgramOptions style options. https://github.com/redboltz/async_mqtt/blob/main/tool/broker.conf is config file. You can also set command line options. The command line options are higher priority than file options.

broker has json like authenticate/authorize file. https://github.com/redboltz/async_mqtt/blob/main/tool/auth.json is an example file.

broker supports MQTT on TCP, TLS, WebSocket, and WebSocket on TLS. They can be mixed. broker supports MQTT v3.1.1 and v5.0. They can be mixed. broker can deliver packets between the different MQTT version clients. The packet is converted from/to v3.1.1 to/from v5.0.

authentication and authorization

https://github.com/redboltz/async_mqtt/blob/main/tool/auth.json helps understanding the following descriptions:

authentication

broker has user concept. user means authentication and authorization unit. One user could have multiple MQTT connections if Client Identifier is different. If user and Client Identifier is the same, the connections and sessions regard to the same. The same online connection exists and then the same new connection is authenticated, the previous one is disconnected by the broker. It is overwrite model that is required by MQTT spec.

broker supports the following authentication method.

name filed is correspondint to user.

sha256

  • name

    • User Name in MQTT CONNECT packet.

  • method

    • Set "sha256"

  • salt

    • salt for generating sha256 digest

  • digest

    • Hexadecimal string of sha256(salt+password)

client certification

  • name

    • User Name in the client certification

  • method

    • Set "client_cert"

The client needs to set its name to the CN field of the client certification. The filed can be changed using the broker option --verify_field. Don’t set User Name and Password in MQTT CONNECT packet.

plain password

  • name

    • User Name in MQTT CONNECT packet.

  • method

    • Set "plain_password"

  • password

    • Password string.

anonymous

  • name

    • Set "anonymous"

  • method

    • Set "anonymous"

If anonymous is appeared in authentication field, then the client that doesn’t have User Name and Password in MQTT CONNECT packet can be authenticated. That doesn’t mean empty string.

unauthenticated

  • name

    • Set "unauthenticated"

  • method

    • Set "unauthenticated"

If the client is unauthenticated, and if the authentication filed has this method, then the client can be connected. In this case, the connection’s User Name is regard to one special "unauthenticated" name (not actual "unauthenticated" string).

group

group is convenient concept to sum up user`s. The name of `group starts with @.

authorization

authorization is a concept that granting publish/subscribe to the topics to `user`s or `group`s.

  • topic

    • Target topic to grant. Not only a topic name but also MQTT’s multi-level wildcard # can be used to specify topics.

  • allow

    • Add permissions to the specified target topic for `user`s and `group`s

  • deny

    • Remove permissions to the specified target topic for `user`s and `group`s

The permissions evaluates the top to bottom of the file. So recommended style is first, declaring widly permissions using # at the top side of authorization fileds, and then declaring specific topic’s permissions. In other words, the recommended order is wide to narrow.