Download FreeRTOS
 

Quality RTOS & Embedded Software

LIBRARIES
WHAT'S NEW
Simplifying Authenticated Cloud Connectivity for Any Device.
Designing an energy efficient and cloud-connected IoT solution with CoAP.
Introducing FreeRTOS Kernel version 11.0.0:
FreeRTOS Roadmap and Code Contribution process.
OPC-UA over TSN with FreeRTOS.

AWS IoT Fleet Provisioning Demo

Introduction

The AWS IoT Fleet Provisioning Demo showcases a way to provision a fleet of IoT devices with unique certificates and register them with AWS IoT Core using the Fleet Provisioning feature. This demo shows how devices with the ability to generate a public-private key-pair on board can utilize a common claim certificate (across the entire fleet of devices) to request unique certificates from AWS IoT Core for their generated key-pairs, and register themselves with AWS IoT Core as AWS IoT thing resources.

For more information on the Fleet Provisioning feature of AWS IoT, refer to Provisioning devices that don't have device certificates using fleet provisioning in the AWS IoT Developer's Guide. There are two provisioning workflows with Fleet Provisioning, Provisioning by Claim and Provisioning by Trusted User. This demo shows how to use the Provisioning by Claim workflow to provision devices with unique certificates using a common Claim certificate registered with AWS IoT Core. This demo project uses the free community edition of Visual Studio.

Prior to starting the Fleet Provisioning demo, we recommend that you use the corePKCS11 Mutual Authentication Demo (MQTT) to connect to AWS IoT. That will ensure that connectivity to AWS IoT is working correctly and that corePKCS11 credential management is functioning properly.

Source Code Organization

The demo project is called fleet_provisioning_demo.sln and can be found in the FreeRTOS repository on GitHub in the following directory:

FreeRTOS-Plus/Demo/AWS/Fleet_Provisioning_Windows_Simulator/Fleet_Provisioning_With_CSR_Demo

Setting up AWS resources before running the demo

To use the Fleet Provisioning feature of AWS IoT Core, you must set up an IAM role and a Provisioning Template in your AWS account. These AWS resources can be set up either through the AWS console or programmatically through the AWS CLI. The following instructions guide you through the set up of these resources using the AWS CLI. (In the following example commands, replace the <aws-region> and <aws-account-id> with the AWS Region and ID relevant to your AWS account.) For information on setting up the AWS CLI, see Getting started with the AWS CLI.

  1. Navigate to the demo subfolder at FreeRTOS-Plus/Demo/AWS/Fleet_Provisioning_Windows_Simulator/Fleet_Provisioning_With_CSR_Demo.

  2. Create an IAM role that will be needed by a fleet provisioning template.

    aws iam create-role &bsol;
        --role-name "FleetProvisioningDemoRole" &bsol;
        --assume-role-policy-document '{"Version":"2012-10-17","Statement":[{"Action":"sts:AssumeRole","Effect":"Allow","Principal":{"Service":"iot.amazonaws.com"}}]}'
  3. Attach the "AWSIoTThingsRegistration" policy to the role created in the above step. This allows the role to register new AWS IoT Things.

    aws iam attach-role-policy &bsol;
        --role-name "FleetProvisioningDemoRole" &bsol;
        --policy-arn arn:aws:iam::aws:policy/service-role/AWSIoTThingsRegistration
  4. Create an AWS IoT Policy which the Fleet Provisioning Claim will attach to newly-created things. An example IoT thing policy which you can modify to work with the demo can be found in the "example_iot_thing_policy.json" file. Before you run the following command, modify the "example_iot_thing_policy.json" file by replacing all occurrences of the following items in angle brackets:
    • <aws-region> with the AWS region of your choice (e.g. us-west-2)
    • <aws-account-id> with your AWS account ID
    aws iot create-policy &bsol;
        --policy-name FleetProvisioningDemoThingPolicy &bsol;
        --policy-document file://example_iot_thing_policy.json

  5. Create an IoT Thing Type. This Thing Type will be attached to all things created by the Fleet Provisioning demo, which allows for easy cleanup.
    aws iot create-thing-type --thing-type-name "fp_demo_things"
    

  6. Create the template resource which will be used for provisioning the demo application. This needs to be done only once. For more information on fleet provisioning templates, refer to this guide. An example fleet provisioning template which works with the demo can be found in the "example_fleet_provisioning_template.json" file.
    aws iot create-provisioning-template &bsol;
        --template-name FleetProvisioningDemoTemplate &bsol;
        --provisioning-role-arn arn:aws:iam::<aws-account>:role/FleetProvisioningDemoRole &bsol;
        --template-body file://example_fleet_provisioning_template.json &bsol;
        --enabled

  7. After you've made your fleet provisioning template, you can verify it was successfully created using the following CLI command.
    aws iot describe-provisioning-template --template-name FleetProvisioningDemoTemplate

  8. Create an ECDSA Keypair and Certificate to be used as a Root Certificate in the AWS IoT Console. NOTE: corePKCS11's MbedTLS Port only supports ECDSA Keys using the prime256v1 curve at this time. For more information please refer to corePKCS11's core_pkcs11_mbedtls.c
    openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 &bsol;
        -x509 -nodes -days 30 -out Root_ECDSA_Cert.pem -keyout Root_ECDSA_Key.pem

  9. Register the new CA Cert either through the AWS IoT Console, or by using the AWS CLI
    aws iot register-ca-certificate &bsol;
        --ca-certificate file://Root_ECDSA_Cert.pem &bsol;
        --certificate-mode SNI_ONLY

  10. Generate an ECDSA Certificate, that is signed by the previously generated Cert, to be used as the Claim Cert for the demo
    openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 &bsol;
        -CA Root_ECDSA_Cert.pem -CAkey Root_ECDSA_Key.pem &bsol;
        -x509 -nodes -days 14 -out ECDSA_Claim_Cert.pem -keyout ECDSA_Claim_Key.pem

  11. Register the Claim Certificate with the AWS IoT Core either through the AWS IoT Console, or the AWS CLI: NOTE: You will need the ARN that is returned by this function in a later step!
    aws iot register-certificate &bsol;
        --set-as-active &bsol;
        --certificate-pem file://ECDSA_Claim_Cert.pem &bsol;
        --ca-certificate-pem file://Root_ECDSA_Cert.pem

  12. Create an IoT policy for the Claim certificate. The following is the AWS CLI command for creating an IoT Policy. An example Claim certificate policy can be found in the "example_claim_policy.json" file. Before you run the create-policy command, modify "example_claim_policy.json" by replacing all occurrences of the following items in angle brackets:
    • <aws-region> with the AWS region of your choice (e.g. us-west-2)
    • <aws-account-id> with your AWS account ID
    aws iot create-policy &bsol;
        --policy-name FleetProvisioningDemoClaimPolicy &bsol;
        --policy-document file://example_claim_policy.json

  13. Attach the policy to the claim certificate. Replace <Claim-Cert-ID> with the certificate ID of the Claim Certificate that you created in Step 11.
    aws iot attach-policy &bsol;
        --target "arn:aws:iot:<aws-region>:<aws-account-id>:cert/<Claim-Cert-ID>" &bsol;
        --policy-name "FleetProvisioningDemoClaimPolicy"

Configure the Demo Project

  1. The demo uses the FreeRTOS-Plus-TCP TCP/IP stack, so follow the instructions provided for the TCP/IP starter project to:

    1. Install the pre-requisite components (such as WinPCap).
    2. Optionally set a static or dynamic IP address, gateway address and netmask.
    3. Optionally set a MAC address.
    4. Select an Ethernet network interface on your host machine.
    The above settings should be changed in the file FreeRTOSConfig.h in the Fleet Provisioning demo project.
  2. Configure demo_config.h. The following macros must be defined by the user for the demo to work:

    • democonfigMQTT_BROKER_ENDPOINT
    • democonfigROOT_CA_PEM
    • democonfigPROVISIONING_TEMPLATE_NAME
     
  3. Convert the Claim certificate and private key files you created in Step 8 above to DER format. This can be done manually or by using the included Python script "convert_credentials_to_der.py".

    • Option 1 - Using the included Python script:
      1. The script requires Python 3. If you do not have the 'cryptography' Python module installed, run the command
        pip3 install cryptography
      2. Navigate to the folder ...&bsol;FreeRTOS-Plus&bsol;Demo&bsol;AWS&bsol;Fleet_Provisioning_Windows_Simulator&bsol;Fleet_Provisioning_With_CSR_Demo&bsol;DemoSetup and move the .pem files to this folder.

      3. Run the script:

        python3 convert_credentials_to_der.py -c ClaimCertificate.pem -k ClaimPrivateKey.pem
        which will output the equivalent .dat files in the same location where the script is run.
      4. Move the *.dat files into ...&bsol;FreeRTOS-Plus&bsol;Demo&bsol;AWS&bsol;Fleet_Provisioning_Windows_Simulator&bsol;Fleet_Provisioning_With_CSR_Demo

    • Option 2 - Manually convert the PEM files:
      1. Use your preferred method of converting PEM files to a PKCS #11 compatible DER format. Here is an example using OpenSSL:
        1. openssl x509 -outform der -in "ClaimCertificate.pem" -out corePKCS11_Claim_Certificate.dat
        2. openssl rsa -in ClaimPrivateKey.pem -out corePKCS11_Claim_Key.dat -outform DER
      2. Move the *.dat files into ...&bsol;FreeRTOS-Plus&bsol;DemoAWS&bsol;Fleet_Provisioning_Windows_Simulator&bsol;Fleet_Provisioning_With_CSR_Demo

Build the Demo Project

The demo project uses the free community edition of Visual Studio. To build the demo:

  1. Open the Visual Studio solution file FreeRTOS-Plus/Demo/AWS/Fleet_Provisioning_Windows_Simulator/Fleet_Provisioning_With_CSR_Demo/fleet_provisioning_demo.sln from within the Visual Studio IDE.
  2. Select build solution from the IDE's build menu.

Functionality

The demo showcases the Provisioning by Claim workflow of the Fleet Provisioning feature of AWS IoT Core using corePKCS11 for credential management.

  1. The demo connects to the AWS IoT MQTT broker using the Claim credentials prepared in step 13.
  2. The demo creates and stores new key-pair and certificate files using corePKCS11. These credentials will be later used to provision a new AWS IoT thing.
  3. The CreateCertificateWithCsr MQTT API is called to make a Certificate Signing Request (CSR), so that AWS IoT will acknowledge and sign the certificate.
  4. The RegisterThing MQTT API is called to create a new AWS IoT thing which uses the key-pair and newly-signed certificate.
  5. After the new thing is provisioned, the demo disconnects from the AWS IoT MQTT broker.
  6. The demo connects to the AWS IoT MQTT broker using the newly-created thing credentials to verify that the thing was successfully registered.

The source code for the prvFleetProvisioningTask() function can be found in the FleetProvisioningDemoExample.c file on GitHub.

The screenshot below shows the expected output when the demo executes correctly:

demo success Click to Enlarge
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.