AWS IoT : Cloud setup for Device Provisioning.

Overview

It is one of the device provisioning ways by AWS for provisioning a device and install unique certificates on it. Devices get shipped with a claim certificate and private key embedded in them. The claim certificate and the private key are shared by all of the devices, it serves a special purpose.

The device uses the claim certificate to generate a unique certificate and its associated private key. It then gets registered as a thing by the associated provisioning template on AWS IoT.

AWS Side

Provisioning setup

1. Create a policy for the claim certificate
2. Create a claim certificate & attach its policy
3. Create a fleet policy
4. Create provisioning template

Device Side

Generate device certificate

1. Subscribe to certificate create response topics (success & error response)
2. Publish to create certificate request topic

Register as a thing

1. Subscribe to Provisioning Templates response topics (success & error response)
2. Publish message with template parameters to provision request topic

AWS Side

Provisioning setup

1. Sign in to the AWS Management Console, open the AWS IoT console
2. In the left navigation pane, choose Secure, choose Policies, and then click Create.
3. Enter a name for the AWS IoT policy (for example, esp32_claim_policy).
4. In the Add Statements, select Advanced Mode.
1. Copy the Policy for claim certificate: JSON shown below and replace the following values <aws-region>, <aws-account-id> with your AWS region, account number.
2. Provide a unique <templateName>  (for example, esp32_fleet_prov_template). Note it down the for further use on console as well as device.
5. Click Create.

Policy for claim certificate:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iot:Connect"
      ],
      "Resource": [
        "*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "iot:Publish",
        "iot:Receive"
      ],
      "Resource": [
        "arn:aws:iot:<aws-region>:<aws-account-id>:topic/$aws/certificates/create/*",
        "arn:aws:iot:<aws-region>:<aws-account-id>:topic/$aws/provisioning-templates/<templateName>/provision/*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "iot:Subscribe",
      "Resource": [
        "arn:aws:iot:<aws-region>:<aws-account-id>:topicfilter/$aws/certificates/create/*",
        "arn:aws:iot:<aws-region>:<aws-account-id>:topicfilter/$aws/provisioning-templates/<templateName>/provision/*"
      ]
    }
  ]
}

Create a claim certificate & attach its policy

1. Open the AWS IoT console
2. In the left navigation pane, choose Secure, choose Certificates, and then click Create.
3. Choose One-click certificate creation (recommended) – Create certificate.
4. From the Certificate created! page, download the client certificate files, public key, private key, and Amazon Root CA(Amazon Root CA 1) certificate to a secure location.
5. Choose Activate to activate the client certificate now.
6. Choose Attach policy, search for the policy created in the earlier section (esp32_claim_policy). Choose Done.

Create a fleet policy

1. Open the AWS IoT console
2. In the left navigation pane, choose Secure, choose Policies, and then click Create.
3. Enter a name for the AWS IoT policy (for example, esp32_fleet_policy).
4. In the Add Statements, select Advanced Mode.
1. Copy Policy for the fleet: JSON shown below and replace the following values <aws-region> & <aws-account-id> with your AWS region and account number.

Policy for the fleet:

{
"Version": "2012-10-17",
"Statement": [
    { "Effect": "Allow", "Action": "iot:Connect", "Resource": "arn:aws:iot:<aws-region>:<aws-account-id>:*" },
    { "Effect": "Allow", "Action": "iot:Publish", "Resource": "arn:aws:iot:<aws-region>:<aws-account-id>:*" },
    { "Effect": "Allow", "Action": "iot:Subscribe", "Resource": "arn:aws:iot:<aws-region>:<aws-account-id>:*" },
    { "Effect": "Allow", "Action": "iot:Receive", "Resource": "arn:aws:iot:<aws-region>:<aws-account-id>:*" }
]
}

Create a Fleet Provisioning Template

1. Open the AWS IoT console
2. In the left navigation pane, choose Connect, choose Fleet provisioning templates, and then click Create.
3. Click Get Started.
4. In the Create your template page
1. Enter template name used earlier section (esp32_fleet_prov_template) and description.
2. In the Provisioning Role
1. Click Create Role, then provide a name to the provisioning role
   (for example, esp32_fleet_prov_role)
3. Under Optional Settings, check the Use the AWS IoT registry to manage your device fleet option
4. Click Next
5. In the Define AWS IoT policies page
1. Select Use an existing AWS IoT policy
2. In the Search policies, enter the fleet policy name (esp32_fleet_policy) created in the previous section
3. Click Next
6. In the Define AWS IoT registry settings
1. Add Thing name prefix (for example, esp32dkc_)
2. (Optional) In the Select a group
1. Add a group name (for example, esp32dkc_group), and then click Create thing group.
3. Click Create template.
7. In the Give certificates or users permission to provision devices
1. In Use provisioning claim, select Use a certificate previously generated by AWS IoT
1. Select the claim certificate created in the earlier section
2. Note: Don’t click Attach Policy, as we have already linked in previous sections. Otherwise, the certificate will have a duplicate policy attached.
8. Click Enable template
9. Click Close

Device Side

You have to set up the AWS Side of things first before you proceed with device-side setup. That’s because the device uses a claim certificate to connect with AWS IoT for the first time to generate and acquire its unique certificate and private key.

Generate device certificate

The device gets shipped with firmware that has a claim certificate embedded in it. The device connects for the first time using the claim certificate, then it should request to generate a new device certificate from AWS IoT. This is achieved in the following order:

1. Subscribe to create certificate response topics (accepted & rejected)
1. $aws/certificates/create/json/accepted
2. $aws/certificates/create/json/rejected
2. Publish to create a topic with an empty payload
1. $aws/certificates/create/json
2. The response is received on either of the subscribed topics.
1. On successfully creating the certificate, the response is received on the accepted topic and contains the following information.
   1. Certificate Id
   2. Certificate
   3. Private Key
   4. Certificate ownership token
2. On failure, the response is received on the rejected topic and contains the following information
   1. status code
   2. error code
   3. error message
3. After receiving the certificate the device should register itself as a thing.

Register as a thing

After obtaining the device certificate it is marked as pending activation by AWS IoT. Using the new certificate the should send a registration request to register itself as a thing in the AWS IoT registry. On successful registration, AWS IoT creates the cloud resources based on the provisioning template and then marks the certificate as active and the device appears as a thing on the dashboard. This is achieved in the following order:

Note: <template_name> should be same as the one used in earlier section (here esp32_fleet_prov_template)

1. Subscribe to register thing response topics (accepted & rejected)
1. $aws/provisioning-templates/<template_name>/provision/json/accepted
2. $aws/provisioning-templates/<template_name>/provision/json/rejected
2. Publish to register thing topic with parameters:
1. $aws/provisioning-templates/<template_name>/provision/json
2. Publish message parameters:
1. Template name
2. Certificate ownership token
3. Template parameters:
4. Serial number
5. Certificate Id
3. The response is received on either of the subscribed topics.
1. On successful registration, the response is received on the accepted topic and contains the following information.
1. device configuration (if any)
2. thing name
2. On failure, the response is received on the rejected topic and contains the following information
1. status code
2. error code
3. error message

After successfully registering the device, the device should save the new certificate and disconnect. Then for the following new connections, it should use the new certificate. The claim certificate and private key would no longer exist on the device.