diff --git a/.gitignore b/.gitignore index 6e92f57d46..64f41bd5cd 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,3 @@ tags +.DS_Store +.idea/ 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..b8b40d19a2 --- /dev/null +++ b/docs/api/security/lifecycle/psa_lifecycle.md @@ -0,0 +1,28 @@ +## PSA lifecycle + +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: + +![](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. + + +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). + +### PSA lifecycle class reference + +[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/development/mbed-os-api-doxy/lifecycle_8h.html) + +### Example + + +### Related content + +* [Platform Security Architecture - Firmware Framework](https://pages.arm.com/psa-resources-ff.html). diff --git a/docs/api/security/lifecycle/psa_lifecycle.png b/docs/api/security/lifecycle/psa_lifecycle.png new file mode 100644 index 0000000000..9d90e6ce97 Binary files /dev/null and b/docs/api/security/lifecycle/psa_lifecycle.png differ diff --git a/docs/api/security/platform_service.md b/docs/api/security/platform_service.md new file mode 100644 index 0000000000..9a9e4dcceb --- /dev/null +++ b/docs/api/security/platform_service.md @@ -0,0 +1,9 @@ +## Platform service + +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); 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) diff --git a/docs/api/security/psa_attestation.md b/docs/api/security/psa_attestation.md new file mode 100644 index 0000000000..998dabcd7c --- /dev/null +++ b/docs/api/security/psa_attestation.md @@ -0,0 +1,51 @@ +## PSA attestation + +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, 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 interfaces: +``` +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); +``` + +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. + +The initial attestation token consists of claims. A claim is a data item, which is represented as a key-value pair. + +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 attestation class reference + +[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/development/mbed-os-api-doxy/???.html) + +### Related content + +* [PSA specification](https://pages.arm.com/PSA-APIs). diff --git a/docs/api/security/security.md b/docs/api/security/security.md index 09c84749bf..8eada1785b 100644 --- a/docs/api/security/security.md +++ b/docs/api/security/security.md @@ -2,10 +2,14 @@ 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). +- [Platform Security Architecture (PSA) Secure Partition Manager (SPM)](../apis/spm-apis.html) - Accesses secure services within a 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 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 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. diff --git a/docs/api/security/spm.md b/docs/api/security/spm.md new file mode 100644 index 0000000000..b8ec7d1145 --- /dev/null +++ b/docs/api/security/spm.md @@ -0,0 +1,13 @@ +## PSA SPM + +Platform Security Architecture (PSA) Secure Partition Manager (SPM) APIs enable calling secure services within the secure processing environment. + +### SPM class reference + +[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/group___s_p_m.html) + +### Example + +### Related content + +* [Platform Security Architecture - Firmware Framework](https://pages.arm.com/psa-resources-ff.html). 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/storage/psa_internal_storage.md b/docs/api/storage/psa_internal_storage.md new file mode 100644 index 0000000000..4c43e95919 --- /dev/null +++ b/docs/api/storage/psa_internal_storage.md @@ -0,0 +1,18 @@ +## PSA internal storage + +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: + +* 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 + +[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/psa__prot__internal__storage_8h.html) + +### Related content + +* [API specification in Mbed OS](../apis/storage.html). + +* [PSA secure storage](https://pages.arm.com/PSA-APIs). diff --git a/docs/api/storage/psa_protected_storage.md b/docs/api/storage/psa_protected_storage.md new file mode 100644 index 0000000000..08ef6f89c9 --- /dev/null +++ b/docs/api/storage/psa_protected_storage.md @@ -0,0 +1,17 @@ +## PSA protected storage + +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 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. + +### PSA protected storage class reference + +[![View code](https://www.mbed.com/embed/?type=library)](../mbed-os-api-doxy/protected__storage_8h.html) + +### Related content + +* [API specification in Mbed OS](../apis/storage.html) + +* [PSA Secure Storage](https://pages.arm.com/PSA-APIs). diff --git a/docs/porting/psa/spm.md b/docs/porting/psa/spm.md index 0bf926d233..5959dee41d 100644 --- a/docs/porting/psa/spm.md +++ b/docs/porting/psa/spm.md @@ -1,6 +1,6 @@

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). @@ -8,6 +8,12 @@ For more information about SPM, please refer to [the SPM overview page](../apis/ ### New target configuration +#### Platform types + +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 + 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 +23,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 +61,20 @@ The example below demonstrates this: } ``` +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) | +| ---------------------- |:---------------------:|:-----------------------------:|:---------------------------:|:----------------------:|:--------------------:| +| `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 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 +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 +### 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. @@ -186,32 +206,17 @@ 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 +### 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. -### HAL functions +#### HAL functions Target-specific code of silicon partners adding SPM capabilities must: @@ -220,11 +225,26 @@ 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 -#### Secure Processing Environment +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 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). @@ -241,12 +261,18 @@ 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 HAL functions are defined in `tfm_spm_hal.h`. + ### Testing diff --git a/docs/api/security/psa.md b/docs/reference/technology/psa/psa.md similarity index 90% rename from docs/api/security/psa.md rename to docs/reference/technology/psa/psa.md index e27bec41fb..77af367c93 100644 --- a/docs/api/security/psa.md +++ b/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 these platforms is based on a *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 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).