: The PKCS #11 library and documentation are part of the FreeRTOS LTS Roadmap
. These libraries are fully functional, but undergoing optimizations or refactoring to improve memory usage, modularity, documentation, demo usability, or test coverage. They are available on GitHub
or part of the LTS Development Snapshot download
PKCS #11 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.
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. These labels can be managed in
iot_pkcs11_pal.c, we have mapped these labels to
Source Code Organization
The Visual Studio solution for the PKCS #11 based mutual authentication demo is called
and is located in the
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
aws_iot_demo_profile.h file, but make sure the Thing name and AWS IoT endpoint are included in
aws_iot_demo_profile.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:
awsiotdemoprofileCLIENT_CERTIFICATE_PEM to an empty string.
#define awsiotdemoprofileCLIENT_CERTIFICATE_PEM ""
awsiotdemoprofileCLIENT_PRIVATE_KEY_PEM to an empty string.
#define awsiotdemoprofileCLIENT_PRIVATE_KEY_PEM ""
- This is to prevent
\FreeRTOS-Plus\Demo\FreeRTOS_IoT_Libraries\include\aws_iot_setup_check.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\FreeRTOS_IoT_Libraries\pkcs11, and pass the absolute path for the key and certificate PEM files to
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 FreeRTOS_P11_Certificate.dat
openssl pkcs8 -topk8 -inform PEM -outfrom -DER -in "KEY_PEM_FILE" -out FreeRTOS_P11_Key.dat
- Move the newly created .dat files to the same folder as the project solution. In this case
Building the Demo Project
The demo project uses the free community edition of Visual Studio.
- Open the
\FreeRTOS-Plus\Demo\FreeRTOS_IoT_Libraries\pkcs11\pkcs11_mqtt_tls_mutual_auth\pkcs11_mqtt_tls_mutual_auth_demo.sln Visual Studio solution file from within the Visual Studio IDE
- Select ‘build solution’ from the IDE’s ‘build’ menu
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\FreeRTOS-IoT-Libraries\abstractions\platform\freertos\iot_network_freertos.c was modified to use PKCS#11. See
FreeRTOS-Plus/Source/FreeRTOS-IoT-Libraries/abstractions/platform/freertos_plus/standard/tls/src/iot_tls.c 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
xNetworkSecurityCredentials struct does not contain the client certificate and key, unlike
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.