1##############
2FF-M Isolation
3##############
4
5:Organization: Arm Limited
6:Contact: tf-m@lists.trustedfirmware.org
7
8This document analyzes the isolation rules of implementing ``FF-M 1.0``
9isolation and introduces the reference implementation in TF-M, which
10complies the rules by operating the hardware and software resources.
11
12.. note::
13  Reference the document :doc:`Glossary </glossary>` for terms
14  and abbreviations.
15
16************
17Introduction
18************
19This chapter describes the definitions from ``FF-M`` and analyzes
20the possible implementation keypoints.
21
22Isolation Levels
23================
24There are 3 isolation levels (1-3) defined in ``FF-M``, the greater level
25number has more isolation boundaries.
26
27The definition for Isolation Level 1:
28
29- L1.1 NPSE needs protection from nobody.
30- L1.2 SPE needs protection from NSPE.
31
32The definition for Isolation Level 2:
33
34- L2.1 NPSE needs protection from nobody.
35- L2.2 Application Root of Trust (ARoT) needs protection from NSPE.
36- L2.3 PSA Root of Trust (PRoT) needs protection from NSPE and ARoT.
37
38The definition for Isolation Level 3:
39
40- L3.1 NPSE needs protection from nobody.
41- L3.2 Secure Partition needs protection from NSPE and other Secure Partitions.
42- L3.3 PSA Root of Trust (RoT) domain needs protection from NSPE and all Secure
43  Partitions.
44
45.. important::
46  A Secure Partition RoT Service is a Root of Trust Service implemented within
47  a Secure Partition. An Application RoT Service must be implemented as
48  a Secure Partition RoT Service. But it is implementation-defined whether a
49  PSA RoT Service is a Secure Partition RoT Service.
50
51  Here listed several possible PSA RoT Service implementation mechanisms:
52
53  1. Implement PSA RoT Services in Secure Partitions with respective
54     boundaries.
55  2. Implement PSA RoT Services in Secure Partitions, but no boundaries between
56     these Secure Partitions as they are in the PSA RoT Domain.
57  3. Implement PSA RoT Services in a customized way instead of Secure
58     Partitions, an internal library of PSA RoT domain e.g.
59
60  TF-M chooses the 2nd option to balance performance and complexity.
61
62Isolation Rules
63===============
64The essence of isolation is to protect the assets of one protection domain from
65being accessed from other domains. The isolation levels define where the
66isolation boundaries should be placed, the isolation rules define the strength
67of the isolation the boundaries should offer.
68
69.. note::
70  Refer to chapter `Memory Assets` in `Firmware Framework for M (FF-M)`_ to
71  know asset class items. Assets are represented by memory addresses in the
72  system memory map, which makes assets named `Memory Assets`. The often-seen
73  asset items are ROM, RAM, and memory-mapped peripherals.
74
75Memory Asset Class
76------------------
77There are 3 memory asset classes defined in `Firmware Framework for M (FF-M)`_:
78
79- Code
80- Constant data
81- Private data
82
83There are 6 isolation rules for protecting assets. Here lists the simplified
84description for the rules, check chapter ``3.1.2`` of ``FF-M 1.0`` for the
85original description:
86
87- I1. Only Code is executable.
88- I2. Only private data is writable.
89- I3. If domain A needs protection from domain B, then Private data in domain A
90  cannot be accessed by domain B.
91- I4. (Optional) If domain A needs protection from domain B, then Code and
92  Constant data in domain A is not readable or executable by domain B.
93- I5. (Optional) Code in a domain is not executable by any other domain.
94- I6. (Optional) All assets in a domain are private to that domain and cannot be
95  accessed by any other domain, with the following exception:
96  The domain containing the SPM can only access Private data and Constant data
97  assets of other domains when required to implement the PSA Firmware Framework
98  API.
99- I7. (Optional, added in FF-M 1.1) Constant data is not executable.
100
101 The first 3 rules from ``I1`` to ``I3`` defines the mandatory rules to comply
102 the isolation, while ``I4`` to ``I6`` are optional rules to enhance the
103 isolation boundaries.
104
105 .. important::
106   There is a table in the chapter ``3.1.2`` of ``FF-M 1.0`` under ``I1`` lists
107   the asset types and allowed access method. Preventing executable access on
108   constant data costs more hardware resources, so there is an optional rule
109   I7 created in `FF-M Extensions (FF-M 1.1)`_ to comfort implementations with
110   constrained hardware resources.
111
112Hardware Infrastructure
113=======================
114To implement a secure system, the hardware security framework (TrustZone or
115multiple-core e.g.) and their auxiliary components (SAU e.g.) are required
116to ensure the isolation between SPE and NSPE. The requirements:
117
118.. important::
119  The interface between secure and non-secure states needs to be fully
120  enumerated and audited to prove the integrity of the secure state
121  isolation.
122
123Besides this SPE and NSPE isolation mechanism, the following analyzes the
124implementation rules to find out the hardware requirements for isolation inside
125SPE domains:
126
127- I1 and I2: The assets can be categorized into 3 `Memory Asset Class`_, each
128  type has the specific access rules.
129- I3: The private data access from the prevented domain needs to be blocked.
130- I4: All the assets access from the prevented domain needs to be blocked.
131- I5: Code execution from all other domains (even the domain not prevented
132  from) needs to be blocked.
133- I6: All the assets access from all other domains (includes non-prevented
134  domain) needs to be blocked, but, SPM is an exception, which can access the
135  private data and constant data of the current domain.
136
137The above items list the requirements for memory access, here are two more
138points:
139
140- If the memory device or the peripheral are shared between multiple hosts
141  (Such as multiple CPU or DMA, etc), specific hardware protection units need
142  to be available for validating accesses to that device or peripheral.
143- The MMIO range for Secure Partitions is not allowed to be overlapped, which
144  means each partition should have exclusive memory-mapped region if they
145  require a peripheral device. The memory-mapped region is regarded as
146  the private data so access to this area needs to be validated.
147
148************************
149Reference Implementation
150************************
151This chapter describes the isolation implementation inside SPE by using the
152Armv8m architecture component - Memory Protection Unit (MPU). The MPU can
153isolate CPU execution and data access.
154
155.. note::
156  Previous version M-profile architecture MPU setting is similar in concept but
157  the difference in practical register formats, which is not described in this
158  document.
159
160The MPU protects memory assets by regions. Each region represents a memory
161range with specific access attributes.
162
163.. note::
164  The maximum numbers of MPU regions are platform-specific.
165
166The SPM is running under the privileged mode for handling access from services.
167The MPU region for SPM needs to be available all the time since SPM controls
168the MPU setting while scheduling.
169
170Since partitions are scheduled by SPM, the MPU regions corresponding to the
171partitions can be configured dynamically while scheduling. Since there is only
172one running at a time and all others are deactivated, the SPM needs to set up
173necessary regions for each asset type in one partition only.
174
175There is re-usable code like the C-Runtime and RoT Service API which are same
176across different partitions. TF-M creates a Secure Partition Runtime Library
177(SPRTL) as a specific library shared by the Secure Partition. Please refer to
178:doc:`Secure Partition Runtime Library </design_docs/services/secure_partition_runtime_library>`
179for more detail.
180
181.. note::
182  Enable SPRTL makes it hard to comply with the rules I4, I5 and I6,
183  duplicating the library code can be one solution but it is not "shared"
184  library anymore.
185
186As mentioned in the last chapter, MMIO needs extra MPU regions as private data.
187
188MPU Region Access Permission
189============================
190The following content would mention the memory access permission to represent
191the corresponded asset classes.
192
193These access permissions are available on Armv8m MPU:
194
195- Privileged Read-Only (RO)
196- All RO
197- Privileged Read-Write (RW)
198- All RW
199- Execution Never (XN)
200
201And one more Armv8.1M access permssion:
202
203- Privileged Execution Never (PXN)
204
205The available regions type list:
206
207======== =========== =============== ========================================
208Type     Attributes  Privilege Level Asset
209======== =========== =============== ========================================
210P_RO     RO          Privileged      PRoT Code
211P_ROXN   RO + XN     Privileged      PRoT Constant Data
212P_RWXN   RW + XN     Privileged      PRoT Private Data/Peripheral
213A_RO     RO          Any privilege   Partition/SPRTL Code
214A_ROXN   RO + XN     Any privilege   Partition/SPRTL Constant Data
215A_RWXN   RW + XN     Any privilege   Partition/SPRTL Private Data/Peripheral
216A_ROPXN  RO + PXN    Any privilege   Armv8.1M Partition/SPRTL Code
217======== =========== =============== ========================================
218
219Example Image Layout
220====================
221The secure firmware image contains components such as partitions, SPM and the
222shared code and data. Each component may have different class assets. There
223would be advantages if placing the assets from all components with the same
224access attributes into one same region:
225
226- The data relocating or clearing when booting can be done in one step instead
227  of breaking into fragments.
228- Assets with statically assigned access attribute can share the same MPU
229  region which saves regions.
230
231Take the TF-M existing implementation image layout as an example::
232
233   Level 1      Level 2             Level 3
234   Boundaries   Boundaries          Boundaries
235  +------------+----------+------------------------------------+
236  |            |          |    PRoT SPM                Code    |
237  |            | PRoT     +------------------------------------+
238  |            | Code     |    PRoT Service            Code    |
239  |  Code      +----------+------------------------------------+
240  |  (ROM)     |          |    Partition 1             Code    |
241  |            |          +------------------------------------+
242  |            | ARoT     |    Partition N             Code    |
243  |            | Code     +------------------------------------+
244  |            |          |    SPRTL                   Code    |
245  +------------+----------+------------------------------------+
246  Check [4] for more details between Code and Constant Data.
247  +------------+----------+------------------------------------+
248  |            | PRoT     |    PRoT SPM       Constant Data    |
249  |            | Constant +------------------------------------+
250  |            | Data     |    PRoT Service   Constant Data    |
251  |  Constant  +----------+------------------------------------+
252  |   Data     | ARoT     |    Partition 1    Constant Data    |
253  |   (ROM)    | Constant +------------------------------------+
254  |            | Data     |    Partition N    Constant Data    |
255  |            |          +------------------------------------+
256  |            |          |    SPRTL          Constant Data    |
257  +------------+----------+------------------------------------+
258
259  +------------+----------+------------------------------------+
260  |            | PRoT     |    PRoT SPM        Private Data    |
261  |            | Private  +------------------------------------+
262  |            | Data     |    PRoT Service    Private Data    |
263  |  Private   +----------+------------------------------------+
264  |   Data     |          |    Partition 1     Private Data    |
265  |   (RAM)    | ARoT     +------------------------------------+
266  |            | Private  |    Partition N     Private Data    |
267  |            | Data     +------------------------------------+
268  |            |          |    SPRTL           Private Data    |
269  +------------+----------+------------------------------------+
270
271.. note::
272  1. Multiple binaries image implementation could also reference this layout if
273     its hardware protection unit can cover the exact boundaries mentioned
274     above.
275  2. Private data includes both initialized and non-initialized (ZI) sections.
276     Check chapter ``3.1.1`` of ``FF-M`` for the details.
277  3. This diagram shows the boundaries but not orders. The order of regions
278     inside one upper region can be adjusted freely.
279  4. As described in the ``important`` of `Memory Asset Class`_, the setting
280     between Code and Constant Data can be skipped if the executable access
281     method is not applied to constant data. In this case, the groups of Code
282     and Constant Data can be combined or even mixed -- but the boundary
283     between PRoT and ARoT are still required under level higher than 1.
284
285Example Region Numbers under Isolation Level 3
286==============================================
287The following table lists the required regions while complying the rules for
288implementing isolation level 3. The level 1 and level 2 can be exported by
289simplifying the items in level 3 table.
290
291.. important::
292  The table described below is trying to be shared between all supported
293  platforms in Trusted Firmware - M. It is obvious that some platforms have
294  special characteristics. In that case, the specific layout table for a
295  particular platform can be totally redesigned but need to fulfil the
296  isolation level requirements.
297
298- Care only the running partitions assets since deactivated partition does not
299  need regions.
300- `X` indicates the existence of this region can't comply with the rule.
301- An `ATTR + n` represent extra ``n`` regions are necessary.
302- Here assumes the rules with a greater number covers the requirements in the
303  rules with less number.
304
305Here lists the required regions while complying with the rules:
306
307+------------------+-------------+-------------+-------------+-------------+
308| Region Purpose   | I1 I2 I3    | I4          | I5          | I6          |
309+==================+=============+=============+=============+=============+
310| PRoT SPM Code    | A_RO        | P_RO        |  P_RO       |   P_RO      |
311+------------------+             |             |             +-------------+
312| PRoT Service Code|             |             |             | A_ROPXN     |
313+------------------+             +-------------+-------------+             |
314| Active Partition |             | A_RO        | A_ROPXN     |             |
315| Code             |             |             |             |             |
316+------------------+             +-------------+-------------+-------------+
317| SPRTL Code       |             | ``X``       | ``X``       | ``X``       |
318+------------------+-------------+-------------+-------------+-------------+
319| PRoT SPM RO      | A_ROXN      | P_ROXN      | P_ROXN      | P_ROXN      |
320+------------------+             |             |             +-------------+
321| PRoT Service RO  |             |             |             | A_ROXN      |
322+------------------+             +-------------+-------------+             |
323| Active Partition |             | A_ROXN      | A_ROXN      |             |
324| RO               |             |             |             |             |
325+------------------+             +-------------+-------------+-------------+
326| SPRTL RO         |             | ``X``       | ``X``       | ``X``       |
327+------------------+-------------+-------------+-------------+-------------+
328| PRoT SPM RW      | P_RWXN      | P_RWXN      | P_RWXN      | P_RWXN      |
329+------------------+             |             |             +-------------+
330| PRoT Service RW  |             |             |             | A_RWXN      |
331+------------------+-------------+-------------+-------------+             |
332| Active Partition | A_RWXN      | A_RWXN      | A_RWXN      |             |
333| RW               |             |             |             |             |
334+------------------+-------------+-------------+-------------+-------------+
335| SPRTL RW [5]     | A_RWXN + 1  | ``X``       | ``X``       | ``X``       |
336+------------------+-------------+-------------+-------------+-------------+
337| Partition Peri   | A_RWXN + n  | A_RWXN + n  | A_RWXN + n  | A_RWXN + n  |
338+------------------+-------------+-------------+-------------+-------------+
339| Total Numbers    | [1]         | [2]         | [3]         | [4]         |
340+------------------+-------------+-------------+-------------+-------------+
341
342.. note::
343  1. Total number = A_RO + A_ROXN + P_RWXN + A_RWXN + (1 + n)A_RWXN, while
344     n equals the maximum peripheral numbers needed by one partition. This is
345     the configuration chosen by the reference implementation.
346  2. Total number = P_RO + P_ROXN + P_RWXN + A_RO + A_ROXN + (1 + n)A_RWXN,
347     the minimal result is `6`, and SPRTL can not be applied.
348  3. Total number = P_RO + P_ROXN + P_RWXN + A_ROXN + (1 + n)A_RWXN +
349     A_ROPXN, the minimal result is `6`, SPRTL can not be applied, and PXN
350     is required.
351  4. Total number = P_RO + P_ROXN + P_RWXN + A_ROXN + (1 + n)A_RWXN +
352     A_ROPXN, the minimal result is `6`, SPRTL can not be applied, and PXN
353     is required. To comply with this rule, the PSA RoT Service needs
354     to be implemented as Secure Partitions.
355  5. This data belongs to SPRTL RW but it is set as Read-Only and only SPM
356     can update this region with the activate partition's metadata for
357     implementing functions with owner SP's context, such as heap functions.
358     This region can be skipped if there is no metadata required (such as no
359     heap functionalities required).
360
361  The memory-mapped regions for peripherals have different memory access
362  attributes in general, they are standalone regions in MPU even their
363  attributes covers 'A_RWXN'.
364
365Default access rules
366====================
367Hardware protection components MAY have the capability to collect regions
368not explicitly configured in static or runtime settings, and then apply
369default access rules to the collected. Furthermore, one default rule can be
370applied to multiple non-contiguous regions which makes them share a common
371boundary. This operation sets up a standalone 'region' as same as other
372explicitly configured regions. And it doesn't affect the analysis summary
373above - just be aware that some regions listed in the table MAY not be
374explicitly configured.
375
376Take the MPU as an example, MPU can assign a default privileged access
377attribute to the regions (SPM and PRoT regions e.g.) not explicitly configured.
378This feature can reduce required MPU regions and ease the programming because
379regions can be put non-address-contiguous and skip the explicit configuration.
380
381.. important::
382  When this default access rules mechanism is applied, the
383  non-explicitly-expressed regions must be reviewed to ensure the isolation
384  boundaries are set properly.
385
386Interfaces
387==========
388The isolation implementation is based on the HAL framework. The SPM relies on
389the HAL API to perform the necessary isolation related operations.
390
391The requirement the software need to do are these:
392
393- Create enough isolation protection at the early stage of system booting, just
394  need to focus on the SPM domain.
395- Create an isolation domain between secure and non-secure before the jump to
396  the non-secure world.
397- Create an isolation domain for each Secure Partition after the Secure
398  Partition is loaded and before jumping to its entry point. The isolation
399  domain should cover all the assets of the Secure Partition, include all its
400  memory, interrupts, and peripherals.
401- Switch isolation domains when scheduling different Secure Partitions.
402- It is also a requirement that the platform needs to help to check if the
403  caller of the PSA APIs is permitted to access some memory ranges.
404
405
406The design document
407:doc:`TF-M Hardware Abstraction Layer </design_docs/software/hardware_abstraction_layer>`
408gives a detail design, include the platform initialization, isolation
409interfaces. Please refer to it for more detail.
410
411Appendix
412========
413| `Firmware Framework for M (FF-M)`_
414
415.. _Firmware Framework for M (FF-M):
416  https://www.arm.com/architecture/security-features/platform-security
417
418| `FF-M Extensions (FF-M 1.1)`_
419
420.. _FF-M Extensions (FF-M 1.1):
421  https://developer.arm.com/documentation/aes0039/latest
422
423| `Trusted Base System Architecture for M (TBSA-M)`_
424
425.. _Trusted Base System Architecture for M (TBSA-M):
426  https://www.arm.com/architecture/security-features/platform-security
427
428--------------
429
430*Copyright (c) 2020-2022, Arm Limited. All rights reserved.*
431