corePKCS11 Mutual Authentication Demo (MQTT)
Note: We recommend that you always use strong mutual authentication in any Internet of Things (IoT) application. This example uses the recommended mutual authentication and is suitable for production IoT.
Introduction
This demo builds upon the MQTT mutual authentication demo. It assumes you are already familiar with the MQTT demo series. Please see the MQTT section if you haven't already.
The PKCS #11 demo projects use the FreeRTOS Windows port, so they can be built and evaluated with the free Community version of Visual Studio on Windows without the need for any particular MCU hardware.
This demo establishes a connection to AWS (Amazon Web Services) IoT in a way similar to MQTT mutual authentication, but it uses PKCS #11 to manage the credentials necessary to establish a connection to AWS IoT. For demonstration purposes, this PKCS #11 implementation uses the Windows file system for credential management.
PKCS #11 works by assigning a human readable label to each crypto object. In this demo, we map the label "Device Priv TLS Key" to our private key and
"Device Cert" to our certificate. The names of these labels can be managed in core_pkcs11_config.h
.
In core_pkcs11_pal_utils.c
,
we have mapped these labels to corePKCS11_Key.dat
and corePKCS11_Certificate.dat
respectively.
Source Code Organization
The Visual Studio solution for the PKCS #11 based mutual authentication demo is called corePKCS11_MQTT_Mutual_Auth.sln
and is located in the \FreeRTOS-Plus\Demo\corePKCS11_MQTT_Mutual_Auth_Windows_Simulator\
directory of the main FreeRTOS download.
Click to enlarge
Configuring the Demo Project
Configure the demo project by following the instructions under MQTT mutual auth, you can ignore the steps that involve migrating your certificate and private key to the democonfig.h
file, but make sure the Thing name and AWS IoT endpoint are included in democonfig.h
. These steps can be ignored since you will be importing your credentials via the PKCS #11 interface instead through this demo.
Once this is complete follow the below steps:
- In
democonfig.h
- Set
democonfigCLIENT_CERTIFICATE_PEM
to an empty string.
#define democonfigCLIENT_CERTIFICATE_PEM ""
- Set
democonfigCLIENT_PRIVATE_KEY_PEM
to an empty string.
#define democonfigCLIENT_PRIVATE_KEY_PEM ""
- This is to prevent
\FreeRTOS-Plus\Demo\corePKCS11_MQTT_Mutual_Auth_Windows_Simulator\demo_config.h
from generating
compiler errors, and will serve as further proof that the credentials in this header file are not used anywhere in the demo.
- Convert the key and certificate PEM files that were authenticated with AWS IoT Core to DER format.
- You should already have acquired PEM formatted credentials in the MQTT demos. If not, please revisit the MQTT mutual auth series
for guidance on retrieving these credentials.
- Option 1: Use the provided python script:
- Navigate to
\FreeRTOS-Plus\Demo\corePKCS11_MQTT_Mutual_Auth_Windows_Simulator
, and pass the absolute path for
the key and certificate PEM files to pkcs11_demo_setup.py
.
python3 pkcs11_demo_setup.py -c thing_cert_pem_file.pem -k thing_private_key_pem_file.pem
This will output equivalent .dat files in the same location as where the script was run.
- Option 2: Manually convert PEM files.
- If you choose not to use the above script, manually convert the PEM files to a PKCS #11 compatible DER format.
- An example using OpenSSL:
openssl x509 -outform der -in "<CERTIFICATE_PEM_FILE>" -out corePKCS11_Certificate.dat
openssl pkcs8 -topk8 -inform PEM -outfrom -DER -in "<KEY_PEM_FILE>" -out <PKCS11_RELEVANT_FILE_TYPE>
- It is advised to use individual keys for individual connections to keep the scope of what any individual key can unlock to a minimum.
This demo is designed to load keys following the names as described in core_pkcs11_pal_utils.c.
- Move the newly created .dat files to the same folder as the project solution. In this case
FreeRTOS-Plus\Demo\corePKCS11_MQTT_Mutual_Auth_Windows_Simulator\corePKCS11_MQTT_Mutual_Auth.sln
.
Building the Demo Project
The demo project uses the
free community edition of Visual Studio.
- Open the
FreeRTOS-Plus\Demo\corePKCS11_MQTT_Mutual_Auth_Windows_Simulator\corePKCS11_MQTT_Mutual_Auth.sln
Visual Studio solution file from within the Visual Studio IDE
- Right click the project and select "Set as Startup Project"
Click to enlarge
- Select "build solution" from the IDE's "build" menu
Functionality
The demo provides the same functionality as the mutual authentication MQTT demo with the addition of using PKCS #11 for managing credentials. For details on MQTT functionality, please view the MQTT demo series.
The major difference between this demo and the MQTT series, is that
FreeRTOS-Plus\Source\Application-Protocols\network_transport\transport_mbedtls_pkcs11.c
was modified to use PKCS #11. See
FreeRTOS-Plus\Source\Application-Protocols\network_transport\transport_mbedtls_pkcs11.c
and
FreeRTOS-Plus\Source\Application-Protocols\network_transport\transport_mbedtls_pkcs11.h
for how PKCS#11 was used to establish a TLS connection.
Code changes also exist at the application layer that emphasize the usage of PKCS #11 for credential management. For example, in
FreeRTOS-Plus\Demo\corePKCS11_MQTT_Mutual_Auth_Windows_Simulator\PKCS11_Mqtt_MutualAuthDemo.c
, the
NetworkCredentials
struct does not contain the client certificate and key, unlike
FreeRTOS-Plus\Demo\coreMQTT_Windows_Simulator\MQTT_Mutual_Auth\DemoTasks\MutualAuthMQTTExample.c
.
As an extra step, try moving your .dat files into a different directory mid demo. This will result in an inability to establish a new connection to AWS IoT Core, so the subsequent iteration of the demo will fail. For the example output of a successful demo, please see the MQTT demo series.
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.