Skip to content

Commit 33ce80a

Browse files
Pratham-TPratham-T
committed
feat(linux): Add secure boot using U-Boot verified boot for AM62LX
Add a new page in the U-Boot user guide documenting secure boot enablement using U-Boot's verified boot framework in AM62LX. For AM62LX, u-boot.img signing and verification has been moved to leverage the mechanisms provided in U-Boot from using HSM core in other K3 devices. This page aims to address this change in AM62LX. Signed-off-by: T Pratham <t-pratham@ti.com>
1 parent c98741c commit 33ce80a

4 files changed

Lines changed: 146 additions & 3 deletions

File tree

‎configs/AM62LX/AM62LX_linux_toc.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ linux/Foundational_Components/U-Boot/UG-Memory-K3
3737
linux/Foundational_Components/U-Boot/UG-UMS
3838
linux/Foundational_Components/U-Boot/UG-QSPI
3939
linux/Foundational_Components/U-Boot/UG-UART
40+
linux/Foundational_Components/U-Boot/UG-Secure-Boot
4041
linux/Foundational_Components/U-Boot/UG-Key-Writer-Lite
4142
linux/Foundational_Components/U-Boot/UG-Programming-OTPs
4243

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

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
.. _u-boot-secure-boot-verified-boot:
2+
3+
################################################
4+
Secure boot using U-Boot verified boot framework
5+
################################################
6+
7+
The complete Secure Boot documentation is available at:
8+
:ref:`foundational-secure-boot`. This page specifically covers the
9+
authentication and verification of U-Boot image using `U-Boot Verified Boot`_.
10+
11+
On most other K3 devices, signing and verification of all boot binaries takes
12+
place in the Hardware Security Module (HSM). Thereafter, U-Boot hands off the
13+
secure chain of trust to the Linux kernel :file:`fitImage`.
14+
15+
On AM62Lx, we have transitioned to use the native U-Boot secure boot framework
16+
for a part of this chain of trust. The U-Boot documentation covers more theory
17+
on this at
18+
`U-Boot Verified Boot <https://docs.u-boot.org/en/latest/usage/fit/verified-boot.html>`_
19+
and `U-Boot FIT Signature Verification <https://docs.u-boot.org/en/latest/usage/fit/signature.html#signed-configurations>`__.
20+
The thing to note is, we are applying the same concepts to U-Boot Flattened
21+
Image Tree (FIT) as the kernel FIT examples in the preceding links.
22+
23+
The HSM still handles the verification of :file:`tiboot3.bin` and
24+
:file:`tispl.bin`. However, we hand off the chain of trust to U-Boot just after
25+
this. The :file:`u-boot.img` is a signed FIT image. The U-Boot Secondary
26+
Program Loader (SPL) binary embeds the public key derived from the private key
27+
used to sign the U-Boot FIT. The U-Boot SPL uses this to verify the
28+
authenticity of the loaded U-Boot binary.
29+
30+
**************
31+
The FIT source
32+
**************
33+
34+
The U-Boot FIT configuration node contains a signature sub-node.
35+
36+
.. code-block:: dts
37+
38+
conf-0 {
39+
description = "k3-am62lx-evm";
40+
firmware = "uboot";
41+
loadables = "uboot";
42+
fdt = "fdt-0";
43+
44+
signature {
45+
algo = "sha512,rsa4096";
46+
key-name-hint = "custMpk";
47+
sign-images = "firmware", "loadables", "fdt";
48+
};
49+
};
50+
51+
It specifies the key name and algorithm to use for signing, and the images
52+
to sign.
53+
54+
The public key is similarly embedded into U-Boot SPL by using a binman property
55+
called :code:`u-boot-spl-pubkey-dtb`. This handles the heavy lifting of calling
56+
the appropriate :code:`mkimage` commands and packing the public key in the SPL
57+
Device Tree Blob (DTB) correctly.
58+
59+
.. code-block:: dts
60+
61+
tispl.bin {
62+
63+
...
64+
65+
spl: section {
66+
u-boot-spl-nodtb {
67+
};
68+
69+
u-boot-spl-pubkey-dtb {
70+
algo = "sha512,rsa4096";
71+
required = "conf";
72+
key-name-hint = "custMpk";
73+
};
74+
};
75+
};
76+
77+
The :code:`key-name-hint` property in both these nodes searches for the
78+
:file:`custMpk.key` private key and :file:`custMpk.crt` public key certificate
79+
in the directories defined in the :code:`BINMAN_INDIRS` variable. The default
80+
TI dummy keys reside in :file:`arch/arm/mach-k3/keys/`, and binman copies them
81+
at the start of the build into the build directory:
82+
83+
.. code-block:: dts
84+
85+
custMpk-crt {
86+
filename = "custMpk.crt";
87+
88+
custmpk_crt: blob-ext {
89+
filename = "arch/arm/mach-k3/keys/custMpk.crt";
90+
};
91+
};
92+
93+
custMpk-key {
94+
filename = "custMpk.key";
95+
96+
custmpk_key: blob-ext {
97+
filename = "arch/arm/mach-k3/keys/custMpk.key";
98+
};
99+
};
100+
101+
********************
102+
Runtime verification
103+
********************
104+
105+
At runtime during device boot, U-Boot SPL loads the :file:`u-boot.img` and then
106+
verifies the FIT signature using the public key it has in its DTB. If the
107+
verification passes, boot continues. Otherwise, the boot is aborted.
108+
109+
***********************
110+
Changing the dummy keys
111+
***********************
112+
113+
The SDKs use the TI dummy key for signing the U-Boot FIT image. But you may
114+
want to use your own key for testing and production. For this, replace the
115+
:file:`arch/arm/mach-k3/keys/custMpk.key` and
116+
:file:`arch/arm/mach-k3/keys/custMpk.crt` with your own key and crt files. The
117+
filenames need to be the same.
118+
119+
It is also possible to use your own keys located at a different location. You
120+
need to change the complete path in the :code:`filename` property above in
121+
:code:`custMpk-crt` and :code:`custMpk-key` in
122+
:file:`arch/arm/dts/k3-am62l3-evm-binman.dtsi` to your .crt and .key files.
123+
124+
After either of the above changes, the U-Boot needs to be built again to get
125+
the signed binaries with the updated keys. Refer to :ref:`top-level-makefile`.
126+
127+
.. note::
128+
129+
Generating a new set of keys:
130+
131+
.. code-block:: console
132+
133+
$ mkdir keys
134+
$ cd keys
135+
$ # Generate an RSA private key:
136+
$ openssl genpkey -algorithm RSA -out custMpk.key \
137+
-pkeyopt rsa_keygen_bits:4096 -pkeyopt rsa_keygen_pubexp:65537
138+
$ # Build your cert template (Enter necessary details in the prompts that follow):
139+
$ openssl req -new -key custMpk.key -out cert.csr
140+
$ # Self-sign the certificate
141+
$ openssl x509 -req -days 3650 -in cert.csr -signkey custMpk.key -out custMpk.crt

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ User's Guide
3131
UG-AVS
3232
UG-Thermal
3333
UG-Splash-Screen
34+
UG-Secure-Boot
3435
UG-Key-Writer-Lite
3536
UG-Programming-OTPs
3637
UG-Falcon-Mode

‎source/linux/Foundational_Components_Secure_Boot.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,9 +35,9 @@ The following is an example list where Chain-of-Trust should be maintained.
3535
.. ifconfig:: CONFIG_part_variant in ('AM62LX')
3636

3737
The U-Boot's Secondary Program Loader (SPL) securely verifies the U-Boot
38-
proper. U-Boot uses its verified boot framework to do this. U-Boot proper
39-
then securely verifies and decrypts the kernel, Device Tree Blobs (DTB),
40-
and initramfs.
38+
proper. U-Boot uses its verified boot framework to do this
39+
(See: :ref:`u-boot-secure-boot-verified-boot`). U-Boot proper then securely
40+
verifies and decrypts the kernel, Device Tree Blobs (DTB), and initramfs.
4141

4242
.. Image:: /images/AM62L_KF.png
4343
:scale: 70%

0 commit comments

Comments
 (0)