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.
In this section
Related Information
Security Services API documentation
Still need help?
If you need more help or have any questions, please send an email to services-support@u-blox.com.
Using API
There are two ways you can add devices in whitelist using API:
by calling the /device/whitelist/add API, and providing in input an array of RoTPublicUIDs
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.