Soracom Krypton

Configuration

Enabling Krypton will incur fees based on the number of devices that use the service. Refer to the Pricing & Fee Schedule for more information.

Preparation - Register Credentials

AWS IoT or Amazon Cognito

As Krypton will connect with AWS IoT or Amazon Cognito during provisioning, Krypton requires programmatic access to your AWS account using an Access key ID and Secret access key. For security, the Access key ID and Secret access key should be generated for an AWS IAM user which contains only the permissions necessary for credential provisioning.

As the required permissions vary depending on the Service Provider, follow the corresponding instructions for setting up the Access key ID and Secret access key with the appropriate permissions:

Once you have generated an Access key ID and Secret access key, proceed with Krypton configuration:

  1. Login to the User Console. Click your account menu, then select Security.

  2. Click the Credentials tab, then click the Register a credentials set button.

    https://console.soracom.io

    Register credentials

  3. Enter a CREDENTIALS SET ID, and select AWS credentials as the TYPE. Then enter the AWS ACCESS KEY ID and AWS SECRET ACCESS KEY, and click the Register button.

    Register AWS credentials

Azure IoT Hub

As Krypton will connect with Azure IoT Device Provisioning Service during provisioning, Krypton requires programmatic access to your Azure account using a Shared access policy. For security, the Shared access policy should contain only the permissions necessary for credential provisioning. Follow the instruction for setting up the Shared access policy with the appropriate permissions:

Once you have generated a Shared access policy, proceed with Krypton configuration:

  1. Login to the User Console. Click your account menu, then select Security.

  2. Click the Credentials tab, then click the Register a credentials set button.

    https://console.soracom.io

    Register credentials

  3. Enter a CREDENTIALS SET ID, and select Azure IoT credentials as the TYPE. Then enter the ACCESS POLICY NAME and SHARED ACCESS KEY, and click the Register button.

    Register Azure IoT credentials

In addition, as Azure IoT Device Provisioning Service (DPS) will use X.509 credentials to register devices with Azure IoT Hub, Krypton will need to pass X.509 credentials to DPS. Follow the instruction for setting up the X.509 credentials.

Once you have generated X.509 credentials, proceed with Krypton configuration:

  1. Login to the User Console. Click your account menu, then select Security.

  2. Click the Credentials tab, then click the Register a credentials set button.

    https://console.soracom.io

    Register credentials

  3. Enter a CREDENTIALS SET ID, and select X.509 certificate as the TYPE. Then enter the KEY, CERT, and CA, and click the Register button.

    Register X.509 credentials

Configure the Group

Soracom Krypton settings are found in Soracom Air for Cellular group settings.

With the credential set registered, you can configure Krypton:

  1. From the Menu, open the Groups screen.

  2. From the list of groups, click the name of the group you want to configure to open its settings page.

  3. From the Basic Settings tab, click the SORACOM Krypton panel to expand its settings.

  4. Enable Krypton by switching the option to ON.

    Krypton configuration

  5. Click the button and select the provisioning Service Provider. Enter the configuration parameters required:

    • AWS IoT configuration

      • REGION - The AWS IoT region used, such as us-east-1.
      • CREDENTIALS SET - The AWS credentials configured earlier.
      • POLICY NAME - The AWS IoT policy name to assign to a provisioned device.
      • THING NAME PATTERN - The name to apply to a provisioned device if not specified by the device. You can include the string #{imsi} to this parameter. #{imsi} will be replaced by the IMSI of the device's IoT SIM.
      • HOST NAME - The AWS IoT endpoint host name.
      • ROOT CA CERTIFICATE - The root CA certificate that will sign the device certificate. If left blank, the root CA certificate of Amazon Trust Services will be used.

    • Amazon Cognito configuration

      • REGION - The Amazon Cognito region used, such as us-east-1.
      • CREDENTIALS SET - The AWS credentials configured earlier.
      • IDENTITY POOL ID - The Cognito identity pool used for device provisioning, such as us-east-1:abcdef00-0000-0000-0000-000012345678.
      • DEVELOPER PROVIDER NAME - krypton.soracom.io
    • Azure IoT Hub configuration
      • GLOBAL DEVICE ENDPOINT - The global endpoint of Azure IoT Hub Device Provisioning Service.
      • X.509 CREDENTIALS - The X.509 credentials configured earlier.
      • AZURE IOT CREDENTIALS - The Azure IoT credentials configured earlier.
      • DEVICE NAME PATTERN - The name to apply to a provisioned device if not specified by the device. You can include the string #{imsi} to this parameter. #{imsi} will be replaced by the IMSI of the device's IoT SIM.
      • ID SCOPE - Specify the ID Scope in Azure IoT Hub Device Provisioning Service.

    Then click the OK button.

  6. Click the Save button at the bottom of the panel.

Once Krypton has been enabled and configured, devices that use an Air for Cellular subscriber that belongs to the configured group will be able to access the Provisioning APIs.

Advanced Configuration

Krypton can also be configured through the Soracom API or CLI by using the SoracomKrypton namespace.

Configuration Structure

When configuring Krypton for use with AWS IoT, the group configuration will have the following structure:

"SoracomKrypton": {
  "enabled": true|false,
  "AwsIot": {
    "region": "us-east-1",
    "credentialsId": "my-aws-credentials",
    "policyName": "us-east-1:abcdef00-0000-0000-0000-000012345678",
    "thingNamePattern": "myDevice-$imsi",
    "host": "acbdef0012345678.iot.us-east-1.amazonaws.com"
  }
}

When configuring Krypton for use with Amazon Cognito, the group configuration will have the following structure:

"SoracomKrypton": {
  "enabled": true|false,
  "AmazonCognito": {
    "region": "us-east-1",
    "credentialsId": "my-aws-credentials",
    "identityPoolId": "us-east-1:abcdef00-0000-0000-0000-000012345678",
    "developerProviderName": "krypton.soracom.io"
  }
}

When configuring Krypton for use with Azure IoT Hub, the group configuration will have the following structure:

"SoracomKrypton": {
  "enabled": true|false,
  "AzureIot": {
    "deviceNamePattern": "myDevice-#{imsi}",
    "globalEndpoint": "https://global.azure-devices-provisioning.net",
    "x509CredentialId": "my-x509-credentials",
    "idScope": "0ne0xxxxxxx",
    "azureIotCredentialId": "my-azure-credentials"
  }
}

Parameters

Enable or disable Krypton:

Modify configuration parameters for use with AWS IoT:

Modify configuration parameters for use with Amazon Cognito:

Modify configuration parameters for use with Azure IoT Hub:

Sample AWS IoT Configuration

[
  {
    "key": "enabled",
    "value": true
  },
  {
    "key": "AwsIot",
    "value": {
      "region": "us-east-1",
      "credentialsId": "my-aws-credentials",
      "policyName": "myThingPolicy",
      "thingNamePattern": "myDevice-$imsi",
      "host": "abcdef0012345678.iot.us-east-1.amazonaws.com"
     }
  }
]

Sample Amazon Cognito Configuration

[
  {
    "key": "enabled",
    "value": true
  },
  {
    "key": "AmazonCognito",
    "value": {
      "region": "us-east-1",
      "credentialsId": "my-aws-credentials",
      "identityPoolId": "us-east-1:abcdef00-0000-0000-0000-000012345678",
      "developerProviderName": "krypton.soracom.io"
    } 
  }
]

Sample Azure IoT Hub Configuration

[
  {
    "key": "enabled",
    "value": true
  },
  {
    "key": "AzureIot",
    "value": {
      "deviceNamePattern": "myDevice-#{imsi}",
      "globalEndpoint": "https://global.azure-devices-provisioning.net",
      "x509CredentialId": "my-x509-credentials",
      "idScope": "0ne0xxxxxxx",
      "azureIotCredentialId": "my-azure-credentials"
    }
  }
]