Porting the Network Transport Interface - FreeRTOS
TLSNTILPrerequisitesPortingTesting

Porting the Network Transport Interface

Integrating the TLS library

For Transport Layer Security (TLS) authentication, use your preferred TLS stack. We recommend using Mbed TLS because it is tested with FreeRTOS libraries. You can find an example of this at this GitHub repository.

Regardless of the TLS implementation used by your device, you must implement the underlying transport hooks for TLS stack with TCP/IP stack. They must support the TLS cipher suites that are supported by AWS IoT.

Porting the Network Transport Interface library

You must implement a network transport interface to use coreMQTT and coreHTTP. Network Transport Interface contains function pointers and context data required to send and receive data on a single network connection. See Transport Interface for more details. FreeRTOS provides a set of built-in network transport interface tests to validate these implementations. The following section guides you how to set up your project to run these tests.

Prerequisites

To port this test, you need the following:

  • A project with a build system that can build FreeRTOS with a validated FreeRTOS kernel port.

  • Working implementation of network drivers.

Porting

  • Add FreeRTOS-Libraries-Integration-Tests as a submodule into your project. It doesn’t matter where the submodule is placed in the project, as long as it can be built.

  • Copy config_template/test_execution_config_template.h and config_template/test_param_config_template.h to a project location in the build path, and rename them to test_execution_config.h and test_param_config.h.

  • Include relevant files into the build system. If using CMake, qualification_test.cmake and src/transport_interface_tests.cmake are used to include relevant files.

  • Implement the following functions at an appropriate project location:

    • A network connect function: The signature is defined by NetworkConnectFunc in src/common/network_connection.h. This function takes in a pointer to network context, a pointer to host info, and a pointer to network credentials. It establishes a connection with the server specified in the host info with the provided network credentials.

    • A network disconnect function: The signature is defined by NetworkDisconnectFunc in src/common/network_connection.h. This function takes in a pointer to a network context. It disconnects a previously established connection stored in the network context.

    • setupTransportInterfaceTestParam(): This is defined in src/transport_interface/transport_interface_tests.h. The implementation must have exactly the same name and signature as defined in transport_interface_tests.h. This function takes in a pointer to a TransportInterfaceTestParam struct. It will populate the fields in the TransportInterfaceTestParam struct that is used by the transport interface test.

  • Implement UNITY_OUTPUT_CHAR so that test output logs do not interleave with device logs.

  • Call runQualificationTest()from the application. The device hardware must be properly initialized and the network must be connected before the call.

Credential management (on-device generated key)

When FORCE_GENERATE_NEW_KEY_PAIR in test_param_config.h is set to 1, the device application generates a new on-device key pair and outputs the public key. The device application uses ECHO_SERVER_ROOT_CA and TRANSPORT_CLIENT_CERTIFICATE as the echo server root CA and client certificate when establishing a TLS connection with the echo server. IDT sets these parameters during the qualification run.

Credential Management (importing key)

The device application uses ECHO_SERVER_ROOT_CA, TRANSPORT_CLIENT_CERTIFICATE and TRANSPORT_CLIENT_PRIVATE_KEY in test_param_config.h as the echo server root CA, client certificate, and client private key when establishing a TLS connection with the echo server. IDT sets these parameters during the qualification run.

Testing

This section describes how you can locally test the transport interface with the qualification tests. Additional details can be found in the README.md file provided in the transport_interface section of the FreeRTOS-Libraries-Integration-Tests on GitHub.

Alternatively, you can also use IDT to automate the execution. See AWS IoT Device Tester for FreeRTOS in the FreeRTOS User Guide for details.

Enable the test

Open test_execution_config.h and define TRANSPORT_INTERFACE_TEST_ENABLED to 1.

Set up the echo server for testing

An echo server accessible from the device running the tests is required for local testing. The echo server must support TLS if the transport interface implementation supports TLS. If you don’t have one already, FreeRTOS-Libraries-Integration-Tests GitHub repository has an echo server implementation.

Configuring the project for testing

In test_param_config.h, update ECHO_SERVER_ENDPOINT and ECHO_SERVER_PORT to the endpoint and server setup in the previous step.

Setup credentials (on-device generated key)

  • Set ECHO_SERVER_ROOT_CA to the server certificate of the echo server.

  • Set FORCE_GENERATE_NEW_KEY_PAIR to 1 to generate a key pair and get the public key.

  • Set FORCE_GENERATE_NEW_KEY_PAIR back to 0 after key generation.

  • User the public key and server key and certificate to generate client certificate.

  • Set TRANSPORT_CLIENT_CERTIFICATE to the generated client certificate.

Setup credentials (importing key)

  • Set ECHO_SERVER_ROOT_CA to the server certificate of the echo server.

  • Set TRANSPORT_CLIENT_CERTIFICATE to the pre-generated client certificate.

  • Set TRANSPORT_CLIENT_PRIVATE_KEY to the pre-generated client private key.

Build and flash the application

Build and flash the application using the tool-chain of your choice. When runQualificationTest() is invoked, the transport interface tests will run. Test results are outputted to the serial port.

Note

To officially qualify a device for FreeRTOS, you must validate the device's ported source code against OTA PAL and OTA E2E test groups with AWS IoT Device Tester. Follow the instructions in Using AWS IoT Device Tester for FreeRTOS in the FreeRTOS User Guide to set up AWS IoT 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 AWS IoT Device Tester configs folder.