docs: Update documents to include the PSA Crypto option

Top level README.md along with applications' documents are updated to illustrate how the new PSA Crypto APIs implementation configuration option can be used, and mention the available configurations for the new option. Signed-off-by: Ahmed Ismail <[email protected]>
FreeRTOS · Sep 25, 2024 · 0d54d03 · 0d54d03
1 parent 832b5d2
commit 0d54d03
Show file tree

Hide file tree

Showing 8 changed files with 48 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -73,8 +73,10 @@ and [AWS OTA PAL PSA implementation](#aws-ota-pal-psa-implementation) can be per
 
 Corstone platform communicates with the AWS IoT Core over a secure TLS
 connection. Mbed TLS running on the NSPE is used to establish the TLS
-connection. Mbed TLS makes use of the PSA Crypto APIs provided by TF-M for
-Crypto operations.
+connection. For crypto operations, Mbed TLS supports PSA Crypto APIs provided by either
+the Mbed TLS itself or the Trusted Firmware-M and the default is
+PSA Crypto API from Trusted Firmware-M. For more information about the PSA Crypto APIs
+implementation, please refer to [Mbed TLS document](docs/components/security/mbedtls/mbedtls.md#psa-crypto-apis-implementation).
 
 [PKCS#11](https://www.freertos.org/pkcs11/index.html) APIs to perform TLS
 client authentication and import TLS client certificate and private key into

diff --git a/docs/applications/device_advisor/running_aws_iot_core_device_advisor_tests.md b/docs/applications/device_advisor/running_aws_iot_core_device_advisor_tests.md
@@ -65,15 +65,15 @@ Save and close the file.
 To build the application, run the following command:
 
 ```bash
-./tools/scripts/build.sh ${APPLICATION_NAME} --certificate_path <certificate pem's path> --private_key_path <private key pem's path> --target <corstone300/corstone310/corstone315> --toolchain GNU
+./tools/scripts/build.sh ${APPLICATION_NAME} --certificate_path <certificate pem's path> --private_key_path <private key pem's path> --target <corstone300/corstone310/corstone315> --toolchain GNU --conn-stack <FREERTOS_PLUS_TCP/IOT_VSOCKET> --psa-crypto-implementation <TF-M/MBEDTLS>
 ```
 
 * The `certificate pem's path` and `private key pem's path` should be the downloaded key's and certificate's paths during the Thing creation.
 
 Or, run the command below to perform a clean build:
 
 ```bash
-./tools/scripts/build.sh ${APPLICATION_NAME} --certificate_path <certificate pem's path> --private_key_path <private key pem's path> --target <corstone300/corstone310/corstone315> --toolchain GNU -c
+./tools/scripts/build.sh ${APPLICATION_NAME} --certificate_path <certificate pem's path> --private_key_path <private key pem's path> --target <corstone300/corstone310/corstone315> --toolchain GNU --conn-stack <FREERTOS_PLUS_TCP/IOT_VSOCKET> --psa-crypto-implementation <TF-M/MBEDTLS> -c
 ```
 
 ## Running the application

diff --git a/docs/applications/keyword_detection.md b/docs/applications/keyword_detection.md
@@ -47,18 +47,23 @@ Follow the instructions described in [Setting Up AWS Connectivity](./aws_iot/set
 To build the Keyword-Detection example, run the following command:
 
 ```bash
-./tools/scripts/build.sh keyword-detection --certificate_path <certificate pem's path> --private_key_path <private key pem's path> --target <corstone300/corstone310/corstone315> --inference <ETHOS/SOFTWARE> --audio <ROM/VSI> --toolchain <ARMCLANG/GNU>
+./tools/scripts/build.sh keyword-detection --certificate_path <certificate pem's path> --private_key_path <private key pem's path> --target <corstone300/corstone310/corstone315> --inference <ETHOS/SOFTWARE> --audio <ROM/VSI> --toolchain <ARMCLANG/GNU> --conn-stack <FREERTOS_PLUS_TCP/IOT_VSOCKET> --psa-crypto-implementation <TF-M/MBEDTLS>
 ```
 * The `certificate pem's path` and `private key pem's path` should be the downloaded key's and certificate's path if you chose the **Auto-generate a new certificate** during the Thing creation. If you chose **Skip creating a certificate at this time** then these paths should locate the generated credential files that were created by the `./tools/scripts/generate_credentials.py` script in the previous step.
 
 * The `inference` is used to select the inference type whether it's `ETHOS` or `SOFTWARE`.
 
 * The `audio` is used to select the input audio source whether it's preloaded into `ROM` or using Arm's Virtual Streaming Interface `VSI`.
 
+* The `conn-stack` is used to select the connectivity stack to be used whether it's `FREERTOS_PLUS_TCP` or `IOT_VSOCKET`.
+
+* The `psa-crypto-implementation` is used to select the library providing the PSA Crypto APIs implementation whether it's `TF-M` or `MBEDTLS`. For more information about the PSA Crypto APIs
+implementation, please refer to [Mbed TLS document](../components/security/mbedtls/mbedtls.md#psa-crypto-apis-implementation).
+
 Or, run the command below to perform a clean build:
 
 ```bash
-./tools/scripts/build.sh keyword-detection --certificate_path <certificate pem's path> --private_key_path <private key pem's path> --target <corstone300/corstone310/corstone315> --inference <ETHOS/SOFTWARE> --audio <ROM/VSI> --toolchain <ARMCLANG/GNU> -c
+./tools/scripts/build.sh keyword-detection --certificate_path <certificate pem's path> --private_key_path <private key pem's path> --target <corstone300/corstone310/corstone315> --inference <ETHOS/SOFTWARE> --audio <ROM/VSI> --toolchain <ARMCLANG/GNU> --conn-stack <FREERTOS_PLUS_TCP/IOT_VSOCKET> --psa-crypto-implementation <TF-M/MBEDTLS> -c
 ```
 
 ## Provisioning the device credentials into Protected Storage

diff --git a/docs/applications/object_detection.md b/docs/applications/object_detection.md
@@ -25,15 +25,20 @@ Follow the instructions described in [Setting Up AWS Connectivity](./aws_iot/set
 
 To build the Object-Detection example, run the following command:
 ```bash
-./tools/scripts/build.sh object-detection --certificate_path <certificate pem's path> --private_key_path <private key pem's path> -t corstone315 --toolchain GNU
+./tools/scripts/build.sh object-detection --certificate_path <certificate pem's path> --private_key_path <private key pem's path> -t corstone315 --toolchain GNU --conn-stack <FREERTOS_PLUS_TCP/IOT_VSOCKET> --psa-crypto-implementation <TF-M/MBEDTLS>
 ```
 - The `certificate pem's path` and `private key pem's path` should be the downloaded key's and certificate's path if you chose the **Auto-generate a new certificate** during the Thing creation. If you chose **Skip creating a certificate at this time** then these paths should locate the generated credential files that were created by the `./tools/scripts/generate_credentials.py` script in the previous step.
 
 - The `toolchain` is used to select the `GNU`, that supports the `Mali-C55`.
 
+* The `conn-stack` is used to select the connectivity stack to be used whether it's `FREERTOS_PLUS_TCP` or `IOT_VSOCKET`.
+
+* The `psa-crypto-implementation` is used to select the library providing the PSA Crypto APIs implementation whether it's `TF-M` or `MBEDTLS`. For more information about the PSA Crypto APIs
+implementation, please refer to [Mbed TLS document](../components/security/mbedtls/mbedtls.md#psa-crypto-apis-implementation).
+
 Or, run the command below to perform a clean build:
 ```bash
-./tools/scripts/build.sh object-detection --certificate_path <certificate pem's path> --private_key_path <private key pem's path> -t corstone315 --toolchain GNU -c
+./tools/scripts/build.sh object-detection --certificate_path <certificate pem's path> --private_key_path <private key pem's path> -t corstone315 --toolchain GNU --conn-stack <FREERTOS_PLUS_TCP/IOT_VSOCKET> --psa-crypto-implementation <TF-M/MBEDTLS> -c
 ```
 
 ## Provisioning the device credentials into Protected Storage

diff --git a/docs/applications/speech_recognition.md b/docs/applications/speech_recognition.md
@@ -27,16 +27,21 @@ Follow the instructions described in [Setting Up AWS Connectivity](./aws_iot/set
 To build the Speech-Recognition example, run the following command:
 
 ```bash
-./tools/scripts/build.sh speech-recognition --certificate_path <certificate pem's path> --private_key_path <private key pem's path> --target <corstone300/corstone310/corstone315> --inference ETHOS --audio <ROM/VSI> --toolchain <ARMCLANG/GNU>
+./tools/scripts/build.sh speech-recognition --certificate_path <certificate pem's path> --private_key_path <private key pem's path> --target <corstone300/corstone310/corstone315> --inference ETHOS --audio <ROM/VSI> --toolchain <ARMCLANG/GNU> --conn-stack <FREERTOS_PLUS_TCP/IOT_VSOCKET> --psa-crypto-implementation <TF-M/MBEDTLS>
 ```
 * The `certificate pem's path` and `private key pem's path` should be the downloaded key's and certificate's path if you chose the **Auto-generate a new certificate** during the Thing creation. If you chose **Skip creating a certificate at this time** then these paths should locate the generated credential files that were created by the `./tools/scripts/generate_credentials.py` script in the previous step.
 
 * The `audio` is used to select the input audio source whether it's preloaded into `ROM` or using Arm's Virtual Streaming Interface `VSI`.
 
+* The `conn-stack` is used to select the connectivity stack to be used whether it's `FREERTOS_PLUS_TCP` or `IOT_VSOCKET`.
+
+* The `psa-crypto-implementation` is used to select the library providing the PSA Crypto APIs implementation whether it's `TF-M` or `MBEDTLS`. For more information about the PSA Crypto APIs
+implementation, please refer to [Mbed TLS document](../components/security/mbedtls/mbedtls.md#psa-crypto-apis-implementation).
+
 Or, run the command below to perform a clean build:
 
 ```bash
-./tools/scripts/build.sh speech-recognition --certificate_path <certificate pem's path> --private_key_path <private key pem's path> --target <corstone300/corstone310/corstone315> --inference ETHOS --audio <ROM/VSI> --toolchain <ARMCLANG/GNU> -c
+./tools/scripts/build.sh speech-recognition --certificate_path <certificate pem's path> --private_key_path <private key pem's path> --target <corstone300/corstone310/corstone315> --inference ETHOS --audio <ROM/VSI> --toolchain <ARMCLANG/GNU> --conn-stack <FREERTOS_PLUS_TCP/IOT_VSOCKET> --psa-crypto-implementation <TF-M/MBEDTLS> -c
 ```
 
 ## Provisioning the device credentials into Protected Storage

diff --git a/docs/components/aws_iot/aws_tool.md b/docs/components/aws_iot/aws_tool.md
@@ -96,7 +96,7 @@ You may now use MQTT to send and receive message for that device. See section [O
 
 You may now rebuild keyword with those certificates:
 ```sh
-./tools/scripts/build.sh keyword-detection --certificate_path certificates/thing_certificate_<your_thing_name>.pem.crt --private_key_path certificates/thing_private_key_<your_thing_name>.pem.key --target <corstone300/corstone310/corstone315> --inference <ETHOS/SOFTWARE> --audio <ROM/VSI> --toolchain <ARMCLANG/GNU>
+./tools/scripts/build.sh keyword-detection --certificate_path certificates/thing_certificate_<your_thing_name>.pem.crt --private_key_path certificates/thing_private_key_<your_thing_name>.pem.key --target <corstone300/corstone310/corstone315> --inference <ETHOS/SOFTWARE> --audio <ROM/VSI> --toolchain <ARMCLANG/GNU> --conn-stack <FREERTOS_PLUS_TCP/IOT_VSOCKET> --psa-crypto-implementation <TF-M/MBEDTLS>
 ```
 Next, we'll create the bucket, upload the binary there, create a role capable of running an OTA update, and create the update. All of those with the following command:
 ```sh

diff --git a/docs/components/security/mbedtls/mbedtls.md b/docs/components/security/mbedtls/mbedtls.md
@@ -38,6 +38,24 @@ target_compile_definitions(mbedtls-config
 
 To enable the FreeRTOS threading protection `#define MBEDTLS_THREADING_ALT` should be present in the user provided mbedtls configuration file.
 
+### PSA Crypto APIs Implementation
+
+PSA Crypto is part of Platform Security Architecture initiative that standardized crypto interfaces. The PSA Crypto specification is available [here](https://arm-software.github.io/psa-api/crypto/1.1/). Mbed TLS, and Trusted Firmware-M libraries provide implementation for PSA Crypto APIs.
+
+User can choose which library is to be used for implementing PSA Crypto APIs used by Mbed TLS library running on the Non-Secure side through the build option `--psa-crypto-implementation <TF-M/MBEDTLS>`.
+
+The default PSA Crypto APIs implementation is the one provided by Trusted Firmware-M library, where the `--psa-crypto-implementation` build option default value is `TF-M`.
+
+In case of using Trusted Firmware-M as the PSA Crypto APIs implementation, `tfm-ns-interface` library has to be linked to the `mbedtls` target.
+
+```cmake
+target_link_libraries(mbedtls
+    PUBLIC
+        mbedtls-config
+        tfm-ns-interface
+)
+```
+
 ## Integration
 
 ### FreeRTOS threading support

diff --git a/docs/development_environment/vscode_dev_env_build_and_debug.md b/docs/development_environment/vscode_dev_env_build_and_debug.md
@@ -129,7 +129,8 @@ Command Palette (F1)
 ./tools/scripts/build.sh <reference application name> --toolchain <GNU/ARMCLANG>
 --certificate_path <certificate pem's path>
 --private_key_path <private key pem's path> --target <target name>
---inference <inference engine> --audio <audio input>
+--inference <inference engine> --audio <audio input> --conn-stack <connectivity stack>
+--psa-crypto-implementation <library providing PSA Crypto APIs implementation>
 ```
 
 ## Running a reference application