Device Whitelist

Overview

Device whitelist service provides an extra layer of security when devices bootstrap in your account.

In order to claim ownership of a device and enable certain features and/or authorizations on a device at the time of bootstrap, a "Device Profile" is needed. To claim the device ownership, you have to generate a "DeviceProfileUID" and write it in the u-blox module using the proper AT command; you can do it a) remotely or b) during the production of your device. When the device bootstraps, the associated features and authorizations are provisioned on the device and the device is added to your account (see Getting started guide)

To avoid the misuse of your device profile by a malicious user you can use the whitelist functionality and enable the automatic feature provisioning only to those devices that have been registered in the whitelist.

How whitelist works

Using the whitelist APIs or the Thingstream portal UI, you can add the device identifier RoTPublicUIDs to the list of devices allowed to complete the bootstrap and provisioning process.

When a device bootstraps in your domain, it is first checked against the whitelist:

  • if it has been added to it, all the selected features and authorizations are provisioned automatically in the device without any effort from your side

  • If the device is not recognized, it is allowed to complete the bootstrap process and it is assigned to your account, but features are not automatically provisioned and the device goes in "ALLOCATED" state (with Blacklist flag), avoiding thus unwanted charging

When a new device profile is created using the UI, the whitelist option is active by default for security reason. If you bootstrap a device without adding it in the whitelist, the device goes in the blacklist and you can unblock it only using the User Interface, as explained in a later section.

There is, however, the possibility of turning off the whitelist option: at the time of creating a device profile, you can select to "ignore" whitelist when a device bootstraps. You can do it at later stage as well modifying the device profile in the UI. Just remind that turning of the whitelist check on an existing device profile, affects only the devices that bootstrap after the moment of the change.

Get the RoTPublicUID module identifier

Each module has a unique and immutable identifier protected by the Root of Trust.

To know the RoTPublicUID of a device you can use the following AT command

You can retrieve the RoTPublicUID of each device during production line and add it it to your whitelist immediately using the API or off-line using UI or API as clarified in the following section.

Whitelist configuration

Using Thingstream portal

To add one or more devices to the whitelist, signup to your Thingstream account and select the Security Services section from the left side menu. From the sub-menu you can enter in the whitelist section and add devices by using the Manage button. You can add single devices or upload a csv file.

Using API

There are two ways you can add devices in whitelist using API:

  1. by calling the /device/whitelist/add API, and providing in input an array of RoTPublicUIDs

  2. By calling /device/whitelist/add API, and providing in input a csv file, which contains a list of comma separated rows containing RoTPublicUIDs

You can also get a list of all devices added in whitelist. In addition, you can use APIa to exclusively get :

  • whitelisted devices

  • blacklisted devices (devices that were not added in whitelist but they are bootstrapped in your account are marked as blacklisted devices).

Note: once the device has completed the bootstrap (including the provisioning of the features) you can remove the RoTPublicUID from the Whitelist without any impact on the device. The removal of the item from the whitelist does not trigger the deletion of the thing in the Thing list section.

Examples

Add devices using an array of RoTs

If you need to add few devices to the whitelist or automat the process you can use the API providing in input a list of RoTPublicUIDs as in the exmple

curl --location --request POST 'https://ssapi.services.u-blox.com/v1/device/whitelist/add' \

--header 'Content-Type: application/json' \

--header 'Authorization: [Bearer Token]' \

--data-raw '{

"RoTPublicUIDs": ["fff0008003fa615"],

"Action": "ADD"

}'

Add a device using a csv file

If you wish to upload data using CSV, please consider that:

  • Content-Type must be set to application/octet-stream

  • Format of the file must be:

    • First row should be header row, with names and data in following order:

      • Id

      • Type

      • Action

    • Second row onwards should be data rows. Sample data row should look like this:

00020001003ffff,ROTPublicUID,ADD

where

    • Id is RoTPublicUID that you want to whitelist.

TYPE is the type of ID provided above. For now the only possible value is:

ROTPublicUID

but in the future other types of identifiers could be supported

        • Action is what to do with the row: should it be added to or deleted from the whitelist

This is an example that you can use

curl --location --request POST 'https://ssapi.services.u-blox.com/v1/device/whitelist/add' \

--header 'Content-Type: application/octet-stream' \

--header 'Authorization: [Bearer Token]' \

--data-raw 'Id,Type,Action\r\n0002000089282256,ROTPublicUID,ADD\r\n\r\n'


Get list of blacklisted devices

Any device that bootstrap in your account and it has not been added to the whitelist, will be blacklisted and no action is possible for this device until it is activated through the UI.

To get the list of devices in the balcklist use the following API

curl --location --request POST 'https://ssapi.services.u-blox.com/v1/device/list/get' \

--header 'Content-Type: application/json' \

--header 'Authorization: [Bearer Token]' \

--data-raw '{"Filter": "BLACKLISTED"}'

To activate a blacklisted device, you need to access to your account in the Thingstream portal and activate the device as explained in the following section

Activate a blacklisted device

To see the devices in the blacklist, login to your Thingstream account and select the Security Services section from the left side menu. From the sub-menu you can enter in the Blacklist section and see the list of blocked devices. To activate a thing

  • select the blacklisted device and click on 'View device'

  • click the Activate button in the Details tab

Once the thing has been activated the corresponding RoTPublicUID is added to the whitelist and the platform triggers the automatic provisioning in the device of the features defined in the device profile (that has been sealed in the device) at the moment of the activation.

Provisioning will happen at the next security heartbeat.