Author: Johan Lofstad, Microchip Technology Inc.
This introductory guide explains how to securely connect an embedded design to Amazon Web Services® (AWS) through the AWS IoT Core module. When connected, the AWS API can be used to send and receive data between the cloud and the board.
This document is primarily written for the AVR-IoT WA, AVR-IoT WG, PIC-IoT WA, and PIC-IoT WG development boards. Users with these boards can follow the guide on a step-by-step basis. Users of AVR-IoT and PIC-IoT are recommended to run the quick start first to connect the board to the internet and explore the cloud sandbox before continuing. Instructions can be found at the "See it in Action" page.
The IoT Provisioning Tool is used to generate and upload the required certificates to AWS and the IoT Board using either Multi-Account Registration (MAR) or Just In Time Registration (JITR). For a deeper understanding of the provisioning process, see Crash Course in Cryptography and X.509 and A More Thorough Look into the Provisioning Process after reading this document.
This guide explores the following topics:
-
Configure AWS IAM with appropriate permissions
-
Use the IoT Provisioning Tool to authenticate the board with AWS IoT Core
-
Configure AWS IoT Core to communicate with the board through MQTT
An AWS account is required for this guide. You can obtain one at aws.amazon.com.
- Connect the Board to your AWS Account
IAM is an AWS service managing who and what has access to different resources. A resource is something "existing" in AWS. This could, for instance, be a registered IoT device, a cloud module such as the IoT Core, or a cryptographic certificate. The security philosophy is, you only have access to a resource if you need that resource.
AWS Identity and Access Management (IAM) is a web service that helps you securely control access to AWS resources. You use IAM to control who is authenticated (signed in) and authorized (has permissions) to use resources.
To connect the board to an AWS account, it must be provisioned using the IoT Provisioning Tool, which requires specific AWS access to configure the required modules.
Permission for these specific resources is given to the tool through a policy. From the AWS Documentation:
You manage access in AWS by creating policies and attaching them to IAM identities (users, groups of users, or roles) or AWS resources. A policy is an object in AWS that, when associated with an identity or resource, defines their permissions.
Open the IAM module in AWS and select Policies in the menu on the left-hand side. Click Create policy and select the JSON tab. Copy and paste the contents of MCHPProvToolAccess.json into the editor and click Review Policy. Name it MCHPProvToolAccess before clicking Create policy.
Note: The MCHPProvToolAccess.json file has been updated in newer revisions of this guide to reflect changes in the IoT Provisioning Tool. If you have already added the permissions at an earlier point, it is recommended to re-add them.
With the policy created, it must be attached to a user. Navigate to the IAM module and click Users followed by Add user. Give it a suitable name such as provtooluser. Check Programmatic access as the Access type. Click on Next: Permissions.
When presented with the Add user screen:
- Click Create group and name it
provtoolgroup. - Check the MCHPProvToolAccess policy.
- Click Create group in the bottom right corner.
Proceed to click Next until the review screen. Review the details and click Create User. A set of user credentials is generated. Make note of the Access key ID and Secret access key (click Show to reveal the secret access key).
Provisioning a device is the process of authenticating it with the cloud.
There are several methods to provision the board with AWS, and the method is dependent on the application. In this guide the Multi-Account Registration (MAR) approach is used, where the IoT Provisioning tool takes care of the cryptography. This is a good choice to get started with a small number of boards (for example when buying with Microchip's Trust&GO Platform).
- Install the AWS Command Line Interface
- Download the IoT Provisioning Tool. Extract the zip folder to a known location.
Open a command line (the Command Prompt for Windows® and the terminal for Mac® and Linux®) and navigate to the extracted IoT Provisioning Tool folder. Run aws configure and enter the fields being asked for. The access credentials are the ones from the IAM section. See the screenshot below.
Note that the console syntax below might be different for your system.
Note also that not all AWS regions are supported by the IoT boards. See the table below for a complete list of supported regions:
| Region name | Region |
|---|---|
| US East (Ohio) | us-east-2 |
| US East (N. Virginia) | us-east-1 |
| US West (Oregon) | us-west-2 |
| Asia Pacific (Singapore) | ap-southeast-1 |
| Asia Pacific (Sydney) | ap-southeast-2 |
| Asia Pacific (Tokyo) | ap-northeast-1 |
| Asia Pacific (Seoul) | ap-northeast-2 |
| EU (Frankfurt) | eu-central-1 |
| EU (Ireland) | eu-west-1 |
| EU (London) | eu-west-2 |
| China (Beijing) | cn-north-1 |
user@sys:/provtool$ aws configure
AWS Access Key ID [None]: AKIAWDV5V***********
AWS Secret Access Key [None]: *********************
Default region name [None]: us-east-2
Default output format [None]:Connect the board through USB to the computer. With the board connected and the AWS credentials set, the provisioning tool can create and upload the certificates.
user@sys:/provtool$ ./iotprovision-bin -c aws -m mar --force
......
......
......
Rebooting debugger
Done.
The tool connects to AWS in the region specified in the Registering the AWS Credentials section. A self-signed certificate is generated by the board and is uploaded to AWS by the provisioning tool. The board itself is registered as a thing in AWS IoT Core, and is then linked to the uploaded certificate - ensuring that device-to-cloud communicaton is authorized.
The details of this process is part of the X.509 cryptography standard and is not required reading for this introductory guide. For now, understand that the uploaded certificate causes AWS to trust the board. For reference, all the certificates and their private keys can be found in the .microchip-iot folder in the user home directory.
| OS | Path |
|---|---|
| Windows | %userprofile%\.microchip-iot |
| Mac and Linux | ~/.microchip-iot |
In cryptography, a certificate authority or certification authority (CA) is an entity that issues digital certificates. A digital certificate certifies the ownership of a public key by the named subject of the certificate. This allows others (relying parties) to rely upon signatures or on assertions made about the private key that corresponds to the certified public key.
Make sure the device is connected to the internet, indicated by a solid blue light on the board. See the "See it in Action" page for instructions on connecting to the internet.
If the device blinks a yellow LED, the board is provisioned, and data flows from the board to AWS. The provisioning tool created and uploaded the following items:
-
The board's certificate under Secure -> Certificates
-
The device (thing) under Manage -> Things
In AWS, a device is called a thing, as in Internet of Things.
The board is now provisioned, and data is sent from the board to AWS. This data can be viewed by going to Test in AWS IoT Core. Under Subscription topic, enter thingName/sensors. The thingName is a unique identifier for the device. The name is found under Manage -> Things. Click Subscribe to topic. The data now streams out to the console, as seen in the figure below.
Potential Pitfall: The thing name must be lowercase when subscribing to its sensor topic.
The protocol used to send and receive data is MQTT. It is recommended to become familiar with MQTT when working with these kinds of IoT devices. By default, the IoT board sends data on the
sensorstopic.
Fore every new device added to AWS IoT, a corresponding self-signed certificate must be extracted from the device and uploaded in a similar manner to that described in Step 2.2 Generate the certificates. Connect the new board through USB, and run the provisioning tool in the same manner:
user@sys:/provtool$ ./iotprovision-bin -c aws -m mar
......
......
......
Rebooting debugger
Done.The tool creates a new certificate and uploads it to AWS IoT, ensuring a trust relationship between the device and AWS. The device's data can be access in the same manner as the first one, on the thingName/sensors MQTT topic.
- PIC-IoT WA Development Board Product Page
- AVR-IoT WA Development Board Product Page
- AWS IAM Documentation
- AWS IoT Core Documentation
- IoT Provisioning Tool
- AWS Provisioning Methods
- JITR using X.509 (This README)
- AWS Multi Account Registration (MAR)
- AWS JITR Registration Blog