docs: add Measured Boot design
Added design document for Measured Boot implementation in
TF-A.
Change-Id: I25b57ec555b289eb6bbf0a6aae014d7bf6d152fd
Signed-off-by: Manish V Badarkhe <Manish.Badarkhe@arm.com>
diff --git a/docs/design_documents/index.rst b/docs/design_documents/index.rst
index d20fc58..ecc68b2 100644
--- a/docs/design_documents/index.rst
+++ b/docs/design_documents/index.rst
@@ -11,6 +11,7 @@
drtm_poc
rss
psci_osi_mode
+ measured_boot
--------------
diff --git a/docs/design_documents/measured_boot.rst b/docs/design_documents/measured_boot.rst
new file mode 100644
index 0000000..8130d7d
--- /dev/null
+++ b/docs/design_documents/measured_boot.rst
@@ -0,0 +1,212 @@
+Measured Boot Design
+====================
+
+This document briefly explains the Measured-Boot design implementation
+in |TF-A|.
+
+Introduction
+------------
+
+Measured Boot is the process of computing and securely recording hashes of code
+and critical data at each stage in the boot chain before the code/data is used.
+
+These measurements can be leveraged by other components in the system to
+implement a complete attestation system. For example, they could be used to
+enforce local attestation policies (such as releasing certain platform keys or
+not), or they could be securely sent to a remote challenger a.k.a. `verifier`
+after boot to attest to the state of the code and critical-data.
+
+Measured Boot does not authenticate the code or critical-data, but simply
+records what code/critical-data was present on the system during boot.
+
+It is assumed that BL1 is implicitly trusted (by virtue of immutability) and
+acts as the root of trust for measurement hence it is not measured.
+
+The Measured Boot implementation in TF-A supports multiple backends to securely
+store measurements mentioned below in the :ref:`Measured Boot Backends` section.
+
+Critical data
+-------------
+
+All firmware images - i.e. BLx images and their corresponding configuration
+files, if any - must be measured. In addition to that, there might be specific
+pieces of data which needs to be measured as well. These are typically different
+on each platform. They are referred to as *critical data*.
+
+Critical data for the platform can be determined using the following criteria:
+
+#. Data that influence boot flow behaviour such as -
+
+ - Configuration parameters that alter the boot flow path.
+ - Parameters that determine which firmware to load from NV-Storage to
+ SRAM/DRAM to pass the boot process successfully.
+
+#. Hardware configurations settings, debug settings and security policies
+ that need to be in a valid state for a device to maintain its security
+ posture during boot and runtime.
+#. Security-sensitive data that is being updated by hardware.
+
+Examples of Critical data:
+
+#. The list of errata workarounds being applied at reset.
+#. State of fuses such as whether an SoC is in secure mode.
+#. NV counters that determine whether firmware is up-to-date and secure.
+
+Measurement slot
+----------------
+
+The measurement slot resides in a Trusted Module and can be either a secure
+register or memory.
+The measurement slot is used to provide a method to cryptographically record
+(measure) images and critical data on a platform.
+The measurement slot update calculation, called an **extend** operation, is
+a one-way hash of all the previous measurements and the new measurement. It
+is the only way to change the slot value, thus no measurements can ever be
+removed or overwritten.
+
+.. _Measured Boot Backends:
+
+Measured Boot Backends
+----------------------
+
+The Measured Boot implementation in TF-A supports:
+
+#. Event Log
+
+ The TCG Event Log holds a record of measurements made into the Measurement
+ Slot aka PCR (Platform Configuration Register).
+
+ The `TCG EFI Protocol Specification`_ provides details on how to measure
+ components. The Arm document
+ `Arm® Server Base Security Guide`_ provides specific guidance for
+ measurements on an SBSA/SBBR server system. By considering these
+ specifications it is decided that -
+
+ #. Use PCR0 for images measurements.
+ #. Use PCR1 for Critical data measurements.
+
+ TCG has specified the architecture for the structure of this log in the
+ `TCG EFI Protocol Specification`_. The specification describes two event
+ log event records—the legacy, fixed size SHA1 structure called TCG_PCR_EVENT
+ and the variable length crypto agile structure called TCG_PCR_EVENT2. Event
+ Log driver implemented in TF-A covers later part.
+
+#. RSS
+
+ It is one of physical backend to extend the measurements. Please refer this
+ document :ref:`Runtime Security Subsystem (RSS)` for more details.
+
+Platform Interface
+------------------
+
+Every image which gets successfully loaded in memory (and authenticated, if
+trusted boot is enabled) then gets measured. In addition to that, platforms
+can measure any relevant piece of critical data at any point during the boot.
+The following diagram outlines the call sequence for Measured Boot platform
+interfaces invoked from generic code:
+
+.. image:: ../resources/diagrams/measured_boot_design.png
+
+These platform interfaces are used by BL1 and BL2 only, and are declared in
+``include/plat/common/platform.h``.
+BL31 does not load and thus does not measure any image.
+
+Responsibilities of these platform interfaces are -
+
+#. **Function : blx_plat_mboot_init()**
+
+ .. code-block:: c
+
+ void bl1_plat_mboot_init(void);
+ void bl2_plat_mboot_init(void);
+
+ Initialise all Measured Boot backends supported by the platform
+ (e.g. Event Log buffer, RSS). 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.
+
+ - On the Arm FVP port -
+
+ - In BL1, this function is used to initialize the Event Log backend
+ driver, and also to write header information in the Event Log
+ buffer.
+ - In BL2, this function is used to initialize the Event Log buffer with
+ the information received from the BL1. It results in panic on
+ error.
+
+#. **Function : plat_mboot_measure_image()**
+
+ .. code-block:: c
+
+ int plat_mboot_measure_image(unsigned int image_id,
+ image_info_t *image_data);
+
+ - Measure the image using a hash function of the crypto module.
+
+ - Record the measurement in the corresponding backend -
+
+ - If it is Event Log backend, then record the measurement in TCG Event Log
+ format.
+ - If it is a secure crypto-processor (like RSS), then extend the designated
+ PCR (or slot) 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
+ records that measurement in the Event Log buffer.
+ The passed id is used to retrieve information about on how to measure
+ the image (e.g. PCR number).
+
+#. **Function : blx_plat_mboot_finish()**
+
+ .. code-block:: c
+
+ void bl1_plat_mboot_finish(void);
+ void bl2_plat_mboot_finish(void);
+
+ - Do all teardown operations with respect to initialised Measured Boot backends.
+ This could be -
+
+ - Pass the Event Log details (start address and size) to Normal world or to
+ Secure World using any platform implementation way.
+ - Measure all critical data if any.
+ - 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.
+
+ - On the Arm FVP port -
+
+ - In BL1, this function is used to pass the base address of
+ the Event Log buffer and its size to BL2 via tb_fw_config to extend the
+ Event Log buffer with the measurement of various images loaded by BL2.
+ It results in panic on error.
+ - In BL2, this function is used to pass the Event Log buffer information
+ (base address and size) to non-secure(BL33) and trusted OS(BL32) via
+ nt_fw and tos_fw config respectively.
+ See :ref:`DTB binding for Event Log properties` for a description of the
+ bindings used for Event Log properties.
+
+#. **Function : plat_mboot_measure_critical_data()**
+
+ .. code-block:: c
+
+ int plat_mboot_measure_critical_data(unsigned int critical_data_id,
+ const void *base,
+ size_t size);
+
+ This interface is not invoked by the generic code and it is up to the
+ platform layer to call it where appropriate.
+
+ This function measures the given critical data structure and records its
+ measurement using the Measured Boot backend driver.
+ This function must return 0 on success, a signed integer error code
+ otherwise.
+
+ In FVP, Non volatile counters get measured and recorded as Critical data
+ using the backend via this interface.
+
+--------------
+
+*Copyright (c) 2023, Arm Limited. All rights reserved.*
+
+.. _Arm® Server Base Security Guide: https://developer.arm.com/documentation/den0086/latest
+.. _TCG EFI Protocol Specification: https://trustedcomputinggroup.org/wp-content/uploads/EFI-Protocol-Specification-rev13-160330final.pdf
diff --git a/docs/design_documents/measured_boot_poc.rst b/docs/design_documents/measured_boot_poc.rst
index 7f9519e..86cf4d1 100644
--- a/docs/design_documents/measured_boot_poc.rst
+++ b/docs/design_documents/measured_boot_poc.rst
@@ -10,6 +10,8 @@
This section focuses on the `TCG event log`_ backend, which stores measurements
in secure memory.
+See details of :ref:`Measured Boot Design`.
+
The driver also provides mechanisms to pass the Event Log to normal world if
needed.
diff --git a/docs/resources/diagrams/Makefile b/docs/resources/diagrams/Makefile
index c951754..faf9634 100644
--- a/docs/resources/diagrams/Makefile
+++ b/docs/resources/diagrams/Makefile
@@ -79,7 +79,13 @@
FWU-update_struct_layers = "background"
FWU-update_struct_opts =
-all:$(RESET_PNGS) $(INT_PNGS) $(XLAT_PNG) $(RMM_PNG) $(RMM_EL3_MANIFEST_PNG) $(PSA_FWU_PNG)
+MB_DESIGN_DIA = measured_boot_design.dia
+MB_DESIGN_PNG = measured_boot_design.png
+
+measured_boot_design_layers = "background"
+measured_boot_design_opts =
+
+all:$(RESET_PNGS) $(INT_PNGS) $(XLAT_PNG) $(RMM_PNG) $(RMM_EL3_MANIFEST_PNG) $(PSA_FWU_PNG) $(MB_DESIGN_PNG)
$(RESET_PNGS):$(RESET_DIA)
$(call generate_image,$($(patsubst %.png,%_layers,$@)),$@,png,$($(patsubst %.png,%_opts,$@)),$<)
@@ -99,3 +105,6 @@
$(PSA_FWU_PNG):$(PSA_FWU_DIA)
$(call generate_image,$($(patsubst %.png,%_layers,$@)),$@,png,$($(patsubst %.png,%_opts,$@)),$<)
+
+$(MB_DESIGN_PNG):$(MB_DESIGN_DIA)
+ $(call generate_image,$($(patsubst %.png,%_layers,$@)),$@,png,$($(patsubst %.png,%_opts,$@)),$<)
diff --git a/docs/resources/diagrams/measured_boot_design.dia b/docs/resources/diagrams/measured_boot_design.dia
new file mode 100644
index 0000000..fdae464
--- /dev/null
+++ b/docs/resources/diagrams/measured_boot_design.dia
Binary files differ
diff --git a/docs/resources/diagrams/measured_boot_design.png b/docs/resources/diagrams/measured_boot_design.png
new file mode 100644
index 0000000..42469be
--- /dev/null
+++ b/docs/resources/diagrams/measured_boot_design.png
Binary files differ
