janus

README

Janus

Janus uses Verifiable Credentials to add a new security layer over IoT devices and MQTT brokers. Providing a way to deploy and manage Aries agents on Iot Devices Through a CLI and ACA-py agents.

A Credential is issued to the IoT device with a list of sensors it is allowed to export data and a presentation proof of this credential is required before every sensor data transmission to the broker.

Table of Contents

1. Janus
2. Workflow
3. Usage
   1. Issuer and Controller
   2. Single Holder
   3. Multiple holders
4. Development

Workflow

The main workflow is based on three steps. The manual deploy of the agents using the CLI, the device provisioning, where the credentials will be issued and the sensor measurement with presentation proofs where the data is sent to the MQTT broker.

sequenceDiagram
    title: Full process
    autonumber

    participant user as janus-cli

    participant janus as janus-controller
    participant server as server-agent
    participant rasp as rasp-agent

    user ->> server: Deploy janus-issuer
    server -->> janus: Done
    user ->>+ rasp: Deploy janus-holder
    rasp -->>- janus: Done
    user ->> janus: Ask for device provision
    janus ->> server: Ask for an invitation
    server -->> janus: Created
    janus ->> rasp: Send invitation
    rasp -->> janus: Accepted
    janus ->>  rasp: Issue credential with permissions
    rasp -->> janus: Done
    janus -->> user: Done

    loop every x seconds
        janus ->> rasp: Ask for sensor measurements
        rasp -->> janus: Sent

        loop for each sensor
            janus ->> rasp: Ask for a presentation-proof with the sensor type
            rasp -->> janus: Sent
            janus ->> server: Validate presentation-proof
            server -->> janus: Validated
        end

        janus ->> janus: Send validated sensor measurements to the broker
    end

Usage

For more details about usage, such as the deployment of Sensor Collectors on the IoT device, and how to run our target MQTT broker, Dojot, see our Usage doc.

Important: Having Docker either in the host machine and IoT device is the only installation requirement of Janus.

Deploy an issuer agent and janus-controller

janus-cli deploy issuer 

Deploy a holder agent on IoT device

Note: A previously configured SSH key authentication between the host and IoT device is required for this step.

janus-cli deploy holder -H pi@192.168.0.1

POST http://localhost:8081/provision HTTP/1.1
content-type: application/json

    {
        "deviceHostName": "pi@192.168.0.6",
        "permissions": ["temperature", "humidity"],
        "brokerIp": "192.168.0.12",
        "brokerUsername": "admin:e72928",
        "brokerPassword": "admin"
    }

Deploy multiple hosts by config file

default: # Default values will be set on agents blank fields.
  sensors:
  - temperature
  - humidity
  broker:
    ip: "127.0.0.1"
    username: "admin"
    password: "admin"
agents:
  - hostname: pi@192.168.0.1
    sensors:
      - humidity
    broker:
      id: "800a9f"
  - hostname: pi@192.168.0.2
    broker:
      id: "e72928"

janus-cli deploy holder -F ./agents.yaml -p

-p refers to auto-provisioning if the janus-controller is already running

Need more help using it?

For more details about the CLI use -h flag to get some help:

janus-cli -h
janus-cli deploy -h

Development

Janus was developed using go 1.20, Docker 20.10.24 and relies over ACA-py agents and docker automation. For diagrams and more details about the implementation, check here.

Before starting working it's required to run go generate ./... so the docker files will be copied to the corresponding directories, required for the docker automation.

For building the application use Make with the command make build-cli. This will generate binaries for Linux, Mac and Windows on /bin folder.