feat(docs): add DPE to RSE desing doc

Signed-off-by: Tamas Ban <tamas.ban@arm.com>
Change-Id: Iec38be8a3eb93a54d9b5bc7db7a7ff8c126920ac
diff --git a/docs/design_documents/measured_boot.rst b/docs/design_documents/measured_boot.rst
index 9dfe494..005903e 100644
--- a/docs/design_documents/measured_boot.rst
+++ b/docs/design_documents/measured_boot.rst
@@ -91,10 +91,10 @@
    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
-   document :ref:`Runtime Security Engine (RSE)` for more details.
+   It is one of the physical backends to extend the measurements. Please refer
+   this document :ref:`Runtime Security Engine (RSE)` for more details.
 
 Platform Interface
 ------------------
@@ -121,7 +121,7 @@
       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 @@
 
      - 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
-       PCR (or slot) with the given measurement.
+     - If it is a secure crypto-processor (like |RSE|), then extend the
+       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 @@
    - 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.
 
 --------------
diff --git a/docs/design_documents/rse.rst b/docs/design_documents/rse.rst
index 57467f3..dd110ca 100644
--- a/docs/design_documents/rse.rst
+++ b/docs/design_documents/rse.rst
@@ -138,6 +138,11 @@
   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 @@
 Build time config options
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-- ``MEASURED_BOOT``: Enable measured boot. It depends on the platform
-  implementation whether RSE or TPM (or both) backend based measured boot is
-  enabled.
+- ``MEASURED_BOOT``: Enable measured boot.
 - ``MBOOT_RSE_HASH_ALG``: Determine the hash algorithm to measure the images.
   The default value is sha-256.
 
@@ -432,10 +435,6 @@
 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 @@
         ]
     }
 
+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 @@
 References
 ----------
 
-.. [1] https://tf-m-user-guide.trustedfirmware.org/platform/arm/rse/readme.html
-.. [2] https://tf-m-user-guide.trustedfirmware.org/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
-.. [4] https://git.trustedfirmware.org/TF-M/tf-m-extras.git/tree/partitions/delegated_attestation/delegated_attest_integration_guide.rst
-.. [5] https://tf-m-user-guide.trustedfirmware.org/platform/arm/rse/rse_key_management.html
+.. [1] https://trustedfirmware-m.readthedocs.io/en/latest/platform/arm/rse/index.html
+.. [2] https://trustedfirmware-m.readthedocs.io/en/latest/platform/arm/rse/rse_comms.html
+.. [3] https://trustedfirmware-m.readthedocs.io/projects/tf-m-extras/en/latest/partitions/measured_boot_integration_guide.html
+.. [4] https://trustedfirmware-m.readthedocs.io/projects/tf-m-extras/en/latest/partitions/delegated_attestation/delegated_attest_integration_guide.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
 
 --------------
 
diff --git a/docs/global_substitutions.txt b/docs/global_substitutions.txt
index ade510d..23a91cd 100644
--- a/docs/global_substitutions.txt
+++ b/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`