Merge changes from topic "dtpm_poc" into integration

* changes:
  feat(docs): add DPE to RSE desing doc
  feat(docs): add RSE provided mboot backends to the threat model
  feat(docs): update mboot threat model

docs/design_documents/measured_boot.rst

@@ -91,10 +91,10 @@ The Measured Boot implementation in TF-A supports:
    and the variable length crypto agile structure called TCG_PCR_EVENT2. Event
    Log driver implemented in TF-A covers later part.
 
-#. RSE
+#. |RSE|
 
-   It is one of physical backend to extend the measurements. Please refer this
+   It is one of the physical backends to extend the measurements. Please refer
-   document :ref:`Runtime Security Engine (RSE)` for more details.
+   this document :ref:`Runtime Security Engine (RSE)` for more details.
 
 Platform Interface
 ------------------
@@ -121,7 +121,7 @@ Responsibilities of these platform interfaces are -
       void bl2_plat_mboot_init(void);
 
    Initialise all Measured Boot backends supported by the platform
-   (e.g. Event Log buffer, RSE). As these functions do not return any value,
+   (e.g. Event Log buffer, |RSE|). As these functions do not return any value,
    the platform should deal with error management, such as logging the error
    somewhere, or panicking the system if this is considered a fatal error.
 
@@ -147,8 +147,9 @@ Responsibilities of these platform interfaces are -
 
      - If it is Event Log backend, then record the measurement in TCG Event Log
        format.
-     - If it is a secure crypto-processor (like RSE), then extend the designated
+     - If it is a secure crypto-processor (like |RSE|), then extend the
-       PCR (or slot) with the given measurement.
+       designated PCR (or store it in secure on-chip memory) with the given
+       measurement.
    - This function must return 0 on success, a signed integer error code
      otherwise.
    - On the Arm FVP port, this function measures the given image and then
@@ -223,7 +224,7 @@ Responsibilities of these platform interfaces are -
    - This function must return 0 on success, a signed integer error code
      otherwise.
    - In TC2 platform, this function is used to calculate the hash of the given
-     key and forward this hash to RSE alongside the measurement of the image
+     key and forward this hash to |RSE| alongside the measurement of the image
      which the key signs.
 
 --------------

docs/design_documents/rse.rst

@@ -138,6 +138,11 @@ RSE provides the following runtime services:
   process can be requested from RSE. Furthermore, AP can request RSE to
   increase a non-volatile counter. Please refer to the
   ``RSE key management`` [5]_ document for more details.
+- ``DICE Protection Environment``: Securely store the firmware measurements
+  which were computed during the boot process and the associated metadata. It is
+  also capable of representing the boot measurements in the form of a
+  certificate chain, which is queriable. Please refer to the
+  ``DICE Protection Environment (DPE)`` [8]_ document for more details.
 
 Runtime service API
 ^^^^^^^^^^^^^^^^^^^
@@ -355,9 +360,7 @@ Defined here:
 Build time config options
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-- ``MEASURED_BOOT``: Enable measured boot. It depends on the platform
+- ``MEASURED_BOOT``: Enable measured boot.
-  implementation whether RSE or TPM (or both) backend based measured boot is
-  enabled.
 - ``MBOOT_RSE_HASH_ALG``: Determine the hash algorithm to measure the images.
   The default value is sha-256.
 
@@ -432,10 +435,6 @@ restricted to BL31 only. Therefore, RMM does not have direct access, all calls
 need to go through BL31. The RMM dispatcher module of the BL31 is responsible
 for delivering the calls between the two parties.
 
-.. Note::
-     Currently the connection between the RMM dispatcher and the PSA/RSE layer
-     is not yet implemented. RMM dispatcher just returns hard coded data.
-
 Delegated Attestation API
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 Defined here:
@@ -674,6 +673,63 @@ JSON format:
         ]
     }
 
+RSE based DICE Protection Environment
+-------------------------------------
+
+The ``DICE Protection Environment (DPE)`` [8]_ service makes it possible to
+execute |DICE| commands within an isolated execution environment. It provides
+clients with an interface to send DICE commands, encoded as CBOR objects,
+that act on opaque context handles. The |DPE| service performs |DICE|
+derivations and certification on its internal contexts, without exposing the
+|DICE| secrets (private keys and CDIs) outside of the isolated execution
+environment.
+
+|DPE| API
+^^^^^^^^^
+
+Defined here:
+
+- ``include/lib/psa/dice_protection_environment.h``
+
+.. code-block:: c
+
+    dpe_error_t
+    dpe_derive_context(int      context_handle,
+                       uint32_t cert_id,
+                       bool     retain_parent_context,
+                       bool     allow_new_context_to_derive,
+                       bool     create_certificate,
+                       const DiceInputValues *dice_inputs,
+                       int32_t  target_locality,
+                       bool     return_certificate,
+                       bool     allow_new_context_to_export,
+                       bool     export_cdi,
+                       int     *new_context_handle,
+                       int     *new_parent_context_handle,
+                       uint8_t *new_certificate_buf,
+                       size_t   new_certificate_buf_size,
+                       size_t  *new_certificate_actual_size,
+                       uint8_t *exported_cdi_buf,
+                       size_t   exported_cdi_buf_size,
+                       size_t  *exported_cdi_actual_size);
+
+Build time config options
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- ``MEASURED_BOOT``: Enable measured boot.
+- ``DICE_PROTECTION_ENVIRONMENT``: Boolean flag to specify the measured boot
+  backend when |RSE| based ``MEASURED_BOOT`` is enabled. The default value is
+  ``0``. When set to ``1`` then measurements and additional metadata collected
+  during the measured boot process are sent to the |DPE| for storage and
+  processing.
+- ``DPE_ALG_ID``: Determine the hash algorithm to measure the images. The
+  default value is sha-256.
+
+Example certificate chain
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``plat/arm/board/tc/tc_dpe.h``
+
 RSE OTP Assets Management
 -------------------------
 
@@ -728,13 +784,14 @@ Arm CCA platform:
 References
 ----------
 
-.. [1] https://tf-m-user-guide.trustedfirmware.org/platform/arm/rse/readme.html
+.. [1] https://trustedfirmware-m.readthedocs.io/en/latest/platform/arm/rse/index.html
-.. [2] https://tf-m-user-guide.trustedfirmware.org/platform/arm/rse/rse_comms.html
+.. [2] https://trustedfirmware-m.readthedocs.io/en/latest/platform/arm/rse/rse_comms.html
-.. [3] https://git.trustedfirmware.org/TF-M/tf-m-extras.git/tree/partitions/measured_boot/measured_boot_integration_guide.rst
+.. [3] https://trustedfirmware-m.readthedocs.io/projects/tf-m-extras/en/latest/partitions/measured_boot_integration_guide.html
-.. [4] https://git.trustedfirmware.org/TF-M/tf-m-extras.git/tree/partitions/delegated_attestation/delegated_attest_integration_guide.rst
+.. [4] https://trustedfirmware-m.readthedocs.io/projects/tf-m-extras/en/latest/partitions/delegated_attestation/delegated_attest_integration_guide.html
-.. [5] https://tf-m-user-guide.trustedfirmware.org/platform/arm/rse/rse_key_management.html
+.. [5] https://trustedfirmware-m.readthedocs.io/en/latest/platform/arm/rse/rse_key_management.html
 .. [6] https://developer.arm.com/-/media/Files/pdf/PlatformSecurityArchitecture/Architect/DEN0063-PSA_Firmware_Framework-1.0.0-2.pdf?revision=2d1429fa-4b5b-461a-a60e-4ef3d8f7f4b4&hash=3BFD6F3E687F324672F18E5BE9F08EDC48087C93
 .. [7] https://developer.arm.com/documentation/DEN0096/A_a/?lang=en
+.. [8] https://trustedfirmware-m.readthedocs.io/projects/tf-m-extras/en/latest/partitions/dice_protection_environment/dice_protection_environment.html
 
 --------------
 

docs/global_substitutions.txt

@@ -8,6 +8,8 @@
 .. |COT| replace:: :term:`COT`
 .. |CSS| replace:: :term:`CSS`
 .. |CVE| replace:: :term:`CVE`
+.. |DICE| replace:: :term:`DICE`
+.. |DPE| replace:: :term:`DPE`
 .. |DTB| replace:: :term:`DTB`
 .. |DS-5| replace:: :term:`DS-5`
 .. |DSU| replace:: :term:`DSU`
@@ -21,6 +23,7 @@
 .. |FVP| replace:: :term:`FVP`
 .. |FWU| replace:: :term:`FWU`
 .. |GIC| replace:: :term:`GIC`
+.. |HES| replace:: :term:`HES`
 .. |ISA| replace:: :term:`ISA`
 .. |Linaro| replace:: :term:`Linaro`
 .. |MMU| replace:: :term:`MMU`
@@ -31,12 +34,14 @@
 .. |OEN| replace:: :term:`OEN`
 .. |OP-TEE| replace:: :term:`OP-TEE`
 .. |OTE| replace:: :term:`OTE`
+.. |PCR| replace:: :term:`PCR`
 .. |PDD| replace:: :term:`PDD`
 .. |PAUTH| replace:: :term:`PAUTH`
 .. |PMF| replace:: :term:`PMF`
 .. |PSCI| replace:: :term:`PSCI`
 .. |RAS| replace:: :term:`RAS`
 .. |ROT| replace:: :term:`ROT`
+.. |RSE| replace:: :term:`RSE`
 .. |SCMI| replace:: :term:`SCMI`
 .. |SCP| replace:: :term:`SCP`
 .. |SDEI| replace:: :term:`SDEI`
@@ -55,6 +60,7 @@
 .. |SVE| replace:: :term:`SVE`
 .. |TBB| replace:: :term:`TBB`
 .. |TBBR| replace:: :term:`TBBR`
+.. |TCB| replace:: :term:`TCB`
 .. |TCG| replace:: :term:`TCG`
 .. |TEE| replace:: :term:`TEE`
 .. |TF-A| replace:: :term:`TF-A`

docs/glossary.rst

@@ -100,6 +100,9 @@ You can find additional definitions in the `Arm Glossary`_.
    GIC
       Generic Interrupt Controller
 
+   HES
+      Arm CCA Hardware Enforced Security
+
    ISA
       Instruction Set Architecture
 
@@ -136,6 +139,9 @@ You can find additional definitions in the `Arm Glossary`_.
    OTE
       Open-source Trusted Execution Environment
 
+   PCR
+      Platform Configuration Register
+
    PDD
       Platform Design Document
 
@@ -162,6 +168,9 @@ You can find additional definitions in the `Arm Glossary`_.
    ROT
       Root of Trust
 
+   RSE
+      Runtime Security Engine
+
    SCMI
       System Control and Management Interface
 

docs/threat_model/firmware_threat_model/threat_model.rst

@@ -892,28 +892,65 @@ nonetheless once execution has reached the runtime EL3 firmware.
 
 .. topic:: Measured Boot Threats (or lack of)
 
- In the current Measured Boot design, BL1, BL2, and BL31, as well as the
+ In the current Measured Boot design the following components form the |TCB|:
- secure world components, form the |SRTM|. Measurement data is currently
+
- considered an asset to be protected against attack, and this is achieved
+   - BL1, BL2, BL31
- by storing them in the Secure Memory.
+   - Secure world components
- Beyond the measurements stored inside the TCG-compliant Event Log buffer,
+   - RMM (if RME extension is implemented)
- there are no other assets to protect or threats to defend against that
+   - The configuration data of the above components
- could compromise |TF-A| execution environment's security.
+
+ Across various Measured Boot backends, the data recorded during the flow as
+ well as the criticality of this data can vary. In most cases, these attributes
+ are considered valuable assets and are protected against potential attacks:
+
+   - Image measurement: the digest value of a component produced by a hash
+     function.
+   - Signer-id: the digest value of the image verification publiy key. The
+     verification public key is part of the image metadata.
+
+ In addition to these, other metadata attributes (image version, hash algorithm
+ identifier, etc) could be recorded during the Measured Boot process. But these
+ are not critical data.
+
+ In this context, an attack means modifying the measurement data (image or
+ public key hash) or recording arbitrary data as valid measurements.
+
+ The current Measured Boot design consists of two main parts. A frontend, which
+ is responsible for taking the measurements, and a backend which is responsible
+ for storing them. |TF-A| makes it possible to integrate various backends. Some
+ of these are implemented by the |TF-A| projects, while others are part of
+ different projects, and |TF-A| provides an integration layer.
+
+   - TCG-compliant Event Log: Implemented by |TF-A|. Measurements are stored in
+     the Event Log which is located on the secure on-chip memory of the AP. The
+     address of the Event Log buffer is handed off between boot stages and new
+     measurements are appended to the Event Log. A limitation of the current
+     Measured Boot implementation in |TF-A| is that it does not extend the
+     measurements into a |PCR| of a Discrete |TPM|, where measurements would
+     be securely stored and protected against tampering.
+   - `CCA Measured Boot`_: Implemented by |TF-M|. Measurements are stored in
+     |HES| secure on-chip memory. |HES| implements protection against tampering
+     its on-chip memory. |HES| interface is available for BL1 and BL2.
+   - `DICE Protection Environment`_ (DPE): Implemented by |TF-M|. Measurements
+     are stored in |RSE| secure on-chip memory. |RSE| implements protection
+     against tampering its on-chip memory. DPE provides additional protection
+     against unauthorized access by malicious actors through the use of one-time
+     context handles and the identification of the client's target locality
+     (location of the client).
+
+ Beyond the measurements (image digest and signer-id) there are no other assets
+ to protect or threats to defend against that could compromise |TF-A| execution
+ environment's security.
 
  There are general security assets and threats associated with remote/delegated
  attestation. However, these are outside the |TF-A| security boundary and
  should be dealt with by the appropriate agent in the platform/system.
  Since current Measured Boot design does not use local attestation, there would
- be no further assets to protect(like unsealed keys).
+ be no further assets to protect (like unsealed keys).
 
- A limitation of the current Measured Boot design is that it is dependent upon
+ System integrators must carefully evaluate the security requirement and
- Secure Boot as implementation of Measured Boot does not extend measurements
+ capabilities of their platform and choose an appropriate Measured Boot
- into a discrete |TPM|, where they would be securely stored and protected
+ solution.
- against tampering. This implies that if Secure-Boot is compromised, Measured
- Boot may also be compromised.
-
- Platforms must carefully evaluate the security of the default implementation
- since the |SRTM| includes all secure world components.
 
 
 .. _Runtime Firmware Threats:
@@ -1169,3 +1206,5 @@ Threats to be Mitigated by an External Agent Outside of TF-A
 .. _Trusted Firmware-A Tests: https://git.trustedfirmware.org/TF-A/tf-a-tests.git/about/
 .. _OP-TEE Dispatcher: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/components/spd/optee-dispatcher.rst
 .. _PSR Specification: https://developer.arm.com/documentation/den0106/0100
+.. _CCA Measured Boot: https://trustedfirmware-m.readthedocs.io/projects/tf-m-extras/en/latest/partitions/measured_boot_integration_guide.html
+.. _DICE Protection Environment: https://trustedfirmware-m.readthedocs.io/projects/tf-m-extras/en/latest/partitions/dice_protection_environment/dice_protection_environment.html