Merge "docs(threat-model): add a threat model for TF-A with Arm CCA" into integration

4 files changed, 317 insertions, 0 deletions

diff --git a/docs/resources/diagrams/plantuml/tfa_arm_cca_dfd.puml b/docs/resources/diagrams/plantuml/tfa_arm_cca_dfd.puml
new file mode 100644
index 000000000..493f07884
--- /dev/null
+++ b/docs/resources/diagrams/plantuml/tfa_arm_cca_dfd.puml
@@ -0,0 +1,82 @@
+/'
+ ' Copyright (c) 2023, Arm Limited. All rights reserved.
+ '
+ ' SPDX-License-Identifier: BSD-3-Clause
+ '/
+
+/'
+TF-A with Arm CCA Data Flow Diagram
+'/
+
+@startuml
+digraph tfa_dfd {
+
+    # Arrange nodes from left to right
+    rankdir="LR"
+
+    # Allow arrows to end on cluster boundaries
+    compound=true
+
+    # Default settings for edges and nodes
+    edge [minlen=2 color="#8c1b07"]
+    node [fillcolor="#ffb866" style=filled shape=box fixedsize=true width=1.6 height=0.7]
+
+    # Nodes outside of the trust boundary
+    realm [label="Realm\nClients"]
+    nsec [label="Non-secure\nClients"]
+    sec [label="Secure\nClients"]
+    dbg [label="Debug & Trace"]
+    uart [label="UART"]
+    nvm [label="Non-volatile\nMemory"]
+
+    # Trust boundary cluster
+    subgraph cluster_trusted{
+        graph [style=dashed color="#f22430"]
+
+        # HW IPs cluster
+        subgraph cluster_ip{
+            label ="Hardware IPs";
+            graph [style=filled color="#000000" fillcolor="#ffd29e"]
+
+            rank="same"
+            gic [label="GIC" width=1.2 height=0.5]
+            mmu [label="MMU" width=1.2 height=0.5]
+            etc [label="..." shape=none style=none height=0.5]
+        }
+
+        # TF-A cluster
+        subgraph cluster_tfa{
+            label ="TF-A";
+            graph [style=filled color="#000000" fillcolor="#faf9cd"]
+
+            bl1 [label="Boot ROM\n(BL1)" fillcolor="#ddffb3"];
+            bl2 [label="Trusted Boot\nFirmware\n(BL2)" fillcolor="#ddffb3" height=1]
+            bl31 [label="TF-A Runtime\n(BL31)" fillcolor="#ddffb3"]
+        }
+
+        # HES cluster
+        subgraph cluster_hes{
+            label ="Arm CCA HES";
+            graph [style=filled color="#000000" fillcolor="#ffd29e"]
+
+            hes [label="Hardware\nEnforced Security"]
+        }
+    }
+
+    # Interactions between nodes
+
+    # -- The following lines are copied from tfa_dfd.puml and must not be
+    #    changed, at the risk of invalidating DF* references.
+    nvm -> bl31 [lhead=cluster_tfa label="DF1"]
+    uart -> bl31 [dir="both" lhead=cluster_tfa label="DF2"]
+    dbg -> bl2 [dir="both" lhead=cluster_tfa label="DF3"]
+    sec -> bl2 [dir="both" lhead=cluster_tfa label="DF4"]
+    nsec -> bl1 [dir="both" lhead=cluster_tfa, label="DF5"]
+    bl2 -> mmu [dir="both" ltail=cluster_tfa lhead=cluster_ip label="DF6"]
+
+    # -- The following lines are new for Arm CCA DFD.
+    bl2 -> hes [dir="both" ltail=cluster_tfa lhead=cluster_hes label="DF7"]
+    realm -> bl2 [dir="both" lhead=cluster_tfa label="DF8"]
+}
+
+@enduml
diff --git a/docs/threat_model/index.rst b/docs/threat_model/index.rst
index 3e0393e38..e22378b0b 100644
--- a/docs/threat_model/index.rst
+++ b/docs/threat_model/index.rst
@@ -34,6 +34,7 @@ data flow diagram, as well as a list of threats we have identified using the
    threat_model_el3_spm
    threat_model_fvp_r
    threat_model_rss_interface
+   threat_model_arm_cca
 
 --------------
 
diff --git a/docs/threat_model/threat_model.rst b/docs/threat_model/threat_model.rst
index d1a77f587..0da255854 100644
--- a/docs/threat_model/threat_model.rst
+++ b/docs/threat_model/threat_model.rst
@@ -36,6 +36,9 @@ assumptions:
 - There are no Root and Realm worlds. These are introduced by :ref:`Realm
   Management Extension (RME)`.
 
+  The :ref:`Threat Model for TF-A with Arm CCA support` covers these types of
+  configurations.
+
 - No experimental features are enabled. We do not consider threats that may come
   from them.
 
@@ -274,6 +277,8 @@ some threats are confined in specific images, while others apply to each of
 them. To help developers implement mitigations in the right place, threats below
 are categorized based on the firmware image that should mitigate them.
 
+.. _General Threats:
+
 General Threats for All Firmware Images
 ---------------------------------------
 
@@ -608,6 +613,8 @@ General Threats for All Firmware Images
 +------------------------+-----------------------------------------------------+
 
 
+.. _Boot Firmware Threats:
+
 Threats to be Mitigated by the Boot Firmware
 --------------------------------------------
 
@@ -842,6 +849,8 @@ nonetheless once execution has reached the runtime EL3 firmware.
  since the |SRTM| includes all secure world components.
 
 
+.. _Runtime Firmware Threats:
+
 Threats to be Mitigated by the Runtime EL3 Firmware
 ---------------------------------------------------
 
diff --git a/docs/threat_model/threat_model_arm_cca.rst b/docs/threat_model/threat_model_arm_cca.rst
new file mode 100644
index 000000000..fbf3327b7
--- /dev/null
+++ b/docs/threat_model/threat_model_arm_cca.rst
@@ -0,0 +1,225 @@
+Threat Model for TF-A with Arm CCA support
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Introduction
+************
+
+This document provides a threat model of TF-A firmware for platforms with Arm
+Realm Management Extension (RME) support which implement Arm Confidential
+Compute Architecture (Arm CCA).
+
+Although it is a separate document, it references the :ref:`Generic Threat
+Model` in a number of places, as some of the contents is commonly applicable to
+TF-A with or without Arm CCA support.
+
+Target of Evaluation
+********************
+
+In this threat model, the target of evaluation is the Trusted Firmware for
+A-class Processors (TF-A) with RME support and Arm CCA support. This includes
+the boot ROM (BL1), the trusted boot firmware (BL2) and the runtime EL3 firmware
+(BL31).
+
+Assumptions
+===========
+
+We make the following assumptions:
+
+- :ref:`Realm Management Extension (RME)` is enabled on the platform.
+
+- Arm CCA Hardware Enforced Security (HES) is available on the platform, as
+  recommended by `Arm CCA security model`_:
+
+    *[R0004] Arm strongly recommends that all implementations of CCA utilize*
+    *hardware enforced security (CCA HES).*
+
+- All TF-A images run from on-chip memory. Data used by these images also live
+  in on-chip memory. This means TF-A is not vulnerable to an attacker that can
+  probe or tamper with off-chip memory.
+
+  These are requirements of the `Arm CCA security model`_:
+
+    *[R0147] Monitor code executes entirely from on-chip memory.*
+
+    *[R0149] Any monitor data that may affect the CCA security guarantee, other*
+    *than GPT, is either held in on-chip memory, or in external memory but with*
+    *additional integrity protection.*
+
+  Note that this threat model hardens *[R0149]* requirement by forbidding to
+  hold data in external memory, even if it is integrity-protected - except for
+  GPT data.
+
+- TF-A BL1 image is immutable and thus implicitly trusted. It runs from
+  read-only memory or write-protected memory. This could be on-chip ROM, on-chip
+  OTP, locked on-chip flash, or write-protected on-chip RAM for example.
+
+  This is a requirement of the `Arm CCA security model`_:
+
+    *[R0158] Arm recommends that all initial boot code is immutable on a*
+    *secured system.*
+
+    *[R0050] If all or part of initial boot code is instantiated in on-chip*
+    *memory then other trusted subsystems or application PE cannot modify that*
+    *code before it has been executed.*
+
+- Trusted boot and measured boot are enabled. This means an attacker can't boot
+  arbitrary images that are not approved by platform providers.
+
+  These are requirements of the `Arm CCA security model`_:
+
+    *[R0048] A secured system can only load authorized CCA firmware.*
+
+    *[R0079] All Monitor firmware loaded by PE initial boot is measured and*
+    *verified as outlined in Verified boot.*
+
+- No experimental features are enabled. These are typically incomplete features,
+  which need more time to stabilize. Thus, we do not consider threats that may
+  come from them. It is not recommended to use these features in production
+  builds.
+
+Data Flow Diagram
+=================
+
+Figure 1 shows a high-level data flow diagram for TF-A. The diagram shows a
+model of the different components of a TF-A-based system and their interactions
+with TF-A. A description of each diagram element is given on Table 1. On the
+diagram, the red broken lines indicate trust boundaries. Components outside of
+the broken lines are considered untrusted by TF-A.
+
+.. uml:: ../resources/diagrams/plantuml/tfa_arm_cca_dfd.puml
+  :caption: Figure 1: Data Flow Diagram
+
+.. table:: Table 1: Data Flow Diagram Description
+
+  +-----------------+--------------------------------------------------------+
+  | Diagram Element | Description                                            |
+  +=================+========================================================+
+  |       DF1       | | Refer to DF1 description in the                      |
+  |                 |   :ref:`Generic Threat Model`. Additionally TF-A       |
+  |                 |   loads realm images.                                  |
+  +-----------------+--------------------------------------------------------+
+  |     DF2-DF6     | | Refer to DF2-DF6 descriptions in the                 |
+  |                 |   :ref:`Generic Threat Model`.                         |
+  +-----------------+--------------------------------------------------------+
+  |       DF7       | | Boot images interact with Arm CCA HES to record boot |
+  |                 |   measurements and retrieve data used for AP images    |
+  |                 |   authentication.                                      |
+  |                 |                                                        |
+  |                 | | The runtime firmware interacts with Arm CCA HES to   |
+  |                 |   obtain sensitive attestation data for the realm      |
+  |                 |   world.                                               |
+  +-----------------+--------------------------------------------------------+
+  |       DF8       | | Realm world software (e.g. TF-RMM) interact with     |
+  |                 |   TF-A through SMC call interface and/or shared        |
+  |                 |   memory.                                              |
+  +-----------------+--------------------------------------------------------+
+
+Threat Analysis
+***************
+
+In this threat model, we use the same method to analyse threats as in the
+:ref:`Generic Threat Model`. This section only points out differences where
+applicable.
+
+- There is an additional threat agent: *RealmCode*. It takes the form of
+  malicious or faulty code running in the realm world, including R-EL2, R-EL1
+  and R-EL0 levels.
+
+- At this time we only consider the ``Server`` target environment. New threats
+  identified in this threat model will only be given a risk rating for this
+  environment. Other environments may be added in a future revision
+
+Threat Assessment
+=================
+
+General Threats for All Firmware Images
+---------------------------------------
+
+The following table analyses the :ref:`General Threats` in the context of this
+threat model. Only deltas are pointed out.
+
+  +----+-------------+-------------------------------------------------------+
+  | ID | Applicable? | Comments                                              |
+  +====+=============+=======================================================+
+  | 05 |     Yes     |                                                       |
+  +----+-------------+-------------------------------------------------------+
+  | 06 |     Yes     |                                                       |
+  +----+-------------+-------------------------------------------------------+
+  | 08 |     Yes     | Additional diagram element: DF8.                      |
+  |    |             |                                                       |
+  |    |             | Additional threat agent: RealmCode.                   |
+  +----+-------------+-------------------------------------------------------+
+  | 11 |     Yes     | | Misconfiguration of the Memory Management Unit      |
+  |    |             |   (MMU) may allow a **normal/secure/realm** world     |
+  |    |             |   software to access sensitive data, execute arbitrary|
+  |    |             |   code or access otherwise restricted HW interface.   |
+  |    |             |                                                       |
+  |    |             | | **Note that on RME systems, MMU configuration also  |
+  |    |             |   includes Granule Protection Tables (GPT) setup.**   |
+  |    |             |                                                       |
+  |    |             | | Additional diagram elements: DF4, DF7, DF8.         |
+  |    |             |                                                       |
+  |    |             | | Additional threat agents: SecCode, RealmCode.       |
+  +----+-------------+-------------------------------------------------------+
+  | 13 |     Yes     | Additional diagram element: DF8.                      |
+  |    |             |                                                       |
+  |    |             | Additional threat agent: RealmCode.                   |
+  +----+-------------+-------------------------------------------------------+
+  | 15 |     Yes     | Additional diagram element: DF8.                      |
+  |    |             |                                                       |
+  |    |             | Additional threat agent: RealmCode.                   |
+  +----+-------------+-------------------------------------------------------+
+
+Threats to be Mitigated by the Boot Firmware
+--------------------------------------------
+
+The following table analyses the :ref:`Boot Firmware Threats` in the context of
+this threat model. Only deltas are pointed out.
+
+  +----+-------------+-------------------------------------------------------+
+  | ID | Applicable? | Comments                                              |
+  +====+=============+=======================================================+
+  | 01 |     Yes     | Additional diagram element: DF8.                      |
+  |    |             |                                                       |
+  |    |             | Additional threat agent: RealmCode.                   |
+  +----+-------------+-------------------------------------------------------+
+  | 02 |     Yes     | Additional diagram element: DF8.                      |
+  |    |             |                                                       |
+  |    |             | Additional threat agent: RealmCode.                   |
+  +----+-------------+-------------------------------------------------------+
+  | 03 |     Yes     |                                                       |
+  +----+-------------+-------------------------------------------------------+
+  | 04 |     Yes     |                                                       |
+  +----+-------------+-------------------------------------------------------+
+
+Threats to be Mitigated by the Runtime EL3 Firmware
+---------------------------------------------------
+
+The following table analyses the :ref:`Runtime Firmware Threats` in the context
+of this threat model. Only deltas are pointed out.
+
+  +----+-------------+-------------------------------------------------------+
+  | ID | Applicable? | Comments                                              |
+  +====+=============+=======================================================+
+  | 07 |     Yes     | Additional diagram element: DF8.                      |
+  |    |             |                                                       |
+  |    |             | Additional threat agent: RealmCode.                   |
+  +----+-------------+-------------------------------------------------------+
+  | 09 |     Yes     | Additional diagram element: DF8.                      |
+  |    |             |                                                       |
+  |    |             | Additional threat agent: RealmCode.                   |
+  +----+-------------+-------------------------------------------------------+
+  | 10 |     Yes     | Additional diagram element: DF8.                      |
+  |    |             |                                                       |
+  |    |             | Additional threat agent: RealmCode.                   |
+  +----+-------------+-------------------------------------------------------+
+  | 12 |     Yes     | Additional diagram element: DF8.                      |
+  |    |             |                                                       |
+  |    |             | Additional threat agent: RealmCode.                   |
+  +----+-------------+-------------------------------------------------------+
+  | 14 |     Yes     |                                                       |
+  +----+-------------+-------------------------------------------------------+
+
+*Copyright (c) 2023, Arm Limited. All rights reserved.*
+
+.. _Arm CCA Security Model: https://developer.arm.com/documentation/DEN0096/A_a