Device provisioning

Device provisioning is the act of supplying each of your connected products with the code and credentials it needs to uniquely and securely identify itself to Xively, and operate smoothly on first time use in a customer's hands. Secure provisioning is an important design consideration for connected product systems.

Provisioning in a nutshell

Fully explained

The process involves:

  1. Defining devices in Xively
  2. Getting credentials for each device
  3. Flashing firmware onto each device
  4. Flashing credentials onto each device
  5. (Optional) Deliver new firmware over the air on boot-up or during everyday operation

Provisioning state
As devices pass through stages of the provisioning lifecycle, Xively automatically flags their provisioning state for easy management in the field called provisioningState that is searchable on any device.

The three states of provisioning that a device can be in are:

`provisioningState`
Description
Happens automatically when

defined

The device has been registered in Xively

device entity is first created in Xively (POST /devices)

activated

The provisioning process has begun, and the device's credentials have been retrieved

The first time a password is generated for the device (POST /access/mqtt-credentials). (Subsequent calls do not affect this state).

associated

The device has been claimed by an end-user in an autonomous association workflow

The first time an association code is used to move a device into a group. (Subsequent calls and password regenerations do not affect this state, it will remain listed as associated in both cases).

1. Define devices

Xively holds a record of the devices you intend to come online, based on their templates.

Providing that you have defined a device template from which all devices of this product line will inherit their custom fields and list of available MQTT channels (see Channels ) ...

There are two ways to define devices:

  1. In the Xively management app
  2. Via the Create a device endpoint

Either of these are a necessary first step to bringing the devices online. Some product manufacturers prefer to define devices long before they are manufactured, to gain the advantage of a searchable record of intended devices vs. number of live devices (or to match similar inventories in their ERP systems). Others prefer to define devices as a manual or automatic part of the manufacturing process - either is perfectly acceptable.

2. Get credentials

Credentials are retrieved for each device by calling the generate device credentials endpoint.

There are a few options for when to generate your devices' credentials:

  • Manually in the Xively management app, to work with test devices
  • Far in advance via the API, for loading into a system or table that will eventually be used to flash the devices
  • At the moment of manufacture via that API, often called directly by the test harness or programming rig that flashes the device with its firmware on an as-needed basis

The API call to Generate device credentials:

// An example call to retrieve device credentials

{
  "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
  "entityId": "e8df5e10-c041-4d52-8d9c-81c8a25dedee",
  "entityType": "device"
}

This call returns a parameter secret, which will be this device's password when connecting to the message broker.

// An example response ("secret" is the device's MQTT password)

{
  "mqttCredential": {
    "accountId": "f85e4fda-827d-46ff-9537-d4b453b27cde",
    "entityId": "e8df5e10-c041-4d52-8d9c-81c8a25dedee",
    "entityType": "device",
    "secret": "xiKZj2qcMXWgLC4kPnVCL+Js9PrYlvBCNOtaGyGxMYI="
  }
}

Passwords must be protected from disclosure. An attacker who obtained a device ID and password for a device can connect to the Xively platform as that device. Once connected, the attacker can publish messages as that device and subscribe to messages for that device. The impact of device impersonation depends on the application, and should be evaluated during application design.
Xively recommends provisioning devices during the manufacturing process.

Regenerating device credentials

The credential endpoint can be called multiple times for a device, but doing so will regenerate the device's password and invalidate its previous one. This is advantageous for testing and blocking potentially compromised devices, but can potentially leave your device bricked in the field if misused.

It is recommended that your firmware include a provision for manually flashing or entering new credentials into a device, if you can foresee scenarios in which they might be regenerated, leaving the device unable to communicate with Xively and update its firmware.

Ideally, the manufacturing process would be designed such that as devices are manufactured, calls are made to the API endpoints to create the devices and assign MQTT passwords (/devices and /access/mqtt-credentials). The password (referred to as the secret in the /access/mqtt-credentials endpoint) should be placed on the device and not stored elsewhere. The password must be specified by the device when it connects to the Xively broker, so the password must be stored in a manner where it can be read by device firmware/software.

If provisioning cannot be done in real-time as devices are manufactured, the platform API can be used by a custom script to obtain device IDs and passwords for a batch of serial numbers. These batches of credentials can then be transferred to a downstream manufacturing process for provisioning onto devices.

If provisioning cannot occur during manufacturing, and must occur when devices are already in possession of product users, the application will need to support a provisioning workflow. This is the least desirable option, as securing a provisioning workflow for devices already in the possession of users opens the door to provisioning and association attacks. These attacks can impact the integrity of the connected product system, and affect the ability of legitimate product users to use the product.

3. Get firmware onto the device

At this point in your manufacturing process, you need to flash each device with the firmware it will run on first activation. Standard manufacturing process would expect that each new device is tested by a fixture on the assembly line that will verify its basic functionality before its microcontroller is flashed with its operating firmware.

4. Flash credentials to devices

The credentials you attained in step 2, can now be flashed to each unique device for its use on wakeup.

// MQTT username
e8df5e10-c041-4d52-8d9c-81c8a25dedee

// MQTT password
xiKZj2qcMXWgLC4kPnVCL+Js9PrYlvBCNOtaGyGxMYI=

// Topics
// Be sure to include a config file in which the device's channels are described, so that it knows which to PUB/SUB to

5. Download latest firmware over the air

The final step of device updating sometimes occurs after installation in the device's final context, as an over-the-air (OTA) firmware update. The advantage of this route is that your manufacturing process can remain fairly consistent, while you develop new capabilities in device firmware that are delivered even after the device has been shipped. This simply requires that the device's boot process involves a call to Xively in which it checks for the latest firmware on first wakeup.

For more on how to deliver OTA firmware updates to devices in the field, see firmware updates.

A note on serial numbers

In the Xively platform, device identity is represented by a device ID, which is the UUID for the device assigned by the Xively platform when the device is created. Every device manufactured should be provisioned with a different device ID, so different instances of a product can be distinguished.

Device IDs are like serial numbers, except that device IDs are generated by the Xively platform and are universally unique. A business could use the device ID to uniquely refer to an instance of a product across its entire product line.

A serial number is assigned and managed by you, and may or may not be unique across your product line - Xively doesn't mind. Every device has a serialNumber field that provides a way to link the serial numbers you may use in your other systems with Xively device IDs, to allow applications to connect enterprise information based on serial number with information in the Xively platform.

Device provisioning