[PATCH] arm-bsp/documentation: corstone1000: describe host level authentication

From: Bence Balogh <[email protected]>

A new section was added for the host level authentication which
explains how the FIP content is verified at TF-A level.

Signed-off-by: Abdellatif El Khlifi [email protected]
Signed-off-by: Bence Balogh [email protected]
---
 .../corstone1000/software-architecture.rst    | 45 ++++++++++++++++++-
 1 file changed, 44 insertions(+), 1 deletion(-)

diff --git a/meta-arm-bsp/documentation/corstone1000/software-architecture.rst b/meta-arm-bsp/documentation/corstone1000/software-architecture.rst
index a4e0a424..95156013 100644
--- a/meta-arm-bsp/documentation/corstone1000/software-architecture.rst
+++ b/meta-arm-bsp/documentation/corstone1000/software-architecture.rst
@@ -116,7 +116,7 @@ BL1_1 also compares the BL1_2 hash with the hash saved to the OTP. The BL1_2
 verifies and transfers control to the next bootstage which is the BL2. During the
 verification, the BL1_2 compares the BL2 image's computed hash with the BL2 hash in
 the OTP. The BL2 is MCUBoot in the system. BL2 can provision additional keys on the
-first boot and it authenticates the initial bootloader of the host (Host TF-A BL2)
+first boot and it authenticates the initial bootloader of the host (Host Trusted Firmware-A BL2)
 and TF-M by checking the signatures of the images.
 The MCUBoot handles the image verification the following way:
 
@@ -145,9 +145,52 @@ limitations:
   comparing the computed hash to the hash which is stored in the OTP. This means the
   BL2 is not updatable.
 
+Host Level Authentication
+=========================
+
 The host follows the boot standard defined in the `TBBR`_ to authenticate the
 secure and non-secure software.
 
+The Firmware Image Package (FIP) packs bootloader images and other payloads into a
+single archive. The FIP for Corstone-1000 contains:
+
+- Trusted Boot Firmware BL2
+- EL3 Runtime Firmware BL31
+- Secure Payload BL32 (Trusted OS)
+- Non-Trusted Firmware BL33,
+- TOS_FW_CONFIG
+- key & content certificates
+
+TF-M does not check the FIP signature, it only checks the Trsuted Firmware-A (TF-A) BL2's signature
+in the FIP. The TF-M BL2 (MCUBoot) gets the offset for the TF-A BL2 by parsing the
+GUID Partition Table (GPT) to find the FIP offset, then parsing the FIP to get the offset for the
+TF-A BL2. Finally, MCUBoot loads and validates the TF-A BL2 image.
+
+The implicitly trusted components are:
+
+- A SHA-256 hash of the Root of Trust Public Key (ROTPK). A development ROTPK
+  is used and its hash embedded into the TF-A BL2 image (only for development purposes).
+  This public key is provided by TF-A source-code.
+- In case of Corstone-1000, the TF-A BL2 image, can be trusted because it has been verified
+  by the secure enclave's BL2 (MCUBoot) before starting TF-A.
+
+
+The remaining components in the Chain of Trust (CoT) are either certificates or bootloader images.
+
+BL images authentication using the FIP certificates:
+
+- The certificates are categorized as "Key" and "Content" certificates.
+  The key certificates are used to verify public keys which have been used to sign
+  content certificates. The content certificates are used to store the hash of a
+  boot loader image. An image can be authenticated by calculating its hash and
+  matching it with the hash extracted from the content certificate.
+
+Verification of the certificates:
+
+- The public keys defined in the Trusted Key certificate are used to verify the
+  later certificates in the CoT process. The Trusted Key certificate is
+  verified with the Root of Trust Public Key.
+
 For UEFI Secure Boot, authenticated variables can be accessed from the secure flash.
 The feature has been integrated in U-Boot, which authenticates the images as per the UEFI
 specification before executing them.