diff --git a/README.md b/README.md index df34150c..75384ba3 100644 --- a/README.md +++ b/README.md @@ -106,6 +106,10 @@ of the verification fails, then MCUBoot stops the booting process. ## Software Components +### Fetching + +Generally all the components used within the FRI project are fetched using `git submodules` from their official repositories into `components/` directory. Exact location and the version are recorded in the [manifest.yml](manifest.yml). + ### Trusted Firmware M Trusted Firmware-M (TF-M) implements the Secure Processing Environment (SPE) @@ -114,7 +118,7 @@ Cortex-M55, Cortex-M85 processors) and dual-core platforms. It is the platform security architecture reference implementation aligning with PSA Certified guidelines, enabling chips, Real Time Operating Systems and devices to become PSA Certified. Follow the [link](https://tf-m-user-guide.trustedfirmware.org/introduction/readme.html) -for more information on Trusted Firmware M. +for more information on Trusted Firmware M. To have a better overview of how Trusted Firmware M is integrated with the FRI project, you're kindly asked to check [Trusted Firmware M component document](docs/components/security/trusted_firmware-m/trusted_firmware-m.md) ### Mbed TLS @@ -123,7 +127,7 @@ the SSL/TLS and DTLS protocols. The project provides reference implementation of [PSA Cryptography API Specification](https://developer.arm.com/documentation/ihi0086/b) by supporting the cryptographic operations via. PSA Crypto APIs. Follow the [link](https://www.trustedfirmware.org/projects/mbed-tls/) for more information -on Mbed TLS. +on Mbed TLS. To have a better overview of how Mbed TLS is integrated with the FRI project, you're kindly asked to check [Mbed TLS component document](docs/components/security/mbedtls/mbedtls.md) ### PKCS11 PSA Shim diff --git a/applications/freertos_iot_libraries_tests/CMakeLists.txt b/applications/freertos_iot_libraries_tests/CMakeLists.txt index e4609eee..739b024a 100644 --- a/applications/freertos_iot_libraries_tests/CMakeLists.txt +++ b/applications/freertos_iot_libraries_tests/CMakeLists.txt @@ -110,7 +110,6 @@ target_link_libraries(${CMAKE_PROJECT_NAME} ota-for-aws-iot-embedded-sdk provisioning-lib mbedtls - mbedtls-threading-freertos tfm-ns-interface ) diff --git a/applications/keyword_detection/CMakeLists.txt b/applications/keyword_detection/CMakeLists.txt index 24a0696c..b9b7c8e3 100644 --- a/applications/keyword_detection/CMakeLists.txt +++ b/applications/keyword_detection/CMakeLists.txt @@ -142,7 +142,6 @@ target_link_libraries(keyword-detection helpers-events helpers-sntp mbedtls - mbedtls-threading-freertos ota-for-aws-iot-embedded-sdk provisioning-lib tfm-ns-interface diff --git a/applications/object_detection/CMakeLists.txt b/applications/object_detection/CMakeLists.txt index 4148fdb9..730096db 100644 --- a/applications/object_detection/CMakeLists.txt +++ b/applications/object_detection/CMakeLists.txt @@ -126,7 +126,6 @@ target_link_libraries(object-detection isp-config isp_platform_driver mbedtls - mbedtls-threading-freertos ota-for-aws-iot-embedded-sdk provisioning-lib tfm-ns-interface diff --git a/applications/speech_recognition/CMakeLists.txt b/applications/speech_recognition/CMakeLists.txt index 8e2b7be3..f8ebf848 100644 --- a/applications/speech_recognition/CMakeLists.txt +++ b/applications/speech_recognition/CMakeLists.txt @@ -152,7 +152,6 @@ target_link_libraries(speech-recognition fri-bsp helpers-events mbedtls - mbedtls-threading-freertos ota-for-aws-iot-embedded-sdk provisioning-lib speexdsp diff --git a/components/security/mbedtls/integration/CMakeLists.txt b/components/security/mbedtls/integration/CMakeLists.txt index dcaca973..5fb88bd3 100644 --- a/components/security/mbedtls/integration/CMakeLists.txt +++ b/components/security/mbedtls/integration/CMakeLists.txt @@ -21,6 +21,11 @@ target_link_libraries(mbedtls-threading-freertos mbedtls ) +target_link_libraries(mbedtls-config + INTERFACE + mbedtls-threading-freertos +) + target_link_libraries(mbedx509 PUBLIC mbedtls-config diff --git a/docs/components/security/mbedtls/mbedtls.md b/docs/components/security/mbedtls/mbedtls.md new file mode 100644 index 00000000..7c58709d --- /dev/null +++ b/docs/components/security/mbedtls/mbedtls.md @@ -0,0 +1,77 @@ +# MbedTLS + +## Overview + +MbedTLS is a lightweight crytographic and SSL/TLS library designed for embedded systems and IoT devices. + +It provides a wide range of cryptographic and security features including: +* SSL/TLS support +* Cryptography +* Certificate handling +* Key Management +* Secure communication + +In the FRI, MbedTLS is a crucial component for ensuring secure communication between IoT devices and +cloud services. It is primarily used for transport layer security, authentication, encryption and certificate management. + +Consult the FRI `manifest.yml` for the currently supported version of MbedTLS. + +## Configuration + +User must provide an MbedTLS configuration file. It can be an empty file or override MbedTLS default [configurations](https://tls.mbed.org/api/config_8h.html). + +The configuration file specified by the application is retrieved by adding the C macro `MBEDTLS_CONFIG_FILE=` to the `mbedtls-config` target and its include path. + +Example: + +```cmake +target_include_directories(mbedtls-config + INTERFACE + mbedtls-config +) + +target_compile_definitions(mbedtls-config + INTERFACE + MBEDTLS_CONFIG_FILE="aws_mbedtls_config.h" +) +``` + +To enable the FreeRTOS threading protection `#define MBEDTLS_THREADING_ALT` should be present in the user provided mbedtls configuration file. + +## Integration + +### FreeRTOS threading support + +The library *`mbedtls-threading-freertos`* is implemented in the FRI to provide a threading implementation for MbedTLS using FreeRTOS threading API. + +The application must call `mbedtls_threading_set_alt()` to enable the multi threading protection. + +### Linking + +In your application's `CMakeLists.txt`, link the application executable against the `mbedtls` library alongside +any other libraries you need: + +```cmake +target_link_libraries(my-application + ... + mbedtls +) +``` + +> :bulb: Replace `my-application` with the actual name of your application. + +This not only enables the linking of the `mbedtls` static library, but also makes its API headers' include paths +available to your application. + +## Documentation + +For detailed documentation and API reference of MbedTLS, refer to the official [MbedTLS documentation][mbedtls-doc] or [GitHub repository][mbedtls-doc]. + +## Support + +If you encounter any issues or have questions regarding the integration of MbedTLS into your IoT +project, feel free to reach out to the Arm support community or consult the official documentation for +assistance. + +[mbedtls-doc]: https://mbed-tls.readthedocs.io/en/latest/ +[mbedtls-repo]: https://github.com/Mbed-TLS/mbedtls diff --git a/docs/components/security/trusted_firmware-m/trusted_firmware-m.md b/docs/components/security/trusted_firmware-m/trusted_firmware-m.md index 00a9dad7..99e5ce38 100644 --- a/docs/components/security/trusted_firmware-m/trusted_firmware-m.md +++ b/docs/components/security/trusted_firmware-m/trusted_firmware-m.md @@ -15,3 +15,115 @@ A software stack running Trusted Firmware-M consists of three executable binarie The non-secure firmware can make API calls (such as cryptography, protected storage, etc.) to the secure firmware via a library known as the NS (non-secure) interface. + +## Configuration + +You need to specify a list of Trusted Firmware-M configuration options in `ARM_CORSTONE_BSP_TARGET_PLATFORM_TFM_CMAKE_ARGS` CMake variable, for example: + +```cmake +set(ARM_CORSTONE_BSP_TARGET_PLATFORM_TFM_CMAKE_ARGS + -DMCUBOOT_LOG_LEVEL=INFO +) +``` + +> You must always set `TFM_PLATFORM` according to your target platform. For example, `arm/mps4/corstone315` is the `TFM_PLATFORM` value for Corstone-315 target. The official list of supported platforms is documented in the [TF-M Platforms] webpage. + +> Additionally, your application may require more options to be set depending on what features it needs: +> * For all available options, see the [Configuration] documentation page +> * For an example of setting multiple options, check how the `ARM_CORSTONE_BSP_TARGET_PLATFORM_TFM_CMAKE_ARGS` CMake variable is defined in [this `CMakeLists.txt`](../../../../bsp/CMakeLists.txt) + +> For our reference platforms, Corstone-315, Corstone-310, and Corstone-300, their `TFM_PLATFORM` respective values are +> `arm/mps4/corstone315`, `arm/mps3/corstone310/fvp`, `arm/mps3/corstone300/fvp`. + +## Integration + +### Build dependency + +Trusted Firmware-M must be built before your application, because your application depends on the NS interface (described in the [Overview](#overview) section) and the BL2 signing scripts, both of which are generated as parts of the Trusted Firmware-M build process. To ensure the order is correct, call `add_dependencies()` in your +`CMakeLists.txt`: + +```cmake +add_dependencies(my_application trusted_firmware-m-build) +``` + +> Replace `my_application` with the actual name of your application executable. + +### Linking + +You need to link your application against the `tfm-ns-interface` library so that your application can make API calls (such as cryptography, protected storage, etc.) to the secure firmware. + +### Image signing + +Your non-secure application image must be signed using the signing script from Trusted Firmware-M. In the signed image, the executable binary is prepended with a header area containing information such as the image size, version, checksum, signature, etc. The bootloader uses this information to validate the image during the boot process. + +To sign your application image, you can include the CMake module [`SignTfmImage`](../../../../components/security/trusted_firmware-m/integration/cmake/SignTfmImage.cmake) and call the helper function `iot_reference_arm_corstone3xx_tf_m_sign_image()` in your `CMakeLists.txt`: + +```cmake +list(APPEND CMAKE_MODULE_PATH ${IOT_REFERENCE_ARM_CORSTONE3XX_SOURCE_DIR}/components/security/trusted_firmware-m/integration/cmake) +include(SignTfmImage) + +iot_reference_arm_corstone3xx_tf_m_sign_image( + my_application + my_application_signed + ${MCUBOOT_IMAGE_VERSION_NS} + TRUE +) +``` + +This will generate a signed image, `my_application_signed.bin`, in your build directory. + +> Replace `my_application` with the actual name of your application executable. +> +> Replace `MCUBOOT_IMAGE_VERSION_NS` with a version of your choice. + +You can merge the bootloader, the secure image, the non-secure application,image, secure provisioning bundle binary, non-secure provisioning bundle binary, and DDR binary into a single `.elf` image to ease loading of the code onto the target. To do this: + +```cmake +iot_reference_arm_corstone3xx_tf_m_merge_images( + my_application + + + + +) +``` + +This will generate a merged image, `my_application_merged.elf`, in your build directory. + +> Replace `my_application` with the actual name of your application executable. Also, replace the following: +> * `NS_PROVISIONING_BUNDLE_LOAD_ADDRESS` with the actual non-secure provisioning bundle load address. +> * `location_of_non_secure_provisioning_bundle_binary` with the actual location of non-secure provisioning bundle binary. +> * `NS_DDR4_IMAGE_LOAD_ADDRESS` with the actual DDR image load address. +> * `location_of_ddr_binary` with the actual location of DDR image binary. + +### Running + +After building your application, you can run it on an FVP. For instance, if you would like to use `FVP_Corstone_SSE-315` for running an application built for `Corstone-315` target: + +* Load the merged `.elf` image, after you have called `iot_reference_arm_corstone3xx_tf_m_merge_images()` during [image signing](#image-signing). + + ```bash + FVP_Corstone_SSE-315 -a /my_application_merged.elf + ``` +> Replace `FVP_OPTIONS` with the options you wish to use with your FVP while running your application. For inspiration, please have a look on the `OPTIONS` shell variable available in the [run script](../../../../tools/scripts/run.sh). +> +> In case your application uses Arm's Virtual Streaming Interface (VSI), replace `AVH_AUDIO_OPTIONS` with the options you wish to use with your FVP while running your application with VSI feature. For inspiration, please have a look on `AVH_AUDIO_OPTIONS` shell variable available in the [run script](../../../../tools/scripts/run.sh). + +## Examples + +To see the full context of the information in the sections above, you are advised to take a look at: +* How TF-M is integrated into Arm FreeRTOS Reference Integration project using [this CMakeLists.txt](https://github.com/FreeRTOS/iot-reference-arm-corstone3xx/blob/main/components/security/trusted_firmware-m/integration/CMakeLists.txt) to generate `tfm-ns-interface` library which is linked to the desired application's executable. +* One of our reference applications [CMakeLists.txt](../../../../applications/blinky/CMakeLists.txt) + +## Documentation + +For more details of how to use Trusted Firmware-M, see its [official documentation]. + +## Support + +If you encounter any issues or have questions regarding the integration of Trusted Firmware M into your IoT project, feel free to reach out to the Arm support community or consult the official documentation for assistance. + +[Configuration]: https://tf-m-user-guide.trustedfirmware.org/configuration +[official documentation]: https://tf-m-user-guide.trustedfirmware.org/ +[TF-M Platforms]: https://tf-m-user-guide.trustedfirmware.org/platform +[Trusted Firmware-M]: https://www.trustedfirmware.org/projects/tf-m/ diff --git a/release_changes/202403221755.change b/release_changes/202403221755.change new file mode 100644 index 00000000..e02de90f --- /dev/null +++ b/release_changes/202403221755.change @@ -0,0 +1,3 @@ +mbedtls: Improve integration and simply usage of component within apps +mbedtls: Add documentation +tf-m: Update the document by adding missing sections