Skip to content

fix(security): Correct key flow diagram and text around it for AM64X #654

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jsuhaas22 wants to merge 2 commits into
base: master
Choose a base branch
from
+43 −25
Open

fix(security): Correct key flow diagram and text around it for AM64X #654

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
da6c3c6
fix(security): Correct key flow diagram and text around it for AM64X
jsuhaas22 Apr 8, 2026
6474e81
feat(security): Generalize boot flow page for non-AM64x SoCs
jsuhaas22 Apr 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions configs/AM62AX/AM62AX_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,7 @@ linux/Foundational_Components/System_Security/Security_overview
linux/Foundational_Components/System_Security/SELinux
linux/Foundational_Components/System_Security/Auth_boot
linux/Foundational_Components/System_Security/Memory_Firewalls
linux/Foundational_Components_Secure_Boot

linux/Foundational_Components_Kernel_Users_Guide
linux/Foundational_Components_Kernel_LTP-DDT_Validation
Expand Down
1 change: 1 addition & 0 deletions configs/AM62PX/AM62PX_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,7 @@ linux/Foundational_Components/System_Security/Security_overview
linux/Foundational_Components/System_Security/SELinux
linux/Foundational_Components/System_Security/Auth_boot
linux/Foundational_Components/System_Security/Memory_Firewalls
linux/Foundational_Components_Secure_Boot

linux/Foundational_Components_Kernel_Users_Guide
linux/Foundational_Components_Kernel_LTP-DDT_Validation
Expand Down
1 change: 1 addition & 0 deletions configs/AM62X/AM62X_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,7 @@ linux/Foundational_Components/System_Security/Security_overview
linux/Foundational_Components/System_Security/SELinux
linux/Foundational_Components/System_Security/Auth_boot
linux/Foundational_Components/System_Security/Memory_Firewalls
linux/Foundational_Components_Secure_Boot

linux/Foundational_Components_PRU_Subsystem
linux/Foundational_Components/PRU-ICSS-Linux-Drivers
Expand Down
1 change: 1 addition & 0 deletions configs/AM67/AM67_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@ linux/Foundational_Components/Virtualization/Docker
linux/Foundational_Components_OPTEE
linux/Foundational_Components_ATF
linux/Foundational_Components_Multimedia_wave5
linux/Foundational_Components_Secure_Boot

linux/Foundational_Components/Graphics/index
linux/Foundational_Components/Graphics/Common/Display
Expand Down
1 change: 1 addition & 0 deletions configs/AM67A/AM67A_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,7 @@ linux/Foundational_Components/Virtualization/Docker
linux/Foundational_Components_OPTEE
linux/Foundational_Components_ATF
linux/Foundational_Components_Multimedia_wave5
linux/Foundational_Components_Secure_Boot
linux/Foundational_Components/Graphics/index
linux/Foundational_Components/Graphics/Common/Display
linux/Foundational_Components/Graphics/Common/GTK+_Graphics_Framework
Expand Down
1 change: 1 addition & 0 deletions configs/AM68/AM68_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,7 @@ linux/Foundational_Components/Virtualization/Docker
linux/Foundational_Components_OPTEE
linux/Foundational_Components_ATF
linux/Foundational_Components_Multimedia_wave5
linux/Foundational_Components_Secure_Boot

linux/Foundational_Components/Graphics/index
linux/Foundational_Components/Graphics/Common/Display
Expand Down
1 change: 1 addition & 0 deletions configs/AM68A/AM68A_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,7 @@ linux/Foundational_Components/Virtualization/Docker
linux/Foundational_Components_OPTEE
linux/Foundational_Components_ATF
linux/Foundational_Components_Multimedia_wave5
linux/Foundational_Components_Secure_Boot
linux/Foundational_Components/Graphics/index
linux/Foundational_Components/Graphics/Common/Display
linux/Foundational_Components/Graphics/Common/GTK+_Graphics_Framework
Expand Down
1 change: 1 addition & 0 deletions configs/AM69/AM69_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,7 @@ linux/Foundational_Components/Virtualization/Docker
linux/Foundational_Components_OPTEE
linux/Foundational_Components_ATF
linux/Foundational_Components_Multimedia_wave5
linux/Foundational_Components_Secure_Boot

linux/Foundational_Components/Graphics/index
linux/Foundational_Components/Graphics/Common/Display
Expand Down
1 change: 1 addition & 0 deletions configs/AM69A/AM69A_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,7 @@ linux/Foundational_Components/Virtualization/Docker
linux/Foundational_Components_OPTEE
linux/Foundational_Components_ATF
linux/Foundational_Components_Multimedia_wave5
linux/Foundational_Components_Secure_Boot
linux/Foundational_Components/Graphics/index
linux/Foundational_Components/Graphics/Common/Display
linux/Foundational_Components/Graphics/Common/GTK+_Graphics_Framework
Expand Down
1 change: 1 addition & 0 deletions configs/J7200/J7200_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,7 @@ linux/Foundational_Components/Kernel/Kernel_Drivers/PCIe/PCIe_Root_Complex
linux/Foundational_Components/Kernel/Kernel_Drivers/PMIC/pmic_tps6594
linux/Foundational_Components_Power_Management
linux/Foundational_Components/Power_Management/pm_dfs
linux/Foundational_Components_Secure_Boot
linux/Foundational_Components/Kernel/Kernel_Drivers/QSPI
linux/Foundational_Components/Kernel/Kernel_Drivers/SERDES/SERDES
linux/Foundational_Components/Kernel/Kernel_Drivers/SPI
Expand Down
1 change: 1 addition & 0 deletions configs/J721E/J721E_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,7 @@ linux/Foundational_Components/Kernel/Kernel_Drivers/PCIe/PCIe_Root_Complex
linux/Foundational_Components/Kernel/Kernel_Drivers/PMIC/pmic_tps6594
linux/Foundational_Components_Power_Management
linux/Foundational_Components/Power_Management/pm_dfs
linux/Foundational_Components_Secure_Boot
linux/Foundational_Components/Kernel/Kernel_Drivers/QSPI
linux/Foundational_Components/Kernel/Kernel_Drivers/SERDES/SERDES
linux/Foundational_Components/Kernel/Kernel_Drivers/SPI
Expand Down
1 change: 1 addition & 0 deletions configs/J721S2/J721S2_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,7 @@ linux/Foundational_Components/Kernel/Kernel_Drivers/PCIe/PCIe_Root_Complex
linux/Foundational_Components/Kernel/Kernel_Drivers/PMIC/pmic_tps6594
linux/Foundational_Components_Power_Management
linux/Foundational_Components/Power_Management/pm_dfs
linux/Foundational_Components_Secure_Boot
linux/Foundational_Components/Kernel/Kernel_Drivers/QSPI
linux/Foundational_Components/Kernel/Kernel_Drivers/SERDES/SERDES
linux/Foundational_Components/Kernel/Kernel_Drivers/SPI
Expand Down
1 change: 1 addition & 0 deletions configs/J722S/J722S_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,7 @@ linux/Foundational_Components/Kernel/Kernel_Drivers/Network/CPSW-TSN-Tuning
linux/Foundational_Components/Kernel/Kernel_Drivers/PCIe/PCIe_Root_Complex
linux/Foundational_Components_Power_Management
linux/Foundational_Components/Power_Management/pm_dfs
linux/Foundational_Components_Secure_Boot
linux/Foundational_Components/Kernel/Kernel_Drivers/QSPI
linux/Foundational_Components/Kernel/Kernel_Drivers/SERDES/SERDES
linux/Foundational_Components/Kernel/Kernel_Drivers/SPI
Expand Down
1 change: 1 addition & 0 deletions configs/J742S2/J742S2_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,7 @@ linux/Foundational_Components/Kernel/Kernel_Drivers/PCIe/PCIe_Root_Complex
linux/Foundational_Components/Kernel/Kernel_Drivers/PMIC/pmic_tps6594
linux/Foundational_Components_Power_Management
linux/Foundational_Components/Power_Management/pm_dfs
linux/Foundational_Components_Secure_Boot
linux/Foundational_Components/Kernel/Kernel_Drivers/QSPI
linux/Foundational_Components/Kernel/Kernel_Drivers/SERDES/SERDES
linux/Foundational_Components/Kernel/Kernel_Drivers/SPI
Expand Down
Binary file removed source/images/K3_KF.JPG
View file
Open in desktop
Binary file not shown.
Binary file added source/images/K3_KF.png
View file
Open in desktop
Comment thread
jsuhaas22 marked this conversation as resolved.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
8 changes: 6 additions & 2 deletions source/linux/Foundational_Components/System_Security/Security_overview.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,8 +71,12 @@ The following table lists some of the key Security Features:
+-------------------------+-----------------------------------------------------------+--------------------------------------+
| Security Feature | Description | Links |
+=========================+===========================================================+======================================+
| **Authenticated Boot** | Verifies each boot component to ensure only authorized | :ref:`auth_boot_guide` |
| | code executes on the device | |
| **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 | |
+-------------------------+-----------------------------------------------------------+--------------------------------------+
| **Authenticated Boot** | Transparent disk encryption using the Linux kernel | :ref:`auth_boot_guide` |
| | device mapper (dm-crypt) for data confidentiality | |
+-------------------------+-----------------------------------------------------------+--------------------------------------+
| **Crypto Acceleration** | Hardware driver support for cryptographic algorithms | :ref:`crypto-accelerator` |
+-------------------------+-----------------------------------------------------------+--------------------------------------+
Expand Down
46 changes: 23 additions & 23 deletions source/linux/Foundational_Components_Secure_Boot.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
.. _foundational-secure-boot:

**********************************
Secure Boot
**********************************

Authenticated Boot
--------------------
Introduction
------------

Each device contains customer programmable keys used to authenticate, and optionally decrypt, code/data to be used on the device. A job for
the Public Boot ROM of both General Purpose (GP) and High Security (HS) devices is to load the next stage of the boot process into memory. On
Expand All @@ -30,17 +32,19 @@
- Disable kernel debug options
- Disable/remove userspace debug tools, devmem disable, etc..

We provide methods for U-Boot's SPL loader to securely verify/decrypt the U-Boot proper, and this U-Boot proper to securely verify/decrypt the
Kernel/DTB/initfamfs. This is accomplished by calling into TIFS via TI-SCI (Texas Instruments System controller Interface). This allows us to use
the same signing/encrypting tools used to authenticate the first-stage image. For more infomation using TI_SCI methods refer to the
`TISCI User Guide <https://software-dl.ti.com/tisci/esd/22_01_02/index.html>`__.
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 <https://software-dl.ti.com/tisci/esd/latest/index.html>`__. U-Boot proper then securely verifies and decrypts the kernel, Device Tree Blobs (DTB), and initramfs.

.. Image:: /images/K3_KF.JPG
.. Image:: /images/K3_KF.png
:scale: 70%

Secure boot is like an onion, it has layers. Some layers are trusted more than others. Secure ROM has the highest trust and REE (Run-time Execution
Environment) non-trustzone user-space applications have the least. If any higher trust code is to be loaded by a lower trust entity, it must be verified
by an even higher trust entity and not allowed to be accessed by the lower trust entity after that point. Some such trust inversions are listed below:
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

Check warning on line 45 in source/linux/Foundational_Components_Secure_Boot.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.TermsSuggestions] Depending on the context, consider using 'later' rather than 'higher'.

Raw Output:
{"message": "[RedHat.TermsSuggestions] Depending on the context, consider using 'later' rather than 'higher'.", "location": {"path": "source/linux/Foundational_Components_Secure_Boot.rst", "range": {"start": {"line": 45, "column": 59}}}, "severity": "INFO"}

Check warning on line 45 in source/linux/Foundational_Components_Secure_Boot.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.TermsSuggestions] Depending on the context, consider using 'later' rather than 'higher'.

Raw Output:
{"message": "[RedHat.TermsSuggestions] Depending on the context, consider using 'later' rather than 'higher'.", "location": {"path": "source/linux/Foundational_Components_Secure_Boot.rst", "range": {"start": {"line": 45, "column": 32}}}, "severity": "INFO"}
must verify it and not allow access by the lower trust entity after that
point. Some such trust inversions are as follows:

- R5 U-Boot loading ATF/OP-TEE
- R5 Public Boot ROM loading TIFS
Expand All @@ -63,21 +67,17 @@

.. ifconfig:: CONFIG_part_variant in ('AM64x')

- `AM64x TRM <https://www.ti.com/lit/pdf/spruim2>`_

The contents of this first stage image are authenticated and decrypted by the Secure ROM. Contents include:

* 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.

.. ifconfig:: CONFIG_part_variant in ('AM62x')

- `AM62x TRM <https://www.ti.com/lit/pdf/spruiv7>`_
.. ifconfig:: CONFIG_part_variant not in ('AM64X')

The contents of this first stage image are authenticated and decrypted by the Secure ROM. Contents include:
Comment thread
jsuhaas22 marked this conversation as resolved.
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 TIFS core.
* R5 SPL`: The R5 SPL bootloader is executed on the R5 core.
* `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.

.. rubric:: R5 SPL

Expand Down Expand Up @@ -122,9 +122,9 @@
.. 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. Each component is extracted and authenticated from this FIT image. Once all components are authenticated, U-boot starts Linux.
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 <https://docs.u-boot.org/en/latest/usage/fit/signature.html>`__

Check warning on line 125 in source/linux/Foundational_Components_Secure_Boot.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'FIT') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'FIT') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components_Secure_Boot.rst", "range": {"start": {"line": 125, "column": 276}}}, "severity": "INFO"}

Check warning on line 125 in source/linux/Foundational_Components_Secure_Boot.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'FIT') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'FIT') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components_Secure_Boot.rst", "range": {"start": {"line": 125, "column": 149}}}, "severity": "INFO"}

U-boot's output will be similar to this: (notice the "Authentication passed" lines as we authenticate the Linux kernel and DTB).
U-boot's output will be similar to this: (notice the "Authentication passed" lines as u-boot verifies the Linux kernel and DTB).

.. code-block:: console

Expand Down Expand Up @@ -196,9 +196,9 @@

U-boot:

The ti-u-boot source is a project used to create tiboot3.bin, tispl.bin, and u-boot.img. To create tiboot3.bin for AM64x family devices, u-boot builds R5 SPL and
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. The openssl library can then then be used to sign each component as specified in k3-am64x-binman.dtsi.
them in a `tispl.bin` image. U-Boot can then use the openssl library to sign each component as specified in k3-<soc>-binman.dtsi.

.. code-block:: console

Expand Down Expand Up @@ -247,7 +247,7 @@
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 <path-to-tisdk>/board-support/prebuilt-images/am64xx-evm. Binman expects to find the device firmware with the following appended to u-boot build command:
under :file:`<path-to-tisdk>/board-support/prebuilt-images/<evm>`. Binman expects to find the device firmware with the following appended to u-boot build command:

Check warning on line 250 in source/linux/Foundational_Components_Secure_Boot.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.UserReplacedValues] Separate words by underscores in user-replaced values.

Raw Output:
{"message": "[RedHat.UserReplacedValues] Separate words by underscores in user-replaced values.", "location": {"path": "source/linux/Foundational_Components_Secure_Boot.rst", "range": {"start": {"line": 250, "column": 18}}}, "severity": "INFO"}
BINMAN_INDIRS=<path-to-tisdk>/board-support/prebuilt-images, and expects to find a ti-sysfw directory in this path.

.. code-block:: console
Expand Down
Loading