Developer-mode key provisioning
Important
This page refers to the Amazon-FreeRTOS repository which is deprecated. We recommend that you start here when you create a new project. If you already have an existing FreeRTOS project based on the now deprecated Amazon-FreeRTOS repository, see the Amazon-FreeRTOS Github Repository Migration Guide.
Introduction
This section discusses two options to get a trusted X.509 client certificate onto an IoT device for lab testing. Depending on the capabilities of the device, various provisioning-related operations may or may not be supported, including onboard ECDSA key generation, private key import, and X.509 certificate enrollment. In addition, different use cases call for different levels of key protection, ranging from onboard flash storage to the use of dedicated crypto hardware. This section provides logic for working within the cryptographic capabilities of your device.
Option #1: private key import from Amazon IoT
For lab testing purposes, if your device allows the import of private keys, follow the instructions in Configuring the FreeRTOS demos.
Option #2: onboard private key generation
If your device has a secure element, or if you prefer to generate your own device key pair and certificate, follow the instructions here.
- Initial Configuration
-
First, perform the steps in Configuring the FreeRTOS demos, but skip the last step (that is, don't do To format your Amazon IoT credentials). The net result should be that the
demos/include/aws_clientcredential.h
file has been updated with your settings, but thedemos/include/aws_clientcredential_keys.h
file has not. - Demo Project Configuration
-
Open the coreMQTT Mutual Authentication demo as described in the guide for your board in Board-specific getting started guides . In the project, open the file
aws_dev_mode_key_provisioning.c
and change the definition ofkeyprovisioningFORCE_GENERATE_NEW_KEY_PAIR
, which is set to zero by default, to one:#define keyprovisioningFORCE_GENERATE_NEW_KEY_PAIR 1
Then build and run the demo project and continue to the next step.
- Public Key Extraction
-
Because the device hasn't been provisioned with a private key and client certificate, the demo will fail to authenticate to Amazon IoT. However, the coreMQTT Mutual Authentication demo starts by running developer-mode key provisioning, resulting in the creation of a private key if one was not already present. You should see something like the following near the beginning of the serial console output.
7 910 [IP-task] Device public key, 91 bytes: 3059 3013 0607 2a86 48ce 3d02 0106 082a 8648 ce3d 0301 0703 4200 04cd 6569 ceb8 1bb9 1e72 339f e8cf 60ef 0f9f b473 33ac 6f19 1813 6999 3fa0 c293 5fae 08f1 1ad0 41b7 345c e746 1046 228e 5a5f d787 d571 dcb2 4e8d 75b3 2586 e2cc 0c
Copy the six lines of key bytes into a file called
DevicePublicKeyAsciiHex.txt
. Then use the command-line tool "xxd" to parse the hex bytes into binary:xxd -r -ps DevicePublicKeyAsciiHex.txt DevicePublicKeyDer.bin
Use "openssl" to format the binary encoded (DER) device public key as PEM:
openssl ec -inform der -in DevicePublicKeyDer.bin -pubin -pubout -outform pem -out DevicePublicKey.pem
Don't forget to disable the temporary key generation setting you enabled above. Otherwise, the device will create yet another key pair, and you will have to repeat the previous steps:
#define keyprovisioningFORCE_GENERATE_NEW_KEY_PAIR 0
- Public Key Infrastructure Setup
-
Follow the instructions in Registering Your CA Certificate to create a certificate hierarchy for your device lab certificate. Stop before executing the sequence described in the section Creating a Device Certificate Using Your CA Certificate.
In this case, the device will not be signing the certificate request (that is, the Certificate Service Request or CSR) because the X.509 encoding logic required for creating and signing a CSR has been excluded from the FreeRTOS demo projects to reduce ROM size. Instead, for lab testing purposes, create a private key on your workstation and use it to sign the CSR.
openssl genrsa -out tempCsrSigner.key 2048 openssl req -new -key tempCsrSigner.key -out deviceCert.csr
Once your Certificate Authority has been created and registered with Amazon IoT, use the following command to issue a client certificate based on the device CSR that was signed in the previous step:
openssl x509 -req -in deviceCert.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out deviceCert.pem -days 500 -sha256 -force_pubkey DevicePublicKey.pem
Even though the CSR was signed with a temporary private key, the issued certificate can only be used with the actual device private key. The same mechanism can be used in production if you store the CSR signer key in separate hardware, and configure your certificate authority so that it only issues certificates for requests that have been signed by that specific key. That key should also remain under the control of a designated administrator.
- Certificate Import
-
With the certificate issued, the next step is to import it into your device. You will also need to import your Certificate Authority (CA) certificate, since it is required in order for first-time authentication to Amazon IoT to succeed when using JITP. In the
aws_clientcredential_keys.h
file in your project, set thekeyCLIENT_CERTIFICATE_PEM
macro to be the contents of deviceCert.pem and set thekeyJITR_DEVICE_CERTIFICATE_AUTHORITY_PEM
macro to be the contents ofrootCA.pem
. - Device Authorization
-
Import
deviceCert.pem
into the Amazon IoT registry as described in Use Your Own Certificate. You must create a new Amazon IoT thing, attach the PENDING certificate and a policy to your thing, then mark the certificate as ACTIVE. All of these steps can be performed manually in the Amazon IoT console.Once the new client certificate is ACTIVE and associated with a thing and a policy, run the coreMQTT Mutual Authentication demo again. This time, the connection to the Amazon IoT MQTT broker will succeed.