docs: add threat model for AP-RSS interface
Signed-off-by: Tamas Ban <tamas.ban@arm.com>
Change-Id: Ic818da12584503e1a96396c4b55a8db14ae7584a
diff --git a/docs/resources/diagrams/plantuml/tfa_rss_dfd.puml b/docs/resources/diagrams/plantuml/tfa_rss_dfd.puml
new file mode 100644
index 0000000..23f5b17
--- /dev/null
+++ b/docs/resources/diagrams/plantuml/tfa_rss_dfd.puml
@@ -0,0 +1,77 @@
+/'
+ ' Copyright (c) 2021-2022, Arm Limited. All rights reserved.
+ '
+ ' SPDX-License-Identifier: BSD-3-Clause
+ '/
+
+/'
+TF-A Data Flow Diagram including RSS
+'/
+
+@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
+ nsec [label="Non-secure\nClients"]
+ sec [label="Secure\nClients"]
+ dbg [label="Debug & Trace"]
+ logs [label="Logs\n(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]
+ tzc [label="TZ\nController" 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"]
+ }
+
+ # RSS cluster
+ subgraph cluster_rss{
+ label ="RSS";
+ graph [style=filled color="#000000" fillcolor="#faf9cd"]
+
+ rss [label="Runtime Security\n\ Subsystem\n\ (RSS)" fillcolor="#ddffb3"]
+ }
+ }
+
+ # Interactions between nodes
+ nvm -> bl31 [lhead=cluster_tfa label="DF1"]
+ logs -> bl31 [dir="back" 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 -> tzc [dir="both" ltail=cluster_tfa lhead=cluster_ip label="DF6" minlen=1]
+ bl31 -> rss [dir="both" ltail=cluster_tfa lhead=cluster_rss label="DF7" minlen=1]
+
+}
+
+@enduml
diff --git a/docs/threat_model/index.rst b/docs/threat_model/index.rst
index ad8b82a..9fd55a9 100644
--- a/docs/threat_model/index.rst
+++ b/docs/threat_model/index.rst
@@ -16,7 +16,8 @@
threat_model_spm
threat_model_el3_spm
threat_model_fvp_r
+ threat_model_rss_interface
--------------
-*Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2021-2022, Arm Limited and Contributors. All rights reserved.*
diff --git a/docs/threat_model/threat_model_rss_interface.rst b/docs/threat_model/threat_model_rss_interface.rst
new file mode 100644
index 0000000..4bceb63
--- /dev/null
+++ b/docs/threat_model/threat_model_rss_interface.rst
@@ -0,0 +1,59 @@
+Threat Model for RSS - AP interface
+***********************************
+
+************
+Introduction
+************
+This document is an extension for the general TF-A threat-model. It considers
+those platforms where a Runtime Security Subsystem (RSS) is included in the SoC
+next to the Application Processor (AP).
+
+********************
+Target of Evaluation
+********************
+The scope of this threat model only includes the interface between the RSS and
+AP. Otherwise, the TF-A :ref:`Generic Threat Model` document is applicable for
+the AP core. The threat model for the RSS firmware will be provided by the RSS
+firmware project in the future.
+
+
+Data Flow Diagram
+=================
+This diagram is different only from the general TF-A data flow diagram in that
+it includes the RSS and highlights the interface between the AP and the RSS
+cores. The interface description only focuses on the AP-RSS interface the rest
+is the same as in the general TF-A threat-model document.
+
+.. uml:: ../resources/diagrams/plantuml/tfa_rss_dfd.puml
+ :caption: Figure 1: TF-A Data Flow Diagram including RSS
+
+.. table:: Table 1: TF-A - RSS data flow diagram
+
+ +-----------------+--------------------------------------------------------+
+ | Diagram Element | Description |
+ +=================+========================================================+
+ | DF7 | | Boot images interact with RSS over a communication |
+ | | channel to record boot measurements and get image |
+ | | verification keys. At runtime, BL31 obtains the |
+ | | realm world attestation signing key from RSS. |
+ +-----------------+--------------------------------------------------------+
+
+Threat Assessment
+=================
+For this section, please reference the Threat Assessment under the general TF-A
+threat-model document, :ref:`Generic Threat Model`. All the threats listed there
+are applicable for the AP core, here only the differences are highlighted.
+
+ - ID 11: The access to the communication interface between AP and RSS is
+ allowed only for firmware running at EL3. Accidentally exposing this
+ interface to NSCode can allow malicious code to interact with RSS and
+ gain access to sensitive data.
+ - ID 13: Relevant in the context of the realm attestation key, which can be
+ retrieved by BL31 through DF7. The RSS communication protocol layer
+ mitigates against this by clearing its internal buffer when reply is
+ received. The caller of the API must do the same if data is not needed
+ anymore.
+
+--------------
+
+*Copyright (c) 2022, Arm Limited. All rights reserved.*
\ No newline at end of file