Provisioning
Provisioning is the process of providing devices with the necessary certificates and credentials to securely connect with cloud-based services.
For devices to securely connect to the cloud, they require X.509 certificates so that they can be uniquely identified and authenticated by the cloud service. Once authorized, the certificates are used by the TLS protocol to securely encrypt all communications.
Ioto Provisioning
Ioto has an automated provisioning process that takes the pain out of device provisioning and certificate distribution for the user.
There are two primary provisioning patterns:
- User Claimed Devices
- Pre-Claimed Devices
User Claimed Devices
User claimed devices will register with an Ioto cloud when manufactured and then wait for a user to "claim" the device from the device cloud.
Pre-Claimed Devices
Pre-claimed devices are those that are configured and claimed by an Ioto device cloud during the device manufacturer. Pre-claimed devices are suitable for proprietary devices or projects where the devices are not distributed generally for resale.
Pre-claimed devices provisioned with certificates when manufactured or first configured.
Provisioning Lifecycle
Ioto provisioning is accomplished in several phases during the device lifecycle.
- Device Serialization
- Device Registration
- Device Claiming
- Device Connection
Device Serialization
For secure operation it is essential that each device can be uniquely identified. Most devices are created with a serial number that may include the product code, manufacturing batch number and individual serial number. However, while this serial number may be unique, it can be easily guessed because serial numbers typically follow a predictable format.
Instead of using the existing serial number, Ioto uses a random, unique claim ID (UCI) that is a random, 80-bit number that is not guessable and does not follow a predictable pattern. When paired with the product ID it is used as a unique claim ticket for users to claim devices for management.
The 10 letter UCI results in over 1 quadrillion numbers (32^10). Ioto claim IDs can be any length, but we recommend at least 10 letters.
During manufacturer, each device should be given a UCI that identifies the device to the service and is saved in the device.json5 configuration file on the device.
For User-Claimed devices, the UCI should be printed on the device label and be clearly identified as the Claim ID. The Claim ID can also be represented as a QR code if you choose to develop a mobile app for users to claim devices. (See Claiming below).
Creating the UCI
You have two alternatives when creating the UCI depending on how you operate your production process. Regardless of which method you choose, the end result is the Ioto device.json5 configuration file is updated with the UCI in the id property.
The product property in the device.json5 file is generated by the Builder Site when you define your product.
There are several ways to create the UCI including:
- Manually configure the UCI in the device.json5
- Create unique firmware for each device
- Dynamically provision the UCI in each device
Manually Creating the UCI
If you have a very small production run of devices, you can manually create the UCI with unique values for each device. You can simply edit the device.json5 with the required values.
With any significant production volumes, you will want an automated process.
Unique Firmware
If you create unique firmware for each device, you can set the UCI in the device.json5 when you create the firmware.
To create the UCI, you can either run the ioto process with the --gen-id argument or you can create a simple program that calls the cryptID API from the libioto library. See the ./factory/serialize.c sample for an example.
Dynamic UCI
If you are using identical firmware for each device, you can provision the UCI by having the Ioto agent in your device, connect to a serialization service during manufacturer. The serialization service will generate and provide the UCI to the agent that will then persist it to the device.json5 configuration file.
This generation should be integrated with your label creation process in manufacturer so that the UCI in the device.json5 matches that product label for the device.
The serialization service should listen for client requests on a HTTP endpoint and provide the UCI as the response. The address of the serialization service should be set in the Ioto agent api.serialize property in the config/ioto.json5 configuration file.
The Ioto agent includes a sample serialization service in the ./factory/serialize.c file.
Device Registration
Before leaving the factory, when the device first powers on during system test, the Ioto agent will start and connect to the Embedthis Ioto cloud service to register itself. This requires that your devices have an opening in the firewall to connect out to https://admin.embedthis.com.
The agent will send the contents of the device.json5 over an encrypted TLS connection to the Ioto cloud service. This registration request includes the device UCI and the product ID. Once received and validated, the Ioto cloud service will save the information in the Ioto device registration database.
If using User-claimed devices, the Ioto agent then awaits for a user to claim the device. If using Pre-claimed devices, the Ioto agent will skip the claiming step and proceed retrieve the required MQTT certificates and securely connect to the cloud.
Device Claiming
When creating a device cloud, Ioto creates a device manager web site for your cloud. The Ioto Device Manager is a generic (white-label) device manager for your devices. It can be extensively customized with your logo, product name and device specific screens and panels. Use the Builder to customize the Device Manager to suit your needs.
When a user purchases or installs a device with the Ioto agent, they can "claim" the device to manage it.
The user claims their device by logging onto the device cloud manager web site and claims the device using the UCI printed on the device label.
They enter the device claim code into a form on the manager site. The device manager then provisions the necessary X.509 certificates and AWS IoT resources required to support and manage the device.
Device Connection
When the device is unclaimed, the Ioto agent will regularly check with the Ioto service to see if it has been claimed. In this state, it is "unmanaged" and awaiting orders.
The Ioto device agent will check the Ioto service immediately on power-on, and then every 5 seconds with an exponentially increasing delay period up to a defined limit. If the device is rebooted, the polling process recommences.
After device claiming, when the device will be provided the X.509 certificate and keys when it next connects or polls the service. The device will save the certificates and keys, then connect to the device cloud. This completes the provisioning process.
Pre-Claiming Devices
If you are using pre-claimed devices, the process is similar, except you claim the device from the Ioto Manager when the device is made. Otherwise the process is the same.