From ac424ebf39b787442171639bb3e4f6bf0c061e6b Mon Sep 17 00:00:00 2001 From: Ahmed Ismail Date: Mon, 23 Sep 2024 18:39:54 +0100 Subject: [PATCH] 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 --- README.md | 6 ++++-- ...unning_aws_iot_core_device_advisor_tests.md | 4 ++-- docs/applications/keyword_detection.md | 9 +++++++-- docs/applications/object_detection.md | 9 +++++++-- docs/applications/speech_recognition.md | 9 +++++++-- docs/components/aws_iot/aws_tool.md | 2 +- docs/components/security/mbedtls/mbedtls.md | 18 ++++++++++++++++++ .../vscode_dev_env_build_and_debug.md | 3 ++- 8 files changed, 48 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 36ff6c52..e533686f 100644 --- 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 index 7615462d..47bf6ac8 100644 --- 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,7 +65,7 @@ Save and close the file. To build the application, run the following command: ```bash -./tools/scripts/build.sh ${APPLICATION_NAME} --certificate_path --private_key_path --target --toolchain GNU +./tools/scripts/build.sh ${APPLICATION_NAME} --certificate_path --private_key_path --target --toolchain GNU --conn-stack --psa-crypto-implementation ``` * 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. @@ -73,7 +73,7 @@ To build the application, run the following command: Or, run the command below to perform a clean build: ```bash -./tools/scripts/build.sh ${APPLICATION_NAME} --certificate_path --private_key_path --target --toolchain GNU -c +./tools/scripts/build.sh ${APPLICATION_NAME} --certificate_path --private_key_path --target --toolchain GNU --conn-stack --psa-crypto-implementation -c ``` ## Running the application diff --git a/docs/applications/keyword_detection.md b/docs/applications/keyword_detection.md index f85e0511..04b1aaca 100644 --- a/docs/applications/keyword_detection.md +++ b/docs/applications/keyword_detection.md @@ -47,7 +47,7 @@ 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 --private_key_path --target --inference --audio --toolchain +./tools/scripts/build.sh keyword-detection --certificate_path --private_key_path --target --inference --audio --toolchain --conn-stack --psa-crypto-implementation ``` * 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. @@ -55,10 +55,15 @@ To build the Keyword-Detection example, run the following command: * 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 --private_key_path --target --inference --audio --toolchain -c +./tools/scripts/build.sh keyword-detection --certificate_path --private_key_path --target --inference --audio --toolchain --conn-stack --psa-crypto-implementation -c ``` ## Provisioning the device credentials into Protected Storage diff --git a/docs/applications/object_detection.md b/docs/applications/object_detection.md index 8b3967f3..656a9991 100644 --- 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 --private_key_path -t corstone315 --toolchain GNU +./tools/scripts/build.sh object-detection --certificate_path --private_key_path -t corstone315 --toolchain GNU --conn-stack --psa-crypto-implementation ``` - 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 --private_key_path -t corstone315 --toolchain GNU -c +./tools/scripts/build.sh object-detection --certificate_path --private_key_path -t corstone315 --toolchain GNU --conn-stack --psa-crypto-implementation -c ``` ## Provisioning the device credentials into Protected Storage diff --git a/docs/applications/speech_recognition.md b/docs/applications/speech_recognition.md index 05decf21..a6c05824 100644 --- 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 --private_key_path --target --inference ETHOS --audio --toolchain +./tools/scripts/build.sh speech-recognition --certificate_path --private_key_path --target --inference ETHOS --audio --toolchain --conn-stack --psa-crypto-implementation ``` * 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 --private_key_path --target --inference ETHOS --audio --toolchain -c +./tools/scripts/build.sh speech-recognition --certificate_path --private_key_path --target --inference ETHOS --audio --toolchain --conn-stack --psa-crypto-implementation -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 index 09ed276a..67b0190f 100644 --- 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_.pem.crt --private_key_path certificates/thing_private_key_.pem.key --target --inference --audio --toolchain +./tools/scripts/build.sh keyword-detection --certificate_path certificates/thing_certificate_.pem.crt --private_key_path certificates/thing_private_key_.pem.key --target --inference --audio --toolchain --conn-stack --psa-crypto-implementation ``` 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 index 7c58709d..4dcc01cc 100644 --- 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 `. + +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 index ecc42f29..1aa32795 100644 --- 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 --toolchain --certificate_path --private_key_path --target ---inference --audio