You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Configuring the MQTT library for testing<aname="afr-porting-mqtt"></a>
1
+
# Configuring the coreMQTT library for testing<aname="afr-porting-mqtt"></a>
2
2
3
3
Devices on the edge can 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\.
4
4
5
-
The MQTT library implements the MQTT protocol for devices running FreeRTOS\. The MQTT library does not need to be ported, but your device's test project must pass all MQTT tests for qualification\. For more information, see [FreeRTOS MQTT Library](https://docs.aws.amazon.com/freertos/latest/userguide/freertos-lib-cloud-mqtt.html) in the FreeRTOS User Guide\.
5
+
The coreMQTT library implements the MQTT protocol for devices running FreeRTOS\. The coreMQTT library doesn't need to be ported, but your device's test project must pass all MQTT tests for qualification\. For more information, see [coreMQTT Library](https://docs.aws.amazon.com/freertos/latest/userguide/coremqtt.html) in the *FreeRTOS User Guide\.*
To set up the FreeRTOS MQTT library tests, you need the following:
9
+
To set up the coreMQTT library tests, you need the following:
10
10
+ A port of the TLS library\.
11
11
12
12
For information about porting the TLS library to your platform, see [Porting the TLS library](afr-porting-tls.md)\.
@@ -15,23 +15,22 @@ If you are using an IDE to build test projects, you need to set up your library
15
15
16
16
## Setting up the IDE test project<aname="testing-ide-mqtt"></a>
17
17
18
-
**To set up the MQTT library in the IDE project**
19
-
+ Add all of the test source files in `freertos/libraries/c_sdk/standard/mqtt` and its subdirectories to the `aws_tests` IDE project\.
18
+
**To set up the coreMQTT library in the IDE project**
20
19
21
-
## Configuring the `CMakeLists.txt` file<aname="testing-cmake-mqtt"></a>
20
+
1. Add all the library source files in the `freertos/libraries/coreMQTT/source` directory and its subdirectories to the `aws_tests` IDE project\.
22
21
23
-
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\.
22
+
1. Add all the source files for the network layer \(used in the tests\) in the `freertos/libraries/abstractions/transport` directory and `secure_sockets` subdirectory to the `aws_tests` IDE project\.
24
23
25
-
To define a library's portable layer target in `CMakeLists.txt`, follow the instructions in [FreeRTOS portable layers](cmake-template.md#cmake-portable)\.
24
+
1. Add a `core_mqtt_config.h` file, required for building the coreMQTT library, to the config files directory at `freertos/vendors/vendor/boards/board/aws_tests/config_files`\.
26
25
27
-
The `CMakeLists.txt` template list file under`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\.
26
+
1. Add the test source file at`freertos/tests/integration_test/core_mqtt_system.c` to the `aws_tests` IDE project\.
28
27
29
28
## Setting up your local testing environment<aname="testing-local-mqtt"></a>
30
29
31
-
After you set up the library in the IDE project, you need to configure some other files for testing\.
30
+
After you set up the library in the IDE project, you need to configure other files for testing\.
32
31
33
32
**To configure the source and header files for the MQTT tests**
34
-
+ To enable the MQTT tests, open `freertos/vendors/vendor/boards/board/aws_tests/config_files/aws_test_runner_config.h`, and set the `testrunnerFULL_MQTTv4_ENABLED ` macro to `1`\.
33
+
+ To enable the MQTT tests, open `freertos/vendors/vendor-name/boards/board-name/aws_tests/config_files/aws_test_runner_config.h`, and set the `testrunnerFULL_CORE_MQTT_AWS_IOT_ENABLED` macro to `1`\.
35
34
36
35
## Running the tests<aname="testing-run-mqtt"></a>
37
36
@@ -41,12 +40,12 @@ After you set up the library in the IDE project, you need to configure some othe
41
40
42
41
1. Check the test results in the UART console\. If all tests pass, then testing is complete\.
43
42
44
-
## Validation<aname="w3aac11c33c19"></a>
43
+
## Validation<aname="validation-mqtt"></a>
45
44
46
45
To officially qualify a device for 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 FreeRTOS](https://docs.aws.amazon.com/freertos/latest/userguide/device-tester-for-freertos-ug.html) in the 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\.
47
46
48
-
After you finish setting up the FreeRTOS MQTT library for your device, you can start porting the OTA agent library\. See [Porting the OTA library](afr-porting-ota.md) for instructions\.
47
+
After you set up the coreMQTT library for your device, you can start porting the OTA agent library\. See [Porting the OTA library](afr-porting-ota.md) for instructions\.
49
48
50
-
If your device does not support OTA functionality, you can start porting the Bluetooth Low Energy library\. See [Porting the Bluetooth Low Energy library](afr-porting-ble.md) for instructions\.
49
+
If your device doesn't support OTA functionality, you can start porting the Bluetooth Low Energy library\. See [Porting the Bluetooth Low Energy library](afr-porting-ble.md) for instructions\.
51
50
52
-
If your device does not support OTA and Bluetooth Low Energy functionality, then you are finished porting and can start the FreeRTOS qualification process\. See the [FreeRTOS Qualification Guide](https://docs.aws.amazon.com/freertos/latest/qualificationguide/) for more information\.
51
+
If your device doesn't support OTA and Bluetooth Low Energy functionality, then you are finished porting and can start the FreeRTOS qualification process\. See the [FreeRTOS Qualification Guide](https://docs.aws.amazon.com/freertos/latest/qualificationguide/) for more information\.
Copy file name to clipboardexpand all lines: doc_source/portingguide/afr-porting-pkcs.md
+11-11
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,4 @@
1
-
# Porting the PKCS \#11 library<aname="afr-porting-pkcs"></a>
1
+
# Porting the corePKCS11 library<aname="afr-porting-pkcs"></a>
2
2
3
3
FreeRTOS uses the open standard PKCS \#11 “CryptoKi” API as the abstraction layer for cryptographic operations, including:
4
4
+ Signing and verifying\.
@@ -7,11 +7,11 @@ FreeRTOS uses the open standard PKCS \#11 “CryptoKi” API as the abstraction
7
7
8
8
For more information, see [PKCS \#11 Cryptographic Token Interface Base Specification](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html)\.
9
9
10
-
Storing private keys in general\-purpose flash memory can be convenient in evaluation and rapid prototyping scenarios\. In production scenarios, to reduce the threats of data theft and device duplication, we recommend that you use dedicated cryptographic hardware\. Cryptographic hardware includes components with features that prevent cryptographic secret keys from being exported\. To use dedicated cryptographic hardware with FreeRTOS, you need to port the PKCS \#11 API to the hardware\. For information about the FreeRTOS PKCS \#11 library, see [FreeRTOS PKCS \#11 Library](https://docs.aws.amazon.com/freertos/latest/userguide/security-pkcs.html) in the FreeRTOS User Guide\.
10
+
Storing private keys in general\-purpose flash memory can be convenient in evaluation and rapid prototyping scenarios\. In production scenarios, to reduce the threats of data theft and device duplication, we recommend that you use dedicated cryptographic hardware\. Cryptographic hardware includes components with features that prevent cryptographic secret keys from being exported\. To use dedicated cryptographic hardware with FreeRTOS, you need to port the PKCS \#11 API to the hardware\. For information about the FreeRTOS corePKCS11 library, see [FreeRTOS corePKCS11 Library](https://docs.aws.amazon.com/freertos/latest/userguide/security-pkcs.html) in the *FreeRTOS User Guide*\.
To port the PKCS \#11 library, you need the following:
14
+
To port the corePKCS11 library, you need the following:
15
15
+ An IDE project or `CMakeLists.txt` list file that includes vendor\-supplied drivers that are suitable for sensitive data\.
16
16
17
17
For information about setting up a test project, see [Setting Up Your FreeRTOS Source Code for Porting](porting-set-up-project.md)\.
@@ -21,7 +21,7 @@ To port the PKCS \#11 library, you need the following:
21
21
22
22
## Porting<aname="porting-steps-pkcs"></a>
23
23
24
-
**To port the PKCS \#11 library**
24
+
**To port the corePKCS11 library**
25
25
26
26
1. Port the PKCS \#11 API functions\.
27
27
@@ -79,29 +79,29 @@ If you are using an IDE for porting and testing, you need to add some source fil
79
79
**Important**
80
80
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\.
81
81
82
-
**To set up the PKCS \#11 library in the IDE project**
82
+
**To set up the corePKCS11 library in the IDE project**
83
83
84
84
1. Add the source file `freertos/vendors/vendor/boards/board/ports/pkcs11/core_pkcs11_pal.c` to the `aws_tests` IDE project\.
85
85
86
86
1. Add all of the files in the `freertos/libraries/abstractions/pkcs11` directory and its subdirectories to the `aws_tests` IDE project\.
87
87
88
88
1. Add all of the files in the `freertos/libraries/freertos_plus/standard/pkcs11` directory and its subdirectories to the `aws_tests` IDE project\. These files implement wrappers for commonly grouped PKCS \#11 function sets\.
89
89
90
-
1. Add the source file `freertos/libraries/freertos_plus/standard/crypto/src/aws_crypto.c` to the `aws_tests` IDE project\. This file implements the CRYPTO abstraction wrapper for mbedTLS\.
90
+
1. Add the source file `freertos/libraries/freertos_plus/standard/crypto/src/iot_crypto.c` to the `aws_tests` IDE project\. This file implements the CRYPTO abstraction wrapper for mbedTLS\.
91
91
92
92
1. Add all of the source and header files from `freertos/libraries/3rdparty/mbedtls` and its subdirectories to the `aws_tests` IDE project\.
93
93
94
-
1. Add `freertos/libraries/3rdparty/mbedtls/include` and `freertos/libraries/abstractions/pkcs11` to the compiler’s include path\.
94
+
1. Add `freertos/libraries/3rdparty/mbedtls/include` and `freertos/libraries/abstractions/pkcs11` to the compiler's include path\.
95
95
96
96
### Configuring the `CMakeLists.txt` file<aname="testing-cmake-pkcs"></a>
97
97
98
-
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\.
98
+
If you're using CMake to build your test project, you need to define a portable layer target for the library in your CMake list file\.
99
99
100
100
To define a library's portable layer target in `CMakeLists.txt`, follow the instructions in [FreeRTOS portable layers](cmake-template.md#cmake-portable)\.
101
101
102
102
The `CMakeLists.txt` template list file under `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\.
103
103
104
-
See below for an example portable layer target definition for the PKCS \#11 library that uses the mbedTLS\-based software implementation of PKCS \#11 and supplies a port\-specific PKCS \#11 PAL file\.
104
+
See the following example portable layer target definition for the corePKCS11 library that uses the mbedTLS\-based software implementation of PKCS \#11 and supplies a port\-specific PKCS \#11 PAL file\.
105
105
106
106
```
107
107
# PKCS11
@@ -137,8 +137,8 @@ After you set up the library in the IDE project, you need to configure some othe
137
137
138
138
Testing is complete when all tests pass\.
139
139
140
-
## Validation<aname="w3aac11c29c17"></a>
140
+
## Validation<aname="pkcs-validation"></a>
141
141
142
142
To officially qualify a device for 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 FreeRTOS](https://docs.aws.amazon.com/freertos/latest/userguide/device-tester-for-freertos-ug.html) in the 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\.
143
143
144
-
After you finish porting the FreeRTOS PKCS \#11 library to your device, you can start porting the TLS library\. See [Porting the TLS library](afr-porting-tls.md) for instructions\.
144
+
After you finish porting the corePKCS11 library to your device, you can start porting the TLS library\. See [Porting the TLS library](afr-porting-tls.md) for instructions\.
0 commit comments