Add Secure Boot documentation for AM62Lx

configs/AM62LX/AM62LX_linux_toc.txt

@@ -37,6 +37,7 @@ linux/Foundational_Components/U-Boot/UG-Memory-K3
 linux/Foundational_Components/U-Boot/UG-UMS
 linux/Foundational_Components/U-Boot/UG-QSPI
 linux/Foundational_Components/U-Boot/UG-UART
+linux/Foundational_Components/U-Boot/UG-Secure-Boot
 linux/Foundational_Components/U-Boot/UG-Key-Writer-Lite
 linux/Foundational_Components/U-Boot/UG-Programming-OTPs
 
@@ -86,6 +87,7 @@ linux/Foundational_Components/System_Security/Security_overview
 linux/Foundational_Components/System_Security/Auth_boot
 linux/Foundational_Components/System_Security/Memory_Firewalls
 linux/Foundational_Components/System_Security/Filesystem_Encryption
+linux/Foundational_Components_Secure_Boot
 
 linux/Foundational_Components_Kernel_Users_Guide
 linux/Foundational_Components_Kernel_LTP-DDT_Validation

source/linux/Foundational_Components/System_Security/Security_overview.rst

@@ -8,19 +8,19 @@ Device Security
 Security Overview
 =================
 
-The |__PART_FAMILY_DEVICE_NAMES__| SoC offers a comprehensive set of 
-security features that protect embedded Linux applications. This guide 
-offers a starting point to understand and implement these capabilities 
+The |__PART_FAMILY_DEVICE_NAMES__| SoC offers a comprehensive set of
+security features that protect embedded Linux applications. This guide
+offers a starting point to understand and implement these capabilities
 as part of product development, with the following advantages:
 
-* **Hardware-backed security** - Leverages built-in security hardware 
+* **Hardware-backed security** - Leverages built-in security hardware
   for robust protection
 * **Defense in-depth** - Implements security at many levels including
   hardware, firmware, software to protect against wide range of attacks
 * **Industry standards compliance** - Incorporates security measures such
   as secure boot, TrustZone, and crypto acceleration that can help meet
   requirements in standards such as IEC 62443 and NIST guidelines
-* **Flexible implementation** - Allows security features that can be 
+* **Flexible implementation** - Allows security features that can be
   tailored to specific application needs
 
 ================
@@ -31,7 +31,7 @@ Below is an overview of the security framework's main domains:
 
 .. figure:: ./images/security_framework.png
 
-These security domains create a chain of trust protecting the 
+These security domains create a chain of trust protecting the
 |__PART_FAMILY_DEVICE_NAMES__| SoC from boot through runtime and storage,
 ensuring system integrity and data confidentiality.
 
@@ -43,31 +43,38 @@ The following table lists some of the key Security Features:
 
 .. ifconfig:: CONFIG_part_variant in ('AM62LX')
 
-  +-------------------------+-----------------------------------------------------------+--------------------------------------+
-  | **Security Feature**    | **Description**                                           | **Links**                            |
-  +=========================+===========================================================+======================================+
-  | **Authenticated Boot**  | Verifies each boot component to ensure only authorized    | :ref:`auth_boot_guide`               |
-  |                         | code executes on the device                               |                                      |
-  +-------------------------+-----------------------------------------------------------+--------------------------------------+
-  | **Crypto Acceleration** | Hardware driver support for cryptographic algorithms and  | :ref:`crypto-accelerator`            |
-  | **and TRNG**            | hardware entropy based secure random number generation    |                                      |
-  +-------------------------+-----------------------------------------------------------+--------------------------------------+
-  | **Key Management**      | Tools for secure key provisioning                         | :ref:`key-writer-lite-label`         |
-  +-------------------------+-----------------------------------------------------------+--------------------------------------+
-  | **Secure Storage**      | Protection mechanisms for sensitive data                  | :ref:`secure-storage-with-rpmb`      |
-  +-------------------------+-----------------------------------------------------------+--------------------------------------+
-  | **Trusted Execution**   | Implementation of secure monitor (EL3) firmware that      | :ref:`foundational-components-atf`   |
-  |                         | manages the secure boot process and TrustZone transitions |                                      |
-  +                         +-----------------------------------------------------------+--------------------------------------+
-  |                         | Trusted Execution Environment that enables isolated       | :ref:`foundational-components-optee` |
-  |                         | execution of security-sensitive applications and services |                                      |
-  +-------------------------+-----------------------------------------------------------+--------------------------------------+
-  | **Memory Firewalls**    | Prevents unauthorized access through hardware-enforced    | :ref:`memory-firewalls`              |
-  |                         | security boundaries                                       |                                      |
-  +-------------------------+-----------------------------------------------------------+--------------------------------------+
-  |**fTPM based**           | Yocto reference implemenation of filesystem  encryption   | :ref:`filesystem-encryption`         |
-  |**Filesystem Encryption**| using LUKS2 with TPM-sealed keys                          |                                      |
-  +-------------------------+-----------------------------------------------------------+--------------------------------------+
+  +-------------------------+-----------------------------------------------------------+-----------------------------------------+
+  | **Security Feature**    | **Description**                                           | **Links**                               |
+  +=========================+===========================================================+=========================================+
+  | **Secure Boot**         | Verifies and decrypts each boot stage, establishing a     | :ref:`foundational-secure-boot`         |
+  |                         | hardware-backed chain of trust from ROM to Linux using    |                                         |
+  |                         | customer-programmable keys                                |                                         |
+  +                         +-----------------------------------------------------------+-----------------------------------------+
+  |                         | Authenticates U-Boot using open-source Verified Boot      | :ref:`u-boot-secure-boot-verified-boot` |
+  |                         | framework                                                 |                                         |
+  +-------------------------+-----------------------------------------------------------+-----------------------------------------+
+  | **Authenticated Boot**  | Verifies each boot component to ensure only authorized    | :ref:`auth_boot_guide`                  |
+  |                         | code executes on the device                               |                                         |
+  +-------------------------+-----------------------------------------------------------+-----------------------------------------+
+  | **Crypto Acceleration** | Hardware driver support for cryptographic algorithms and  | :ref:`crypto-accelerator`               |
+  | **and TRNG**            | hardware entropy based secure random number generation    |                                         |
+  +-------------------------+-----------------------------------------------------------+-----------------------------------------+
+  | **Key Management**      | Tools for secure key provisioning                         | :ref:`key-writer-lite-label`            |
+  +-------------------------+-----------------------------------------------------------+-----------------------------------------+
+  | **Secure Storage**      | Protection mechanisms for sensitive data                  | :ref:`secure-storage-with-rpmb`         |
+  +-------------------------+-----------------------------------------------------------+-----------------------------------------+
+  | **Trusted Execution**   | Implementation of secure monitor (EL3) firmware that      | :ref:`foundational-components-atf`      |
+  |                         | manages the secure boot process and TrustZone transitions |                                         |
+  +                         +-----------------------------------------------------------+-----------------------------------------+
+  |                         | Trusted Execution Environment that enables isolated       | :ref:`foundational-components-optee`    |
+  |                         | execution of security-sensitive applications and services |                                         |
+  +-------------------------+-----------------------------------------------------------+-----------------------------------------+
+  | **Memory Firewalls**    | Prevents unauthorized access through hardware-enforced    | :ref:`memory-firewalls`                 |
+  |                         | security boundaries                                       |                                         |
+  +-------------------------+-----------------------------------------------------------+-----------------------------------------+
+  |**fTPM based**           | Yocto reference implemenation of filesystem  encryption   | :ref:`filesystem-encryption`            |
+  |**Filesystem Encryption**| using LUKS2 with TPM-sealed keys                          |                                         |
+  +-------------------------+-----------------------------------------------------------+-----------------------------------------+
 
 
 .. ifconfig:: CONFIG_part_variant in ('AM62X', 'AM62PX', 'AM62AX')
@@ -120,6 +127,6 @@ The following table lists some of the key Security Features:
   |                         | execution of security-sensitive applications and services |                                      |
   +-------------------------+-----------------------------------------------------------+--------------------------------------+
   | **Memory Firewalls**    | Prevents unauthorized access through hardware-enforced    | :ref:`memory-firewalls`              |
-  |                         | security boundaries                                       |				       |
+  |                         | security boundaries                                       |                                      |
   +-------------------------+-----------------------------------------------------------+--------------------------------------+
 

source/linux/Foundational_Components/U-Boot/UG-Secure-Boot.rst

@@ -0,0 +1,141 @@
+.. _u-boot-secure-boot-verified-boot:
+
+################################################
+Secure boot using U-Boot verified boot framework
+################################################
+
+The complete Secure Boot documentation is available at:
+:ref:`foundational-secure-boot`. This page specifically covers the
+authentication and verification of U-Boot image using `U-Boot Verified Boot`_.
+
+On most other K3 devices, signing and verification of all boot binaries takes
+place in the Hardware Security Module (HSM). Thereafter, U-Boot hands off the
+secure chain of trust to the Linux kernel :file:`fitImage`.
+
+On AM62Lx, we have transitioned to use the native U-Boot secure boot framework
+for a part of this chain of trust. The U-Boot documentation covers more theory
+on this at
+`U-Boot Verified Boot <https://docs.u-boot.org/en/latest/usage/fit/verified-boot.html>`_
+and `U-Boot FIT Signature Verification <https://docs.u-boot.org/en/latest/usage/fit/signature.html#signed-configurations>`__.
+The thing to note is, we are applying the same concepts to U-Boot Flattened
+Image Tree (FIT) as the kernel FIT examples in the preceding links.
+
+The HSM still handles the verification of :file:`tiboot3.bin` and
+:file:`tispl.bin`. However, we hand off the chain of trust to U-Boot just after
+this. The :file:`u-boot.img` is a signed FIT image. The U-Boot Secondary
+Program Loader (SPL) binary embeds the public key derived from the private key
+used to sign the U-Boot FIT. The U-Boot SPL uses this to verify the
+authenticity of the loaded U-Boot binary.
+
+**************
+The FIT source
+**************
+
+The U-Boot FIT configuration node contains a signature sub-node.
+
+.. code-block:: dts
+
+   conf-0 {
+      description = "k3-am62lx-evm";
+      firmware = "uboot";
+      loadables = "uboot";
+      fdt = "fdt-0";
+
+      signature {
+         algo = "sha512,rsa4096";
+         key-name-hint = "custMpk";
+         sign-images = "firmware", "loadables", "fdt";
+      };
+   };
+
+It specifies the key name and algorithm to use for signing, and the images
+to sign.
+
+The public key is similarly embedded into U-Boot SPL by using a binman property
+called :code:`u-boot-spl-pubkey-dtb`. This handles the heavy lifting of calling
+the appropriate :code:`mkimage` commands and packing the public key in the SPL
+Device Tree Blob (DTB) correctly.
+
+.. code-block:: dts
+
+   tispl.bin {
+
+      ...
+
+      spl: section {
+         u-boot-spl-nodtb {
+         };
+
+         u-boot-spl-pubkey-dtb {
+            algo = "sha512,rsa4096";
+            required = "conf";
+            key-name-hint = "custMpk";
+         };
+      };
+   };
+
+The :code:`key-name-hint` property in both these nodes searches for the
+:file:`custMpk.key` private key and :file:`custMpk.crt` public key certificate
+in the directories defined in the :code:`BINMAN_INDIRS` variable. The default
+TI dummy keys reside in :file:`arch/arm/mach-k3/keys/`, and binman copies them
+at the start of the build into the build directory:
+
+.. code-block:: dts
+
+   custMpk-crt {
+      filename = "custMpk.crt";
+
+      custmpk_crt: blob-ext {
+         filename = "arch/arm/mach-k3/keys/custMpk.crt";
+      };
+   };
+
+   custMpk-key {
+      filename = "custMpk.key";
+
+      custmpk_key: blob-ext {
+         filename = "arch/arm/mach-k3/keys/custMpk.key";
+      };
+   };
+
+********************
+Runtime verification
+********************
+
+At runtime during device boot, U-Boot SPL loads the :file:`u-boot.img` and then
+verifies the FIT signature by using the public key it has in its DTB. If the
+verification passes, boot continues. Otherwise, it aborts the boot.
+
+***********************
+Changing the dummy keys
+***********************
+
+The SDKs use the TI dummy key for signing the U-Boot FIT image. But you might
+want to use your own key for testing and production. For this, replace the
+:file:`arch/arm/mach-k3/keys/custMpk.key` and
+:file:`arch/arm/mach-k3/keys/custMpk.crt` with your own key and crt files. The
+filenames need to be the same.
+
+It is also possible to use your own keys located at a different location. You
+need to change the complete path in the :code:`filename` property above in
+:code:`custMpk-crt` and :code:`custMpk-key` in
+:file:`arch/arm/dts/k3-am62l3-evm-binman.dtsi` to your .crt and .key files.
+
+After either of the above changes, the U-Boot needs to be built again to get
+the signed binaries with the updated keys. Refer to :ref:`top-level-makefile`.
+
+.. note::
+
+   Generating a new set of keys:
+
+   .. code-block:: console
+
+      $ mkdir keys
+      $ cd keys
+      $ # Generate an RSA private key:
+      $ openssl genpkey -algorithm RSA -out custMpk.key \
+         -pkeyopt rsa_keygen_bits:4096 -pkeyopt rsa_keygen_pubexp:65537
+      $ # Build your cert template (Enter necessary details in the prompts that follow):
+      $ openssl req -new -key custMpk.key -out cert.csr
+      $ # Self-sign the certificate
+      $ openssl x509 -req -days 3650 -in cert.csr -signkey custMpk.key -out custMpk.crt

source/linux/Foundational_Components/U-Boot/Users-Guide.rst

@@ -31,6 +31,7 @@ User's Guide
    UG-AVS
    UG-Thermal
    UG-Splash-Screen
+   UG-Secure-Boot
    UG-Key-Writer-Lite
    UG-Programming-OTPs
    UG-Falcon-Mode