Soracom Krypton
Overview
Soracom Krypton is a credential provisioning service that securely initializes IoT devices using Soracom Air SIM authentication in order to provide secure access to cloud services.
Krypton provides an API for AWS IoT, Amazon Cognito, and Azure IoT Hub, which allows you to integrate credential provisioning and device configuration directly into your application during device bootstrapping. By simply calling the Krypton API, you can easily generate device certificates and register your device automatically with AWS IoT or Azure IoT Hub, or issue temporary credentials from Amazon Cognito in order to access cloud services such as Amazon S3.
By performing credential provisioning at the bootstrapping stage, certificates and other credentials do not need to be preloaded during the manufacturing process, which in turn allows you to build a master device firmware image that does not require per-device configuration at the factory, and more effectively manage the typical security risks associated with distributing device credentials.
Once a device has received credentials through Krypton, it can securely communicate with cloud services on any network interface, giving you the ability to build IoT applications that utilize wired or Wifi connection as the primary backhaul, and reserve the Soracom Air cellular connection as a backup.
Provisioning Process
Components
At a high level, Krypton is composed of two components:
- Service Provider - The credential or certificate issuing authority. Currently, Krypton support AWS IoT, Amazon Cognito, Azure IoT Hub, and Soracom Inventory.
- Provisioning API - The API methods used during provisioning. These methods can be implemented into your application to automate the provisioning process.
- AWS IoT
/provisioning/aws/iot/bootstrap
- Amazon Cognito
/provisioning/aws/cognito/credentials
/provisioning/aws/cognito/open_id_tokens
- Azure IoT Hub
/provisioning/azure/iot/register
/provisioning/azure/iot/registrations
- Soracom Inventory
/provisioning/soracom/inventory/bootstrap
- AWS IoT
Bootstrap Customization
When bootstrapping with AWS IoT, Krypton by default will return a response which contains a full set of X.509 credentials, which includes the AWS IoT Thing key, Thing certificate, and AWS IoT root CA certificate. In some cases, resource-constrained devices may not be able to handle the entire response containing the full set of credentials. You can optionally specify a "skipCertificates": true
parameter in bootstrap request, which will return only the Thing key and a Thing certificate ID.
Then, your device can make a separate request to retrieve the Thing certificate and root CA certificate:
/provisioning/aws/iot/certificates/:cert_id
- Retrieve the Thing certificate by specifying the certificate ID returned in the original bootstrap request./provisioning/aws/iot/ca_certificate
- Retrieve the AWS IoT root CA certificate.
For more information, refer to the getAwsIotThingCertificate and getAwsIotThingCACertificate API endpoints in the Krypton API reference.
Authentication Methods
When using Krypton, your device must first be authenticated in order to secure the provisioning process. Krypton works with the following authentication methods:
Soracom Air for Cellular
Communication between the device and Krypton is secured using SIM authentication and cellular connection with Soracom Air. Calls to Krypton's Provisinoing APIs are made over the cellular connection. Krypton receives the provisioning request and forwards the request to the Service Provider. Once the Service provider returns credentials to Krypton, the credentials are delivered to the device as an API response.
The device can then use the credentials to begin accessing cloud services.
Soracom Endorse
You can also perform device authentication without using a cellular connection by performing authentication through Soracom Endorse and a Krypton Client running on the device. The Krypton Client accesses authentication information embedded in a Soracom Air SIM card and performs authentication with Endorse over ethernet or Wifi. Once authenticated, the device can continue with provisioning through Krypton.
While this authentication method does not require a cellular connection, the Soracom Air SIM card must be accessible by the device.
This authentication method is currently only available for plan01s, plan01s - LDV, plan-NA1, and plan-US SIMs.
Soracom provides the Soracom Krypton Client for Go and Soracom Krypton Client for Java for use with authentication using Endorse. The Krypton Client provides the following functionality:
- Access SIM authentication information and authenticate with Soracom Endorse
- Perform provisioning with the Krypton Provisionining API
- Display Krypton API response
Requirements
The Soracom Air SIM card used for device authentication must have an Active SIM status. SIM cards that are not Active will result in an error when trying to access the Krypton Provisioning APIs.
When using the Soracom Endorse authentication method, these additional requirements apply:
- The Krypton Client for Go requires Golang.
- On Linux, the Krypton Client for Go also requires
pcscd
,libpcsclite1
, andlibpcsclite-dev
.
- On Linux, the Krypton Client for Go also requires
- The Krypton Client for Java requires Java runtime 8 or later.
- You must use a plan01s, plan01s - LDV, plan-NA1, or plan-US Soracom Air SIM.
-
The SIM must be inserted into a compatible modem or SIM card reader. As reference, Soracom has tested the following devices:
- Huawei MS2131i-8 3G USB modem
- Gemalto USB-TR HWP119316 card reader
When using other modems, ensure that the modem supports the
AT+CSIM
command.