Amazon FreeRTOS
Porting Guide

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Porting the TLS Library

For TLS authentication, Amazon FreeRTOS uses either mbedTLS or an off-chip TLS implementation, such as those found on some network co-processors. Amazon FreeRTOS includes a port of mbedTLS. If you use mbedTLS for TLS, TLS porting is not required. To allow different TLS implementations, third-party TLS libraries are accessed through a TLS abstraction layer.

Note

No matter which TLS implementation is used by your device's port of Amazon FreeRTOS, the port must pass the qualification tests for TLS. Qualification is based on results from AWS IoT Device Tester.

To prepare your platform for testing TLS, you need to configure your device in the AWS Cloud, and you need certificate and key provisioning on the device.

Prerequisites

To port the Amazon FreeRTOS TLS library, you need the following:

Porting

If your target hardware offloads TLS functionality to a separate network chip, you need to implement the TLS abstraction layer functions in the following table.

Function Description
TLS_Init Initialize the TLS context.
TLS_Connect Negotiate TLS and connect to the server.
TLS_Recv Read the requested number of bytes from the TLS connection.
TLS_Send Write the requested number of bytes to the TLS connection.
TLS_Cleanup Free resources consumed by the TLS context.

aws_tls.h contains the information required to implement these functions. Save the file in which you implement the functions as aws_tls.c.

Testing

If you are using an IDE to build test projects, you need to set up your library port in the IDE project.

Setting Up the IDE Test Project

If you are using an IDE for porting and testing, you need to add some source files to the IDE test project before you can test your ported code.

Important

In the following steps, make sure that you add the source files to your IDE project from their on-disk location. Do not create duplicate copies of source files.

To set up the TLS library in the IDE project

  1. Add aws_tls.c to the aws_tests IDE project.

  2. Add the source file aws_test_tls.c to the virtual folder aws_tests/application_code/common_tests/tls. This file includes the TLS tests.

Configuring the CMakeLists.txt File

If you are using CMake to build your test project, you need to define a portable layer target for the library in your CMake list file.

To define a library's portable layer target in CMakeLists.txt, follow the instructions in Amazon FreeRTOS Portable Layers.

The CMakeLists.txt template list file under <amazon-freertos>/vendors/<vendor>/boards/<board>/CMakeLists.txt includes example portable layer target definitions. You can uncomment the definition for the library that you are porting, and modify it to fit your platform.

Setting Up Your Local Testing Environment

There are five separate tests for the TLS port, one for each type of authentication supported by the Amazon FreeRTOS TLS library:

  • TLS_ConnectRSA()

  • TLS_ConnectEC()

  • TLS_ConnectMalformedCert()

  • TLS_ConnectBYOCCredentials()

  • TLS_ConnectUntrustedCert()

To run these tests, your board must use the MQTT protocol to communicate with the AWS Cloud. AWS IoT hosts an MQTT broker that sends and receives messages to and from connected devices at the edge. The AWS IoT MQTT broker accepts mutually authenticated TLS connections only.

Follow the instructions in Connecting Your Device to AWS IoT to connect your device to AWS IoT.

Each TLS test requires a different certificate/key combination, formatted and defined in either <amazon-freertos>/tests/include/aws_clientcredential_keys.h or <amazon-freertos>/libraries/freertos_plus/standard/tls/test/aws_test_tls.h.

Follow the instructions in Setting Up Certificates and Keys for the TLS Tests to obtain the certificates and keys that you need for testing.

After you set up the library in the IDE project, you need to configure some other files for testing.

To configure the source and header files for the TLS tests

  1. To enable the TLS tests, open <amazon-freertos>/vendors/<vendor>/boards/<board>/aws_tests/config_files/aws_test_runner_config.h, and set the testrunnerFULL_TLS_ENABLED macro to 1.

  2. Open <amazon-freertos>/libraries/freertos_plus/standard/utils/src/iot_system_init.c, and in the function SYSTEM_Init(), comment out the lines that call BUFFERPOOL_Init() and MQTT_AGENT_Init(), if you have not done so already. Bufferpool and the MQTT agent are not used in this library's porting tests. When you reach the Configuring the MQTT Library for Testing section, you will be instructed to uncomment these initialization function calls for testing the MQTT library.

    Make sure that the line that calls SOCKETS_Init() is uncommented.

Running the Tests

To execute the TLS tests

  1. Build the test project, and then flash it to your device for execution.

  2. Check the test results in the UART console.

    If all tests pass, then testing is complete.

Important

After you have ported the TLS library and tested your ports, you must run the Secure Socket tests that depend on TLS functionality. For more information, see Testing in the Secure Sockets porting documentation.

Validation

To officially qualify a device for Amazon FreeRTOS, you need to validate the device's ported source code with AWS IoT Device Tester. Follow the instructions in Using AWS IoT Device Tester for Amazon FreeRTOS in the Amazon FreeRTOS User Guide to set up Device Tester for port validation. To test a specific library's port, the correct test group must be enabled in the device.json file in the Device Tester configs folder.

After you finish porting the Amazon FreeRTOS TLS library to your device, you can start setting up the MQTT library for testing. See Configuring the MQTT Library for Testing for instructions.