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