Skip to content

Commit dce2a4f

Browse files
Pratham-TPratham-T
committed
fix(security): Formatting cleanup to Secure Boot page
Changes the indentation to 3 spaces, adds :file: and :code: directive to appropriate places, and wrap long lines to 80 characters. While here, also update the name "U-Boot" to have a consistent case everywhere, and update ATF to TF-A. Signed-off-by: T Pratham <t-pratham@ti.com>
1 parent a0e4784 commit dce2a4f

1 file changed

Lines changed: 125 additions & 98 deletions

File tree

‎source/linux/Foundational_Components_Secure_Boot.rst‎

Lines changed: 125 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ pass authentication for Public Boot ROM to continue boot. It is then the respons
1515
each next stage is itself authenticated. One weak link and all lower trust levels could be compromised.
1616

1717
.. Note::
18-
Example: Forgetting to disable u-boot console or environment loading means a non-secured linux can be loaded. The U-Boot console (or command
18+
Example: Forgetting to disable U-Boot console or environment loading means a non-secured linux can be loaded. The U-Boot console (or command
1919
line interface (CLI)) and environment are powerful features that make it great for creating a customized boot process. However,
2020
leaving either or them enabled in a production system allows non-secured software to be loaded and the Chain-of-Trust to be broken.
2121

@@ -24,7 +24,7 @@ The following is an example list where Chain-of-Trust should be maintained.
2424
- Remove U-Boot uEnv.txt loading support.
2525
- Disable environment loading (the default built-in environment must be compiled to be the one you want).
2626
- Environment must not fallback to other boot modes.
27-
- Place firewalls in board-config to match the location of loaded artifacts (ATF/OP-TEE).
27+
- Place firewalls in board-config to match the location of loaded artifacts (TF-A/OP-TEE).
2828
- Update debug sections of initial image cert.
2929
- Enable DM-verity/DM-crypt.
3030
- Set root password or disable root account.
@@ -55,11 +55,12 @@ The following is an example list where Chain-of-Trust should be maintained.
5555
.. Image:: /images/K3_KF.png
5656
:scale: 70%
5757

58-
Secure boot has layers. Some layers are trusted more than others. Secure ROM has the highest trust and Runtime Execution
59-
Environment (REE) non-trustzone user-space applications have the least. If a
60-
lower trust entity must load a higher trust code, an even higher trust entity
61-
must verify it and not allow access by the lower trust entity after that
62-
point. Some such trust inversions are as follows:
58+
Secure boot has layers. Some layers are trusted more than others. Secure ROM
59+
has the highest trust and Runtime Execution Environment (REE) non-trustzone
60+
user-space applications have the least. If a lower trust entity must load a
61+
higher trust code, an even higher trust entity must verify it and not allow
62+
access by the lower trust entity after that point. Some such trust inversions
63+
are as follows:
6364

6465
.. ifconfig:: CONFIG_part_variant in ('AM62LX')
6566

@@ -73,7 +74,8 @@ point. Some such trust inversions are as follows:
7374
- R5 Public Boot ROM loading TIFS
7475
- Linux loading Trusted applications (TA)
7576

76-
These are called out in the sequence as shown in the following image and their method of ensuring trust is explained.
77+
These are called out in the sequence as shown in the following image and
78+
their method of ensuring trust is explained.
7779

7880
Secure Boot Flow
7981
--------------------
@@ -128,7 +130,8 @@ Secure Boot Flow
128130
location is device dependent. More details can be found in the device
129131
"Technical Reference Manual".
130132

131-
The contents of this first stage image are authenticated and decrypted by the Secure ROM. Contents include:
133+
The contents of this first stage image are authenticated and decrypted by
134+
the Secure ROM. Contents include:
132135

133136
* `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.
134137
* BL-1: The pre-bootloader executed on the A53 core, initializes the console and DDR for the 2nd phase of the boot.
@@ -212,84 +215,98 @@ Secure Boot Flow
212215
213216
.. rubric:: U-Boot
214217

215-
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
216-
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>`__
218+
The boot flow continues as it does on a non-secure device, until loading the
219+
next FIT image named :file:`fitImage`. This FIT image includes the Linux
220+
kernel, DTB, and other required boot artifacts. U-Boot verifies the signed
221+
images on boot independently, without using TIFS. U-Boot extracts each
222+
component from the FIT image and verifies its signature. Once U-Boot verifies
223+
all components, it starts Linux. For more information, see:
224+
`U-Boot FIT Signature Documentation <https://docs.u-boot.org/en/latest/usage/fit/signature.html>`__
217225

218-
U-boot's output will be similar to this:
226+
U-Boot's output will be similar to this:
219227

220228
.. code-block:: console
221229
222-
U-Boot 2021.01-g2de57d278b (May 16 2022 - 14:28:40 +0000)
223-
224-
SoC: AM64X SR1.0
225-
Model: Texas Instruments AM642 EVM
226-
Board: AM64-GPEVM rev A
227-
DRAM: 2 GiB
228-
NAND: 0 MiB
229-
MMC: mmc@fa10000: 0, mmc@fa00000: 1
230-
Loading Environment from FAT... *** Warning - bad CRC, using default environment
231-
232-
In: serial@2800000
233-
Out: serial@2800000
234-
Err: serial@2800000
235-
Net: eth0: ethernet@8000000port@1
236-
Hit any key to stop autoboot: 0
237-
switch to partitions #0, OK
238-
mmc1 is current device
239-
SD/MMC found on device 1
240-
Failed to load 'boot.scr'
241-
1011 bytes read in 2 ms (493.2 KiB/s)
242-
Loaded env from uEnv.txt
243-
Importing environment from mmc1 ...
244-
Running uenvcmd ...
245-
7862647 bytes read in 328 ms (22.9 MiB/s)
246-
## Loading kernel from FIT Image at 90000000 ...
247-
Using 'k3-am642-evm.dtb' configuration
248-
Trying 'kernel@1' kernel subimage
249-
Description: Linux kernel
250-
Type: Kernel Image
251-
Compression: gzip compressed
252-
Data Start: 0x900000f8
253-
Data Size: 7743643 Bytes = 7.4 MiB
254-
Architecture: AArch64
255-
OS: Linux
256-
Load Address: 0x80080000
257-
Entry Point: 0x80080000
258-
Verifying Hash Integrity ... OK
259-
## Loading fdt from FIT Image at 90000000 ...
260-
Using 'k3-am642-evm.dtb' configuration
261-
Trying 'k3-am642-evm.dtb' fdt subimage
262-
Description: Flattened Device Tree blob
263-
Type: Flat Device Tree
264-
Compression: uncompressed
265-
Data Start: 0x90762a54
266-
Data Size: 56436 Bytes = 55.1 KiB
267-
Architecture: AArch64
268-
Load Address: 0x83000000
269-
Verifying Hash Integrity ... OK
270-
Loading fdt from 0x90762a54 to 0x83000000
271-
Booting using the fdt blob at 0x83000000
272-
Uncompressing Kernel Image
273-
Loading Device Tree to 000000008ffef000, end 000000008ffff602 ... OK
230+
U-Boot 2021.01-g2de57d278b (May 16 2022 - 14:28:40 +0000)
231+
232+
SoC: AM64X SR1.0
233+
Model: Texas Instruments AM642 EVM
234+
Board: AM64-GPEVM rev A
235+
DRAM: 2 GiB
236+
NAND: 0 MiB
237+
MMC: mmc@fa10000: 0, mmc@fa00000: 1
238+
Loading Environment from FAT... *** Warning - bad CRC, using default environment
239+
240+
In: serial@2800000
241+
Out: serial@2800000
242+
Err: serial@2800000
243+
Net: eth0: ethernet@8000000port@1
244+
Hit any key to stop autoboot: 0
245+
switch to partitions #0, OK
246+
mmc1 is current device
247+
SD/MMC found on device 1
248+
Failed to load 'boot.scr'
249+
1011 bytes read in 2 ms (493.2 KiB/s)
250+
Loaded env from uEnv.txt
251+
Importing environment from mmc1 ...
252+
Running uenvcmd ...
253+
7862647 bytes read in 328 ms (22.9 MiB/s)
254+
## Loading kernel from FIT Image at 90000000 ...
255+
Using 'k3-am642-evm.dtb' configuration
256+
Trying 'kernel@1' kernel subimage
257+
Description: Linux kernel
258+
Type: Kernel Image
259+
Compression: gzip compressed
260+
Data Start: 0x900000f8
261+
Data Size: 7743643 Bytes = 7.4 MiB
262+
Architecture: AArch64
263+
OS: Linux
264+
Load Address: 0x80080000
265+
Entry Point: 0x80080000
266+
Verifying Hash Integrity ... OK
267+
## Loading fdt from FIT Image at 90000000 ...
268+
Using 'k3-am642-evm.dtb' configuration
269+
Trying 'k3-am642-evm.dtb' fdt subimage
270+
Description: Flattened Device Tree blob
271+
Type: Flat Device Tree
272+
Compression: uncompressed
273+
Data Start: 0x90762a54
274+
Data Size: 56436 Bytes = 55.1 KiB
275+
Architecture: AArch64
276+
Load Address: 0x83000000
277+
Verifying Hash Integrity ... OK
278+
Loading fdt from 0x90762a54 to 0x83000000
279+
Booting using the fdt blob at 0x83000000
280+
Uncompressing Kernel Image
281+
Loading Device Tree to 000000008ffef000, end 000000008ffff602 ... OK
274282
275283
.. rubric:: Linux
276284

277-
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
278-
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
279-
any changes to this block-device will cause the authentication to fail, we cannot put any user-modifiable configurations or user installed programs
280-
here. Only important, read-only, files should be placed on this partition, such as static kernel and operating system files and configurations. All
281-
other files must be placed in a non-verifiable read-write user partition.
285+
If initramfs is included, we can trust our initial modules and tasks, but we
286+
cannot trust anything beyond this as the root file-system may have been
287+
modified. To allow trusted use of files outside of our initramfs we use
288+
dm-verity. With this we can authenticate a block device as we read from it. As
289+
any changes to this block-device will cause the authentication to fail, we
290+
cannot put any user-modifiable configurations or user installed programs here.
291+
Only important, read-only, files should be placed on this partition, such as
292+
static kernel and operating system files and configurations. All other files
293+
must be placed in a non-verifiable read/write user partition.
282294

283295
HS Boot Flow Tools
284296
-------------------
285297

286-
U-boot:
298+
U-Boot:
287299

288300
.. ifconfig:: CONFIG_part_variant not in ('AM62LX')
289301

290-
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
291-
binman packages it in a `tiboot3.bin` image. To build A53 SPL, binman takes TF-A (bl31.bin), OPTEE (bl32.bin), A53 SPL, and A53 DTBs and packages
292-
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.
302+
The ti-u-boot source is a project used to create :file:`tiboot3.bin`,
303+
:file:`tispl.bin`, and :file:`u-boot.img`. To create :file:`tiboot3.bin`
304+
for K3 family devices, U-Boot builds R5 SPL and binman packages it in a
305+
:file:`tiboot3.bin` image. To build A53 SPL, binman takes TF-A
306+
(:file:`bl31.bin`), OPTEE (:file:`bl32.bin`), A53 SPL, and A53 DTBs and
307+
packages them in a :file:`tispl.bin` image. U-Boot can then use the
308+
openssl library to sign each component as specified in
309+
:file:`k3-<soc>-binman.dtsi`.
293310

294311
.. code-block:: console
295312
@@ -320,47 +337,57 @@ U-boot:
320337
321338
Linux:
322339

323-
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
324-
`fitImage`. For HS devices, only the fitImage will be allowed to boot once `fitImage` has been authenticated.
340+
The ti-linux source is a TI project used to build Linux kernel, DTB, and
341+
other boot artifacts. Some of these components could be included in a
342+
verifiable image :file:`fitImage`. For HS devices, only the fitImage will be
343+
allowed to boot once :file:`fitImage` has been authenticated.
325344

326-
.. code-block:: console
345+
.. code-block:: console
327346
328-
$ git clone https://git.ti.com/git/ti-linux-kernel/ti-linux-kernel.git
347+
$ git clone https://git.ti.com/git/ti-linux-kernel/ti-linux-kernel.git
329348
330-
Example use:
331-
$ make ARCH=arm64 CROSS_COMPILE=aarch64-none-linux-gnu- defconfig ti_arm64_prune.config
332-
$ make ARCH=arm64 CROSS_COMPILE=aarch64-none-linux-gnu- menuconfig
333-
$ make ARCH=arm64 CROSS_COMPILE=aarch64-none-linux-gnu-
349+
$ #Example use:
350+
$ make ARCH=arm64 CROSS_COMPILE=aarch64-none-linux-gnu- defconfig ti_arm64_prune.config
351+
$ make ARCH=arm64 CROSS_COMPILE=aarch64-none-linux-gnu- menuconfig
352+
$ make ARCH=arm64 CROSS_COMPILE=aarch64-none-linux-gnu-
334353
335-
ATF:
354+
TF-A:
336355

337-
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.
356+
The TF-A source (formerly called ATF) is used to build :file:`bl31.bin` that
357+
gets packaged into :file:`tispl.bin`. For HS devices, this binary needs to
358+
be signed.
338359

339-
.. code-block:: console
360+
.. code-block:: console
340361
341-
$ git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
362+
$ git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
342363
343-
Example use:
344-
$ make ARCH=aarch64 CROSS_COMPILE=aarch64-none-linux-gnu- PLAT=k3 TARGET_BOARD=lite SPD=opteed
364+
$ # Example use:
365+
$ make ARCH=aarch64 CROSS_COMPILE=aarch64-none-linux-gnu- PLAT=k3 TARGET_BOARD=lite SPD=opteed
345366
346367
OPTEE:
347368

348-
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.
369+
The OPTEE source is used to build :file:`bl32.bin/tee-pager_v2.bin` that
370+
gets packaged into :file:`tispl.bin`. For HS devices, this binary needs to
371+
be signed.
349372

350-
.. code-block:: console
373+
.. code-block:: console
351374
352-
$ git clone https://github.com/OP-TEE/optee_os.git
375+
$ git clone https://github.com/OP-TEE/optee_os.git
353376
354-
Example use:
355-
$ make CROSS_COMPILE64=aarch64-linux-gnu- PLATFORM=k3-<soc> CFG_ARM64_core=y
377+
$ # Example use:
378+
$ make CROSS_COMPILE64=aarch64-linux-gnu- PLATFORM=k3-<soc> CFG_ARM64_core=y
356379
357380
Ti-linux-firmware:
358381

359-
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
360-
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:
361-
BINMAN_INDIRS=<path-to-tisdk>/board-support/prebuilt-images, and expects to find a ti-sysfw directory in this path.
382+
The ti-linux-firmware is a TI repository where all firmware releases are
383+
stored. Firmwares for a device family can also be found in the pre-built SDK
384+
under :file:`<path-to-tisdk>/board-support/prebuilt-images/<evm>`. Binman
385+
expects to find the device firmware with the following appended to U-Boot
386+
build command:
387+
:code:`BINMAN_INDIRS=<path-to-tisdk>/board-support/prebuilt-images`, and
388+
expects to find a ti-sysfw directory in this path.
362389

363-
.. code-block:: console
390+
.. code-block:: console
364391
365-
$ <https://git.ti.com/git/processor-firmware/ti-linux-firmware.git
366-
Branch: ti-linux-firmware.
392+
$ git clone https://git.ti.com/git/processor-firmware/ti-linux-firmware.git
393+
Branch: ti-linux-firmware.

0 commit comments

Comments
 (0)