Catenis Flow Guide

Set Permission Rights Node

The “Set Permission Rights” node sets the permission rights for a specific permission event on the subject virtual device (the virtual device issuing the request). All permissions are set from the perspective of the virtual device issuing the request (we refer to this virtual device as the subject or controlling virtual device). The subject controls its own permissions as to whether or not any other device(s) have the capacity to perform a permissioned event with it.  Permission events are specific actions that can be set to either “allow” or “deny” at four different levels.

How Permissions Work for Decentralized Systems

The Catenis permission system was envisioned and built to protect   decentralized applications and devices. To handle permissions on the decentralized open public Bitcoin blockchain Catenis creates the virtual equivalent of a shield or force field that can be set on the devices you control. This is  because Catenis does not control the global Bitcoin blockchain and is unable to keep a random transaction from being sent to any address across the blockchain. Therefore, Catenis shields any unauthorized transactions from ever reaching any device across our network and manages  permissions for devices which are under your control. This is why permissioned events are set on the “subject” or “controlling” device. The subject device is the device you control and when setting permission for a given event you are allowing or denying your subject device to receive events. 

Catenis blocks any unwanted events from ever reaching your device. As an example: If you control virtual device A and set the permission event “receive-msg” to “allow” for device C and “deny” for all other devices, it means that random devices can still attempt to send a message to device A (costing them a network fee and a Bitcoin amount above dust [bare minimum value that can be sent]) but device A will never receive it unless it came from device C. Catenis effectively creates a force field around each device from within its own network and completely shields from systems connected to the Bitcoin blockchain outside it’s network. 

Permission Rights Levels

All rights across permission events can be set at four levels; permission events can be set to either “allow”, “deny” or once set they can be “unset” or “cleared”. The System Level is unique because permissions can only be toggled from “allow” to “deny” or vice versa. The permission at this level  cannot be cleared. Setting permission rights at a higher level will affect how all virtual devices within the context of that level and levels below  can or cannot interact with the subject device. For example, permissions set at the node level will affect all devices across all clients within that node if there are no other, more granular permissions set. 

  1. System Level: controls permissions rights across the entire Catenis network where the default permission rights are defined.
  2. Catenis node Level: controls the permission rights for all devices that belong to all clients defined for that Catenis node. Catenis nodes are computers referred to as either “hubs” or “gateways”.  Each hub or gateway has a specific index number. If you are using our cloud implementation the index number is always 0 .
  3. Client Level: controls the permission rights for all devices that belong to this client. Clients are Catenis system entities within a Catenis node.  A hub or gateway for instance may have one or more clients.
  4. Virtual Device Level: controls the permission rights for specific virtual device.

How Permissions are Evaluated

Setting permission rights at a higher level will affect how all virtual devices within the context of that level and levels below  can or cannot interact with the subject device. For example, permissions set at the node level will affect all devices across all clients within that node. However, the system evaluates permissions giving precedent to  the more granular virtual device levels over the very broad system level. The system first looks to see if a device is allowed or denied permission for a premissoned event. If there are no permissions set then it evaluates the next level which is the Client level, then the Catenis node level, and finally the System level. Keep in mind that within this hierarchy  it is possible to set what seems to be (yet are not) conflicting permissions. This is because permissions that are set at a more granular level will always override what is set at a higher level

Let’s review an example: You may set the “receive-asset-from” permission event for virtual device A to “deny” for all devices at the Catenis node Level. This means virtual device A will not be able to receive any assets from any device that is part of that Catenis node.  However, if you had previously set the same “receive-asset-from” permission event for virtual device B at the Virtual Device Level to “allow”, then device A will be allowed to receive assets from device B even though device B is part of the same Catenis node you recently denied access to all devices. Always review granular permissions for each event before setting permissions broadly. If ever in doubt use the “check effective permission right” node using the subject device to connect and supplying the the device ID of the device that is attempting to execute a permission event with the subject device.

Image of the Set Permission Rights Node

Node Properties Panel Field Description

Node property configuration slide-out panel (this panel is accessed by double-clicking on the node).

2020-07-28_10-19-57
Properties Configuration Panel of the Set Permission Rights Node

Node-RED Specific Fields

  1. Name Field:  Add a descriptive name of your choice that will help differentiate this node from others of the same type on the Node-RED workspace (not required).
  2. Connection Field: This drop-down selection is required.  Set a previously configured Catenis connection (virtual device). If you need to configure a new virtual device click the pencil button to the right of the field and follow the direction on setting up a new virtual device that can be found here.

Catenis Flow Setting Fields

  1. Event: from the dropdown list select the permission event for which you wish to set permissions for (Required). Options include
    1. receive-notify-new-msg: Receive notification of new message from a device
    2. receive-notify-msg-read: Receive notification of message read by a device
    3. receive-notify-asset-of: Receive notification of asset received for assets issued by a device
    4. receive-notify-asset-from: Receive notification of asset received from a device
    5. receive-notify-confirm-asset-of: Receive notification of confirmation of pending asset issued by a device
    6. receive-notify-confirm-asset-from: Receive notification of confirmation of pending asset transferred by a device
    7. send-read-msg-confirm: Send read message confirmation to a device
    8. receive-msg: Receive message from a device
    9. disclose-main-props: Disclose device’s main properties (name, product unique ID) to a device
    10. disclose-identity-info: Disclose device’s basic identification information to a device
    11. receive-asset-of: Receive an amount of an asset issued by a device
    12. receive-asset-from: Receive an amount of an asset from a device
  2. System right: This controls the “Allow” or “Deny” permission rights that you will be applying to the permission event you select. Permissions are always applied to the subject device allowing or denying other devices to interact with it based on whichever permission event it is set to.
  3. Allowed Catenis Node Indices: Set allow access to a given permission events across all Catenis nodes that are listed in this field. Catenis nodes can be either a Hub or a gateway. If you are using our Cloud offering your Catenis node index will always be zero “0”. The special value “self” can be used in place of the index of the Catenis node where the client to which the virtual device issuing the request belongs to is defined.
  4. Allowed Catenis Node Indices: Set deny access to a given permission events across all Catenis nodes that are listed in this field. Catenis nodes can be either a Hub or a gateway. If you are using our Cloud offering your Catenis node index will always be zero “0”. The special value “self” can be used in place of the index of the Catenis node where the client to which the virtual device issuing the request belongs to is defined.
  5. Clear Catenis Node Indices: This clears any previously sets permissions for a given permission event at the Catenis node Level. The special value “self” can be used in place of the index of the Catenis node where the client to which the virtual device issuing the request belongs to is defined. The special wildcard character * can also be used to indicate that the rights for all Catenis nodes should be removed.
  6. Allowed Client IDs: Each Catenis node (hub or gateway) can have many clients.  A client is a structural unit within a Catenis node. You can specify the clients across a node that are allowed the permissioned event by listing each client ID. The special value “self” can be used in place of the client ID of the client to which the virtual device issuing the request belongs to.
  7. Denied Client IDs: Each Catenis node (hub or gateway) can have many clients.  A client is a structural unit within a Catenis node. You can specify the clients across a node that are denied the permissioned event by listing each client ID. The special value self can be used in place of the client ID of the client to which the virtual device issuing the request belongs to.
  8. Clear Client IDs: This clears any previously set permissions for a given permission event at the Catenis node Client Level. The special value “self” can be used in place of the client ID of the client to which the virtual device issuing the request belongs to. The special wildcard character * can also be used to indicate that the rights for all clients should be removed.
  9. Allowed Device IDs: Set allow access to a given permission events across all Catenis Devices that are listed in this field. Separate each ID with a comma. The special value “self” can be used in place of the device ID of the virtual device issuing the request.
  10. Allowed Device product unique ID: Set allow access to a given permission events across all Catenis Devices that use a product unique ID in this field.  Separate each ID with a comma. The special value “self” can be used in place of the device ID of the virtual device issuing the request.
  11. Denied Device ID: Set deny access to a given permission events across all Catenis Devices that are listed in this field. Separate each ID with a comma. The special value “self” can be used in place of the device ID of the virtual device issuing the request.
  12. Denied Device product unique ID: Set allow access to a given permission events across all Catenis Devices that use a product unique ID in this field.  Separate each ID with a comma. The special value “self” can be used in place of the device ID of the virtual device issuing the request.
  13. Clear Device ID: Clear all previous permissions that you have previously set for a given permission event using Device IDs. The special value “self” can be used in place of the device ID of the virtual device issuing the request. The special wildcard character * can also be used to indicate that the rights for all devices should be removed.
  14. Clear Device Product Unique ID: Clear all previous permissions that you have previously set for a given permission event using a Device  product unique IDs. The special value “self” can be used in place of the device ID of the virtual device issuing the request. The special wildcard character * can also be used to indicate that the rights for all devices should be removed.

How to use

  1. Drag and drop this node from the Catenis Flow pallet area to the Node-RED workspace. Double click it to display its properties slide out panel.
  2. On the “Device” drop-down field of the properties slide out panel choose the Catenis virtual device you previously configured. The virtual device is a configuration node containing the Catenis Virtual device information (device ID and API Secret key). This should be the controlling device (the device for which you want to receive permission event rights for).
  3. Click on the “🔔 Event” drop-down menu and then select the event for which you wish to set event permissions rights for.
  4. On the “System Rights” drop-down field select either Allow or Deny based on which right you want to set.
  5. Wire this node to a debug node if you wish to see the output of the node printed on the debug sidebar. Otherwise, the output from this node can be passed into another node on this flow. 
  6. Next, drag and drop an “inject” node to the Node-RED workspace.
  7. Wire the “inject” node to the  “Set Permissions Rights” node, then double click the “inject” node to open its properties slide out panel. 
  8. Alter the information in the “inject” node’s properties slide out panel by selecting the drop-down “Payload” field and choose the “JSON” Type. An Ellipse button “…” will appear to the right of the field. Click this ellipse button to display a JSON edit box. 
  9. Enter the JSON information you wish to pass as input to the Catenis node (an example JSON input is below). After entering your JSON text entry click the red Done button. Then click the Done button again to exit the properties dialogue box.
  10. Click the red Deploy button on the upper right hand side of the Node-RED dashboard to deploy this flow.
  11. Now let’s test the flow: Click the button on the left attached to the “inject” node to send the input from the “inject” node to the flow.
  12. The debug sidebar should display the returned JSON object containing the API call results to the right side of the workspace.

How to use Interactively

  1. Drag and drop this node from the Catenis Flow pallet area to the Node-RED workspace. Double click it to display its properties slide out panel.
  2. On the “Device” drop-down field of the properties slide out panel choose the Catenis virtual device you previously configured. The virtual device is a configuration node containing the Catenis Virtual device information (device ID and API Secret key).
  3. Click on the “🔔 Event” drop-down menu and then select the event for which you wish to set event permissions rights for.
  4. Set the rest of the properties field according to the permission event properties you wish to set permissions for. 
  5. Wire this node to a debug node.
  6. Click the red “Deploy” button on the upper right hand side of the Node-RED dashboard to deploy this flow. 
  7. To test the flow: click the square gray box to the left of the “list permission events” node. A JSON object containing all possible permission events should now be printed onto the debug sidebar.

Example JSON Object that can be passed to this node


{
    "eventName": "receive-msg",
    "rights": {
        "device": {
            "allow": [
                {
                    "id": "self"
                },
                {
                    "id": "xyz12341235123",
                    "isProdUniqueId": true
                }
            ]
        }
    }
}


Note: Inputs injected into this node via a JSON object containing alternate node properties will override the properties set on this node's slide-out properties panel.

Example Flow - Import Into Node-Red to Get Started


[{"id":"4997c8e3.587ca8","type":"set permission rights","z":"de9ae5f3.3e8108","name":"","device":"","eventName":"receive-notify-new-msg","sysRight":"allow","allowCtnNodeIndices":"","denyCtnNodeIndices":"","noneCtnNodeIndices":"","allowClientIds":"","denyClientIds":"","noneClientIds":"","allowDeviceIds":"","denyDeviceIds":"","noneDeviceIds":"","allowProdIds":"","denyProdIds":"","noneProdIds":"","x":517,"y":140,"wires":[["14203907.469ec7"]]},{"id":"14203907.469ec7","type":"debug","z":"de9ae5f3.3e8108","name":"","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"false","x":790,"y":140,"wires":[]},{"id":"cdf5c320.b6427","type":"inject","z":"de9ae5f3.3e8108","name":"","topic":"","payload":"{\"eventName\":\"disclose-main-props\",\"rights\":{\"device\":{\"allow\":[{\"id\":\"self\"},{\"id\":\"Enter client ID you wish to allow here\",\"isProdUniqueId\":false}]}}}","payloadType":"json","repeat":"","crontab":"","once":false,"onceDelay":0.1,"x":90,"y":140,"wires":[["4997c8e3.587ca8"]]},{"id":"b5ac92d9.3c5bb","type":"comment","z":"de9ae5f3.3e8108","name":"Set virtual device for this Catenis node","info":"All Catenis nodes require that you set the proper virtual device on its slideout property panel on the device field.\n\nNot setting the device properly will result in a \"TypeError: Cannot read property 'ctnApiClient' of null\" ","x":542,"y":101,"wires":[]},{"id":"82fe59f5.cb69b8","type":"comment","z":"de9ae5f3.3e8108","name":"Double click for instructions","info":"Enter the desired client ID in this JSON object","x":123,"y":100,"wires":[]}]

Note: After importing this flow you will need to set the Catenis Flow node(s) in this flow to use a previously configured virtual devices. Instructions on how to set up your virtual device on Node-RED can be found here: https://blockchainofthings.com/docs/configure-your-first-virtual-device-on-catenis-flow/

Related Articles

CompanyElement_SM_LightBackgrounds
How can we make things Better for you?
  • Accepted file types: jpg, gif, png, pdf.
  • This field is for validation purposes and should be left unchanged.