Provision Service¶
1. Introduction¶
Provision Service enables remote devices to get TCUP URLs endpoints and credentials over a secured channel. It enables and automates the device registration and connectivity process eliminating the need for human intervention or manual inputs at the remote sites. This service addresses the key distribution challenge across multiple devices in multitenant systems. Provisioning of a device means creating initial records for a device with unique Endpoint ID (EPN ID), validity period, time allowed for services and optional bootstrapping info. Once the entry is done, TCUP is ready to accept registration request from the device. Any device that requires Device Management, Over the Air Service usage, must be enabled from Provision Service first.
1.1 Intended Audience¶
The intended audience of this document is anyone who wants to have an overview of TCUP Provision Service. After reading this document user will understand the capability of TCUP Provision Service as an IoT platform.
2. Key Concepts¶
In order to use Provision Service, a user needs to understand some of the basic concepts of the service. Please refer to the following section:
2.1 Endpoint ID¶
Endpoint ID (or EPN ID) is a unique device identification number that is assigned to each device in the system. EPN ID needs to be specified during device provisioning.
2.2 Bootstrap Agent¶
Bootstrap agent is the software component running on the device that initiates the bootstrapping process. This software component needs to be pre-installed in the device
2.3 Provisioning¶
Provision service is used to create an initial entry in the device database known as pre registration of the device. Once pre-registration is done, device is known to TCUP and TCUP is ready to accept registration request from device.
2.4 De-provisioning¶
The already provisioned device can also be de-provisioned from this service. Once de-provisioned, the device cannot be used further in any other device related services.
2.5 Modify provisioning¶
The already provisioned device details can also be modified.
2.6 Bootstrapping Information¶
This is the information packet consisting of service and user related information such as the url, ports for Device Management and OTA, user names, API keys, user-key etc. All this information is required for a device to securely connect to the correct service backend. These are
Platform Information like user details, Tenant details, API key, User Key etc
Device Management Information such as Device Management URL, port ETC
Over The Air upgrade information such as OTA URL, port, user details OTA Key etc.
2.7 Bootstrapping Process¶
The bootstrapping process works as follows.
The device to be bootstrapped must be pre-registered in TCUP system using the Provision service. This allows the Bootstrap server to recognize and authenticate the device as a valid device during bootstrapping.
Once Bootstrap agent starts running on the device, it tries to establish a secure transport channel with the Bootstrap server. In order to do this, the agent and the server mutually authenticate each other using pre-installed certificates.
Once the handshaking is completed, the agent requests the server to send the bootstrap information. This information is then stored in an encrypted file.
The file is stored in a predefined location in the device. If there is any update on bootstrap information the device automatically gets the updated encrypted file through secured channel.
When the OTA or DM agents are started, they decrypt the encrypted data from the secured file to access the connection URLs and necessary keys / credentials.
3. Functional Capabilities¶
The Provision Service provides the following functional capabilities:
Allows a device to securely discover a device management server and get necessary credentials to register itself
Allows to create an initial entry in the device database with all bootstrap information.
Marks the bootstrap process as completed on receipt of confirmation from device.
Allows to update bootstrap information using re-enabling feature.
Allows to query bootstrap status for any device using EPN id.
Allows to add extra bootstrap information if required
4. Purpose/Usage¶
Provision service allows us to distribute and install TCUP edge components with minimal information fixed or known beforehand. The only information that needs to be known by the device is the web link to the bootstrap server. The bootstrap server provides necessary inputs for the agents installed in the TCUP device to connect to the right sever endpoint addresses. Bootstrap information includes path to the Device Management server, Over-the-Air Update server and the API keys and credentials needed to connect to them. Since these data are provisioned at run time, Provision service brings in the necessary flexibility and scalability capabilities.
5. Examples¶
Consider the case where an Original Equipment Manufacturer (OEM) wants to manage and control their industrial printers using TCUP Device Management service and remote upgrade using TCUP OTA service. To achieve this, TCUP Provision service is used for providing the bootstrapping information.
During manufacturing process, the printers should be pre-loaded with the following.
Certificate provided by TCUP
URL to connect TCUP Provision service
Bootstrap Agent
Over the Air (OTA) Agent.
Each device must also be pre-registered in TCUP using the TCUP Provision service. This could be done using the TCUP portal or via the APIs provide by the Provision service. The pre-registration process is an offline step and does not require any connectivity to be established.
Now as soon as the printer is plugged in and connected to the network, the bootstrap agent establishes a secure connection with TCUP Bootstrap server using the pre-loaded certificate. Once this connection is established the bootstrap agent requests the bootstrap server for the bootstrap information. The server transmits this information to the agent and the agent stores the information locally in the printer in an encrypted file.
The OTA agent running in the printer decrypts the bootstrap information file to get all the necessary information to securely connect the OTA server. Once connected OTA updates and installs the DM agent in the printer. Now the printer is connected to OTA and DM server. DM allows to control the printer whereas OTA allows to update any software in the printer when required.
6. Reference Document¶
For more details about this service please refer the following documents
User guide
API Guide