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
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
526f6c6
feat(security): Generalize boot flow page for non-AM64x SoCs
jsuhaas22 Apr 13, 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
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
Copy link
Copy Markdown

@p-shivhare-ti p-shivhare-ti Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The fitImage box shows "u-boot-dtb*.dtb". Is it correct? It should be Kernel DTBs, right?

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
42 changes: 26 additions & 16 deletions source/linux/Foundational_Components_Secure_Boot.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _foundational-secure-boot:

**********************************
Secure Boot
**********************************
Expand Down Expand Up @@ -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/22_01_02/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 Down Expand Up @@ -70,14 +74,20 @@
* 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')
.. ifconfig:: CONFIG_part_variant not in ('AM64X')

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

The contents of this first stage image are authenticated and decrypted by the Secure ROM. Contents include:
- `AM62x TRM <https://www.ti.com/lit/pdf/spruiv7>`_

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

- `AM62P TRM <https://www.ti.com/lit/pdf/spruj83>`_

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 @@ -196,9 +206,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 +257,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 260 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": 260, "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