1.. SPDX-License-Identifier: GPL-2.0+
2
3U-Boot Verified Boot
4====================
5
6Introduction
7------------
8
9Verified boot here means the verification of all software loaded into a
10machine during the boot process to ensure that it is authorised and correct
11for that machine.
12
13Verified boot extends from the moment of system reset to as far as you wish
14into the boot process. An example might be loading U-Boot from read-only
15memory, then loading a signed kernel, then using the kernel's dm-verity
16driver to mount a signed root filesystem.
17
18A key point is that it is possible to field-upgrade the software on machines
19which use verified boot. Since the machine will only run software that has
20been correctly signed, it is safe to read software from an updatable medium.
21It is also possible to add a secondary signed firmware image, in read-write
22memory, so that firmware can easily be upgraded in a secure manner.
23
24
25Signing
26-------
27
28Verified boot uses cryptographic algorithms to 'sign' software images.
29Images are signed using a private key known only to the signer, but can
30be verified using a public key. As its name suggests the public key can be
31made available without risk to the verification process. The private and
32public keys are mathematically related. For more information on how this
33works look up "public key cryptography" and "RSA" (a particular algorithm).
34
35The signing and verification process looks something like this::
36
37
38          Signing                                      Verification
39          =======                                      ============
40
41      +--------------+                 *
42      | RSA key pair |                 *             +---------------+
43      | .key  .crt   |                 *             | Public key in |
44      +--------------+     +------> public key ----->| trusted place |
45            |              |           *             +---------------+
46            |              |           *                    |
47            v              |           *                    v
48       +---------+         |           *             +--------------+
49       |         |---------+           *             |              |
50       | signer  |                     *             |    U-Boot    |
51       |         |---------+           *             |  signature   |--> yes/no
52       +---------+         |           *             | verification |
53            ^              |           *             |              |
54            |              |           *             +--------------+
55            |              |           *                    ^
56       +----------+        |           *                    |
57       | Software |        +----> signed image -------------+
58       |  image   |                    *
59       +----------+                    *
60
61
62The signature algorithm relies only on the public key to do its work. Using
63this key it checks the signature that it finds in the image. If it verifies
64then we know that the image is OK.
65
66The public key from the signer allows us to verify and therefore trust
67software from updatable memory.
68
69It is critical that the public key be secure and cannot be tampered with.
70It can be stored in read-only memory, or perhaps protected by other on-chip
71crypto provided by some modern SOCs. If the public key can be changed, then
72the verification is worthless.
73
74
75Chaining Images
76---------------
77
78The above method works for a signer providing images to a run-time U-Boot.
79It is also possible to extend this scheme to a second level, like this:
80
81#. Master private key is used by the signer to sign a first-stage image.
82#. Master public key is placed in read-only memory.
83#. Secondary private key is created and used to sign second-stage images.
84#. Secondary public key is placed in first stage images
85#. We use the master public key to verify the first-stage image. We then
86   use the secondary public key in the first-stage image to verify the second-
87   state image.
88#. This chaining process can go on indefinitely. It is recommended to use a
89   different key at each stage, so that a compromise in one place will not
90   affect the whole change.
91
92
93Flattened Image Tree (FIT)
94--------------------------
95
96The FIT format is already widely used in U-Boot. It is a flattened device
97tree (FDT) in a particular format, with images contained within. FITs
98include hashes to verify images, so it is relatively straightforward to
99add signatures as well.
100
101The public key can be stored in U-Boot's CONFIG_OF_CONTROL device tree in
102a standard place. Then when a FIT is loaded it can be verified using that
103public key. Multiple keys and multiple signatures are supported.
104
105See :doc:`signature` for more information.
106
107.. sectionauthor:: Simon Glass <sjg@chromium.org> 1-1-13
108