diff --git a/docs/design_documents/measured_boot.rst b/docs/design_documents/measured_boot.rst index 9dfe49415..005903eda 100644 --- a/docs/design_documents/measured_boot.rst +++ b/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 - 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 @@ 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 - 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 @@ 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. -------------- diff --git a/docs/design_documents/rse.rst b/docs/design_documents/rse.rst index 57467f395..dd110ca82 100644 --- a/docs/design_documents/rse.rst +++ b/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 - 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 @@ 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 -.. [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 ade510dc8..23a91cdcd 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`