ubimqtt

Mqtt conveniecy library for using the Ubikampus Mqtt bus. Supports publishing signed content on Mqtt (ES512 signatures only!), subscribing to content signed by a given keypair, and subscribing to content signed by a known publisher whose public key can be found on the Mqtt bus itself.

The signature format is JWS JSON, but the payload is unconventionally publised on Mqtt in the format output by JSON.stringify() without Base64 encoding to keep string payloads human-readable on-the-wire.

Install using npm

npm install ubimqtt

Generate a keypair for testing

mkdir -p ~/.private
# ES512
# private key
openssl ecparam -genkey -name secp521r1 -noout -out ~/.private/ubimqtt-testing-key.pem
# public key
openssl ec -in ~/.private/ubimqtt-testing-key.pem -pubout -out ~/.private/ubimqtt-testing-key-public.pem

Example usage

var UbiMqtt = require("ubimqtt");

var fs = require("fs");
var homedir = require('os').homedir();

var logger = console;


var privateKey= fs.readFileSync(homedir+"/.private/ubimqtt-testing-key.pem");
var publicKey= fs.readFileSync(homedir+"/.private/ubimqtt-testing-key-public.pem");

var mqtt = new UbiMqtt("mqtt://localhost:1883");

mqtt.connect(function(error)
    {
    if (error)
        logger.error(error);

    var onMessage = function(topic, message)
        {
        logger.log("Message received from mqtt server: {topic: \""+topic+"\",message: \""+message+"\"}");
        mqtt.disconnect(function(err)
            {
            if (!err)
                logger.log("Disconnected from Mqtt server");
            });
        };
    mqtt.subscribeSigned("test/test", publicKey, this, onMessage, function(err)
        {
        mqtt.publishSigned("test/test", "testmessage", null, privateKey, function(err)
            {
            if (!err)
                logger.log("Publication made");
            else
                logger.log("Publishing failed: "+err);
            });
        });
    });

Do not edit this README.md file directly, it is autogenerated from the template file README.hbs. Edit the template file README.hbs instead.

To generate this README.md file, execute:

npm run jsdoc

Api documentation

UbiMqtt

Kind: global class

• UbiMqtt
  • new UbiMqtt(serverAddress, [options])
  • .connect(callback)
  • .disconnect(callback)
  • .forceDisconnect(callback)
  • .publish(topic, message, opts, callback)
  • .publishSigned(topic, message, opts, privateKey, callback)
  • .subscribe(topic, obj, listener, callback)
  • .subscribeSigned(topic, publicKeys, obj, listener, callback)
  • .subscribeFromPublisher(topic, publiserName, obj, listener, callback)

new UbiMqtt(serverAddress, [options])

Class for signed Mqtt communications at Ubikampus

| Param | Type | Description | | --- | --- | --- | | serverAddress | string | the Mqtt server to cennect to | | [options] | object | | | [options.silent] | boolean | do not print logs |

ubiMqtt.connect(callback)

Connecs to the Mqtt server the address of which was given as a constructor parameter

Kind: instance method of UbiMqtt

| Param | Type | Description | | --- | --- | --- | | callback | function | the callback to call upon connection or error |

ubiMqtt.disconnect(callback)

Disconnects from the Mqtt server

Kind: instance method of UbiMqtt

| Param | Type | Description | | --- | --- | --- | | callback | function | the callback to call upon successful disconnection or error |

ubiMqtt.forceDisconnect(callback)

Immediately disconnect without waiting for ACKs. If called before bus connection is established, connection is canceled.

Kind: instance method of UbiMqtt

| Param | Type | Description | | --- | --- | --- | | callback | function | called when disconnect succeeds |

ubiMqtt.publish(topic, message, opts, callback)

Publishes a message on the connected Mqtt server

Kind: instance method of UbiMqtt

| Param | Type | Description | | --- | --- | --- | | topic | string | the Mqtt topic to publish to | | message | any | the message to publish | | opts | object | the options to pass to node-mqtt | | callback | function | the callback to call upon success or error |

ubiMqtt.publishSigned(topic, message, opts, privateKey, callback)

Publishes a signed message on the connected Mqtt server

Kind: instance method of UbiMqtt

| Param | Type | Description | | --- | --- | --- | | topic | string | the Mqtt topic to publish to | | message | any | the message to publish | | opts | object | the options to pass to node-mqtt | | privateKey | string | the private key in .pem format to sign the message with | | callback | function | the callback to call upon success or error |

ubiMqtt.subscribe(topic, obj, listener, callback)

Subscribes to a Mqtt topic on the connected Mqtt server

Kind: instance method of UbiMqtt

| Param | Type | Description | | --- | --- | --- | | topic | string | the Mqtt topic to subscribe to | | obj | any | the value of "this" to be used whan calling the listener | | listener | function | the listener function to call whenever a message matching the topic arrives | | callback | function | the callback to be called upon successful subscription or error |

ubiMqtt.subscribeSigned(topic, publicKeys, obj, listener, callback)

Subscribes to messages signed by particular keypair on a Mqtt topic on the connected Mqtt server

Kind: instance method of UbiMqtt

| Param | Type | Description | | --- | --- | --- | | topic | string | the Mqtt topic to subscribe to | | publicKeys | Array.<string> | the public keys of the keypairs the messages need to to be signed with. Only messages signed with these keypairs will invoke the listener | | obj | any | the value of "this" to be used whan calling the listener | | listener | function | the listener function to call whenever a message matching the topic and signed with the publicKey arrives | | callback | function | the callback to be called upon successful subscription or error |

ubiMqtt.subscribeFromPublisher(topic, publiserName, obj, listener, callback)

Subscribes to messages on a Mqtt topic on the connected Mqtt server signed by a known publiser The public key of the publiser is used for recognizing the messages originating from the publisher. The public key of the publisher is fetched from the Mqtt topic publishers/publishername/publicKey and kept up-to-date with the help of a regular Mqtt subscription

Kind: instance method of UbiMqtt

| Param | Type | Description | | --- | --- | --- | | topic | string | the Mqtt topic to subscribe to | | publiserName | string | the name of the known publisher | | obj | any | the value of "this" to be used whan calling the listener | | listener | function | the listener function to call whenever a message matching the topic and signed with the publicKey arrives | | callback | function | the callback to be called upon successful subscription or error |

© 2019 University Of Helsinki