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`