| ############## |
| FF-M Isolation |
| ############## |
| |
| :Organization: Arm Limited |
| :Contact: tf-m@lists.trustedfirmware.org |
| |
| This document analyzes the isolation rules of implementing ``FF-M 1.0`` |
| isolation and introduces the reference implementation in TF-M, which |
| complies the rules by operating the hardware and software resources. |
| |
| .. note:: |
| Reference the document :doc:`Glossary </glossary>` for terms |
| and abbreviations. |
| |
| ************ |
| Introduction |
| ************ |
| This chapter describes the definitions from ``FF-M`` and analyzes |
| the possible implementation keypoints. |
| |
| Isolation Levels |
| ================ |
| There are 3 isolation levels (1-3) defined in ``FF-M``, the greater level |
| number has more isolation boundaries. |
| |
| The definition for Isolation Level 1: |
| |
| - L1.1 NPSE needs protection from nobody. |
| - L1.2 SPE needs protection from NSPE. |
| |
| The definition for Isolation Level 2: |
| |
| - L2.1 NPSE needs protection from nobody. |
| - L2.2 Application Root of Trust (ARoT) needs protection from NSPE. |
| - L2.3 PSA Root of Trust (PRoT) needs protection from NSPE and ARoT. |
| |
| The definition for Isolation Level 3: |
| |
| - L3.1 NPSE needs protection from nobody. |
| - L3.2 Secure Partition needs protection from NSPE and other Secure Partitions. |
| - L3.3 PSA Root of Trust (RoT) domain needs protection from NSPE and all Secure |
| Partitions. |
| |
| .. important:: |
| A Secure Partition RoT Service is a Root of Trust Service implemented within |
| a Secure Partition. An Application RoT Service must be implemented as |
| a Secure Partition RoT Service. But it is implementation-defined whether a |
| PSA RoT Service is a Secure Partition RoT Service. |
| |
| Here listed several possible PSA RoT Service implementation mechanisms: |
| |
| 1. Implement PSA RoT Services in Secure Partitions with respective |
| boundaries. |
| 2. Implement PSA RoT Services in Secure Partitions, but no boundaries between |
| these Secure Partitions as they are in the PSA RoT Domain. |
| 3. Implement PSA RoT Services in a customized way instead of Secure |
| Partitions, an internal library of PSA RoT domain e.g. |
| |
| TF-M chooses the 2nd option to balance performance and complexity. |
| |
| Isolation Rules |
| =============== |
| The essence of isolation is to protect the assets of one protection domain from |
| being accessed from other domains. The isolation levels define where the |
| isolation boundaries should be placed, the isolation rules define the strength |
| of the isolation the boundaries should offer. |
| |
| .. note:: |
| Refer to chapter `Memory Assets` in `Firmware Framework for M (FF-M)`_ to |
| know asset class items. Assets are represented by memory addresses in the |
| system memory map, which makes assets named `Memory Assets`. The often-seen |
| asset items are ROM, RAM, and memory-mapped peripherals. |
| |
| Memory Asset Class |
| ------------------ |
| There are 3 memory asset classes defined in `Firmware Framework for M (FF-M)`_: |
| |
| - Code |
| - Constant data |
| - Private data |
| |
| There are 6 isolation rules for protecting assets. Here lists the simplified |
| description for the rules, check chapter ``3.1.2`` of ``FF-M 1.0`` for the |
| original description: |
| |
| - I1. Only Code is executable. |
| - I2. Only private data is writable. |
| - I3. If domain A needs protection from domain B, then Private data in domain A |
| cannot be accessed by domain B. |
| - I4. (Optional) If domain A needs protection from domain B, then Code and |
| Constant data in domain A is not readable or executable by domain B. |
| - I5. (Optional) Code in a domain is not executable by any other domain. |
| - I6. (Optional) All assets in a domain are private to that domain and cannot be |
| accessed by any other domain, with the following exception: |
| The domain containing the SPM can only access Private data and Constant data |
| assets of other domains when required to implement the PSA Firmware Framework |
| API. |
| - I7. (Optional, added in FF-M 1.1) Constant data is not executable. |
| |
| The first 3 rules from ``I1`` to ``I3`` defines the mandatory rules to comply |
| the isolation, while ``I4`` to ``I6`` are optional rules to enhance the |
| isolation boundaries. |
| |
| .. important:: |
| There is a table in the chapter ``3.1.2`` of ``FF-M 1.0`` under ``I1`` lists |
| the asset types and allowed access method. Preventing executable access on |
| constant data costs more hardware resources, so there is an optional rule |
| I7 created in `FF-M Extensions (FF-M 1.1)`_ to comfort implementations with |
| constrained hardware resources. |
| |
| Hardware Infrastructure |
| ======================= |
| To implement a secure system, the hardware security framework (TrustZone or |
| multiple-core e.g.) and their auxiliary components (SAU e.g.) are required |
| to ensure the isolation between SPE and NSPE. The requirements: |
| |
| .. important:: |
| The interface between secure and non-secure states needs to be fully |
| enumerated and audited to prove the integrity of the secure state |
| isolation. |
| |
| Besides this SPE and NSPE isolation mechanism, the following analyzes the |
| implementation rules to find out the hardware requirements for isolation inside |
| SPE domains: |
| |
| - I1 and I2: The assets can be categorized into 3 `Memory Asset Class`_, each |
| type has the specific access rules. |
| - I3: The private data access from the prevented domain needs to be blocked. |
| - I4: All the assets access from the prevented domain needs to be blocked. |
| - I5: Code execution from all other domains (even the domain not prevented |
| from) needs to be blocked. |
| - I6: All the assets access from all other domains (includes non-prevented |
| domain) needs to be blocked, but, SPM is an exception, which can access the |
| private data and constant data of the current domain. |
| |
| The above items list the requirements for memory access, here are two more |
| points: |
| |
| - If the memory device or the peripheral are shared between multiple hosts |
| (Such as multiple CPU or DMA, etc), specific hardware protection units need |
| to be available for validating accesses to that device or peripheral. |
| - The MMIO range for Secure Partitions is not allowed to be overlapped, which |
| means each partition should have exclusive memory-mapped region if they |
| require a peripheral device. The memory-mapped region is regarded as |
| the private data so access to this area needs to be validated. |
| |
| ************************ |
| Reference Implementation |
| ************************ |
| This chapter describes the isolation implementation inside SPE by using the |
| Armv8m architecture component - Memory Protection Unit (MPU). The MPU can |
| isolate CPU execution and data access. |
| |
| .. note:: |
| Previous version M-profile architecture MPU setting is similar in concept but |
| the difference in practical register formats, which is not described in this |
| document. |
| |
| The MPU protects memory assets by regions. Each region represents a memory |
| range with specific access attributes. |
| |
| .. note:: |
| The maximum numbers of MPU regions are platform-specific. |
| |
| The SPM is running under the privileged mode for handling access from services. |
| The MPU region for SPM needs to be available all the time since SPM controls |
| the MPU setting while scheduling. |
| |
| Since partitions are scheduled by SPM, the MPU regions corresponding to the |
| partitions can be configured dynamically while scheduling. Since there is only |
| one running at a time and all others are deactivated, the SPM needs to set up |
| necessary regions for each asset type in one partition only. |
| |
| There is re-usable code like the C-Runtime and RoT Service API which are same |
| across different partitions. TF-M creates a Secure Partition Runtime Library |
| (SPRTL) as a specific library shared by the Secure Partition. Please refer to |
| :doc:`Secure Partition Runtime Library </design_docs/services/secure_partition_runtime_library>` |
| for more detail. |
| |
| .. note:: |
| Enable SPRTL makes it hard to comply with the rules I4, I5 and I6, |
| duplicating the library code can be one solution but it is not "shared" |
| library anymore. |
| |
| As mentioned in the last chapter, MMIO needs extra MPU regions as private data. |
| |
| MPU Region Access Permission |
| ============================ |
| The following content would mention the memory access permission to represent |
| the corresponded asset classes. |
| |
| These access permissions are available on Armv8m MPU: |
| |
| - Privileged Read-Only (RO) |
| - All RO |
| - Privileged Read-Write (RW) |
| - All RW |
| - Execution Never (XN) |
| |
| And one more Armv8.1M access permssion: |
| |
| - Privileged Execution Never (PXN) |
| |
| The available regions type list: |
| |
| ======== =========== =============== ======================================== |
| Type Attributes Privilege Level Asset |
| ======== =========== =============== ======================================== |
| P_RO RO Privileged PRoT Code |
| P_ROXN RO + XN Privileged PRoT Constant Data |
| P_RWXN RW + XN Privileged PRoT Private Data/Peripheral |
| A_RO RO Any privilege Partition/SPRTL Code |
| A_ROXN RO + XN Any privilege Partition/SPRTL Constant Data |
| A_RWXN RW + XN Any privilege Partition/SPRTL Private Data/Peripheral |
| A_ROPXN RO + PXN Any privilege Armv8.1M Partition/SPRTL Code |
| ======== =========== =============== ======================================== |
| |
| Example Image Layout |
| ==================== |
| The secure firmware image contains components such as partitions, SPM and the |
| shared code and data. Each component may have different class assets. There |
| would be advantages if placing the assets from all components with the same |
| access attributes into one same region: |
| |
| - The data relocating or clearing when booting can be done in one step instead |
| of breaking into fragments. |
| - Assets with statically assigned access attribute can share the same MPU |
| region which saves regions. |
| |
| Take the TF-M existing implementation image layout as an example:: |
| |
| Level 1 Level 2 Level 3 |
| Boundaries Boundaries Boundaries |
| +------------+----------+------------------------------------+ |
| | | | PRoT SPM Code | |
| | | PRoT +------------------------------------+ |
| | | Code | PRoT Service Code | |
| | Code +----------+------------------------------------+ |
| | (ROM) | | Partition 1 Code | |
| | | +------------------------------------+ |
| | | ARoT | Partition N Code | |
| | | Code +------------------------------------+ |
| | | | SPRTL Code | |
| +------------+----------+------------------------------------+ |
| Check [4] for more details between Code and Constant Data. |
| +------------+----------+------------------------------------+ |
| | | PRoT | PRoT SPM Constant Data | |
| | | Constant +------------------------------------+ |
| | | Data | PRoT Service Constant Data | |
| | Constant +----------+------------------------------------+ |
| | Data | ARoT | Partition 1 Constant Data | |
| | (ROM) | Constant +------------------------------------+ |
| | | Data | Partition N Constant Data | |
| | | +------------------------------------+ |
| | | | SPRTL Constant Data | |
| +------------+----------+------------------------------------+ |
| |
| +------------+----------+------------------------------------+ |
| | | PRoT | PRoT SPM Private Data | |
| | | Private +------------------------------------+ |
| | | Data | PRoT Service Private Data | |
| | Private +----------+------------------------------------+ |
| | Data | | Partition 1 Private Data | |
| | (RAM) | ARoT +------------------------------------+ |
| | | Private | Partition N Private Data | |
| | | Data +------------------------------------+ |
| | | | SPRTL Private Data | |
| +------------+----------+------------------------------------+ |
| |
| .. note:: |
| 1. Multiple binaries image implementation could also reference this layout if |
| its hardware protection unit can cover the exact boundaries mentioned |
| above. |
| 2. Private data includes both initialized and non-initialized (ZI) sections. |
| Check chapter ``3.1.1`` of ``FF-M`` for the details. |
| 3. This diagram shows the boundaries but not orders. The order of regions |
| inside one upper region can be adjusted freely. |
| 4. As described in the ``important`` of `Memory Asset Class`_, the setting |
| between Code and Constant Data can be skipped if the executable access |
| method is not applied to constant data. In this case, the groups of Code |
| and Constant Data can be combined or even mixed -- but the boundary |
| between PRoT and ARoT are still required under level higher than 1. |
| |
| Example Region Numbers under Isolation Level 3 |
| ============================================== |
| The following table lists the required regions while complying the rules for |
| implementing isolation level 3. The level 1 and level 2 can be exported by |
| simplifying the items in level 3 table. |
| |
| .. important:: |
| The table described below is trying to be shared between all supported |
| platforms in Trusted Firmware - M. It is obvious that some platforms have |
| special characteristics. In that case, the specific layout table for a |
| particular platform can be totally redesigned but need to fulfil the |
| isolation level requirements. |
| |
| - Care only the running partitions assets since deactivated partition does not |
| need regions. |
| - `X` indicates the existence of this region can't comply with the rule. |
| - An `ATTR + n` represent extra ``n`` regions are necessary. |
| - Here assumes the rules with a greater number covers the requirements in the |
| rules with less number. |
| |
| Here lists the required regions while complying with the rules: |
| |
| +------------------+-------------+-------------+-------------+-------------+ |
| | Region Purpose | I1 I2 I3 | I4 | I5 | I6 | |
| +==================+=============+=============+=============+=============+ |
| | PRoT SPM Code | A_RO | P_RO | P_RO | P_RO | |
| +------------------+ | | +-------------+ |
| | PRoT Service Code| | | | A_ROPXN | |
| +------------------+ +-------------+-------------+ | |
| | Active Partition | | A_RO | A_ROPXN | | |
| | Code | | | | | |
| +------------------+ +-------------+-------------+-------------+ |
| | SPRTL Code | | ``X`` | ``X`` | ``X`` | |
| +------------------+-------------+-------------+-------------+-------------+ |
| | PRoT SPM RO | A_ROXN | P_ROXN | P_ROXN | P_ROXN | |
| +------------------+ | | +-------------+ |
| | PRoT Service RO | | | | A_ROXN | |
| +------------------+ +-------------+-------------+ | |
| | Active Partition | | A_ROXN | A_ROXN | | |
| | RO | | | | | |
| +------------------+ +-------------+-------------+-------------+ |
| | SPRTL RO | | ``X`` | ``X`` | ``X`` | |
| +------------------+-------------+-------------+-------------+-------------+ |
| | PRoT SPM RW | P_RWXN | P_RWXN | P_RWXN | P_RWXN | |
| +------------------+ | | +-------------+ |
| | PRoT Service RW | | | | A_RWXN | |
| +------------------+-------------+-------------+-------------+ | |
| | Active Partition | A_RWXN | A_RWXN | A_RWXN | | |
| | RW | | | | | |
| +------------------+-------------+-------------+-------------+-------------+ |
| | SPRTL RW [5] | A_RWXN + 1 | ``X`` | ``X`` | ``X`` | |
| +------------------+-------------+-------------+-------------+-------------+ |
| | Partition Peri | A_RWXN + n | A_RWXN + n | A_RWXN + n | A_RWXN + n | |
| +------------------+-------------+-------------+-------------+-------------+ |
| | Total Numbers | [1] | [2] | [3] | [4] | |
| +------------------+-------------+-------------+-------------+-------------+ |
| |
| .. note:: |
| 1. Total number = A_RO + A_ROXN + P_RWXN + A_RWXN + (1 + n)A_RWXN, while |
| n equals the maximum peripheral numbers needed by one partition. This is |
| the configuration chosen by the reference implementation. |
| 2. Total number = P_RO + P_ROXN + P_RWXN + A_RO + A_ROXN + (1 + n)A_RWXN, |
| the minimal result is `6`, and SPRTL can not be applied. |
| 3. Total number = P_RO + P_ROXN + P_RWXN + A_ROXN + (1 + n)A_RWXN + |
| A_ROPXN, the minimal result is `6`, SPRTL can not be applied, and PXN |
| is required. |
| 4. Total number = P_RO + P_ROXN + P_RWXN + A_ROXN + (1 + n)A_RWXN + |
| A_ROPXN, the minimal result is `6`, SPRTL can not be applied, and PXN |
| is required. To comply with this rule, the PSA RoT Service needs |
| to be implemented as Secure Partitions. |
| 5. This data belongs to SPRTL RW but it is set as Read-Only and only SPM |
| can update this region with the activate partition's metadata for |
| implementing functions with owner SP's context, such as heap functions. |
| This region can be skipped if there is no metadata required (such as no |
| heap functionalities required). |
| |
| The memory-mapped regions for peripherals have different memory access |
| attributes in general, they are standalone regions in MPU even their |
| attributes covers 'A_RWXN'. |
| |
| Default access rules |
| ==================== |
| Hardware protection components MAY have the capability to collect regions |
| not explicitly configured in static or runtime settings, and then apply |
| default access rules to the collected. Furthermore, one default rule can be |
| applied to multiple non-contiguous regions which makes them share a common |
| boundary. This operation sets up a standalone 'region' as same as other |
| explicitly configured regions. And it doesn't affect the analysis summary |
| above - just be aware that some regions listed in the table MAY not be |
| explicitly configured. |
| |
| Take the MPU as an example, MPU can assign a default privileged access |
| attribute to the regions (SPM and PRoT regions e.g.) not explicitly configured. |
| This feature can reduce required MPU regions and ease the programming because |
| regions can be put non-address-contiguous and skip the explicit configuration. |
| |
| .. important:: |
| When this default access rules mechanism is applied, the |
| non-explicitly-expressed regions must be reviewed to ensure the isolation |
| boundaries are set properly. |
| |
| Interfaces |
| ========== |
| The isolation implementation is based on the HAL framework. The SPM relies on |
| the HAL API to perform the necessary isolation related operations. |
| |
| The requirement the software need to do are these: |
| |
| - Create enough isolation protection at the early stage of system booting, just |
| need to focus on the SPM domain. |
| - Create an isolation domain between secure and non-secure before the jump to |
| the non-secure world. |
| - Create an isolation domain for each Secure Partition after the Secure |
| Partition is loaded and before jumping to its entry point. The isolation |
| domain should cover all the assets of the Secure Partition, include all its |
| memory, interrupts, and peripherals. |
| - Switch isolation domains when scheduling different Secure Partitions. |
| - It is also a requirement that the platform needs to help to check if the |
| caller of the PSA APIs is permitted to access some memory ranges. |
| |
| |
| The design document |
| :doc:`TF-M Hardware Abstraction Layer </design_docs/software/hardware_abstraction_layer>` |
| gives a detail design, include the platform initialization, isolation |
| interfaces. Please refer to it for more detail. |
| |
| Appendix |
| ======== |
| | `Firmware Framework for M (FF-M)`_ |
| |
| .. _Firmware Framework for M (FF-M): |
| https://www.arm.com/architecture/security-features/platform-security |
| |
| | `FF-M Extensions (FF-M 1.1)`_ |
| |
| .. _FF-M Extensions (FF-M 1.1): |
| https://developer.arm.com/documentation/aes0039/latest |
| |
| | `Trusted Base System Architecture for M (TBSA-M)`_ |
| |
| .. _Trusted Base System Architecture for M (TBSA-M): |
| https://www.arm.com/architecture/security-features/platform-security |
| |
| -------------- |
| |
| *Copyright (c) 2020-2022, Arm Limited. All rights reserved.* |