From 0f33d991e6ec53c3aaebebedd9db082d7968bc7c Mon Sep 17 00:00:00 2001 From: Alexander Zilberkant Date: Thu, 28 Feb 2019 11:47:16 +0200 Subject: [PATCH 01/38] PSA core 5.12 docs add psa_lifecycle description add psa_platform description add TF-M porting guide extend porting guide with targets and labels description --- docs/api/security/lifecycle/generate_png.sh | 3 + docs/api/security/lifecycle/psa_lifecycle.dot | 11 +++ docs/api/security/lifecycle/psa_lifecycle.md | 18 +++++ docs/api/security/lifecycle/psa_lifecycle.png | Bin 0 -> 73977 bytes docs/api/security/platform_service.md | 6 ++ docs/api/security/psa.md | 5 +- docs/porting/psa/spm.md | 72 +++++++++++++----- 7 files changed, 93 insertions(+), 22 deletions(-) create mode 100755 docs/api/security/lifecycle/generate_png.sh create mode 100644 docs/api/security/lifecycle/psa_lifecycle.dot create mode 100644 docs/api/security/lifecycle/psa_lifecycle.md create mode 100644 docs/api/security/lifecycle/psa_lifecycle.png create mode 100644 docs/api/security/platform_service.md diff --git a/docs/api/security/lifecycle/generate_png.sh b/docs/api/security/lifecycle/generate_png.sh new file mode 100755 index 0000000000..5f48ebae6b --- /dev/null +++ b/docs/api/security/lifecycle/generate_png.sh @@ -0,0 +1,3 @@ +#!/usr/bin/env bash + +dot -Tpng psa_lifecycle.dot -o psa_lifecycle.png \ No newline at end of file diff --git a/docs/api/security/lifecycle/psa_lifecycle.dot b/docs/api/security/lifecycle/psa_lifecycle.dot new file mode 100644 index 0000000000..215cae34ad --- /dev/null +++ b/docs/api/security/lifecycle/psa_lifecycle.dot @@ -0,0 +1,11 @@ +digraph { + PSA_LIFECYCLE_ASSEMBLY_AND_TEST -> PSA_LIFECYCLE_ASSEMBLY_AND_TEST [label=<ITS reset>]; + PSA_LIFECYCLE_ASSEMBLY_AND_TEST -> PSA_LIFECYCLE_PSA_ROT_PROVISIONING [style=dashed, color=grey, label=<ITS reset 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"]; +} \ No newline at end of file diff --git a/docs/api/security/lifecycle/psa_lifecycle.md b/docs/api/security/lifecycle/psa_lifecycle.md new file mode 100644 index 0000000000..c16518ed29 --- /dev/null +++ b/docs/api/security/lifecycle/psa_lifecycle.md @@ -0,0 +1,18 @@ +

PSA lifecycle reference API

+ +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) + + **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. + + +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) + +TODO: link to doxygen \ No newline at end of file diff --git a/docs/api/security/lifecycle/psa_lifecycle.png b/docs/api/security/lifecycle/psa_lifecycle.png new file mode 100644 index 0000000000000000000000000000000000000000..9d90e6ce972f85bedd04c2e8d63640bd148b835a GIT binary patch literal 73977 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 QLx6u?%d5*($ykK^4+lC7*Z=?k literal 0 HcmV?d00001 diff --git a/docs/api/security/platform_service.md b/docs/api/security/platform_service.md new file mode 100644 index 0000000000..a53c4d17aa --- /dev/null +++ b/docs/api/security/platform_service.md @@ -0,0 +1,6 @@ +

Platfrom Service API

+ +Platform service introduces system reset and PSA Lifecycle APIs. +PSA platform service may be extended by target vendors to expose target peripherals only accessible from secure side. + +Todo: link to doxygen \ No newline at end of file diff --git a/docs/api/security/psa.md b/docs/api/security/psa.md index e27bec41fb..c6aaa66228 100644 --- a/docs/api/security/psa.md +++ b/docs/api/security/psa.md @@ -32,7 +32,7 @@ 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 @@ -40,3 +40,6 @@ 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) diff --git a/docs/porting/psa/spm.md b/docs/porting/psa/spm.md index 0bf926d233..556a949a44 100644 --- a/docs/porting/psa/spm.md +++ b/docs/porting/psa/spm.md @@ -6,8 +6,19 @@ For more information about SPM, please refer to [the SPM overview page](../apis/ This page gives guidelines for silicon partners adding SPM capabilities. +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
(Target) | V7-dual NSPE
(NSPE_Target) | V7-dual SPE
(SPE_Target) | V8-NS
(NSPE_Target) | V8-S
(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 **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. -### 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. From 1ad712c72d47a139513b6a1e62d4e39b585f4fb8 Mon Sep 17 00:00:00 2001 From: Alexander Zilberkant Date: Thu, 28 Feb 2019 11:50:11 +0200 Subject: [PATCH 02/38] update .gitignore --- .gitignore | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.gitignore b/.gitignore index 6e92f57d46..64f41bd5cd 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,3 @@ tags +.DS_Store +.idea/ From e4af98d92df188c9a5e90d1b638ab3b8871b4643 Mon Sep 17 00:00:00 2001 From: Alexander Zilberkant Date: Sat, 2 Mar 2019 21:51:06 +0200 Subject: [PATCH 03/38] rearrange docs according to docs sync meeting --- docs/api/security/psa_attestation.md | 19 ++++++++++++++++++ docs/api/security/psa_crypto.md | 20 +++++++++++++++++++ docs/api/security/psa_internal_storage.md | 20 +++++++++++++++++++ docs/api/security/psa_protected_storage.md | 19 ++++++++++++++++++ docs/api/security/security.md | 14 +++++++++++-- docs/api/security/spm.md | 13 ++++++++++++ docs/api/security/trusted_storage.md | 3 --- .../technology/psa}/psa.md | 0 8 files changed, 103 insertions(+), 5 deletions(-) create mode 100644 docs/api/security/psa_attestation.md create mode 100644 docs/api/security/psa_crypto.md create mode 100644 docs/api/security/psa_internal_storage.md create mode 100644 docs/api/security/psa_protected_storage.md create mode 100644 docs/api/security/spm.md delete mode 100644 docs/api/security/trusted_storage.md rename docs/{api/security => reference/technology/psa}/psa.md (100%) diff --git a/docs/api/security/psa_attestation.md b/docs/api/security/psa_attestation.md new file mode 100644 index 0000000000..f0be15a623 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/api/security/psa_crypto.md b/docs/api/security/psa_crypto.md new file mode 100644 index 0000000000..470e3c57a0 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/api/security/psa_internal_storage.md b/docs/api/security/psa_internal_storage.md new file mode 100644 index 0000000000..7bb5f6f5fc --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/api/security/psa_protected_storage.md b/docs/api/security/psa_protected_storage.md new file mode 100644 index 0000000000..4e9e03af9a --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/api/security/security.md b/docs/api/security/security.md index 09c84749bf..51d0a71ee9 100644 --- a/docs/api/security/security.md +++ b/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) diff --git a/docs/api/security/spm.md b/docs/api/security/spm.md new file mode 100644 index 0000000000..5023f9ca7c --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/api/security/trusted_storage.md b/docs/api/security/trusted_storage.md deleted file mode 100644 index fc4ab0003c..0000000000 --- a/docs/api/security/trusted_storage.md +++ /dev/null @@ -1,3 +0,0 @@ -

PSA internal trusted storage reference API

- -Mbed OS uses PSA internal trusted storage APIs to support PSA specifications. For more information about PSA internal trusted storage API, please refer to [the documentation](https://github.com/ARM-software/psa-arch-tests). diff --git a/docs/api/security/psa.md b/docs/reference/technology/psa/psa.md similarity index 100% rename from docs/api/security/psa.md rename to docs/reference/technology/psa/psa.md From 2778c2d860abefa6cd96c82db3e5f6d2f52c8921 Mon Sep 17 00:00:00 2001 From: Alexander Zilberkant Date: Sat, 2 Mar 2019 22:07:51 +0200 Subject: [PATCH 04/38] lifecycle - doxyden --- docs/api/security/lifecycle/psa_lifecycle.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/api/security/lifecycle/psa_lifecycle.md b/docs/api/security/lifecycle/psa_lifecycle.md index c16518ed29..882879ed01 100644 --- a/docs/api/security/lifecycle/psa_lifecycle.md +++ b/docs/api/security/lifecycle/psa_lifecycle.md @@ -1,4 +1,7 @@ -

PSA lifecycle reference API

+## 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: @@ -15,4 +18,11 @@ Lifecycle can be specified during build time by `MBED_CONF_LIFECYCLE_STATE` macr In mbed-os PSA Lifecycle is implemented as part of [platform service](../platform_servcie.md) -TODO: link to doxygen \ No newline at end of file +### 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) From 619d63a2420e2d34d706c8424ed13410595b0def Mon Sep 17 00:00:00 2001 From: Alexander Zilberkant Date: Sat, 2 Mar 2019 22:13:46 +0200 Subject: [PATCH 05/38] platform partition --- docs/api/security/platform_service.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/api/security/platform_service.md b/docs/api/security/platform_service.md index a53c4d17aa..27d7ff9e4f 100644 --- a/docs/api/security/platform_service.md +++ b/docs/api/security/platform_service.md @@ -1,6 +1,9 @@ -

Platfrom Service API

+## Platfrom Service +### Description Platform service introduces system reset and PSA Lifecycle APIs. -PSA platform service may be extended by target vendors to expose target peripherals only accessible from secure side. +System reset API can be used to request system reset from NSPE. -Todo: link to doxygen \ No newline at end of file +### Doxygen + +[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/lifecycle_8h.html) \ No newline at end of file From 69845d44976ba8b4d13fd53c14a7e482eb81171c Mon Sep 17 00:00:00 2001 From: Alexander Zilberkant Date: Sun, 3 Mar 2019 22:06:37 +0200 Subject: [PATCH 06/38] Move psa IST and PS to storage folder --- docs/api/security/security.md | 4 ++-- docs/api/{security => storage}/psa_internal_storage.md | 0 docs/api/{security => storage}/psa_protected_storage.md | 0 3 files changed, 2 insertions(+), 2 deletions(-) rename docs/api/{security => storage}/psa_internal_storage.md (100%) rename docs/api/{security => storage}/psa_protected_storage.md (100%) diff --git a/docs/api/security/security.md b/docs/api/security/security.md index 51d0a71ee9..0719940b5e 100644 --- a/docs/api/security/security.md +++ b/docs/api/security/security.md @@ -4,9 +4,9 @@ Security on Arm Mbed OS is divided into the following parts: - [PSA SPM](./spm.md) - used for accessing secure services within Secure Processing environment (on PSA targets only) -- [PSA internal storage](./psa_internal_storage.md) - used to save PSA RoT state +- [PSA internal storage](../storage/psa_internal_storage.md) - used to save PSA RoT state -- [PSA protected storage](./psa_protected_storage.md) +- [PSA protected storage](../storage/psa_protected_storage.md) - [PSA Crypto](psa_crypto.md) diff --git a/docs/api/security/psa_internal_storage.md b/docs/api/storage/psa_internal_storage.md similarity index 100% rename from docs/api/security/psa_internal_storage.md rename to docs/api/storage/psa_internal_storage.md diff --git a/docs/api/security/psa_protected_storage.md b/docs/api/storage/psa_protected_storage.md similarity index 100% rename from docs/api/security/psa_protected_storage.md rename to docs/api/storage/psa_protected_storage.md From 7f20a7f23b1ca1681ede37b1690a6b73303c0485 Mon Sep 17 00:00:00 2001 From: Alexander Zilberkant Date: Sun, 3 Mar 2019 22:08:14 +0200 Subject: [PATCH 07/38] Fix typo in ITS --- docs/api/storage/psa_internal_storage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/storage/psa_internal_storage.md b/docs/api/storage/psa_internal_storage.md index 7bb5f6f5fc..47ee0cf45e 100644 --- a/docs/api/storage/psa_internal_storage.md +++ b/docs/api/storage/psa_internal_storage.md @@ -4,7 +4,7 @@ PSA internal storage APIs allows saving and retrieving data from PSA internal flash. -PSA internal storage is implementation varies depending on the target type: +PSA internal storage 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. From 818a8e5158c4ce9562a13fe5533615e0ec79b356 Mon Sep 17 00:00:00 2001 From: Moran Peker Date: Mon, 4 Mar 2019 10:59:18 +0200 Subject: [PATCH 08/38] Update PSA Initial Attestation Service document --- docs/api/security/psa_attestation.md | 45 +++++++++++++++++++++++----- 1 file changed, 38 insertions(+), 7 deletions(-) diff --git a/docs/api/security/psa_attestation.md b/docs/api/security/psa_attestation.md index f0be15a623..ca6c76997a 100644 --- a/docs/api/security/psa_attestation.md +++ b/docs/api/security/psa_attestation.md @@ -2,18 +2,49 @@ ### Description -TODO: AlexV +The PSA initial attestation service enables an application to prove a device's identity to a caller during the authentication process. +The initial attestation service creates a token that contains a fixed set of device-specific data, on request. To sign the token, the device must contain an attestation key pair, which is unique per device. The service uses the attestation private key to sign the token, and the caller uses the public key to verify the token's authenticity. + +The PSA initial attestation service is based on the TF-M attestation service, which is available in the [TF-M repository]( https://git.trustedfirmware.org/trusted-firmware-m.git/). ### Specification -TODO: AlexV - describe here about APIs and the difference in behavior whether bootlaoder is present or not +The initial attestation service exposes the following PSA interface: +``` +enum psa_attest_err_t +psa_initial_attest_get_token(const uint8_t *challenge_obj, + uint32_t challenge_size, + uint8_t *token, + uint32_t *token_size); +enum psa_attest_err_t +psa_initial_attest_get_token_size(uint32_t challenge_size, + uint32_t *token_size); +psa_status_t +psa_attestation_inject_key(const uint8_t *key_data, + size_t key_data_length, + psa_key_type_t type, + uint8_t *public_key_data, + size_t public_key_data_size, + size_t *public_key_data_length); +``` -PSA specification can be found here [PSA Secure Storage](https://pages.arm.com/PSA-APIs) +To generate or import a key pair and export the public key in binary format, call the `psa_attestation_inject_key()` function. The function stores the attestation key as a persistent key with a specific key-id. + +The size of the token that the service creates is highly dependent on the number of software components in the system and the provided attributes of these components. The caller must allocate a sufficiently large buffer for the initial attestation service to create the token into. + +To get the exact size of the created token, call the `psa_initial_attest_get_token_size()` function. + +You must call the `psa_crypto_init()` API before calling the attestation API. -### Doxygen +The initial attestation token consists of claims. A claim is a data item, which is represented as a key-value pair. -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 +For the list of claims that are included in the token, see [the TF-M Initial Attestation Service Integration Guide](https://git.trustedfirmware.org/trusted-firmware-m.git/tree/docs/user_guides/services/tfm_attestation_integration_guide.md). + +The token might also include data about the distinct software components on the device. The bootloader must provide this data encoded in TLV format. + +In the current implementation, a bootloader does not exist in single and dual V7; therefore, we have provided temporary hardcoded boot status data claims in the `attestation_bootloader_data.c` file, including `HW version`, `Boot seed`, and some `Software components` entries. `Security lifecycle` should also be part of the boot status, but in the current implementation, it is provided by calling the `psa_security_lifecycle_state()` API directly. + + +PSA specification can be found here [PSA Secure Storage](https://pages.arm.com/PSA-APIs) [![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/psa__prot__internal__storage_8h.html) \ No newline at end of file From 02a3bd756c1eb035d2bd660a5a460b4dff41a194 Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Mon, 4 Mar 2019 12:23:03 +0200 Subject: [PATCH 09/38] Update psa_lifecycle.md --- docs/api/security/lifecycle/psa_lifecycle.md | 26 +++++++++----------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/docs/api/security/lifecycle/psa_lifecycle.md b/docs/api/security/lifecycle/psa_lifecycle.md index 882879ed01..cc12842b10 100644 --- a/docs/api/security/lifecycle/psa_lifecycle.md +++ b/docs/api/security/lifecycle/psa_lifecycle.md @@ -1,28 +1,26 @@ ## PSA lifecycle +The PSA lifecycle enables fine-grained control of the target root of trust (RoT). -### Description - -PSA Lifecycle allows fine grained control over target RoT without compromising on developer experience. -PSA Lifecycle can be described by following state machine: +The following is a state machine depiction of the PSA lifecycle: ![lifecycle](./psa_lifecycle.png) - **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. + **Note:** PSA Lifecycle is not a standalone feature; it depends on PSA bootloader support, which has not yet been introduced in Mbed OS. The only lifecycle change currently supported is `PSA_LIFECYCLE_ASSEMBLY_AND_TEST` to `PSA_LIFECYCLE_ASSEMBLY_AND_TEST`, which you can use in testing to reset the device RoT state. +All of the lifecycle changes represented by dashed lines in the diagram above have not yet been implemented. -Lifecycle can be specified during build time by `MBED_CONF_LIFECYCLE_STATE` macro. Default value is `PSA_LIFECYCLE_ASSEMBLY_AND_TEST`. +You can specify the lifecycle during build time using the `MBED_CONF_LIFECYCLE_STATE` macro. The default lifecycle value is `PSA_LIFECYCLE_ASSEMBLY_AND_TEST`. + +In Mbed OS, the PSA lifecycle is implemented as part of the [platform service](../apis/platform_service.html). -In mbed-os PSA Lifecycle is implemented as part of [platform service](../platform_servcie.md) +### PSA lifecycle class reference -### Specification +[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/lifecycle_8h.html) -More details can be found in [Platform Security Architecture - Firmware Framework ](https://pages.arm.com/psa-resources-ff.html) +### Example -###Doxygen: +### Related content -[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/lifecycle_8h.html) +* [Platform Security Architecture - Firmware Framework](https://pages.arm.com/psa-resources-ff.html). From 81dedfe0cce34f0395f8be8a08182e2a357e63af Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Mon, 4 Mar 2019 12:23:41 +0200 Subject: [PATCH 10/38] Update platform_service.md --- docs/api/security/platform_service.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/api/security/platform_service.md b/docs/api/security/platform_service.md index 27d7ff9e4f..5da0558f85 100644 --- a/docs/api/security/platform_service.md +++ b/docs/api/security/platform_service.md @@ -1,9 +1,11 @@ -## Platfrom Service +## Platform service -### Description -Platform service introduces system reset and PSA Lifecycle APIs. -System reset API can be used to request system reset from NSPE. +The Platform service introduces System Reset and PSA Lifecycle APIs. -### Doxygen +The System Reset API enables you to request system reset from a Non-Secure Processing Environment (NSPE). -[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/lifecycle_8h.html) \ No newline at end of file +### Platform service class reference + +[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/lifecycle_8h.html) + +### Example From ae37b516ed94f279e3ad401ccafe31d4c998391e Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Mon, 4 Mar 2019 12:24:06 +0200 Subject: [PATCH 11/38] Update psa_attestation.md --- docs/api/security/psa_attestation.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/api/security/psa_attestation.md b/docs/api/security/psa_attestation.md index ca6c76997a..5fc2c22f55 100644 --- a/docs/api/security/psa_attestation.md +++ b/docs/api/security/psa_attestation.md @@ -1,7 +1,5 @@ ## PSA Attestation -### Description - The PSA initial attestation service enables an application to prove a device's identity to a caller during the authentication process. The initial attestation service creates a token that contains a fixed set of device-specific data, on request. To sign the token, the device must contain an attestation key pair, which is unique per device. The service uses the attestation private key to sign the token, and the caller uses the public key to verify the token's authenticity. @@ -44,7 +42,10 @@ The token might also include data about the distinct software components on the In the current implementation, a bootloader does not exist in single and dual V7; therefore, we have provided temporary hardcoded boot status data claims in the `attestation_bootloader_data.c` file, including `HW version`, `Boot seed`, and some `Software components` entries. `Security lifecycle` should also be part of the boot status, but in the current implementation, it is provided by calling the `psa_security_lifecycle_state()` API directly. - -PSA specification can be found here [PSA Secure Storage](https://pages.arm.com/PSA-APIs) +### PSA attestation class reference + +[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/???.html) + +### Related content -[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/psa__prot__internal__storage_8h.html) \ No newline at end of file +* [PSA specification](https://pages.arm.com/PSA-APIs). From 1c0426e24c7c18cb430b50ac184c05bd61777f4f Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Mon, 4 Mar 2019 12:24:58 +0200 Subject: [PATCH 12/38] Update security.md --- docs/api/security/security.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/api/security/security.md b/docs/api/security/security.md index 0719940b5e..0e8a8e1361 100644 --- a/docs/api/security/security.md +++ b/docs/api/security/security.md @@ -2,20 +2,18 @@ Security on Arm Mbed OS is divided into the following parts: -- [PSA SPM](./spm.md) - used for accessing secure services within Secure Processing environment (on PSA targets only) +- [Platform Security Architecture (PSA) Secure Partition Manager (SPM)](../spm.html) - Accesses secure services within a secure processing environment (on PSA targets only). -- [PSA internal storage](../storage/psa_internal_storage.md) - used to save PSA RoT state +- [PSA internal storage](../apis/psa_internal_storage.html) - Saves the PSA root of trust (RoT) state. -- [PSA protected storage](../storage/psa_protected_storage.md) +- [PSA protected storage](../apis/psa_protected_storage.html) - Saves data to and retrieves data from PSA protected storage. -- [PSA Crypto](psa_crypto.md) +- [PSA Crypto](../apis/psa_crypto.html) - A reference implementation of the cryptography interface of PSA. -- 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). +- [Mbed TLS](../apis/tls.html) - A comprehensive SSL/TLS solution. For full details, see the [Mbed TLS site](https://tls.mbed.org/). - For full details, please see the [Mbed TLS site](https://tls.mbed.org/). +- [PSA attestation](../apis/psa_attestation.html) - Enables an application to prove a device's identity to a caller during the authentication process. -- [[PSA Attestation](psa_attestation.md) +- [PSA lifecycle](../apis/lifecycle/psa_lifecycle.html) - Enables fine-grained control of the target root of trust (RoT). -- [PSA Lifecycle](./lifecycle/psa_lifecycle.md) - -- [Device Key](./DeviceKey.md) +- [Device key](../apis/DeviceKey.html) - Implements key derivation from a root of trust key. From e9c6050e4355734b0caf60ca1acd700dfc897f5c Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Mon, 4 Mar 2019 12:25:25 +0200 Subject: [PATCH 13/38] Update spm.md --- docs/api/security/spm.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/api/security/spm.md b/docs/api/security/spm.md index 5023f9ca7c..fa93238fe7 100644 --- a/docs/api/security/spm.md +++ b/docs/api/security/spm.md @@ -1,13 +1,13 @@ ## SPM APIs -### Description +Platform Security Architecture (PSA) Secure Partition Manager (SPM) APIs enable calling secure services within the secure processing environment. -PSA SPM APIs are used for calling Secure Services within Secure Processing environment +### SPM class reference -### Specification +[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/group___s_p_m.html) -More details can be found in [Platform Security Architecture - Firmware Framework ](https://pages.arm.com/psa-resources-ff.html) +### Example -### Doxygen +### Related content -[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/group___s_p_m.html) \ No newline at end of file +* [Platform Security Architecture - Firmware Framework](https://pages.arm.com/psa-resources-ff.html). From 8a13c4f44850ee7c65053d57b34dda8017f64e8f Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Mon, 4 Mar 2019 12:27:22 +0200 Subject: [PATCH 14/38] Update psa_internal_storage.md --- docs/api/storage/psa_internal_storage.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/api/storage/psa_internal_storage.md b/docs/api/storage/psa_internal_storage.md index 47ee0cf45e..9fec074e10 100644 --- a/docs/api/storage/psa_internal_storage.md +++ b/docs/api/storage/psa_internal_storage.md @@ -1,20 +1,20 @@ -## PSA Internal Storage +## PSA internal storage -### Description +PSA internal storage APIs enable saving data to and retrieving data from a PSA internal flash. -PSA internal storage APIs allows saving and retrieving data from PSA internal flash. +The implementation of PSA internal storage varies depending on the target type: -PSA internal storage 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. +* On a single core ARMv7-M target, PSA internal storage APIs are implemented by calling the default internal TDBStore instance. +* On PSA targets that implement Secure Partition Manager (SPM), PSA internal storage is implemented as a secure service. The service uses an access control list to ensure that it only accesses entries created from the Non-Secure Processing Environment (NSPE). -### Specification +### PSA internal storage class reference -API specification in mbed-os specific context can be found here: [mbed-os/Storage](../../storage/storage.md) +[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/psa__prot__internal__storage_8h.html) -PSA specification can be found here [PSA Secure Storage](https://pages.arm.com/PSA-APIs) +### Example -### Doxygen +### Related content -[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/psa__prot__internal__storage_8h.html) \ No newline at end of file +* [Storage overview (Mbed OS)](..apis/storage.html). + +* [PSA secure storage](https://pages.arm.com/PSA-APIs). From 9857a5261eec6bf39a557b8b0bfc28df8ecc5666 Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Mon, 4 Mar 2019 12:27:57 +0200 Subject: [PATCH 15/38] Update psa_protected_storage.md --- docs/api/storage/psa_protected_storage.md | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/docs/api/storage/psa_protected_storage.md b/docs/api/storage/psa_protected_storage.md index 4e9e03af9a..36ac679365 100644 --- a/docs/api/storage/psa_protected_storage.md +++ b/docs/api/storage/psa_protected_storage.md @@ -1,19 +1,15 @@ -## PSA Protected Storage +## PSA protected storage -### Description +PSA protected storage APIs enable saving data to and retrieving data from PSA protected storage. -PSA Protected storage APIs allows saving and retrieving data from PSA protected storage. +Unlike [PSA internal storage](../apis/psa_internal_storage.html), PSA protected storage always runs on the NSPE side and redirects calls to the KVStore instance. -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. +### PSA protected storage class reference -TODO: Danniel Benor - review and add links to this page from Storage landing page +[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/protected__storage_8h.html) -### Specification +### Related content -API specification in mbed-os specific context can be found here: [mbed-os/Storage](../../storage/storage.md) +* [API specification in Mbed OS](../apis/storage.html) -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) \ No newline at end of file +* [PSA Secure Storage](https://pages.arm.com/PSA-APIs). From 52113f03ac085ae1da13d0c8792f136a58671421 Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Mon, 4 Mar 2019 12:29:05 +0200 Subject: [PATCH 16/38] Update spm.md --- docs/porting/psa/spm.md | 64 +++++++++++++++++++---------------------- 1 file changed, 30 insertions(+), 34 deletions(-) diff --git a/docs/porting/psa/spm.md b/docs/porting/psa/spm.md index 556a949a44..5959dee41d 100644 --- a/docs/porting/psa/spm.md +++ b/docs/porting/psa/spm.md @@ -1,21 +1,16 @@

PSA SPM

-Secure Partition Manager (SPM) is a part of the PSA Firmware Framework that is responsible for isolating software in partitions, managing the execution of software within partitions and providing interprocessor communication (IPC) between partitions. +Secure Partition Manager (SPM) is a part of the PSA Firmware Framework that is responsible for isolating software in partitions, managing the execution of software within partitions and providing inter-process communication (IPC) between partitions. For more information about SPM, please refer to [the SPM overview page](../apis/psa-api.html). This page gives guidelines for silicon partners adding SPM capabilities. -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. - +For information about the platform types supported by the Mbed implementation of PSA, see [Platform types](../reference/psa-api.html#platform-types). #### JSON target definition @@ -66,18 +61,18 @@ The example below demonstrates: } ``` -Following flags & Labels are should be added to each target type to add right version of source files to a compilation: +The following flags and labels must be added to each target type to add the relevant version of the source files to a compilation: -| Label \ Core | V7-single
(Target) | V7-dual NSPE
(NSPE_Target) | V7-dual SPE
(SPE_Target) | V8-NS
(NSPE_Target) | V8-S
(SPE_Target) | +| Label/core | V7-single
(Target) | V7-dual NSPE
(NSPE_Target) | V7-dual SPE
(SPE_Target) | V8-NS
(NSPE_Target) | V8-S
(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 | +| `PSA_SRV_IMPL` (component) | ✓ | | ✓ | | ✓ | +| `PSA_SRV_EMUL` (component) | ✓ | | | | | +| `PSA_SRV_IPC` (component) | | ✓ | ✓ | ✓ | ✓ | +| `SPE` (component) | | | ✓ | | ✓ | +| `NSPE` (component) | ✓ | ✓ | | ✓ | | +| `SPM_MAILBOX` (component) | | ✓ | ✓ | | | +| `MBED_SPM` (label) | | ✓ | ✓ | | | +| `TFM` (label) | | | | ✓ | ✓ | #### Memory layout @@ -103,7 +98,7 @@ To achieve RAM and flash partitioning, you must add start and size values to a t **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. -### Linker scripts concepts +### Linker script 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. @@ -211,13 +206,13 @@ define symbol __ICFEDIT_region_IROM1_end__ = (MBED_ROM_START + MBED_ROM_SIZE); ... ``` -### Mbed-SPM porting (Asymmetric Multiprocessing systems - Multicore ARMv7-M) +### Porting SPM (asymmetric multiprocessing systems - multicore ARMv7-M) These are the guidelines you should follow if you have multicore systems: -- For each core, initialize, configure and enable the a mailbox event (usually an interrupt) at `SystemInit()`. +- For each core, initialize, configure and enable the mailbox event (usually an interrupt) at `SystemInit()`. - For each core, implement the IPC event handler (usually interrupt handler): - - The handler must call an Arm callback function. Refer to [HAL functions section](#hal-functions) for more details. + - The handler must call an Arm callback function. See the [HAL functions section](#hal-functions) for more details. - 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. @@ -231,15 +226,15 @@ Target-specific code of silicon partners adding SPM capabilities must: The HAL can be logically divided into two different fields: -#### Mailbox +##### 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 +###### 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 +###### Requirements The SPM mailbox mechanism requires the platform to have the following capabilities: @@ -247,8 +242,9 @@ The SPM mailbox mechanism requires the platform to have the following capabiliti - 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 enables you to implement a thin, platform-specific layer of the mailbox mechanism. + +##### 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). @@ -265,17 +261,17 @@ The implementation of this function must be aligned with the SPM general guideli Processor access |Secure RAM |Secure FLASH|Nonsecure RAM |Nonsecure FLASH --------------------|------------------|------------|-------------------|---------------- -`Non Secure Read` | X | X | V | V -`Non Secure Write` | X | X | V | ? -`Non Secure Execute`| X | X | X? | V -`Secure Read` | V | V | V | V -`Secure Write` | V | V | V | ? -`Secure Execute` | X? | V | X | ? +`Non Secure Read` | X | X | ✓ | ✓ +`Non Secure Write` | X | X | ✓ | ? +`Non Secure Execute`| X | X | X? | ✓ +`Secure Read` | ✓ | ✓ | ✓ | ✓ +`Secure Write` | ✓ | ✓ | ✓ | ? +`Secure Execute` | X? | ✓ | X | ? -### TF-M SPM porting for (ARMv8-M targets) +### TF-M SPM porting (for ARMv8-M targets) -TF-M HAL functions are defined in `tfm_spm_hal.h` +TF-M HAL functions are defined in `tfm_spm_hal.h`. ### Testing From 6524fdf5099ee06452c542d19a0ba0ff148934d1 Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Mon, 4 Mar 2019 12:30:52 +0200 Subject: [PATCH 17/38] Update psa.md --- docs/reference/technology/psa/psa.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/reference/technology/psa/psa.md b/docs/reference/technology/psa/psa.md index c6aaa66228..72260aede8 100644 --- a/docs/reference/technology/psa/psa.md +++ b/docs/reference/technology/psa/psa.md @@ -32,7 +32,7 @@ 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 based on *specialized* [TrustedFirmware-M](https://www.trustedfirmware.org) implementation. +- ARMv8-M: Generation of ARM processors featuring TrustZone-M architecture. PSA support for these platforms is based on a *specialized* [TrustedFirmware-M](https://www.trustedfirmware.org) implementation. ### RoT services @@ -40,6 +40,6 @@ 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) +- [PSA attestation](../apis/psa_attestation.html). +- [PSA lifecycle](../apis/psa_lifecycle.html). +- [PSA platform service](../apis/platform_service.html). From a83cc98428e62d8f15551241767bccf34d6bd0fd Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Mon, 4 Mar 2019 12:38:46 +0200 Subject: [PATCH 18/38] Update security.md --- docs/api/security/security.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/security/security.md b/docs/api/security/security.md index 0e8a8e1361..2cd28e062c 100644 --- a/docs/api/security/security.md +++ b/docs/api/security/security.md @@ -4,9 +4,9 @@ Security on Arm Mbed OS is divided into the following parts: - [Platform Security Architecture (PSA) Secure Partition Manager (SPM)](../spm.html) - Accesses secure services within a secure processing environment (on PSA targets only). -- [PSA internal storage](../apis/psa_internal_storage.html) - Saves the PSA root of trust (RoT) state. +- [PSA internal storage](../storage/psa_internal_storage.html) - Saves the PSA root of trust (RoT) state. -- [PSA protected storage](../apis/psa_protected_storage.html) - Saves data to and retrieves data from PSA protected storage. +- [PSA protected storage](../storage/psa_protected_storage.html) - Saves data to and retrieves data from PSA protected storage. - [PSA Crypto](../apis/psa_crypto.html) - A reference implementation of the cryptography interface of PSA. From 079c4d14ac22687d38190e9716c0d463f08e627b Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Mon, 4 Mar 2019 12:45:42 +0200 Subject: [PATCH 19/38] Update psa_internal_storage.md --- docs/api/storage/psa_internal_storage.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/storage/psa_internal_storage.md b/docs/api/storage/psa_internal_storage.md index 9fec074e10..d531c62bdc 100644 --- a/docs/api/storage/psa_internal_storage.md +++ b/docs/api/storage/psa_internal_storage.md @@ -2,9 +2,9 @@ PSA internal storage APIs enable saving data to and retrieving data from a PSA internal flash. -The implementation of PSA internal storage varies depending on the target type: +The PSA internal storage functionality varies depending on the target type: -* On a single core ARMv7-M target, PSA internal storage APIs are implemented by calling the default internal TDBStore instance. +* On a single core ARMv7-M target, PSA internal storage APIs call the default internal TDBStore instance. * On PSA targets that implement Secure Partition Manager (SPM), PSA internal storage is implemented as a secure service. The service uses an access control list to ensure that it only accesses entries created from the Non-Secure Processing Environment (NSPE). ### PSA internal storage class reference From e22de4a3a8277c60e542b452e7e441ee30fd575e Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Mon, 4 Mar 2019 12:48:49 +0200 Subject: [PATCH 20/38] Updates based on Danny's feedback. --- docs/api/storage/psa_internal_storage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/storage/psa_internal_storage.md b/docs/api/storage/psa_internal_storage.md index d531c62bdc..ed2dad38cb 100644 --- a/docs/api/storage/psa_internal_storage.md +++ b/docs/api/storage/psa_internal_storage.md @@ -1,6 +1,6 @@ ## PSA internal storage -PSA internal storage APIs enable saving data to and retrieving data from a PSA internal flash. +PSA internal storage APIs enable software running in a secure environment to save data to and retrieve data from a PSA internal flash. The PSA internal storage functionality varies depending on the target type: From a1332cd22a085e0cd654e9d86ed3deefc1704f84 Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Mon, 4 Mar 2019 13:00:24 +0200 Subject: [PATCH 21/38] Updates based on Danny's feedback. --- docs/api/storage/psa_protected_storage.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/api/storage/psa_protected_storage.md b/docs/api/storage/psa_protected_storage.md index 36ac679365..fdb8c65de8 100644 --- a/docs/api/storage/psa_protected_storage.md +++ b/docs/api/storage/psa_protected_storage.md @@ -2,7 +2,9 @@ PSA protected storage APIs enable saving data to and retrieving data from PSA protected storage. -Unlike [PSA internal storage](../apis/psa_internal_storage.html), PSA protected storage always runs on the NSPE side and redirects calls to the KVStore instance. +Unlike [PSA internal storage](../apis/psa_internal_storage.html), PSA protected storage always runs the Non-Secure Processing Environment (NSPE) and redirects calls to the KVStore static API. + +**Note:** In general, we recommend using the [KVStore static API](../storage/KVStoreGlobalAPI.html) in the NSPE. ### PSA protected storage class reference From 2e65a88828eaa28da839a0ad02e9949235b262d6 Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Mon, 4 Mar 2019 13:10:15 +0200 Subject: [PATCH 22/38] Updated based on Danny's feedback. --- docs/api/storage/psa_internal_storage.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/storage/psa_internal_storage.md b/docs/api/storage/psa_internal_storage.md index ed2dad38cb..67b7437d3a 100644 --- a/docs/api/storage/psa_internal_storage.md +++ b/docs/api/storage/psa_internal_storage.md @@ -4,8 +4,8 @@ PSA internal storage APIs enable software running in a secure environment to sav The PSA internal storage functionality varies depending on the target type: -* On a single core ARMv7-M target, PSA internal storage APIs call the default internal TDBStore instance. -* On PSA targets that implement Secure Partition Manager (SPM), PSA internal storage is implemented as a secure service. The service uses an access control list to ensure that it only accesses entries created from the Non-Secure Processing Environment (NSPE). +* On a single core ARMv7-M target, PSA internal storage APIs call the default internal TDBStore instance allocated by the KVStore configuration. For more information, see [KVStore configuration](..reference/storage.html#kvstore-configuration). +* On PSA targets that implement Secure Partition Manager (SPM), PSA internal storage is implemented as a secure service. The service uses an access control list, which ensures that software executed in the Non-Secure Processing Environment (NSPE) cannot access entries created by the Secure Processing Environment (SPE). ### PSA internal storage class reference From 109582501cb1d983439813f5b369bbdce6c2843f Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Tue, 5 Mar 2019 10:15:22 +0200 Subject: [PATCH 23/38] Update psa_protected_storage.md --- docs/api/storage/psa_protected_storage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/storage/psa_protected_storage.md b/docs/api/storage/psa_protected_storage.md index fdb8c65de8..08ef6f89c9 100644 --- a/docs/api/storage/psa_protected_storage.md +++ b/docs/api/storage/psa_protected_storage.md @@ -2,7 +2,7 @@ PSA protected storage APIs enable saving data to and retrieving data from PSA protected storage. -Unlike [PSA internal storage](../apis/psa_internal_storage.html), PSA protected storage always runs the Non-Secure Processing Environment (NSPE) and redirects calls to the KVStore static API. +Unlike [PSA internal storage](../apis/psa_internal_storage.html), PSA protected storage always runs in the Non-Secure Processing Environment (NSPE) and redirects calls to the KVStore static API. **Note:** In general, we recommend using the [KVStore static API](../storage/KVStoreGlobalAPI.html) in the NSPE. From 5a21af093436405f8627ce37b7f3418d7f6d7410 Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Tue, 5 Mar 2019 12:17:08 +0200 Subject: [PATCH 24/38] Updated based on Alex Z's clarifications. --- docs/api/security/lifecycle/psa_lifecycle.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/api/security/lifecycle/psa_lifecycle.md b/docs/api/security/lifecycle/psa_lifecycle.md index cc12842b10..3544b05d5e 100644 --- a/docs/api/security/lifecycle/psa_lifecycle.md +++ b/docs/api/security/lifecycle/psa_lifecycle.md @@ -1,16 +1,18 @@ ## PSA lifecycle -The PSA lifecycle enables fine-grained control of the target root of trust (RoT). +The PSA lifecycle API enables setting the lifecycle state. + +Setting a lower lifecycle state - for example, factory or test state - allows you to control the target root of trust (RoT) and change the debugging policy when testing or debugging. The following is a state machine depiction of the PSA lifecycle: ![lifecycle](./psa_lifecycle.png) - **Note:** PSA Lifecycle is not a standalone feature; it depends on PSA bootloader support, which has not yet been introduced in Mbed OS. The only lifecycle change currently supported is `PSA_LIFECYCLE_ASSEMBLY_AND_TEST` to `PSA_LIFECYCLE_ASSEMBLY_AND_TEST`, which you can use in testing to reset the device RoT state. + **Note:** PSA lifecycle is not a standalone feature; it depends on PSA bootloader support, which has not yet been introduced in Mbed OS. The only lifecycle change currently supported is `PSA_LIFECYCLE_ASSEMBLY_AND_TEST` to `PSA_LIFECYCLE_ASSEMBLY_AND_TEST`, which you can use in testing to reset the device RoT state. All of the lifecycle changes represented by dashed lines in the diagram above have not yet been implemented. -You can specify the lifecycle during build time using the `MBED_CONF_LIFECYCLE_STATE` macro. The default lifecycle value is `PSA_LIFECYCLE_ASSEMBLY_AND_TEST`. +You can specify the lifecycle value during build time using the `MBED_CONF_LIFECYCLE_STATE` macro. The default lifecycle value is `PSA_LIFECYCLE_ASSEMBLY_AND_TEST`. In Mbed OS, the PSA lifecycle is implemented as part of the [platform service](../apis/platform_service.html). From 7b0722b76dcd645a84dd60266e3701221a9ab059 Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Tue, 5 Mar 2019 17:15:22 +0200 Subject: [PATCH 25/38] Update psa_lifecycle.md --- docs/api/security/lifecycle/psa_lifecycle.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/security/lifecycle/psa_lifecycle.md b/docs/api/security/lifecycle/psa_lifecycle.md index 3544b05d5e..24c704de89 100644 --- a/docs/api/security/lifecycle/psa_lifecycle.md +++ b/docs/api/security/lifecycle/psa_lifecycle.md @@ -14,11 +14,11 @@ All of the lifecycle changes represented by dashed lines in the diagram above ha You can specify the lifecycle value during build time using the `MBED_CONF_LIFECYCLE_STATE` macro. The default lifecycle value is `PSA_LIFECYCLE_ASSEMBLY_AND_TEST`. -In Mbed OS, the PSA lifecycle is implemented as part of the [platform service](../apis/platform_service.html). +In Mbed OS, the PSA lifecycle is implemented as part of the [platform service](../apis/platform-service.html). ### PSA lifecycle class reference -[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/lifecycle_8h.html) +[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/development/mbed-os-api-doxy/lifecycle_8h.html) ### Example From 1e5a85742e63b93beee06bc501b62ebfe7f2de93 Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Tue, 5 Mar 2019 17:23:14 +0200 Subject: [PATCH 26/38] Update psa_attestation.md --- docs/api/security/psa_attestation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/security/psa_attestation.md b/docs/api/security/psa_attestation.md index 5fc2c22f55..5aa9cbfe73 100644 --- a/docs/api/security/psa_attestation.md +++ b/docs/api/security/psa_attestation.md @@ -1,4 +1,4 @@ -## PSA Attestation +## PSA attestation The PSA initial attestation service enables an application to prove a device's identity to a caller during the authentication process. From 89311f91d7c7d07ccbef9ab271b1775c9b0b4844 Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Tue, 5 Mar 2019 17:28:57 +0200 Subject: [PATCH 27/38] Update psa_attestation.md --- docs/api/security/psa_attestation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/api/security/psa_attestation.md b/docs/api/security/psa_attestation.md index 5aa9cbfe73..998dabcd7c 100644 --- a/docs/api/security/psa_attestation.md +++ b/docs/api/security/psa_attestation.md @@ -2,12 +2,12 @@ The PSA initial attestation service enables an application to prove a device's identity to a caller during the authentication process. -The initial attestation service creates a token that contains a fixed set of device-specific data, on request. To sign the token, the device must contain an attestation key pair, which is unique per device. The service uses the attestation private key to sign the token, and the caller uses the public key to verify the token's authenticity. +The initial attestation service creates a token that contains a fixed set of device-specific data, upon request. To sign the token, the device must contain an attestation key pair, which is unique per device. The service uses the attestation private key to sign the token, and the caller uses the public key to verify the token's authenticity. The PSA initial attestation service is based on the TF-M attestation service, which is available in the [TF-M repository]( https://git.trustedfirmware.org/trusted-firmware-m.git/). ### Specification -The initial attestation service exposes the following PSA interface: +The initial attestation service exposes the following PSA interfaces: ``` enum psa_attest_err_t psa_initial_attest_get_token(const uint8_t *challenge_obj, @@ -44,7 +44,7 @@ In the current implementation, a bootloader does not exist in single and dual V7 ### PSA attestation class reference -[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/???.html) +[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/development/mbed-os-api-doxy/???.html) ### Related content From afc8bdc5dcdf4cae9f3ac5cfff6b51b3a25615ec Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Tue, 5 Mar 2019 18:10:46 +0200 Subject: [PATCH 28/38] Update security.md --- docs/api/security/security.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/api/security/security.md b/docs/api/security/security.md index 2cd28e062c..8eada1785b 100644 --- a/docs/api/security/security.md +++ b/docs/api/security/security.md @@ -2,18 +2,14 @@ Security on Arm Mbed OS is divided into the following parts: -- [Platform Security Architecture (PSA) Secure Partition Manager (SPM)](../spm.html) - Accesses secure services within a secure processing environment (on PSA targets only). +- [Platform Security Architecture (PSA) Secure Partition Manager (SPM)](../apis/spm-apis.html) - Accesses secure services within a secure processing environment (on PSA targets only). -- [PSA internal storage](../storage/psa_internal_storage.html) - Saves the PSA root of trust (RoT) state. - -- [PSA protected storage](../storage/psa_protected_storage.html) - Saves data to and retrieves data from PSA protected storage. - -- [PSA Crypto](../apis/psa_crypto.html) - A reference implementation of the cryptography interface of PSA. +- [PSA Crypto](../apis/psa-crypto.html) - A reference implementation of the cryptography interface of PSA. - [Mbed TLS](../apis/tls.html) - A comprehensive SSL/TLS solution. For full details, see the [Mbed TLS site](https://tls.mbed.org/). -- [PSA attestation](../apis/psa_attestation.html) - Enables an application to prove a device's identity to a caller during the authentication process. +- [PSA attestation](../apis/psa-attestation.html) - Enables an application to prove a device's identity to a caller during the authentication process. -- [PSA lifecycle](../apis/lifecycle/psa_lifecycle.html) - Enables fine-grained control of the target root of trust (RoT). +- [PSA lifecycle](../apis/lifecycle/psa-lifecycle.html) - Enables fine-grained control of the target root of trust (RoT). - [Device key](../apis/DeviceKey.html) - Implements key derivation from a root of trust key. From f9f7b08b28935b02d7429284cf5bdf47981dcc38 Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Tue, 5 Mar 2019 18:42:39 +0200 Subject: [PATCH 29/38] Update psa_internal_storage.md --- docs/api/storage/psa_internal_storage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/storage/psa_internal_storage.md b/docs/api/storage/psa_internal_storage.md index 67b7437d3a..914b876709 100644 --- a/docs/api/storage/psa_internal_storage.md +++ b/docs/api/storage/psa_internal_storage.md @@ -15,6 +15,6 @@ The PSA internal storage functionality varies depending on the target type: ### Related content -* [Storage overview (Mbed OS)](..apis/storage.html). +* [API specification in Mbed OS](../apis/storage.html). * [PSA secure storage](https://pages.arm.com/PSA-APIs). From df93f268294e21a8a84bdd0d8a3235ef713f6280 Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Tue, 5 Mar 2019 18:43:47 +0200 Subject: [PATCH 30/38] Update psa_internal_storage.md --- docs/api/storage/psa_internal_storage.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/api/storage/psa_internal_storage.md b/docs/api/storage/psa_internal_storage.md index 914b876709..4c43e95919 100644 --- a/docs/api/storage/psa_internal_storage.md +++ b/docs/api/storage/psa_internal_storage.md @@ -11,8 +11,6 @@ The PSA internal storage functionality varies depending on the target type: [![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/psa__prot__internal__storage_8h.html) -### Example - ### Related content * [API specification in Mbed OS](../apis/storage.html). From 6a9f6aab7df703a32c5dddfbfa64b1b052f998db Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Wed, 6 Mar 2019 10:56:11 +0200 Subject: [PATCH 31/38] Update spm.md --- docs/api/security/spm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/security/spm.md b/docs/api/security/spm.md index fa93238fe7..b8ec7d1145 100644 --- a/docs/api/security/spm.md +++ b/docs/api/security/spm.md @@ -1,4 +1,4 @@ -## SPM APIs +## PSA SPM Platform Security Architecture (PSA) Secure Partition Manager (SPM) APIs enable calling secure services within the secure processing environment. From ce744d5af677907d6ee6b1fe0cbaa9d5a5253ec4 Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Wed, 6 Mar 2019 11:57:18 +0200 Subject: [PATCH 32/38] Update psa.md --- docs/reference/technology/psa/psa.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/reference/technology/psa/psa.md b/docs/reference/technology/psa/psa.md index 72260aede8..77af367c93 100644 --- a/docs/reference/technology/psa/psa.md +++ b/docs/reference/technology/psa/psa.md @@ -38,8 +38,8 @@ The Mbed implementation of PSA supports the following platform types: 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](../apis/psa_attestation.html). -- [PSA lifecycle](../apis/psa_lifecycle.html). -- [PSA platform service](../apis/platform_service.html). +- [PSA RoT internal storage](..apis/psa-internal-storage.html). +- [PSA crypto](../apis/psa-crypto.html). +- [PSA attestation](../apis/psa-attestation.html). +- [PSA lifecycle](../apis/psa-lifecycle.html). +- [PSA platform service](../apis/platform-service.html). From b42c68c658f6da0e712e4f2588b5b714e02ca3ce Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Wed, 6 Mar 2019 13:09:29 +0200 Subject: [PATCH 33/38] Update psa_crypto.md --- docs/api/security/psa_crypto.md | 59 +++++++++++++++++++++++++-------- 1 file changed, 46 insertions(+), 13 deletions(-) diff --git a/docs/api/security/psa_crypto.md b/docs/api/security/psa_crypto.md index 470e3c57a0..78754790b0 100644 --- a/docs/api/security/psa_crypto.md +++ b/docs/api/security/psa_crypto.md @@ -1,20 +1,53 @@ -## PSA Crypto +## Mbed Crypto -### Description +Arm Mbed Crypto is the reference implementation of the cryptography interface +of the Arm Platform Security Architecture (PSA). -TODO: Jaeden +**Note:** The version of Mbed Crypto shipping with Mbed OS +implements PSA Crypto API v1.0b1. +We have adapted and [integrated Mbed Crypto with Mbed +OS](https://github.com/ARMmbed/mbed-os/blob/master/features/mbedtls/mbed-crypto). +On PSA platforms that support it, Mbed Crypto comes integrated with Mbed OS to +leverage the platform's segmented architecture and isolate cryptographic keys +and operations from applications. -### Specification -TODO: Jaeden - describe here about APIs being available from NSPE and SPE -about differences in behaviour if any +You can import Mbed Crypto from its standalone +[release](https://github.com/ARMmbed/mbed-crypto). Mbed Crypto as integrated +with Mbed OS does not include all test code or scripts used in the development +of the library. You can find all of these in the standalone release. -PSA specification can be found here [PSA Secure Storage](https://pages.arm.com/PSA-APIs) +**Note:** Mbed Crypto, like Mbed TLS, needs a secure source +of random numbers; make sure that your target board has one and that it is +fully ported to Arm Mbed OS. You can read more about this in our [porting +guide](../contributing/index.html). -### Doxygen +### Configuring Mbed Crypto features -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) \ No newline at end of file +The Mbed TLS configuration system configures Mbed Crypto. Please refer to [Mbed +TLS documentation for how to configure Mbed TLS and Mbed +Crypto](../apis/tls.html#configuring-mbed-tls-features). + +### Mbed Crypto examples + +[![View code](https://github.com/ARMmbed/mbed-os-example-mbed-crypto/)](https://github.com/ARMmbed/mbed-os-example-mbed-crypto/blob/master/main.cpp) + +[The Mbed Crypto +example](https://github.com/ARMmbed/mbed-os-example-mbed-crypto) covers some +basic use of the PSA Crypto API as well as factory entropy injection. + +For further information, refer to the readme file in [the example +repository](https://github.com/ARMmbed/mbed-os-example-mbed-crypto). + +### Other resources + +The [Mbed Crypto project homepage on +GitHub](https://github.com/ARMmbed/mbed-crypto) contains the following +resources: + + - [An overview of the PSA Crypto + API](https://github.com/ARMmbed/mbed-crypto/blob/psa-api-1.0-beta/docs/PSA_Crypto_API_Overview.pdf). + - [The PSA Crypto API + reference](https://github.com/ARMmbed/mbed-crypto/blob/psa-api-1.0-beta/docs/PSA_Crypto_API_Reference.pdf). + - [Other general developer + documentation](https://github.com/ARMmbed/mbed-crypto/tree/development/docs). From e79b2e87b31221040991469ffbb918065fbf006f Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Wed, 6 Mar 2019 17:38:21 +0200 Subject: [PATCH 34/38] Delete psa_crypto.md --- docs/api/security/psa_crypto.md | 53 --------------------------------- 1 file changed, 53 deletions(-) delete mode 100644 docs/api/security/psa_crypto.md diff --git a/docs/api/security/psa_crypto.md b/docs/api/security/psa_crypto.md deleted file mode 100644 index 78754790b0..0000000000 --- a/docs/api/security/psa_crypto.md +++ /dev/null @@ -1,53 +0,0 @@ -## Mbed Crypto - -Arm Mbed Crypto is the reference implementation of the cryptography interface -of the Arm Platform Security Architecture (PSA). - -**Note:** The version of Mbed Crypto shipping with Mbed OS -implements PSA Crypto API v1.0b1. - -We have adapted and [integrated Mbed Crypto with Mbed -OS](https://github.com/ARMmbed/mbed-os/blob/master/features/mbedtls/mbed-crypto). -On PSA platforms that support it, Mbed Crypto comes integrated with Mbed OS to -leverage the platform's segmented architecture and isolate cryptographic keys -and operations from applications. - -You can import Mbed Crypto from its standalone -[release](https://github.com/ARMmbed/mbed-crypto). Mbed Crypto as integrated -with Mbed OS does not include all test code or scripts used in the development -of the library. You can find all of these in the standalone release. - -**Note:** Mbed Crypto, like Mbed TLS, needs a secure source -of random numbers; make sure that your target board has one and that it is -fully ported to Arm Mbed OS. You can read more about this in our [porting -guide](../contributing/index.html). - -### Configuring Mbed Crypto features - -The Mbed TLS configuration system configures Mbed Crypto. Please refer to [Mbed -TLS documentation for how to configure Mbed TLS and Mbed -Crypto](../apis/tls.html#configuring-mbed-tls-features). - -### Mbed Crypto examples - -[![View code](https://github.com/ARMmbed/mbed-os-example-mbed-crypto/)](https://github.com/ARMmbed/mbed-os-example-mbed-crypto/blob/master/main.cpp) - -[The Mbed Crypto -example](https://github.com/ARMmbed/mbed-os-example-mbed-crypto) covers some -basic use of the PSA Crypto API as well as factory entropy injection. - -For further information, refer to the readme file in [the example -repository](https://github.com/ARMmbed/mbed-os-example-mbed-crypto). - -### Other resources - -The [Mbed Crypto project homepage on -GitHub](https://github.com/ARMmbed/mbed-crypto) contains the following -resources: - - - [An overview of the PSA Crypto - API](https://github.com/ARMmbed/mbed-crypto/blob/psa-api-1.0-beta/docs/PSA_Crypto_API_Overview.pdf). - - [The PSA Crypto API - reference](https://github.com/ARMmbed/mbed-crypto/blob/psa-api-1.0-beta/docs/PSA_Crypto_API_Reference.pdf). - - [Other general developer - documentation](https://github.com/ARMmbed/mbed-crypto/tree/development/docs). From 14ce3a7e0c0b3eac7f9d2d61ec2c523ba20113a4 Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Wed, 6 Mar 2019 18:44:17 +0200 Subject: [PATCH 35/38] Update psa_lifecycle.md --- docs/api/security/lifecycle/psa_lifecycle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/security/lifecycle/psa_lifecycle.md b/docs/api/security/lifecycle/psa_lifecycle.md index 24c704de89..b8b40d19a2 100644 --- a/docs/api/security/lifecycle/psa_lifecycle.md +++ b/docs/api/security/lifecycle/psa_lifecycle.md @@ -6,7 +6,7 @@ Setting a lower lifecycle state - for example, factory or test state - allows yo The following is a state machine depiction of the PSA lifecycle: -![lifecycle](./psa_lifecycle.png) +![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/psa_lifecycle.png) **Note:** PSA lifecycle is not a standalone feature; it depends on PSA bootloader support, which has not yet been introduced in Mbed OS. The only lifecycle change currently supported is `PSA_LIFECYCLE_ASSEMBLY_AND_TEST` to `PSA_LIFECYCLE_ASSEMBLY_AND_TEST`, which you can use in testing to reset the device RoT state. All of the lifecycle changes represented by dashed lines in the diagram above have not yet been implemented. From 78e26cb636cdeb2d8672a5111e41dcd941c2b7df Mon Sep 17 00:00:00 2001 From: Alexander Zilberkant Date: Thu, 7 Mar 2019 15:11:56 +0200 Subject: [PATCH 36/38] Update platform service doc --- docs/api/security/platform_service.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/api/security/platform_service.md b/docs/api/security/platform_service.md index 5da0558f85..e2cec1f329 100644 --- a/docs/api/security/platform_service.md +++ b/docs/api/security/platform_service.md @@ -1,8 +1,10 @@ ## Platform service -The Platform service introduces System Reset and PSA Lifecycle APIs. +The Platform service introduces System Reset and [PSA Lifecycle](./lifecycle/psa_lifecycle.md) APIs. -The System Reset API enables you to request system reset from a Non-Secure Processing Environment (NSPE). +The System Reset API allows Nonsecure Processing environment to request a system reset. +[Trusted Base System Architecture for M (TBSA-M)](https://pages.arm.com/psa-resources-tbsa-m.html) specification defines that power state should be managed by SPE. +System reset will be carried out by SPE once all critical task are finished. ### Platform service class reference From b8f57c346e179bc06b2cd39ab4894d28902edf7e Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Thu, 7 Mar 2019 15:42:42 +0200 Subject: [PATCH 37/38] Update platform_service.md --- docs/api/security/platform_service.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/api/security/platform_service.md b/docs/api/security/platform_service.md index e2cec1f329..f707889d73 100644 --- a/docs/api/security/platform_service.md +++ b/docs/api/security/platform_service.md @@ -1,10 +1,8 @@ ## Platform service -The Platform service introduces System Reset and [PSA Lifecycle](./lifecycle/psa_lifecycle.md) APIs. +The Platform service introduces System Reset and [PSA Lifecycle](../lifecycle/psa-lifecycle.html) APIs. -The System Reset API allows Nonsecure Processing environment to request a system reset. -[Trusted Base System Architecture for M (TBSA-M)](https://pages.arm.com/psa-resources-tbsa-m.html) specification defines that power state should be managed by SPE. -System reset will be carried out by SPE once all critical task are finished. +The System Reset API enables a Non-Secure Processing Environment (NSPE) to request a system reset. The [Trusted Base System Architecture for M (TBSA-M)](https://pages.arm.com/psa-resources-tbsa-m.html) specification defines that power state must be managed by the Secure Processing Environment (SPE). System reset is carried out by the SPE after all critical tasks are finished. ### Platform service class reference From f02cd8a3d66c2c7f65996e6f71093e90ae2aa257 Mon Sep 17 00:00:00 2001 From: Guy Wild Date: Thu, 7 Mar 2019 16:21:26 +0200 Subject: [PATCH 38/38] Update platform_service.md --- docs/api/security/platform_service.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/api/security/platform_service.md b/docs/api/security/platform_service.md index f707889d73..9a9e4dcceb 100644 --- a/docs/api/security/platform_service.md +++ b/docs/api/security/platform_service.md @@ -2,10 +2,8 @@ The Platform service introduces System Reset and [PSA Lifecycle](../lifecycle/psa-lifecycle.html) APIs. -The System Reset API enables a Non-Secure Processing Environment (NSPE) to request a system reset. The [Trusted Base System Architecture for M (TBSA-M)](https://pages.arm.com/psa-resources-tbsa-m.html) specification defines that power state must be managed by the Secure Processing Environment (SPE). System reset is carried out by the SPE after all critical tasks are finished. +The System Reset API enables a Non-Secure Processing Environment (NSPE) to request a system reset. The [Trusted Base System Architecture for M (TBSA-M)](https://pages.arm.com/psa-resources-tbsa-m.html) specification defines that power state must be managed by the Secure Processing Environment (SPE); therefore, the SPE carries out system reset after all critical tasks are completed. ### Platform service class reference [![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/lifecycle_8h.html) - -### Example