ark-broker

This reposiory is a modification of hbmqtt. It improves security on subcription or publication and provides an easy way to bridge the IOT broker with a powered by Ark blockchain.

Support this project

Buy Ѧ and:

• Send Ѧ to AUahWfkfr5J4tYakugRbfow7RWVTK35GPW
• Vote arky on Ark blockchain and earn Ѧ weekly

Install

Linux

$ bash <(curl -s https://raw.githubusercontent.com/Moustikitos/hbmqtt/master/ark-broker/install-ark-broker.sh)

This installation script will manage dependencies and virtual environement needed to run ark-broker.

Windows

pip install git+https://github.com/Moustikitos/hbmqtt.git

Configure / check

Broker configuration is done in a yaml file, you can edit it with a simple text editor.

linux

yaml file is stored into user configuration folder.

$ nano $HOME/.config/ark-broker.yaml

On unix system, ark-broker is set as a linux service. It responds to journalctl and systemctl commands:

# check broker log
$ sudo journalctl -u ark-broker -ef
# start|stop|restart broker
$ sudo systemctl (start|stop|restart) ark-broker
# activate|desactivate broker on server startup
$ sudo systemctl (enable|disable) ark-broker
# check broker service
$ sudo systemctl status ark-broker

Configure ark-broker unit file:

$ sudo nano /etc/systemd/system/ark-broker.service
...
$ sudo systemctl daemon-reload
$ sudo systemctl restart ark-broker

Windows

Download yaml configuration file and use hbmqtt command:

hbmqtt -c full\path\to\ark-broker.yaml

secp256k1 connection

Asymetric encryption provides an easy way to trust data with ownership verification. Because MQTT protocol is designed to be simple and efficient, best way to secure IOT broker connections with any device is to be guaranted of device genuinity.

Configuration

Genuine connection is set with yaml configuration:

auth:
    plugins:
    # auth_ecdsa: mandatory plugin to activate genuine check
    - auth_ecdsa
    # restricted-puk: not mandatory (default: false)
    # only public keys found in 'puk-file' are allowed to connect on secp256k1
    # reserved topics.
    restricted-puk: true
    # puk-file: not mandatory, used to restrict access.
    # file line format:
    #     secp256k1.puk:<hex_string_encoded_public_key>
    puk-file: full/path/to/puk.file
...
topic-check:
    # enable: mandatory to activate subscrition
    enabled: true
    plugins:
    # topic_ecdsa : mandatory plugin to activate subscription restrictions
    - topic_ecdsa
    ecdsa-roots:
    # ecdsa-roots: restricted topics to genuine subscribers
    - blockchain/
...

Use

To subscribe and publish with secp256k1 genuine connection, use --ecdsa or --schnorr option available with hbmqtt_pub and hbmqtt_sub commands.

$ hbmqtt_pub --help
$ hbmqtt_sub --help

Bridge concept

Listening

Listening is set with yaml configuration:

auth:
    ...
    plugins:
    # broker_bc: mandatory plugin to activate the bridge
    - broker_bc
...
broker-blockchain:
    # nethash: not mandatory if only GET requests are sent by broker
    nethash: 6e84d08bd299ed97c212c886c98a57e36545c8f5d645ca7eeae63a8bd62d8988
    # peers: mandatory, at least one valid peer is needed
    peers:
    - https://explorer.ark.io:8443
    # bridged-topics: mandatory
    #   topic: [module=None, function]
    #   if module is None: use plugin instance function
    #   else if module loaded on plugin initialization: use module.function
    bridged-topics:
        blockchain/event: [null, dummy]
    # endoints: not mandatory
    #   name: [method, path]
    endpoints:
        configuration: [GET, /api/node/configuration]
        post_transactions: [POST, /api/transactions]

Bridged topics are listed in bridged-topics field of the yaml config. They are stored in an hbmqtt plugin as python dictionary, topic as keys, module-function pair as value. Modules are imported on plugin initialization as the broker starts. if a module is not found, ImportError exception is ignored and associated topic is removed.

Once a message is received on a bridged topic, even if there is no subscription, module.function is called with plugin itself and genuine data provided by plockchain (when module is None, the function is found in the plugin). Genuine data is either a transaction (dict) or a block (dict).

Python function interface

def function(plg, data):
    pass

plugin interface

# hbmqtt context
plg.context
# `broker-blockchain` part of yaml conf as python dict
plg.config
# `endpoints` part of yaml conf as key list
plg.endpoints
# awaitable blockchain request
#   - endpoint: either a valid path ('/api/transactions') or a value from plg.endpoints
#   - data: dict or list for HTTP request with body
#   - qs: keyword argument to add a query string to the url
await plg.bc_request(endpoint, data={}, **qs)

API interface

Relaying is set with yaml configuration:

auth:
    ...
    plugins:
    # bc_api: mandatory plugin to activate the api
    - bc_api
    # auth_anonymous : mandatory for blockchain response
    - auth_anonymous
    allow-anonymous: true
...
broker-blockchain:
    # nethash: mandatory for HTTP POST requests
    nethash: 6e84d08bd299ed97c212c886c98a57e36545c8f5d645ca7eeae63a8bd62d8988
    # peers: mandatory, at least one valid peer is needed
    peers:
    - https://explorer.ark.io:8443