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 OrganizationThe Visual Studio solution for the PKCS #11 based mutual authentication demo is called
pkcs11_mqtt_tls_mutual_auth_demo.slnand is located in the
\FreeRTOS-Plus\Demo\FreeRTOS_IoT_Libraries\pkcs11\pkcs11_mqtt_tls_mutual_auth\directory of the main FreeRTOS download.
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_PEMto an empty string.
#define awsiotdemoprofileCLIENT_CERTIFICATE_PEM ""
awsiotdemoprofileCLIENT_PRIVATE_KEY_PEMto an empty string.
#define awsiotdemoprofileCLIENT_PRIVATE_KEY_PEM ""
- This is to prevent
\FreeRTOS-Plus\Demo\FreeRTOS_IoT_Libraries\include\aws_iot_setup_check.hfrom 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.
- Navigate to
- 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 ProjectThe 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.slnVisual 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.