PSA core 5.12

.gitignore

@@ -1 +1,3 @@
 tags
+.DS_Store
+.idea/

docs/api/security/lifecycle/generate_png.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+dot -Tpng psa_lifecycle.dot -o psa_lifecycle.png

docs/api/security/lifecycle/psa_lifecycle.dot

@@ -0,0 +1,11 @@
+digraph {
+ PSA_LIFECYCLE_ASSEMBLY_AND_TEST -> PSA_LIFECYCLE_ASSEMBLY_AND_TEST [label=<<font color='red'><b>ITS reset</b></font>>];
+ PSA_LIFECYCLE_ASSEMBLY_AND_TEST -> PSA_LIFECYCLE_PSA_ROT_PROVISIONING [style=dashed, color=grey, label=<<font color='red'><b>ITS reset</b></font> and reboot>];
+ PSA_LIFECYCLE_PSA_ROT_PROVISIONING -> PSA_LIFECYCLE_SECURED [style=dashed, color=grey, label="reboot"];
+ PSA_LIFECYCLE_SECURED -> PSA_LIFECYCLE_NON_PSA_ROT_DEBUG [style=dashed, color=grey, label="reboot"];
+ PSA_LIFECYCLE_SECURED -> PSA_LIFECYCLE_RECOVERABLE_PSA_ROT_DEBUG [style=dashed, color=grey, label="reboot"];
+ PSA_LIFECYCLE_SECURED -> PSA_LIFECYCLE_DECOMMISSIONED [style=dashed, color=grey, label="reboot"];
+
+ PSA_LIFECYCLE_NON_PSA_ROT_DEBUG -> PSA_LIFECYCLE_SECURED [style=dashed, color=grey, label="reboot"];
+ PSA_LIFECYCLE_RECOVERABLE_PSA_ROT_DEBUG -> PSA_LIFECYCLE_SECURED [style=dashed, color=grey, label="reboot"];
+}

docs/api/security/lifecycle/psa_lifecycle.md

@@ -0,0 +1,28 @@
+## PSA lifecycle
+
+
+### Description
+
+PSA Lifecycle allows fine grained control over target RoT without compromising on developer experience.
+PSA Lifecycle can be described by following state machine:
+
+![lifecycle](./psa_lifecycle.png)
+
+<span class="notes"> **Note:**
+PSA Lifectcle is not a standalone feature as it depends on a PSA bootloader support, which is not yet introduced to mbed-os.
+The only supported lifecycle change available at the moment is `PSA_LIFECYCLE_ASSEMBLY_AND_TEST` to `PSA_LIFECYCLE_ASSEMBLY_AND_TEST`, which can be used for tests to reset device RoT state.
+All the dashed edges are not implemented.
+</span>
+
+Lifecycle can be specified during build time by `MBED_CONF_LIFECYCLE_STATE` macro. Default value is `PSA_LIFECYCLE_ASSEMBLY_AND_TEST`.
+
+In mbed-os PSA Lifecycle is implemented as part of [platform service](../platform_servcie.md)
+
+### Specification
+
+More details can be found in [Platform Security Architecture - Firmware Framework ](https://pages.arm.com/psa-resources-ff.html)
+
+
+###Doxygen:
+
+[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/lifecycle_8h.html)

docs/api/security/platform_service.md

@@ -0,0 +1,9 @@
+## Platfrom Service
+
+### Description
+Platform service introduces system reset and PSA Lifecycle APIs.
+System reset API can be used to request system reset from NSPE.
+
+### Doxygen
+
+[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/lifecycle_8h.html)

docs/api/security/psa_attestation.md

@@ -0,0 +1,19 @@
+## PSA Attestation
+
+### Description
+
+TODO: AlexV
+
+
+### Specification
+TODO: AlexV - describe here about APIs and the difference in behavior whether bootlaoder is present or not
+
+PSA specification can be found here [PSA Secure Storage](https://pages.arm.com/PSA-APIs)
+
+### Doxygen
+
+TODO: AlexV - find PSA attestation APIs in doxygen web site once merged - perhaps will be generated over night.
+ if it is conditionally compiled under some ifdef make sure to add it to doxyfile_options
+ Once addded Doxygen will be generate - perhaps on next day fix the link below
+
+[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/psa__prot__internal__storage_8h.html)

docs/api/security/psa_crypto.md

@@ -0,0 +1,20 @@
+## PSA Crypto
+
+### Description
+
+TODO: Jaeden
+
+
+### Specification
+TODO: Jaeden - describe here about APIs being available from NSPE and SPE
+about differences in behaviour if any
+
+PSA specification can be found here [PSA Secure Storage](https://pages.arm.com/PSA-APIs)
+
+### Doxygen
+
+TODO: Jaeden - find PSA crypto APIs in doxygen web site. I was not able to find it. 
+ Perhaps MBED_TLS_PSA_CRYPTO_C macro should be added doxyfile_options file so PSA crypto docs will be generated 
+ Once addded Doxygen will be generate - perhaps on next day fix the link below
+
+[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/psa__prot__internal__storage_8h.html)

docs/api/security/psa_internal_storage.md

@@ -0,0 +1,20 @@
+## PSA Internal Storage
+
+### Description
+
+PSA internal storage APIs allows saving and retrieving data from PSA internal flash.
+
+PSA internal storage is implementation varies depending on the target type:
+- on single core ARMv7-M target it PSA internal storage APIs are implemented by calling to "default" internal TDBStore instance.
+- on PSA targets implementing SPM, PSA internal storage implemented as a secure service. PSA internal storage has access control list, 
+ which makes sure that only the entries created from NSPE will be accessible to it.
+
+### Specification
+
+API specification in mbed-os specific context can be found here: [mbed-os/Storage](../../storage/storage.md) 
+
+PSA specification can be found here [PSA Secure Storage](https://pages.arm.com/PSA-APIs)
+
+### Doxygen
+
+[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/psa__prot__internal__storage_8h.html)

docs/api/security/psa_protected_storage.md

@@ -0,0 +1,19 @@
+## PSA Protected Storage
+
+### Description
+
+PSA Protected storage APIs allows saving and retrieving data from PSA protected storage.
+
+Unlike [PSA Internal storage](./psa_internal_storage.md), PSA Protected storage implemented to always run in NSPE side and redirect the calls to KVStore instance.
+
+TODO: Danniel Benor - review and add links to this page from Storage landing page 
+
+### Specification
+
+API specification in mbed-os specific context can be found here: [mbed-os/Storage](../../storage/storage.md) 
+
+PSA specification can be found here [PSA Secure Storage](https://pages.arm.com/PSA-APIs)
+
+### Doxygen
+
+[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/protected__storage_8h.html)

docs/api/security/security.md

@@ -2,10 +2,20 @@
 
 Security on Arm Mbed OS is divided into the following parts:
 
-- Platform Security Architecture (PSA). For information about working with PSA in the context of Mbed OS, please see [Mbed PSA asset protection](../apis/psa-api.html).
+- [PSA SPM](./spm.md) - used for accessing secure services within Secure Processing environment (on PSA targets only)
 
- For full details, please see the [PSA site](https://developer.arm.com/products/architecture/security-architectures/platform-security-architecture).
+- [PSA internal storage](./psa_internal_storage.md) - used to save PSA RoT state
+
+- [PSA protected storage](./psa_protected_storage.md)
+
+- [PSA Crypto](psa_crypto.md) 
 
 - Mbed TLS. For information about working with Mbed TLS in the context of Mbed OS, please see [Connection security through Arm Mbed TLS](../apis/tls.html).
 
  For full details, please see the [Mbed TLS site](https://tls.mbed.org/).
+
+- [[PSA Attestation](psa_attestation.md)
+
+- [PSA Lifecycle](./lifecycle/psa_lifecycle.md)
+
+- [Device Key](./DeviceKey.md)

docs/api/security/spm.md

@@ -0,0 +1,13 @@
+## SPM APIs
+
+### Description
+
+PSA SPM APIs are used for calling Secure Services within Secure Processing environment
+
+### Specification
+
+More details can be found in [Platform Security Architecture - Firmware Framework ](https://pages.arm.com/psa-resources-ff.html)
+
+### Doxygen
+
+[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/group___s_p_m.html)

docs/porting/psa/spm.md

@@ -6,8 +6,19 @@ For more information about SPM, please refer to [the SPM overview page](../apis/
 
 <span class="notes">This page gives guidelines for silicon partners adding SPM capabilities.</span>
 
+mbed-os 
+
 ### New target configuration
 
+#### Platform types
+
+- Non-PSA platform: These are single core ARMv7-M targets. On these targets, the Mbed implementation of PSA provides the same PSA services exposing PSA APIs as it would on PSA targets. The PSA emulation layer allows seamless software portability to more security-oriented targets.
+- Asymmetric Multiprocessing (AMP) systems: Multicore ARMv7-M targets (for example, PSoC6 featuring CM4 and CM0+ cores). On these targets, one of the cores is dedicated to PSA use only and implements SPE.
+- ARMv8-M: Generation of ARM processors featuring TrustZone-M architecture. PSA support for this platforms is based on *specialized* [TrustedFirmware-M](https://www.trustedfirmware.org) implementation.
+
+
+#### JSON target definition
+
 When adding a new target, add a new root target node to the `mbed-os/targets/targets.json` file. For PSA support, define specific PSA-related fields for this target:
 
 - A secure target must inherit from `SPE_Target` metatarget.
@@ -17,7 +28,7 @@ When adding a new target, add a new root target node to the `mbed-os/targets/tar
  - Both targets must override the default configuration by specifying flash RAM and shared RAM regions. The [memory layout section](#memory-layout) explains this in more detail.
  - The secure target must declare its corresponding nonsecure target using the `deliver_to_target` field.
 
-The example below demonstrates this:
+The example below demonstrates:
 
 ```json
 "SPM_SECURE_CORE_PSA": {
@@ -55,6 +66,20 @@ The example below demonstrates this:
  }
 ```
 
+Following flags & Labels are should be added to each target type to add right version of source files to a compilation:
+
+| Label \ Core | V7-single<br>(Target) | V7-dual NSPE<br>(NSPE_Target) | V7-dual SPE<br>(SPE_Target) | V8-NS<br>(NSPE_Target) | V8-S<br>(SPE_Target) |
+| ---------------------- |:---------------------:|:-----------------------------:|:---------------------------:|:----------------------:|:--------------------:|
+| component: `PSA_SRV_IMPL` | V | | V | | V |
+| component: `PSA_SRV_EMUL` | V | | | | |
+| component: `PSA_SRV_IPC` | | V | V | V | V |
+| component: `SPE` | | | V | | V |
+| component: `NSPE` | V | V | | V | |
+| component: `SPM_MAILBOX` | | V | V | | |
+| label: `MBED_SPM` | | V | V | | |
+| label: `TFM` | | | | V | V |
+
+
 #### Memory layout
 
 Typically, PSA platforms share the same RAM and flash between secure and nonsecure cores. To provide PSA isolation level 1 or higher, you need to partition both RAM and flash to secure and nonsecure parts, in a way the following image describes:
@@ -78,7 +103,7 @@ To achieve RAM and flash partitioning, you must add start and size values to a t
 
 <span class="notes">**Note:** For isolation levels higher than 1, on top of the partitioning between secure and nonsecure parts, secure flash and RAM must have an inner level of partitioning, creating sections per secure partition.</span>
 
-### Linker scripts
+### Linker scripts concepts
 
 Linker scripts must include `MBED_ROM_START`, `MBED_ROM_SIZE`, `MBED_RAM_START` and `MBED_RAM_START` macros for defining memory regions. You can define a shared memory region by reserving RAM space for shared memory use. The shared memory location is target specific and depends on the memory protection scheme applied.
 
@@ -186,22 +211,7 @@ define symbol __ICFEDIT_region_IROM1_end__ = (MBED_ROM_START + MBED_ROM_SIZE);
 ...
 ```
 
-### Mailbox
-
-Mailbox is the mechanism used to implement IPC and is **only relevant for multicore systems**. SPM uses mailbox to communicate with secure partitions from a nonsecure processing environment.
-
-#### Concepts
-
-The mailbox mechanism is based on message queues and dispatcher threads. Each core has a single dispatcher thread and a single message queue. The dispatcher thread waits on a mailbox event. Once this event occurs, the dispatcher thread reads and runs "tasks" accumulated on its local message queue.
-
-#### Requirements
-
-The SPM mailbox mechanism requires the platform to have the following capabilities:
-
-- IPC capabilities - the ability to notify the peer processor about an event (usually implemented with interrupts).
-- Ability to set a RAM section shared between the cores.
-
-#### Porting
+### Mbed-SPM porting (Asymmetric Multiprocessing systems - Multicore ARMv7-M)
 
 These are the guidelines you should follow if you have multicore systems:
 
@@ -211,7 +221,7 @@ These are the guidelines you should follow if you have multicore systems:
 - For each core, implement the HAL function that notifies the peer processor about a mailbox event occurrence. This is a part of the HAL, and the section below explains this in more detail.
 - For each core, add the `SPM_MAILBOX` component field for its target node in the `mbed-os/targets/targets.json` file.
 
-### HAL functions
+#### HAL functions
 
 Target-specific code of silicon partners adding SPM capabilities must:
 
@@ -220,10 +230,24 @@ Target-specific code of silicon partners adding SPM capabilities must:
 
 The HAL can be logically divided into two different fields:
 
-#### Mailbox
 
-This part of HAL allows you to implement a thin layer of the mailbox mechanism that is specific to your platform. You must only implement it if you have multicore systems.
+#### Mailbox 
+
+Mailbox is the mechanism used to implement IPC and is **only relevant for multicore systems**. SPM uses mailbox to communicate with secure partitions from a nonsecure processing environment.
+
+##### Concepts
+
+The mailbox mechanism is based on message queues and dispatcher threads. Each core has a single dispatcher thread and a single message queue. The dispatcher thread waits on a mailbox event. Once this event occurs, the dispatcher thread reads and runs "tasks" accumulated on its local message queue.
+
+##### Requirements
+
+The SPM mailbox mechanism requires the platform to have the following capabilities:
+
+- IPC capabilities - the ability to notify the peer processor about an event (usually implemented with interrupts).
+- Ability to set a RAM section shared between the cores.
+
 
+This part of HAL allows you to implement a thin layer of the mailbox mechanism that is specific to your platform.
 #### Secure Processing Environment
 
 This part of HAL allows you to apply your specific memory protection scheme. You can find a list of [these functions](https://os.mbed.com/docs/development/mbed-os-api-doxy/group___s_p_m.html).
@@ -248,6 +272,12 @@ Processor access |Secure RAM |Secure FLASH|Nonsecure RAM |Nonsecu
 `Secure Write` | V | V | V | ?
 `Secure Execute` | X? | V | X | ?
 
+
+### TF-M SPM porting for (ARMv8-M targets)
+
+TF-M HAL functions are defined in `tfm_spm_hal.h`
+
+
 ### Testing
 
 Arm provides a list of tests to check that the HAL functions are implemented according to requirements, and the porting is done correctly.

docs/api/security/psa.md → docs/reference/technology/psa/psa.md

@@ -32,11 +32,14 @@ The Mbed implementation of PSA supports the following platform types:
 
 - Asymmetric Multiprocessing (AMP) systems: Multicore ARMv7-M targets (for example, PSoC6 featuring CM4 and CM0+ cores). On these targets, one of the cores is dedicated to PSA use only and implements SPE. The Mbed implementation of PSA provides PSA API proxy implementation on a nonsecure core, which redirects execution to the SPE.
 
-- ARMv8-M: Generation of ARM processors featuring TrustZone-M architecture. PSA support for this platforms is in final stages of development and will be added to the list of platforms supported by the Mbed implementation of PSA shortly.
+- ARMv8-M: Generation of ARM processors featuring TrustZone-M architecture. PSA support for this platforms is based on *specialized* [TrustedFirmware-M](https://www.trustedfirmware.org) implementation.
 
 ### RoT services
 
 The Mbed implementation of PSA provides the following services:
 
 - PSA [RoT](../introduction/glossary.html) internal storage.
 - [PSA Crypto APIs (on GitHub)](https://github.com/ARMmbed/mbed-crypto/tree/development/docs).
+- PSA Attestation - TBD
+- [PSA Lifecycle](./lifecycle/psa_lifecycle.md)
+- [PSA Platform service](./platform_service.md)