diff --git a/configs/AM62LX/AM62LX_linux_toc.txt b/configs/AM62LX/AM62LX_linux_toc.txt index 86ec9e1d8..8cf6195f7 100644 --- a/configs/AM62LX/AM62LX_linux_toc.txt +++ b/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 diff --git a/source/images/AM62L_BF.png b/source/images/AM62L_BF.png new file mode 100644 index 000000000..3e9ff7c0f Binary files /dev/null and b/source/images/AM62L_BF.png differ diff --git a/source/images/AM62L_KF.png b/source/images/AM62L_KF.png new file mode 100644 index 000000000..d834a2ea4 Binary files /dev/null and b/source/images/AM62L_KF.png differ diff --git a/source/linux/Foundational_Components/System_Security/Security_overview.rst b/source/linux/Foundational_Components/System_Security/Security_overview.rst index 22ee4936b..1d1135d2b 100644 --- a/source/linux/Foundational_Components/System_Security/Security_overview.rst +++ b/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 | | +-------------------------+-----------------------------------------------------------+--------------------------------------+ diff --git a/source/linux/Foundational_Components/U-Boot/UG-Secure-Boot.rst b/source/linux/Foundational_Components/U-Boot/UG-Secure-Boot.rst new file mode 100644 index 000000000..c05e63cbd --- /dev/null +++ b/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 `_ +and `U-Boot FIT Signature Verification `__. +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 diff --git a/source/linux/Foundational_Components/U-Boot/Users-Guide.rst b/source/linux/Foundational_Components/U-Boot/Users-Guide.rst index 09bbc3ff0..9a59e8741 100644 --- a/source/linux/Foundational_Components/U-Boot/Users-Guide.rst +++ b/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 diff --git a/source/linux/Foundational_Components_Secure_Boot.rst b/source/linux/Foundational_Components_Secure_Boot.rst index 347c2bb86..f07692435 100644 --- a/source/linux/Foundational_Components_Secure_Boot.rst +++ b/source/linux/Foundational_Components_Secure_Boot.rst @@ -15,7 +15,7 @@ pass authentication for Public Boot ROM to continue boot. It is then the respons each next stage is itself authenticated. One weak link and all lower trust levels could be compromised. .. Note:: - Example: Forgetting to disable u-boot console or environment loading means a non-secured linux can be loaded. The U-Boot console (or command + Example: Forgetting to disable U-Boot console or environment loading means a non-secured linux can be loaded. The U-Boot console (or command line interface (CLI)) and environment are powerful features that make it great for creating a customized boot process. However, leaving either or them enabled in a production system allows non-secured software to be loaded and the Chain-of-Trust to be broken. @@ -24,7 +24,7 @@ The following is an example list where Chain-of-Trust should be maintained. - Remove U-Boot uEnv.txt loading support. - Disable environment loading (the default built-in environment must be compiled to be the one you want). - Environment must not fallback to other boot modes. -- Place firewalls in board-config to match the location of loaded artifacts (ATF/OP-TEE). +- Place firewalls in board-config to match the location of loaded artifacts (TF-A/OP-TEE). - Update debug sections of initial image cert. - Enable DM-verity/DM-crypt. - Set root password or disable root account. @@ -32,223 +32,362 @@ The following is an example list where Chain-of-Trust should be maintained. - Disable kernel debug options - Disable/remove userspace debug tools, devmem disable, etc.. -We offer methods for U-Boot's Secondary Program Loader (SPL) to securely verify the U-Boot -proper. U-Boot calls Texas Instrument Foundational Security (TIFS) through Texas Instruments System Controller Interface (TISCI) -to do this. For more information about using TISCI methods see the -`TISCI User Guide `__. U-Boot proper then securely verifies and decrypts the kernel, Device Tree Blobs (DTB), and initramfs. +.. ifconfig:: CONFIG_part_variant in ('AM62LX') -.. Image:: /images/K3_KF.png - :scale: 70% + The U-Boot's Secondary Program Loader (SPL) securely verifies the U-Boot + proper. U-Boot uses its verified boot framework to do this + (See: :ref:`u-boot-secure-boot-verified-boot`). U-Boot proper then securely + verifies and decrypts the kernel, Device Tree Blobs (DTB), and initramfs. -Secure boot has layers. Some layers are trusted more than others. Secure ROM has the highest trust and Runtime Execution -Environment (REE) non-trustzone user-space applications have the least. If a -lower trust entity must load a higher trust code, an even higher trust entity -must verify it and not allow access by the lower trust entity after that -point. Some such trust inversions are as follows: + .. Image:: /images/AM62L_KF.png + :scale: 70% -- R5 U-Boot loading ATF/OP-TEE -- R5 Public Boot ROM loading TIFS -- Linux loading Trusted applications(TA) +.. ifconfig:: CONFIG_part_variant not in ('AM62LX') -These are called out in the sequence as shown in the following image and their method of ensuring trust is explained. + We offer methods for U-Boot's Secondary Program Loader (SPL) to securely + verify the U-Boot proper. U-Boot calls Texas Instrument Foundational + Security (TIFS) through Texas Instruments System Controller Interface + (TISCI) to do this. For more information about using TISCI methods see the + `TISCI User Guide `__. + U-Boot proper then securely verifies and decrypts the kernel, Device Tree + Blobs (DTB), and initramfs. + + .. Image:: /images/K3_KF.png + :scale: 70% + +Secure boot has layers. Some layers are trusted more than others. Secure ROM +has the highest trust and Runtime Execution Environment (REE) non-trustzone +user-space applications have the least. If a lower trust entity must load a +higher trust code, an even higher trust entity must verify it and not allow +access by the lower trust entity after that point. Some such trust inversions +are as follows: + +.. ifconfig:: CONFIG_part_variant in ('AM62LX') + + - A53 Public Boot ROM loading TF-A/OP-TEE + - A53 Public Boot ROM loading TIFS + - Linux loading Trusted applications (TA) + +.. ifconfig:: CONFIG_part_variant not in ('AM62LX') + + - R5 U-Boot loading TF-A/OP-TEE + - R5 Public Boot ROM loading TIFS + - Linux loading Trusted applications (TA) + +These are called out in the sequence as shown in the following image and +their method of ensuring trust is explained. Secure Boot Flow -------------------- -.. Image:: /images/K3_BF.jpg - :scale: 70% +.. ifconfig:: CONFIG_part_variant in ('AM62LX') + + .. Image:: /images/AM62L_BF.png + :scale: 70% + +.. ifconfig:: CONFIG_part_variant not in ('AM62LX') + + .. Image:: /images/K3_BF.jpg + :scale: 70% .. rubric:: ROM -On device startup, execution begins with the ROM bootloader (Secure ROM) running on the DSMC/TIFS core. After initial device security -setup the Secure ROM starts the Public ROM running on the R5 core. The Public Boot ROM handles loading the first stage image `tiboot3.bin` from a -peripheral as selected by the BOOTMODE pins. This image is placed into on chip SRAM as external memory interfaces such as DDR are not yet enabled. -The exact location is device dependent. More details can be found in the device "Technical Reference Manual". +.. ifconfig:: CONFIG_part_variant not in ('AM62LX') -.. ifconfig:: CONFIG_part_variant in ('AM64x') + On device startup, execution begins with the ROM bootloader (Secure ROM) + running on the DSMC/TIFS core. After initial device security setup the + Secure ROM starts the Public ROM running on the R5 core. The Public Boot ROM + handles loading the first stage image :file:`tiboot3.bin` from a peripheral + as selected by the BOOTMODE pins. This image is placed into on chip SRAM as + external memory interfaces such as DDR are not yet enabled. The exact + location is device dependent. More details can be found in the device + "Technical Reference Manual". - The contents of this first stage image are authenticated and decrypted by the Secure ROM. Contents include: + .. ifconfig:: CONFIG_part_variant in ('AM64X') - * DMSC firmware: `Texas Instruments Foundational Security (TIFS)` + Device/Power Manager: After authentication/decryption, DMSC firmware replaces the Secure ROM as the authenticator entity executing on the DMSC core. - * R5 SPL: The R5 SPL bootloader is executed on the R5 core. + The contents of this first stage image are authenticated and decrypted by + the Secure ROM. Contents include: -.. ifconfig:: CONFIG_part_variant not in ('AM64X') + * DMSC firmware: `Texas Instruments Foundational Security (TIFS)` + Device/Power Manager: After authentication/decryption, DMSC firmware replaces the Secure ROM as the authenticator entity executing on the DMSC core. + * R5 SPL: The R5 SPL bootloader is executed on the R5 core. - The contents of this first stage image are authenticated and decrypted by the Secure ROM. Contents include: + .. ifconfig:: CONFIG_part_variant not in ('AM64X') - * `Texas Instruments Foundational Security (TIFS)` firmware: After authentication/decryption, TIFS firmware replaces the Secure ROM as the authenticator entity executing on the TIFS core. - * R5 SPL`: The R5 SPL bootloader is executed on the R5 core. + The contents of this first stage image are authenticated and decrypted by + the Secure ROM. Contents include: -.. rubric:: R5 SPL + * `Texas Instruments Foundational Security (TIFS)` firmware: After authentication/decryption, TIFS firmware replaces the Secure ROM as the authenticator entity executing on the TIFS core. + * R5 SPL: The R5 SPL bootloader is executed on the R5 core. -R5 SPL loads the second boot stage FIT image `tispl.bin` from the peripheral as selected by the BOOTMODE pins. From this FIT image, TF-A, OPTEE, A53 SPL, -and SPL DTB are extracted and authenticated and/or decrypted by TIFS. If authentication passed, the R5 SPL starts the ARM64 core. TF-A, OPTEE, and A53 SPL -will begin execution on the ARM64 core. R5 SPL also configures DDR and the console so the user can see the first prints as seen below: +.. ifconfig:: CONFIG_part_variant in ('AM62LX') -R5 SPL's output will be similar to this: -Notice the "Authentication passed" lines as TF-A, OPTEE, A53 SPL, and SPL DTB are authenticated. + On device startup, execution begins with the ROM bootloader (Secure ROM) + running on SMS M4 core. After initial device security setup, the Secure ROM + starts the Public ROM running on the A53 core. The Public ROM handles + loading the first stage image :file:`tiboot3.bin` from a peripheral as + selected by the BOOTMODE pins. This image is placed into on-chip SRAM as + external memory interfaces such as DDR are not yet enabled. The exact + location is device dependent. More details can be found in the device + "Technical Reference Manual". -.. code-block:: console + The contents of this first stage image are authenticated and decrypted by + the Secure ROM. Contents include: + + * `Texas Instruments Foundational Security (TIFS)` firmware: After authentication/decryption, TIFS firmware replaces the Secure ROM as the authenticator entity executing on the M4 core in the 2nd phase of the boot. + * BL-1: The pre-bootloader executed on the A53 core, initializes the console and DDR for the 2nd phase of the boot. + +.. ifconfig:: CONFIG_part_variant not in ('AM62LX') + + .. rubric:: R5 SPL + + R5 SPL loads the second boot stage FIT image `tispl.bin` from the + peripheral as selected by the BOOTMODE pins. From this FIT image, TF-A, + OPTEE, A53 SPL, and SPL DTB are extracted and authenticated and/or decrypted + by TIFS. If authentication passed, the R5 SPL starts the ARM64 core. TF-A, + OPTEE, and A53 SPL will begin execution on the ARM64 core. R5 SPL also + configures DDR and the console so the user can see the first prints as seen + below: + + R5 SPL's output will be similar to this: + Notice the "Authentication passed" lines as TF-A, OPTEE, A53 SPL, and SPL DTB are authenticated. - U-Boot SPL 2021.01-dirty (May 13 2022 - 15:05:11 -0500) - SYSFW ABI: 3.1 (firmware rev 0x0008 '8.4.0-3-gd5cb1+ (Jolly Jellyfis') - SPL initial stack usage: 13392 bytes - Trying to boot from MMC2 - Authentication passed - Authentication passed - Authentication passed - Authentication passed - Starting ATF on ARM64 core... + .. code-block:: console -.. ifconfig:: CONFIG_part_variant in ('AM62x') + U-Boot SPL 2021.01-dirty (May 13 2022 - 15:05:11 -0500) + SYSFW ABI: 3.1 (firmware rev 0x0008 '8.4.0-3-gd5cb1+ (Jolly Jellyfis') + SPL initial stack usage: 13392 bytes + Trying to boot from MMC2 + Authentication passed + Authentication passed + Authentication passed + Authentication passed + Starting ATF on ARM64 core... - After R5 SPL, the device/power manager firmware continues running on the R5 core. + .. ifconfig:: CONFIG_part_variant in ('AM62x') + + After R5 SPL, the device/power manager firmware continues running on the R5 core. .. rubric:: A53 SPL -A53 SPL then loads the U-Boot proper FIT image `U-boot.img` from the peripheral as selected by the BOOTMODE pins. From this FIT image, the U-boot bootloader -and DTB are extracted before passing execution to u-boot proper. +.. ifconfig:: CONFIG_part_variant not in ('AM62LX') -A53 SPL's output will be similar to this: (notice the "Authentication passed" lines as U-Boot and the DTB are authenticated). + A53 SPL then loads the U-Boot proper FIT image :file:`u-boot.img` from the + peripheral as selected by the BOOTMODE pins. From this FIT image, the U-Boot + bootloader and DTB are extracted before passing execution to U-Boot proper. -.. code-block:: console + A53 SPL's output will be similar to this: (notice the "Authentication passed" lines as U-Boot and the DTB are authenticated). + + .. code-block:: console + + U-Boot SPL 2021.01-g2de57d278b (May 16 2022 - 14:28:40 +0000) + SYSFW ABI: 3.1 (firmware rev 0x0008 '8.4.0-3-gd5cb1+ (Jolly Jellyfis') + Trying to boot from MMC2 + Authentication passed + Authentication passed + +.. ifconfig:: CONFIG_part_variant in ('AM62LX') + + Public ROM loads the second boot stage image :file:`tispl.bin` from the + peripheral as selected by the BOOTMODE pins. From this image, TF-A, OP-TEE, + A53 SPL (U-Boot SPL) and SPL DTB are extracted and authenticated and/or + decrypted by the Secure ROM. If authenticated, the Secure ROM resets the A53 + core. TF-A, OP-TEE and U-Boot SPL begin execution on the A53 core. + + U-Boot SPL then loads the U-Boot proper FIT image :file:`u-boot.img` from + the peripheral as selected by the BOOTMODE pins. The U-Boot SPL verifies the + signed FIT image independently, without using TIFS. From this FIT image, the + U-Boot bootloader and DTB are extracted before passing execution to U-Boot + proper. + + U-Boot SPL's output will be similar to this: (notice the "Checking hash(es)" + lines as U-Boot and DTB are authenticated). - U-Boot SPL 2021.01-g2de57d278b (May 16 2022 - 14:28:40 +0000) - SYSFW ABI: 3.1 (firmware rev 0x0008 '8.4.0-3-gd5cb1+ (Jolly Jellyfis') - Trying to boot from MMC2 - Authentication passed - Authentication passed + .. code-block:: console + + U-Boot SPL 2026.01-ti-gee3048ee0822 (Apr 09 2026 - 00:09:07 +0000) + SPL initial stack usage: 1936 bytes + Trying to boot from DFU + ######DOWNLOAD ... OK + Ctrl+C to exit ... + ## Checking hash(es) for config conf-0 ... sha512,rsa4096:custMpk+ OK + ## Checking hash(es) for Image uboot ... sha512+ OK + ## Checking hash(es) for Image fdt-0 ... sha512+ OK .. rubric:: U-Boot -The boot flow continues as it does on a non-secure device, until loading the next FIT image named `fitImage`. This FIT image includes the Linux kernel, DTB, and -other required boot artifacts. U-boot verifies the signed images on boot independently, without using TIFS. U-boot extracts each component from the FIT image and verifies its signature. Once u-boot verifies all components, it starts Linux. For more information, see: `U-Boot FIT Signature Documentation `__ +The boot flow continues as it does on a non-secure device, until loading the +next FIT image named :file:`fitImage`. This FIT image includes the Linux +kernel, DTB, and other required boot artifacts. U-Boot verifies the signed +images on boot independently, without using TIFS. U-Boot extracts each +component from the FIT image and verifies its signature. Once U-Boot verifies +all components, it starts Linux. For more information, see: +`U-Boot FIT Signature Documentation `__ -U-boot's output will be similar to this: +U-Boot's output will be similar to this: .. code-block:: console - U-Boot 2021.01-g2de57d278b (May 16 2022 - 14:28:40 +0000) - - SoC: AM64X SR1.0 - Model: Texas Instruments AM642 EVM - Board: AM64-GPEVM rev A - DRAM: 2 GiB - NAND: 0 MiB - MMC: mmc@fa10000: 0, mmc@fa00000: 1 - Loading Environment from FAT... *** Warning - bad CRC, using default environment - - In: serial@2800000 - Out: serial@2800000 - Err: serial@2800000 - Net: eth0: ethernet@8000000port@1 - Hit any key to stop autoboot: 0 - switch to partitions #0, OK - mmc1 is current device - SD/MMC found on device 1 - Failed to load 'boot.scr' - 1011 bytes read in 2 ms (493.2 KiB/s) - Loaded env from uEnv.txt - Importing environment from mmc1 ... - Running uenvcmd ... - 7862647 bytes read in 328 ms (22.9 MiB/s) - ## Loading kernel from FIT Image at 90000000 ... - Using 'k3-am642-evm.dtb' configuration - Trying 'kernel@1' kernel subimage - Description: Linux kernel - Type: Kernel Image - Compression: gzip compressed - Data Start: 0x900000f8 - Data Size: 7743643 Bytes = 7.4 MiB - Architecture: AArch64 - OS: Linux - Load Address: 0x80080000 - Entry Point: 0x80080000 - Verifying Hash Integrity ... OK - ## Loading fdt from FIT Image at 90000000 ... - Using 'k3-am642-evm.dtb' configuration - Trying 'k3-am642-evm.dtb' fdt subimage - Description: Flattened Device Tree blob - Type: Flat Device Tree - Compression: uncompressed - Data Start: 0x90762a54 - Data Size: 56436 Bytes = 55.1 KiB - Architecture: AArch64 - Load Address: 0x83000000 - Verifying Hash Integrity ... OK - Loading fdt from 0x90762a54 to 0x83000000 - Booting using the fdt blob at 0x83000000 - Uncompressing Kernel Image - Loading Device Tree to 000000008ffef000, end 000000008ffff602 ... OK + U-Boot 2021.01-g2de57d278b (May 16 2022 - 14:28:40 +0000) + + SoC: AM64X SR1.0 + Model: Texas Instruments AM642 EVM + Board: AM64-GPEVM rev A + DRAM: 2 GiB + NAND: 0 MiB + MMC: mmc@fa10000: 0, mmc@fa00000: 1 + Loading Environment from FAT... *** Warning - bad CRC, using default environment + + In: serial@2800000 + Out: serial@2800000 + Err: serial@2800000 + Net: eth0: ethernet@8000000port@1 + Hit any key to stop autoboot: 0 + switch to partitions #0, OK + mmc1 is current device + SD/MMC found on device 1 + Failed to load 'boot.scr' + 1011 bytes read in 2 ms (493.2 KiB/s) + Loaded env from uEnv.txt + Importing environment from mmc1 ... + Running uenvcmd ... + 7862647 bytes read in 328 ms (22.9 MiB/s) + ## Loading kernel from FIT Image at 90000000 ... + Using 'k3-am642-evm.dtb' configuration + Trying 'kernel@1' kernel subimage + Description: Linux kernel + Type: Kernel Image + Compression: gzip compressed + Data Start: 0x900000f8 + Data Size: 7743643 Bytes = 7.4 MiB + Architecture: AArch64 + OS: Linux + Load Address: 0x80080000 + Entry Point: 0x80080000 + Verifying Hash Integrity ... OK + ## Loading fdt from FIT Image at 90000000 ... + Using 'k3-am642-evm.dtb' configuration + Trying 'k3-am642-evm.dtb' fdt subimage + Description: Flattened Device Tree blob + Type: Flat Device Tree + Compression: uncompressed + Data Start: 0x90762a54 + Data Size: 56436 Bytes = 55.1 KiB + Architecture: AArch64 + Load Address: 0x83000000 + Verifying Hash Integrity ... OK + Loading fdt from 0x90762a54 to 0x83000000 + Booting using the fdt blob at 0x83000000 + Uncompressing Kernel Image + Loading Device Tree to 000000008ffef000, end 000000008ffff602 ... OK .. rubric:: Linux -If initramfs is included, we can trust our initial modules and tasks, but we cannot trust anything beyond this as the root file-system may have been -modified. To allow trusted use of files outside of our initramfs we use dm-verity. With this we can authenticate a block device as we read from it. As -any changes to this block-device will cause the authentication to fail, we cannot put any user-modifiable configurations or user installed programs -here. Only important, read-only, files should be placed on this partition, such as static kernel and operating system files and configurations. All -other files must be placed in a non-verifiable read-write user partition. +If initramfs is included, we can trust our initial modules and tasks, but we +cannot trust anything beyond this as the root file-system may have been +modified. To allow trusted use of files outside of our initramfs we use +dm-verity. With this we can authenticate a block device as we read from it. As +any changes to this block-device will cause the authentication to fail, we +cannot put any user-modifiable configurations or user installed programs here. +Only important, read-only, files should be placed on this partition, such as +static kernel and operating system files and configurations. All other files +must be placed in a non-verifiable read/write user partition. HS Boot Flow Tools ------------------- -U-boot: +U-Boot: + + .. ifconfig:: CONFIG_part_variant not in ('AM62LX') + + The ti-u-boot source is a project used to create :file:`tiboot3.bin`, + :file:`tispl.bin`, and :file:`u-boot.img`. To create :file:`tiboot3.bin` + for K3 family devices, U-Boot builds R5 SPL and binman packages it in a + :file:`tiboot3.bin` image. To build A53 SPL, binman takes TF-A + (:file:`bl31.bin`), OPTEE (:file:`bl32.bin`), A53 SPL, and A53 DTBs and + packages them in a :file:`tispl.bin` image. U-Boot can then use the + openssl library to sign each component as specified in + :file:`k3--binman.dtsi`. + + .. code-block:: console + + $ git clone https://git.ti.com/git/ti-u-boot/ti-u-boot.git + + $ # Example use: + $ make ARCH=arm CROSS_COMPILE=aarch64-none-linux-gnu- am64x_evm_a53_defconfig + $ make CROSS_COMPILE=aarch64-none-linux-gnu- BL31=bl31.bin TEE=tee-pager_v2.bin BINMAN_INDIRS=/board-support/prebuilt-images + + .. ifconfig:: CONFIG_part_variant in ('AM62LX') - The ti-u-boot source is a project used to create tiboot3.bin, tispl.bin, and u-boot.img. To create tiboot3.bin for K3 family devices, u-boot builds R5 SPL and - binman packages it in a `tiboot3.bin` image. To build A53 SPL, binman takes ATF (bl31.bin), OPTEE (bl32.bin), A53 SPL, and A53 DTBs and packages - them in a `tispl.bin` image. U-Boot can then use the openssl library to sign each component as specified in k3--binman.dtsi. + The ti-u-boot source is a project used to create :file:`tiboot3.bin`, + :file:`tispl.bin`, and :file:`u-boot.img`. To create :file:`tiboot3.bin` + for K3 family devices, U-Boot builds BL-1 and binman packages it in a + :file:`tiboot3.bin` image. To build A53 SPL, binman takes TF-A + (:file:`bl31.bin`), OPTEE (:file:`bl32.bin`), A53 SPL, and A53 DTBs and + packages them in a :file:`tispl.bin` image. U-Boot can then use the + openssl library to sign each component as specified in + :file:`k3-am62l3-evm-binman.dtsi`. - .. code-block:: console + .. code-block:: console - $ git clone https://git.ti.com/git/ti-u-boot/ti-u-boot.git + $ git clone https://git.ti.com/git/ti-u-boot/ti-u-boot.git - Example use: - $ make ARCH=arm CROSS_COMPILE=aarch64-none-linux-gnu- am64x_evm_a53_defconfig - $ make CROSS_COMPILE=aarch64-none-linux-gnu- ATF=bl31.bin TEE=tee-pager_v2.bin BINMAN_INDIRS=/board-support/prebuilt-images + $ # Example use: + $ make ARCH=arm CROSS_COMPILE=aarch64-none-linux-gnu- am62lx_evm_defconfig + $ make CROSS_COMPILE=aarch64-none-linux-gnu- BL1=bl1.bin BL31=bl31.bin TEE=tee-pager_v2.bin BINMAN_INDIRS=/board-support/prebuilt-images Linux: - The ti-linux source is a TI project used to build Linux kernel, DTB, and other boot artifacts. Some of these components could be included in a verifiable image - `fitImage`. For HS devices, only the fitImage will be allowed to boot once `fitImage` has been authenticated. + The ti-linux source is a TI project used to build Linux kernel, DTB, and + other boot artifacts. Some of these components could be included in a + verifiable image :file:`fitImage`. For HS devices, only the fitImage will be + allowed to boot once :file:`fitImage` has been authenticated. - .. code-block:: console + .. code-block:: console - $ git clone https://git.ti.com/git/ti-linux-kernel/ti-linux-kernel.git + $ git clone https://git.ti.com/git/ti-linux-kernel/ti-linux-kernel.git - Example use: - $ make ARCH=arm64 CROSS_COMPILE=aarch64-none-linux-gnu- defconfig ti_arm64_prune.config - $ make ARCH=arm64 CROSS_COMPILE=aarch64-none-linux-gnu- menuconfig - $ make ARCH=arm64 CROSS_COMPILE=aarch64-none-linux-gnu- + $ #Example use: + $ make ARCH=arm64 CROSS_COMPILE=aarch64-none-linux-gnu- defconfig ti_arm64_prune.config + $ make ARCH=arm64 CROSS_COMPILE=aarch64-none-linux-gnu- menuconfig + $ make ARCH=arm64 CROSS_COMPILE=aarch64-none-linux-gnu- -ATF: +TF-A: - The ATF source (now called TF-A) is used to build `bl31.bin` that gets packaged into `tispl.bin`. For HS devices, this binary needs to be signed. + The TF-A source (formerly called ATF) is used to build :file:`bl31.bin` that + gets packaged into :file:`tispl.bin`. For HS devices, this binary needs to + be signed. - .. code-block:: console + .. code-block:: console - $ git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git + $ git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git - Example use: - $ make ARCH=aarch64 CROSS_COMPILE=aarch64-none-linux-gnu- PLAT=k3 TARGET_BOARD=lite SPD=opteed + $ # Example use: + $ make ARCH=aarch64 CROSS_COMPILE=aarch64-none-linux-gnu- PLAT=k3 TARGET_BOARD=lite SPD=opteed OPTEE: - The OPTEE source is used to build `bl32.bin/tee-pager_v2.bin` that gets packaged into `tispl.bin`. For HS devices, this binary needs to be signed. + The OPTEE source is used to build :file:`bl32.bin/tee-pager_v2.bin` that + gets packaged into :file:`tispl.bin`. For HS devices, this binary needs to + be signed. - .. code-block:: console + .. code-block:: console - $ git clone https://github.com/OP-TEE/optee_os.git + $ git clone https://github.com/OP-TEE/optee_os.git - Example use: - $ make CROSS_COMPILE64=aarch64-linux-gnu- PLATFORM=k3- CFG_ARM64_core=y + $ # Example use: + $ make CROSS_COMPILE64=aarch64-linux-gnu- PLATFORM=k3- CFG_ARM64_core=y Ti-linux-firmware: - The ti-linux-firmware is a TI repository where all firmware releases are stored. Firmwares for a device family can also be found in the pre-built SDK - under :file:`/board-support/prebuilt-images/`. Binman expects to find the device firmware with the following appended to u-boot build command: - BINMAN_INDIRS=/board-support/prebuilt-images, and expects to find a ti-sysfw directory in this path. + The ti-linux-firmware is a TI repository where all firmware releases are + stored. Firmwares for a device family can also be found in the pre-built SDK + under :file:`/board-support/prebuilt-images/`. Binman + expects to find the device firmware with the following appended to U-Boot + build command: + :code:`BINMAN_INDIRS=/board-support/prebuilt-images`, and + expects to find a ti-sysfw directory in this path. - .. code-block:: console + .. code-block:: console - $