This example shows all steps for an onboarding process of a device to AWS IoT Core using the pre-provisioned credentials of the EdgeLock SE050E secure element.
AWS IoT authenticates client certificates using the TLS protocol's client authentication mode. In TLS client authentication, AWS IoT requests an X.509 client certificate and validates the certificate's status against a registry of certificates in the AWS account. It challenges the client for proof of ownership of the private key that corresponds to the public key contained in the certificate.
The secure element EdgeLock SE050E is used to securely store the private client keys and perform the client authentication.
AWS IoT supports these types of X.509 client certificates, all are supported by EdgeLock SE050E:
- X.509 certificates generated by AWS IoT
- X.509 certificates signed by a CA registered with AWS IoT.
- X.509 certificates signed by a CA that is not registered with AWS IoT. Client certificates must be registered with AWS IoT before a client can communicate with AWS IoT.
Only Option 3 supports the onboarding process of a device to AWS IoT Core using pre-provisioned credentials of a generic EdgeLock SE050. This option is known as “AWS IoT Core Multi-Account Registration” and is supported by the AWS CLI interface. Customer-specific configurations of EdgeLock SE050E can even use Option 2 with pre-provisioned certificates.
Hardware setup
Hardware Prerequisite
The following hardware will be used for this demo:
- Raspberry Pi 4 Model B or Pi 3 Model B+
- OM-SE050ARD-E development kit (NXP 12NC 9354 332 66598)
- Optional - OM-SE050RPI adapter board for Raspberry Pi (12NC 9353 798 33598)[1]
[1] .. For further details see NXP “AN12570 Quick start guide with Raspberry Pi” chapter “2 Prepare your Raspberry Pi”. In the following sections, we will use the OM-SE050RPI adapter board.
Connecting the OM-SE050ARD-E to the Raspberry Pi
Make sure the jumpers in your OM-SE050ARD-E board are configured as shown in the figure below (equal to the default configuration of OM-SE050ARD-E
Stack the OM-SE050ARD-E with the adapter board to the Raspberry Pi
Alternative it is possible to connect the OM-SE050ARD-E via wires to the OM-SE050RPI Raspberry Pi board as shown in the figure below:
Software Setup
This section explains how to get your Raspberry Pi ready to execute the EdgeLock SE050 Plug & Trust middleware.
Prerequisite
- AWS account
- a current 32-bit Raspbian should be running on Raspberry Pi. The detailed Raspberry Pi software setup is described in the “AN12570 Quick start guide with Raspberry Pi” chapter “2.2 Software setup”.
Enable I2C if not yet enabled on your Raspberry Pi.
ls /sys/bus/i2c/devices
If does not list i2c-1, I2C needs to be enabled for your board.
sudo raspi-config
Use the down arrow to select Interfacing Options. Follow instructions and Enable I2C.
Create a new folder called se_mw:
cd ~
mkdir se05x_mw
cd se05x_mw
EdgeLock SE05x Plug & Trust middleware - Build Instructions
Install the required build tools, if the image does not have them already.
sudo apt-get install cmake cmake-curses-gui cmake-gui libssl-dev
Download the EdgeLock SE05x Plug & Trust middleware (nxp.com login needed) from the NXP website .
Unzip the EdgeLock SE05x Plug & Trust middleware in the se_mw folder:
unzip ~/Downloads/SE050-PLUG-TRUST-MW.zip -d ~/se05x_mw
Run the following commands to build OpenSSL engine for SE050. For further details see please “AN12570 Quick start guide with Raspberry Pi” chapter “4.1 Example: SE050E CMake build settings”. If the hostname is “raspberrypi” automatically the config for a Raspberry Pi is created:
cd simw-top
python3 scripts/create_cmake_projects.py
cd ~/se05x_mw/simw-top_build/raspbian_native_se050_t1oi2c
cmake-gui .
Update the CMake settings as shown in the figure below. Press first the Configure button and
second the Generate button and close the CMake GUI.
cmake --build .
sudo make install
sudo ldconfig /usr/local/lib
Install the ssscli tool
In this example, the SE050 Python-based ssscli tool is used to extract the credentials of the EdgeLock SE050. The following steps are needed before running the ssscli tool and needed
are needed once per installation:
sudo apt-get install python3-pip
sudo apt-get install libffi-dev
cd ~/se05x_mw/simw-top/pycli
pip3 install -r requirements.txt
To install ssscli tool, run the following commands once:
pip3 install --editable src
Install AWS CLI
To install the AWS CLI tool, run the following commands once:
pip3 install awscli --upgrade --user
Add AWS CLI executable to your Command-Line Path:
export PATH=/home/pi/.local/bin:$PATH
Confirm the AWS CLI tool was successful installed:
aws --version
Configure AWS
Get access key ID and secret access key
When you first create an AWS account, you begin with a single sign-in identity that has complete access to all AWS services and resources in the account. This identity is called the AWS account root user. Amazon strongly recommend that you do not use the root user for your everyday tasks, even the administrative ones. Instead, it is recommended to create an IMA user. Please read the following documentation for more details: What is IAM? - AWS Identity and Access Management (amazon.com)
Perform the following steps to create an IAM (Identity and Access Management) user.
- Sign in as AWS account root user by using the email address and password that you used to create the AWS account.
- On the navigation menu, choose “Users” and press the “Add user” button.
- Add a username and select the options as shown below and press the “Next: Permissions” button.
- Press the “Attach existing policies directly” button.
- For this demo select “AWSIoTFullAccess” policy and press the “Next” button.
- For this demo you do not need to add any tag. Simple press the “Next” button.
- Review your entries and press the “Create user” button.
- Finally download the IAM user credentials as csv file. For the next steps you need to retrieve the Access key ID and Secret access key from the csv file. The csv file includes the user name, the password, access key id, the secret access key and the console login link.
You can use the console login link to login as IAM user.
Set AWS credentials in AWS cli
You can save your frequently used configuration settings and credentials in files that are maintained by the AWS CLI.
Run the following command to quickly set your credentials, region, and output format:
aws configure
Example:
$ aws configure
AWS Access Key ID [None]: <access key ID>
AWS Secret Access Key [None]: <secret access key>
Default region name [None]: <aws region name>
Default output format [None]: json
Using credentials from EdgeLock SE050E
We will be using ECC credentials in this example, the key with ID 0xF0000100 and the corresponding certificate at ID 0xF0000101. You can use any of the available certificates that are pre-provisioned in your EdgeLock SE050E. Please refer to AN12436 - SE050 Configurations for a list of available key and certificate IDs.
Create a folder to store the EdgeLock SE050 credentials:
cd ~/se05x_mw/
mkdir se050_device_credentials
cd se050_device_credentialsls
Extracting the EdgeLock SE050E Device Certificate
Using pySSSCLI Tool, read out the device certificate.
ssscli connect se05x t1oi2c none
ssscli get cert 0xF0000101 se050_device_cert0_ecc.cer
The Certificate/Public Key as read from the Secure Element can be inserted into the OpenSSL key structure. The x509 OpenSSL command also supports to display the public keys contents:
openssl x509 -noout -text -in se050_device_cert0_ecc.cer
Creating the EdgeLock SE050E Device Key Reference
OpenSSL requires a key pair, consisting of a private and a public key, to be generated or loaded into the EdgeLock SE050E before the cryptographic operations can be executed.
Private Key: The Private key is securely stored inside the SE050E Secure Element and cannot be retrieved by the OpenSSL engine.
Reference Key: Standard OpenSSL API needs to be called with a key. Instead of a real private key the OpenSSL key data structure gets used with a reference to the private key inside the SE050E Secure Element. The reference key looks for OpenSSL like a real key, but it does not contain secret data.
Using pySSSCLI Tool, read out the device reference key.
sudo ssscli refpem ecc pair 0xF0000100 se050_device_key_ref0_ecc.pem
ssscli disconnect
In the first glance, the reference key looks like as any other private key, therefore it is
required to use OpenSSL to display the details:
openssl ec -in se050_device_key_ref0_ecc.pem -text
Registering Device Certificate
Use the AWS CLI Tool to register the extracted device certificate on to your AWS IoT Console.
The command line options are:
aws iot register-certificate-without-ca --certificate-pem <certificate-filename>
Execute the following command:
aws iot register-certificate-without-ca --certificate-pem file://se050_device_cert0_ecc.cer --status ACTIVE
This command returns the certificate ANR and ANR ID. A certificate Amazon Resource Name (ARN) uniquely identifies this certificate. You can open the AWS IoT console to check if the certificate was successfully registered.
Note: You need to select the correct AWS region.
Create an AWS IoT policy.
First, create a JSON document “se050_raspi_policy.json” with the following content.
Note: this policy allows for demo purpose access to all IoT actions on all resources.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:*",
"Resource": "*"
}
]
}
using for example the nano editor. The following command creates an empty file.
nano se050_raspi_policy.json
Copy & Paste the content into the text editor and save the file.
Use the AWS CLI Tool to create the policy on your AWS IoT Console.
aws iot create-policy --policy-name se050_raspi_policy --policy-document file://se050_raspi_policy.json
You can open the AWS IoT console to check if the policy was successfully created.
Attach AWS IoT policy to certificate.
Attaching an AWS IoT Core policy to a certificate gives the device connecting with this certificate the permissions specified in the policy.
Use the AWS CLI Tool to attach the policy to the device certificate.
aws iot attach-policy --target <certificate ARN> --policy-name se050_raspi_policy
Obtain the custom AWS IoT endpoint URL
Run the following command to print out your AWS’ user’s endpoint address. This will be used later:
aws iot describe-endpoint --endpoint-type iot:Data-ATS
Alternative you can obtain the customer AWS IoT endpoint using the AWS IoT console.
Run the IoT demo MQTT Example
Navigate to demos se_mw/simw-top/demos/linux/aws_eou directory and execute the buildScript.sh. This will build the project iot_demo_mqtt.
cd ~/se_mw/simw-top/demos/linux/aws_eou/
chmod +x buildScript.sh
./buildScript.sh
Copy all SE50 credentials into the example output/bin folder:
cd ~/se05x_mw/simw-top/demos/linux/aws_eou/aws-iot-device-sdk-embedded-C/build/output/bin
cp ~/se05x_mw/simw-top/demos/linux/aws_eou/AmazonRootCA1.pem ~/se_mw/simw-top/demos/linux/aws_eou/aws-iot-device-sdk-embedded-C/build/output/bin
cp ~/se05x_mw/se050_device_credentials/se050_device_cert0_ecc.cer ~/se_mw/simw-top/demos/linux/aws_eou/aws-iot-device-sdk-embedded-C/build/output/bin
cp ~/se05x_mw/se050_device_credentials/se050_device_key_ref0_ecc.pem ~/se_mw/simw-top/demos/linux/aws_eou/aws-iot-device-sdk-embedded-C/build/output/bin
To let openSSL use the engine set the openssl config path to point to the preconfigured config file:
export OPENSSL_CONF=/home/pi/se05x_mw/simw-top/demos/linux/common/openssl11_sss_se050.cnf
Navigate to demos binary folder:
cd ~/se05x_mw/simw-top/demos/linux/aws_eou/aws-iot-device-sdk-embedded-C/build/output/bin
Run the demo with specifying your endpoint URL and certificate + key files:
./iot_demo_mqtt -i "ThingName" -h <endpoint> -r AmazonRootCA1.pem -c <certificate-filename> -k <ref-filename>
For example:
./iot_demo_mqtt -i "myRaspiSE050" -h <endpoint> -r AmazonRootCA1.pem -c se050_device_cert0_ecc.cer -k se050_device_key_ref0_ecc.pem
Go to the AWS IoT Core dashboard and subscribe to the following topic:
iotdemo/#
The MQTT topic you subscribed will now appear in the Subscriptions section as
shown in the figure below in case your run the demo again.
