docs: Update documentation

Add detailed introduction and overview of the examples in README.md.
Describe how the components are put together in aws-iot-example.md.

Signed-off-by: Devaraj Ranganna <[email protected]>

Author: urutva

Docs/aws-iot-example.md

@@ -1,12 +1,49 @@
 # AWS FreeRTOS MQTT example with OTA support
 
+## Introduction
+
 This AWS FreeRTOS MQTT example demonstrates how to develop cloud connected
 applications and update them securely by integrating the modular [FreeRTOS kernel](https://www.freertos.org/RTOS.html)
 and [libraries](https://www.freertos.org/libraries/categories.html) and
 utilizing hardware enforced security based on [Arm TrustZone (Armv8-M)](https://www.arm.com/technologies/trustzone-for-cortex-m).
 This example is based on the [Corstone-300](https://developer.arm.com/Processors/Corstone-300)
 platform.
 
+### Secure TLS Connection
+
+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.
+
+[PKCS#11](https://www.freertos.org/pkcs11/index.html) APIs to perform TLS
+client authentication and import TLS client certificate and private key into
+the device. PKCS#11 has been integrated with TF-M using a thin shim. In the
+integration, the PKCS#11 APIs invoke the appropriate PSA Secure Storage API or
+Cryptographic API via the shim. This ensures the keys and certificates are
+protected and the cryptographic operations are performed securely within the
+SPE of TF-M and is isolated from the kernel, libraries and applications in the
+Non-secure Processing Environment. Keys and certificates are securely stored.
+This is enabled by TF-M’s Internal Trusted Storage (ITS) and Protected Storage
+(PS) services. Signing during TLS client authentication is performed by TF-M’s
+Crypto service.
+
+### Secure OTA Updates
+
+FreeRTOS OTA Agent provides an OTA PAL layer for platforms to integrate and
+enable OTA updates. The demo integrates and OTA PAL implementation that makes
+use of the PSA Certified Firmware Update API implemented in TF-M. This allows
+Corstone-300 to receive new images from AWS IoT Core, authenticate using TF-M
+before deploying the image as the active image. The secure (TF-M) and the
+non-secure (FreeRTOS kernel and the application) images can be updated
+separately.
+
+Every time the device boots, MCUBoot (bootloader) verifies that the image
+signature is valid before booting the image. Since the secure (TF-M) and the
+non-secure (FreeRTOS kernel and the application) images are singed separately,
+MCUBoot verifies that both image signatures are valid before booting. If either
+of the verification fails, then MCUBoot stops the booting process.
+
 ## Setting up Arm Virtual Hardware using Amazon Machine Images
 
 Follow the instructions described in [Launch Arm Virtual Hardware Instance](setting-up-arm-virtual-hardware.md)

Docs/blinky.md

@@ -1,13 +1,15 @@
 # Blinky example
 
+## Introduction
+
 This blinky example demonstrates the integration of FreeRTOS kernel and
 [TrustedFirmware-M](https://www.trustedfirmware.org/projects/tf-m/). The FreeRTOS application running on non-secure side uses
 PSA APIs to fetch the firmware framework version of TrustedFirmware-M running
 on the secure-side and prints it on the console. In addition, to simulate LED
 blinking, `LED On` and `LED off` are printed onto the console at regular
 intervals.
 
-# Setting up Arm Virtual Hardware using Amazon Machine Images
+## Setting up Arm Virtual Hardware using Amazon Machine Images
 
 Follow the instructions described in [Launch Arm Virtual Hardware Instance](setting-up-arm-virtual-hardware.md)
 to setup your development environment.
@@ -17,12 +19,12 @@ console (either AWS-Web-Console or Local-Console) to Arm Virtual Hardware
 Instance. From now on, any command-line commands described in this document
 must be run on the console connected to Arm Virtual Hardware Instance.
 
-# Setting up development environment
+## Setting up development environment
 
 Follow the instructions described in [Setting Up your Development Environment](development-environment.md)
 to setup your development environment.
 
-# Building the application
+## Building the application
 
 To build the blinky example, run the following command:
 ```bash
@@ -40,14 +42,14 @@ on AWS. If you would like to build it with the Arm GNU Toolchain (arm-none-eabi-
 [installed by yourself](./development-environment.md), append the extra option
 `--toolchain GNU` to the build command above.
 
-# Running the application
+## Running the application
 
 To run the blinky example, run the following command:
 ```bash
 ./Tools/scripts/run.sh blinky
 ```
 
-## Expected output
+### Expected output
 
 ```bash
 [INF] Starting bootloader

README.md

@@ -1,22 +1,74 @@
-# IoT Reference Integration for Corstone-3xx
+# IoT Reference Integration for Arm Corstone-3xx
 
 ## Introduction
 
 This reference integration demonstrates how to develop cloud connected
 applications and update them securely by integrating modular
 [FreeRTOS kernel](https://www.freertos.org/RTOS.html) and [libraries](https://www.freertos.org/libraries/categories.html)
 and utilizing hardware enforced security based on [Arm TrustZone (Armv8-M)](https://www.arm.com/architecture/learn-the-architecture/m-profile).
+
+To utilize the hardware enforced security, this integration uses PSA Certified
+reference implementation [Trusted Firmware-M](https://www.trustedfirmware.org/projects/tf-m/).
+Trusted Firmware-M provides various Secure services such as Secure boot, Crypto, Secure Storage,
+Attestation and Update services meeting [PSA Certified requirements](https://www.psacertified.org/blog/psa-certified-10-security-goals-explained/).
 This project is based on the [Corstone-300](https://developer.arm.com/Processors/Corstone-300)
 platform.
 
-## Arm TrustZone (Armv8-M)
+Developers and partners can use this integration as a starting point to build
+FreeRTOS kernel and libraires based software stack on top of Arm Cortex-M based
+platforms. All the components are put together in a modular manner to make
+porting of this integration across platforms easy.
+
+## Examples
 
-TrustZone technology for Armv8-M is an optional Security Extension that is
-designed to provide a foundation for improved system security in a wide range
-of embedded applications. Follow the [link](https://developer.arm.com/documentation/100690/0201/Arm-TrustZone-technology)
-for more information on TrustZone technology for Armv8-M.
+This reference integration contains following two examples:
 
-## Trusted Firmware M
+* [Blinky example](Docs/blinky.md)
+    * Demonstrates FreeRTOS kernel and TF-M integration
+* [AWS IoT example](Docs/aws-iot-example.md)
+    * Demonstrates [secure connectivity](#secure-tls-connection) to AWS IoT core using [Mbed TLS](#mbed-tls),
+      [PKCS#11 PSA Shim](#pkcs11-psa-shim) and [coreMQTT-agent](https://docs.aws.amazon.com/freertos/latest/userguide/coremqtt-agent.html)
+      library. In addition, [secure OTA](#secure-ota-updates) using [OTA agent](https://freertos.org/ota/index.html)
+      and [AWS OTA PAL PSA implementation](#aws-ota-pal-psa-implementation).
+
+### Secure TLS Connection
+
+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.
+
+[PKCS#11](https://www.freertos.org/pkcs11/index.html) APIs to perform TLS
+client authentication and import TLS client certificate and private key into
+the device. PKCS#11 has been integrated with TF-M using a thin shim. In the
+integration, the PKCS#11 APIs invoke the appropriate PSA Secure Storage API or
+Cryptographic API via the shim. This ensures the keys and certificates are
+protected and the cryptographic operations are performed securely within the
+SPE of TF-M and is isolated from the kernel, libraries and applications in the
+Non-secure Processing Environment. Keys and certificates are securely stored.
+This is enabled by TF-M’s Internal Trusted Storage (ITS) and Protected Storage
+(PS) services. Signing during TLS client authentication is performed by TF-M’s
+Crypto service.
+
+### Secure OTA Updates
+
+FreeRTOS OTA Agent provides an OTA PAL layer for platforms to integrate and
+enable OTA updates. The demo integrates and OTA PAL implementation that makes
+use of the PSA Certified Firmware Update API implemented in TF-M. This allows
+Corstone-300 to receive new images from AWS IoT Core, authenticate using TF-M
+before deploying the image as the active image. The secure (TF-M) and the
+non-secure (FreeRTOS kernel and the application) images can be updated
+separately.
+
+Every time the device boots, MCUBoot (bootloader) verifies that the image
+signature is valid before booting the image. Since the secure (TF-M) and the
+non-secure (FreeRTOS kernel and the application) images are singed separately,
+MCUBoot verifies that both image signatures are valid before booting. If either
+of the verification fails, then MCUBoot stops the booting process.
+
+## Software Components
+
+### Trusted Firmware M
 
 Trusted Firmware-M (TF-M) implements the Secure Processing Environment (SPE)
 for Armv8-M, Armv8.1-M architectures (e.g. the Cortex-M33, Cortex-M23,
@@ -26,10 +78,20 @@ 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.
 
-## PKCS#11 PSA Shim
+### Mbed TLS
+
+Project implements cryptographic primitives, X.509 certificate manipulation and
+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.
+
+### PKCS11 PSA Shim
 
-PKCS#11 PSA shim layer provides a reference implementation of PKCS#11 API based
-on [Platform Security Architecture](https://www.arm.com/architecture/psa-certified)
+[PKCS#11 PSA shim layer](https://github.com/Linaro/freertos-pkcs11-psa.git)
+provides a reference implementation of PKCS#11 API based on
+[Platform Security Architecture](https://www.arm.com/architecture/psa-certified)
 API.
 
 This shim layer maps the PKCS#11 APIs to PSA Cryptography and Storage APIs
@@ -39,22 +101,16 @@ Certificate objects and key objects are protected by PSA secure service.
 By default, the device private/public keys are persistent while the code verify
 key is volatile.
 
-## AWS OTA PAL PSA implementation
+### AWS OTA PAL PSA implementation
 
-Implementation of AWS OTA PAL based on [Platform Security Architecture](https://www.arm.com/architecture/psa-certified)
+Implementation of [AWS OTA PAL](https://github.com/Linaro/freertos-ota-pal-psa.git)
+based on [Platform Security Architecture](https://www.arm.com/architecture/psa-certified)
 API.
 
 This implementation maps the AWS OTA PAL APIs to the PSA Firmware Update and
 PSA Cryptography APIs. The writing, verification and activation of the update
 image are protected by the PSA secure services.
 
-## Examples
-
-This reference integration contains following two examples:
-
-* [Blinky example](Docs/blinky.md)
-* [AWS IoT example](Docs/aws-iot-example.md)
-
 ## Contributing
 
 See [CONTRIBUTING](CONTRIBUTING.md) for more information.