Introduction

As described in the Wirepas Massive Concept document [1] different parameters are available in Wirepas Massive to ensure device identity and network isolation. For obvious security reasons devices are usually provisioned to belong to a given network to ensure proper device isolation and security. This way a node installed or flashed with different parameters won’t be able to join an existing network. 

For most use cases network parameter configuration during production is not an option as the device manufacturer is not the network owner and manager. In addition, customization during manufacturing can add a lot of unnecessary complexity to the supply chain. 

This document describes the different strategies available for device provisioning in a typical Wirepas Massive network. Two strategies are described:

• In-band provisioning: using the Wirepas network.
• Out-of-Band provisioning: using methods not linked to Wirepas Massive itself, e.g. NFC, BLE beaconing

What you'll learn

• The different options available for node provisioning
• How the Wirepas In-Band provisioning works

What you’ll need

• Basic knowledge of Wirepas Massive from the Wirepas Massive Concept document [1]

Wirepas In-Band provisioning

This provisioning uses the Wirepas Open Joining feature to provision new devices via the existing and secured Wirepas Massive network. In a nutshell, the Wirepas Open Joining allows a new node (called the “Joining Node”) to establish a peer-to-peer communication with an already provisioned and connected node (called a “Proxy Node”). This peer-to-peer communication only allows a Joining Node to communicate with an existing node without any interaction with the rest of the network. Both the Joining Node and the Proxy Node are then running a provisioning library that defines the protocol to make a joining request and in return securely receive the network parameters.

This provisioning method allows for a zero interaction installation, which makes the device provisioning fully transparent and automatic to the installer.

The diagram below describes the typical provisioning flow between a provisioned network and a Joining node.

Wirepas Provisioning process

The Wirepas Network Provisioning is developed on top of the open joining to enable nodes to be provisioned to the Wirepas network. The Wirepas Network Provisioning is coming as a set of libraries in the Wirepas SDK and can be used to enable two different provisioning strategies:

• Remote Provisioning, where joining requests are centrally managed in a backend server, typically in the cloud.
• Local Provisioning, where joining requests are managed locally in the network nodes. This removes the requirement for a backend server (the Local Provisioning is only supported in Wirepas Massive v5.2 and above).

The Wirepas Network Provisioning supports the following features:

• Allows to provision all Wirepas Network and device parameters.
• Allows to extend the provisioning to also include application parameters using a configurable provisioning packet.
• Supports device UUID independent from the Device address (or the future one) for device unicity.
• Supports provisioning packet encryption using pre-shared keys in devices.

The following diagram describes the typical flow:

The Open Joining protocol is responsible for transmitting the Joining Beacons, transferring the network parameters and the security keys from an existing device to the Joining Node. The Joining Beacons are always transmitted on the pre-defined Joining Channel. Wirepas Provisioning is responsible for making the decision regarding which device can join / can not join the network. 

The next sections describe the Remote and Local provisioning.

Remote Provisioning

Remote Provisioning is designed to be used if the system consists of devices from multiple vendors. With Remote Provisioning, it can be verified one-by-one, which nodes are allowed to join the network.

In Remote Provisioning, the joining request from a Joining Node flows to a gateway and thus to the backend. The Proxy Nodes in the network simply relay the joining messages but they do not do anything with them. It is then decided at the gateway/backend/application if a certain device is allowed to join the network or not.

The diagram below describes the Remote Provisioning flow assuming the Open Joining has been previously enabled in the networks.

The diagram below describes the different messages sent during the Remote Provisioning process

When the backend receives the START message it must decide if this certain node can join the network. The decision can be based on the address of the device or some other parameter. The start packet may include some application-specific data. The backend then responses to the network with NACK (if the device is not allowed to join) or a DATA packet that includes the network (and optionally application) parameters (when allowed to join).

 Because all decisions related to a joining request are handled in the backend, the Remote Provisioning solution is well suited for:

• Multi-vendor device provisioning with different devices having different pre-shared keys.
• Device Whitelisting to only allow some specific devices to join a given network.
• Provisioning individual device parameters, typically for the application.
• Managing several networks with one provisioning server.

The Remote Provisioning requires the following points of attention:

• The Remote Provisioning requires 3 packets per provisioning (2 uplinks and 1 downlink) which shall be taken into account (especially in the case of mass provisioning).
• The Remote Provisioning may take some time in the case of Low Energy (LE) networks as the latency can be up to 8 seconds per hop. The total round trip may take several tens of seconds depending on the number of hops.
• During the provisioning process, the Joining Node must remain connected to the Proxy Node as there is a peer-to-peer connection (only between the Joining Node and Proxy Node).

Local Provisioning

Local Provisioning reuses the concepts described in the Remote Provisioning. However, the decision regarding which device is allowed to join the network is done locally in the Proxy Node. Local Provisioning supports security to encrypt the provisioning messages using pre-shared keys. It makes the Local Provisioning well suited for systems where there is no need for a central provisioning server to validate, which device is allowed to join the network. 

NOTE: The Local Provisioning is only supported in Wirepas Massive v5.2 and above.

Local Provisioning is controlled using shared AppConfig data used to enable/disable and configure the provisioning. Any node being a router or a sink can act as a proxy node (Sinks are configured via the dual MCU API). The exception here are Subnodes (aka non-router nodes) which can’t act as Proxy Nodes.

In Local Provisioning:

• The Local Provisioning is enabled by setting a shared AppConfig data to enable local provisioning. This triggers all routers and sinks to start the Open Joining Beacons.
• The Joining node scans for the Joining Beacons and selects automatically the best candidate to initiate a connection.
• The Joining node then sends a joining request to the proxy node.
• The Proxy node sends back the provisioning packet, encrypted using the pre-shared key (configurable via AppConfig).
• If the Joining node is able to decrypt it (meaning the Pre-shared key matches) then the Joining node applies parameters and reboots.
• The Joining node then joins the network and can act as a Proxy node if the joining is still enabled in the shared AppConfig and node is a router. 

Because all decisions related to a joining request are locally managed the Local Provisioning solution is well suited for:

• A fairly closed system where all devices are from the same vendor, as the security relies on more global pre-shared keys.
• No device whitelisting is required
• Individual device application parameters are not required to be set during the network provisioning. Application parameters can still be set afterward (when node is connected to the network) by application requesting those from backend.

Local Provisioning requires the following points of attention:

• The recommendation is to enable Local Provisioning only during new device installation (as this is controlled via the AppConfig) and this shall be controlled on ALL sinks from the backend.
• As the security relies on pre-shared keys, only one pre-shared key can be set at a time. Thus all the devices shall have the same key or devices with different keys must be provisioned in separate batches
• The provisioning process may take around 30 seconds per device depending on network configuration.

Out-of-Band Provisioning

Out-of-Band provisioning relies on an external link between a provisioning device and a Joining Node. In this scenario, the device is typically using another interface (e.g. NFC) to receive its parameters from another device (e.g from a mobile phone or from a PC).

Compared to Wirepas Network-based provisioning, Out-of-Band provisioning requires an operation external to the network to program the network parameters into the device. As well as in the Wirepas Network-based provisioning, both the Wirepas Network parameters and the application parameters can be configured using Out-of-band provisioning. Additional security can be added to this to ensure secured provisioning of the system.

Out-of-Band provisioning does not require any specific feature of Wirepas Massive. Because of the large variety of interfaces and scenarios Wirepas does not provide any reference library to support Out-of-Band provisioning.

References

[1] Wirepas Massive Concepts

Revision History

Legal Notice

Use of this document is strictly subject to Wirepas’ Terms of Use and Legal Notice.

Copyright © 2021 Wirepas Oy