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
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 Amazon IoT.
Porting the Network Transport Interface library
You must implement a network transport interface to use coreMQTT
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
andconfig_template/test_param_config_template.h
to a project location in the build path, and rename them totest_execution_config.h
andtest_param_config.h
.Include relevant files into the build system. If using
CMake
,qualification_test.cmake
andsrc/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 byNetworkConnectFunc
insrc/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 byNetworkDisconnectFunc
insrc/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 insrc/transport_interface/transport_interface_tests.h
. The implementation must have exactly the same name and signature as defined intransport_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
Alternatively, you can also use IDT to automate the execution. See Amazon 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
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 Amazon IoT Device Tester. Follow the instructions in
Using Amazon IoT Device Tester for FreeRTOS in the FreeRTOS User Guide
to set up Amazon 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 Amazon IoT Device Tester configs
folder.