1. Home
  2. Docs
  3. IoTGtw Introduction
  4. Bootstrap Service for IoT Devices

Bootstrap Service for IoT Devices

IoT Device Bootstrapping Service

The platform provides a secure and very easy to use bootstrap service. The bootstrap service can be used for devices to securely retrieve configuration settings such as:

  • Global Unique Device ID (udid)  (The ID automatically assigned to the device on the platform)
  • SimplyTiny Messaging Authentication Token
  • TLS/DTLS Bearer Encryption Pre-shared Key
  • TLS/DTLS Bearer Encryption X.509 PEM Certificate
  • TLS/DTLS Bearer Encryption X509 PEM Private key
  • TLS/DTLS Bearer Encryption X509 certificate and Private key with the option to obliterate the Private Key after device has retrieved it

All the above can be done over secure and encrypted bearer with any of the support protocols and application framework from any of your preferred regions.

The bootstrap service can be used on any device without any special software installation or libraries. All you need is configure the device with the platform assigned customer id and the bootstrap token which can be easily configured on the device object on the platform.

The bootstrap mode settings can be configured on the service template and you can enable the type of device details that can be retrieved in a bootstrap request operation by the devices associated to the service template. A device can indicate the type of device bootstrap details it wants to retrieve by specifying the correct MTI (message type indicator) number (90 – 99) in the SimplyTiny mti field of the request message. For security reasons only the operations enabled on the device service template will be permitted to be retrieved.

  • 90: Retrieve UDID                                                 | Sample Response: {“udid”:”5af188932693aa3edc77fa03″}
  • 91: Retrieve SimplyTiny Auth Token                  | Sample Response: {“at”: “9a9fDa0s23du/T”}
  • 92: Retrieve Combined UDID + Auth Token       | Sample Response: {“at”: “9a9fDa0s23du/T”, “udid”:”5af188932693aa3edc77fa03″}
  • 93: Retrieve Customer account id + custom device id (if configured)| Sample Response: {“cid”: “5bf177965873bb3edc66fa08”, “dvid”:”gas_turbine_546_tcu_33″}
  • 94: Retrieve PSK Secret Retrieval | returns PSK secret    | Sample Response: {“psk”: “E:swj+97Z,_xR]WeB`<q@({~&4(fa4R)E”, “udid”:”5af188932693aa3edc77fa03″}
  • 95: Retrieve X.509 PEM Certificate  (if configured)           | Sample Response: {“pem_cert”: “XXXXXXXXXXXXXXXXX”}
  • 96: Retrieve X.509 PEM Private Key (if configured)          | Sample Response: {“pem_key”:”YYYYYYYYYYYYYYYYYYYYY”}
  • 97: Retrieve X.509 Certificate + Key  (If configured)         | Sample Response: {“pem_cert”: “XXXXXXXXXXXXXXXXX”, “pem_key”:”YYYYYYYYYYYYYYYYYYYYY”}
  • 98: Delete the temporarily stored Device Private KEY after device key retrieve operation

The message type indicator (MTI) codes can be used by the device to indicate what settings it is trying to retrieve. If the bootstrap service is enabled AND the device bootstrap request is successfully authenticated with the pre-shared bootstrap token configured for the device on the platform AND the MTI being requested is permitted to be retrieved as per the service template settings then the platform will respond to the device’s request. If any of the criteria is not met the request is silently discarded.

All the above can be configured securely for the device via the Portal or via the platform management APIs at any point.

Note: The SimplyTiny Auth Token retrieve request can be used to retrieve the Auth Token configured for the device on the platform.

 

For example assuming device X bootstrap token on the platform is set to value: 434dl$sf9s8udDR4G52d16Tvf2 . Device X must provide this token and the customer id of the customer account under which the device is provisioned whenever it wants to perform bootstrap operation.

Retrieving Static or Dynamically issued Authentication Tokens

When a token retrieve request is received (MTI 90 or 91) If an Auth Token value is configured on the platform for the device, the configured token value will be returned in the simplytiny at (auth token) parameter. If the device service profile is configured with a Cloud Service Provider (CSP) Upstream Profile (i.e. an Azure IoThub or AWS IoTCore upstream profile), then the CSP device scoped token is also returned in the same response message in the simplytiny data parameter.

By default the platform token is valid untill refreshed by device or manually updated. The CSP token is valid for 8 Hours by default however the device can request a specific validity time by specifying the validity duration in Hours (integer value) in the SimplyTiny payload section of the Auth token request.

 

SimplyTiny Bootstrap Service – Request Example:

If device X wants to perform a bootstrap request to retrieve its PSK secret it will have to use the message type indicator code 94. Further, the device must supply the bootstrap token as well as the customer id in the bootstrap request. In this example the customer_id is 5bf177965873bb3edc66fa08.

Note: When using the SimplyTiny strings format, the customer id value is conveyed in the first field after the selected delimiter which in this example is the asterisk * symbol. The bootstrap token which in this example is  sf9s8udDR4G52d16Tvf2 is conveyed in the auth token field position of the SimplyTiny Strings format.

Example: Device makes a Bootstrap Request with SimplyTiny Strings

*5bf177965873bb3edc66fa08*434dl$sf9s8udDR4G52d16Tvf2**94

Example: Device makes a Bootstrap Request (same as above) with SimplyTiny JSON

“, //bootstrap token
mti: 94, //SimplyTiny message type indicator (9 = Bootstrap Service)
}[/crayon]
 

Platform Response :

 

Was this article helpful to you? Yes No

How can we help?