Download FreeRTOS

Quality RTOS & Embedded Software

Simplifying Authenticated Cloud Connectivity for Any Device.
Designing an energy efficient and cloud-connected IoT solution with CoAP.
Introducing FreeRTOS Kernel version 11.0.0:
FreeRTOS Roadmap and Code Contribution process.
OPC-UA over TSN with FreeRTOS.

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.


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:

  1. In democonfig.h
    1. Set democonfigCLIENT_CERTIFICATE_PEM to an empty string.
      #define democonfigCLIENT_CERTIFICATE_PEM ""
    2. Set democonfigCLIENT_PRIVATE_KEY_PEM to an empty string.
      #define democonfigCLIENT_PRIVATE_KEY_PEM ""
    3. 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.
  2. Convert the key and certificate PEM files that were authenticated with AWS IoT Core to DER format.
    1. 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.
    2. Option 1: Use the provided python script:
      1. Navigate to \FreeRTOS-Plus\Demo\corePKCS11_MQTT_Mutual_Auth_Windows_Simulator, and pass the absolute path for the key and certificate PEM files to
        python3 -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.
    3. Option 2: Manually convert PEM files.
      1. If you choose not to use the above script, manually convert the PEM files to a PKCS #11 compatible DER format.
      2. An example using OpenSSL:
        1. openssl x509 -outform der -in "<CERTIFICATE_PEM_FILE>" -out corePKCS11_Certificate.dat
        2. openssl pkcs8 -topk8 -inform PEM -outfrom -DER -in "<KEY_PEM_FILE>" -out <PKCS11_RELEVANT_FILE_TYPE>
      3. 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.
  3. Move the newly created .dat files to the same folder as the project solution. In this case FreeRTOS-Plus&bsol;Demo&bsol;corePKCS11_MQTT_Mutual_Auth_Windows_Simulator&bsol;corePKCS11_MQTT_Mutual_Auth.sln.


Building the Demo Project

The demo project uses the free community edition of Visual Studio
  1. Open the FreeRTOS-Plus&bsol;Demo&bsol;corePKCS11_MQTT_Mutual_Auth_Windows_Simulator&bsol;corePKCS11_MQTT_Mutual_Auth.sln Visual Studio solution file from within the Visual Studio IDE
    1. Right click the project and select "Set as Startup Project"
      Click to enlarge
  2. 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&bsol;Source&bsol;Application-Protocols&bsol;network_transport&bsol;transport_mbedtls_pkcs11.c was modified to use PKCS #11. See FreeRTOS-Plus&bsol;Source&bsol;Application-Protocols&bsol;network_transport&bsol;transport_mbedtls_pkcs11.c and FreeRTOS-Plus&bsol;Source&bsol;Application-Protocols&bsol;network_transport&bsol;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&bsol;Demo&bsol;corePKCS11_MQTT_Mutual_Auth_Windows_Simulator&bsol;PKCS11_Mqtt_MutualAuthDemo.c, the NetworkCredentials struct does not contain the client certificate and key, unlike FreeRTOS-Plus&bsol;Demo&bsol;coreMQTT_Windows_Simulator&bsol;MQTT_Mutual_Auth&bsol;DemoTasks&bsol;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.