Bring these files into the documentation.
Fix 'wtih' and 'it' typos and repeated 'could' while we are here.
Signed-off-by: Simon Glass <s...@chromium.org>
---
doc/uImage.FIT/beaglebone_vboot.txt | 607 --------------
doc/uImage.FIT/signature.txt | 707 ----------------
doc/usage/cmd/source.rst | 2 +-
doc/usage/fit/beaglebone_vboot.rst | 607 ++++++++++++++
doc/usage/fit/index.rst | 3 +
doc/usage/fit/signature.rst | 760 ++++++++++++++++++
.../fit/verified-boot.rst} | 83 +-
7 files changed, 1414 insertions(+), 1355 deletions(-)
delete mode 100644 doc/uImage.FIT/beaglebone_vboot.txt
delete mode 100644 doc/uImage.FIT/signature.txt
create mode 100644 doc/usage/fit/beaglebone_vboot.rst
create mode 100644 doc/usage/fit/signature.rst
rename doc/{uImage.FIT/verified-boot.txt => usage/fit/verified-boot.rst} (54%)
diff --git a/doc/uImage.FIT/beaglebone_vboot.txt
b/doc/uImage.FIT/beaglebone_vboot.txt
deleted file mode 100644
index ebd2068ed38d..000000000000
--- a/doc/uImage.FIT/beaglebone_vboot.txt
+++ /dev/null
@@ -1,607 +0,0 @@
-Verified Boot on the Beaglebone Black
-=====================================
-
-Introduction
-------------
-
-Before reading this, please read verified-boot.txt and signature.txt. These
-instructions are for mainline U-Boot from v2014.07 onwards.
-
-There is quite a bit of documentation in this directory describing how
-verified boot works in U-Boot. There is also a test which runs through the
-entire process of signing an image and running U-Boot (sandbox) to check it.
-However, it might be useful to also have an example on a real board.
-
-Beaglebone Black is a fairly common board so seems to be a reasonable choice
-for an example of how to enable verified boot using U-Boot.
-
-First a note that may to help avoid confusion. U-Boot and Linux both use
-device tree. They may use the same device tree source, but it is seldom useful
-for them to use the exact same binary from the same place. More typically,
-U-Boot has its device tree packaged wtih it, and the kernel's device tree is
-packaged with the kernel. In particular this is important with verified boot,
-since U-Boot's device tree must be immutable. If it can be changed then the
-public keys can be changed and verified boot is useless. An attacker can
-simply generate a new key and put his public key into U-Boot so that
-everything verifies. On the other hand the kernel's device tree typically
-changes when the kernel changes, so it is useful to package an updated device
-tree with the kernel binary. U-Boot supports the latter with its flexible FIT
-format (Flat Image Tree).
-
-
-Overview
---------
-
-The steps are roughly as follows:
-
-1. Build U-Boot for the board, with the verified boot options enabled.
-
-2. Obtain a suitable Linux kernel
-
-3. Create a Image Tree Source file (ITS) file describing how you want the
-kernel to be packaged, compressed and signed.
-
-4. Create a key pair
-
-5. Sign the kernel
-
-6. Put the public key into U-Boot's image
-
-7. Put U-Boot and the kernel onto the board
-
-8. Try it
-
-
-Step 1: Build U-Boot
---------------------
-
-a. Set up the environment variable to point to your toolchain. You will need
-this for U-Boot and also for the kernel if you build it. For example if you
-installed a Linaro version manually it might be something like:
-
- export
CROSS_COMPILE=/opt/linaro/gcc-linaro-arm-linux-gnueabihf-4.8-2013.08_linux/bin/arm-linux-gnueabihf-
-
-or if you just installed gcc-arm-linux-gnueabi then it might be
-
- export CROSS_COMPILE=arm-linux-gnueabi-
-
-b. Configure and build U-Boot with verified boot enabled:
-
- export UBOOT=/path/to/u-boot
- cd $UBOOT
- # You can add -j10 if you have 10 CPUs to make it faster
- make O=b/am335x_boneblack_vboot am335x_boneblack_vboot_config all
- export UOUT=$UBOOT/b/am335x_boneblack_vboot
-
-c. You will now have a U-Boot image:
-
- file b/am335x_boneblack_vboot/u-boot-dtb.img
-b/am335x_boneblack_vboot/u-boot-dtb.img: u-boot legacy uImage, U-Boot
2014.07-rc2-00065-g2f69f8, Firmware/ARM, Firmware Image (Not compressed),
395375 bytes, Sat May 31 16:19:04 2014, Load Address: 0x80800000, Entry Point:
0x00000000, Header CRC: 0x0ABD6ACA, Data CRC: 0x36DEF7E4
-
-
-Step 2: Build Linux
---------------------
-
-a. Find the kernel image ('Image') and device tree (.dtb) file you plan to
-use. In our case it is am335x-boneblack.dtb and it is built with the kernel.
-At the time of writing an SD Boot image can be obtained from here:
-
-
http://www.elinux.org/Beagleboard:Updating_The_Software#Image_For_Booting_From_microSD
-
-You can write this to an SD card and then mount it to extract the kernel and
-device tree files.
-
-You can also build a kernel. Instructions for this are are here:
-
- http://elinux.org/Building_BBB_Kernel
-
-or you can use your favourite search engine. Following these instructions
-produces a kernel Image and device tree files. For the record the steps were:
-
- export KERNEL=/path/to/kernel
- cd $KERNEL
- git clone git://github.com/beagleboard/kernel.git .
- git checkout v3.14
- ./patch.sh
- cp configs/beaglebone kernel/arch/arm/configs/beaglebone_defconfig
- cd kernel
- make beaglebone_defconfig
- make uImage dtbs # -j10 if you have 10 CPUs
- export OKERNEL=$KERNEL/kernel/arch/arm/boot
-
-c. You now have the 'Image' and 'am335x-boneblack.dtb' files needed to boot.
-
-
-Step 3: Create the ITS
-----------------------
-
-Set up a directory for your work.
-
- export WORK=/path/to/dir
- cd $WORK
-
-Put this into a file in that directory called sign.its:
-
-/dts-v1/;
-
-/ {
- description = "Beaglebone black";
- #address-cells = <1>;
-
- images {
- kernel {
- data = /incbin/("Image.lzo");
- type = "kernel";
- arch = "arm";
- os = "linux";
- compression = "lzo";
- load = <0x80008000>;
- entry = <0x80008000>;
- hash-1 {
- algo = "sha1";
- };
- };
- fdt-1 {
- description = "beaglebone-black";
- data = /incbin/("am335x-boneblack.dtb");
- type = "flat_dt";
- arch = "arm";
- compression = "none";
- hash-1 {
- algo = "sha1";
- };
- };
- };
- configurations {
- default = "conf-1";
- conf-1 {
- kernel = "kernel";
- fdt = "fdt-1";
- signature-1 {
- algo = "sha1,rsa2048";
- key-name-hint = "dev";
- sign-images = "fdt", "kernel";
- };
- };
- };
-};
-
-
-The explanation for this is all in the documentation you have already read.
-But briefly it packages a kernel and device tree, and provides a single
-configuration to be signed with a key named 'dev'. The kernel is compressed
-with LZO to make it smaller.
-
-
-Step 4: Create a key pair
--------------------------
-
-See signature.txt for details on this step.
-
- cd $WORK
- mkdir keys
- openssl genrsa -F4 -out keys/dev.key 2048
- openssl req -batch -new -x509 -key keys/dev.key -out keys/dev.crt
-
-Note: keys/dev.key contains your private key and is very secret. If anyone
-gets access to that file they can sign kernels with it. Keep it secure.
-
-
-Step 5: Sign the kernel
------------------------
-
-We need to use mkimage (which was built when you built U-Boot) to package the
-Linux kernel into a FIT (Flat Image Tree, a flexible file format that U-Boot
-can load) using the ITS file you just created.
-
-At the same time we must put the public key into U-Boot device tree, with the
-'required' property, which tells U-Boot that this key must be verified for the
-image to be valid. You will make this key available to U-Boot for booting in
-step 6.
-
- ln -s $OKERNEL/dts/am335x-boneblack.dtb
- ln -s $OKERNEL/Image
- ln -s $UOUT/u-boot-dtb.img
- cp $UOUT/arch/arm/dts/am335x-boneblack.dtb am335x-boneblack-pubkey.dtb
- lzop Image
- $UOUT/tools/mkimage -f sign.its -K am335x-boneblack-pubkey.dtb -k keys -r
image.fit
-
-You should see something like this:
-
-FIT description: Beaglebone black
-Created: Sun Jun 1 12:50:30 2014
- Image 0 (kernel)
- Description: unavailable
- Created: Sun Jun 1 12:50:30 2014
- Type: Kernel Image
- Compression: lzo compressed
- Data Size: 7790938 Bytes = 7608.34 kB = 7.43 MB
- Architecture: ARM
- OS: Linux
- Load Address: 0x80008000
- Entry Point: 0x80008000
- Hash algo: sha1
- Hash value: c94364646427e10f423837e559898ef02c97b988
- Image 1 (fdt-1)
- Description: beaglebone-black
- Created: Sun Jun 1 12:50:30 2014
- Type: Flat Device Tree
- Compression: uncompressed
- Data Size: 31547 Bytes = 30.81 kB = 0.03 MB
- Architecture: ARM
- Hash algo: sha1
- Hash value: cb09202f889d824f23b8e4404b781be5ad38a68d
- Default Configuration: 'conf-1'
- Configuration 0 (conf-1)
- Description: unavailable
- Kernel: kernel
- FDT: fdt-1
-
-
-Now am335x-boneblack-pubkey.dtb contains the public key and image.fit contains
-the signed kernel. Jump to step 6 if you like, or continue reading to increase
-your understanding.
-
-You can also run fit_check_sign to check it:
-
- $UOUT/tools/fit_check_sign -f image.fit -k am335x-boneblack-pubkey.dtb
-
-which results in:
-
-Verifying Hash Integrity ... sha1,rsa2048:dev+
-## Loading kernel from FIT Image at 7fc6ee469000 ...
- Using 'conf-1' configuration
- Verifying Hash Integrity ...
-sha1,rsa2048:dev+
-OK
-
- Trying 'kernel' kernel subimage
- Description: unavailable
- Created: Sun Jun 1 12:50:30 2014
- Type: Kernel Image
- Compression: lzo compressed
- Data Size: 7790938 Bytes = 7608.34 kB = 7.43 MB
- Architecture: ARM
- OS: Linux
- Load Address: 0x80008000
- Entry Point: 0x80008000
- Hash algo: sha1
- Hash value: c94364646427e10f423837e559898ef02c97b988
- Verifying Hash Integrity ...
-sha1+
-OK
-
-Unimplemented compression type 4
-## Loading fdt from FIT Image at 7fc6ee469000 ...
- Using 'conf-1' configuration
- Trying 'fdt-1' fdt subimage
- Description: beaglebone-black
- Created: Sun Jun 1 12:50:30 2014
- Type: Flat Device Tree
- Compression: uncompressed
- Data Size: 31547 Bytes = 30.81 kB = 0.03 MB
- Architecture: ARM
- Hash algo: sha1
- Hash value: cb09202f889d824f23b8e4404b781be5ad38a68d
- Verifying Hash Integrity ...
-sha1+
-OK
-
- Loading Flat Device Tree ... OK
-
-## Loading ramdisk from FIT Image at 7fc6ee469000 ...
- Using 'conf-1' configuration
-Could not find subimage node
-
-Signature check OK
-
-
-At the top, you see "sha1,rsa2048:dev+". This means that it checked an RSA key
-of size 2048 bits using SHA1 as the hash algorithm. The key name checked was
-'dev' and the '+' means that it verified. If it showed '-' that would be bad.
-
-Once the configuration is verified it is then possible to rely on the hashes
-in each image referenced by that configuration. So fit_check_sign goes on to
-load each of the images. We have a kernel and an FDT but no ramkdisk. In each
-case fit_check_sign checks the hash and prints sha1+ meaning that the SHA1
-hash verified. This means that none of the images has been tampered with.
-
-There is a test in test/vboot which uses U-Boot's sandbox build to verify that
-the above flow works.
-
-But it is fun to do this by hand, so you can load image.fit into a hex editor
-like ghex, and change a byte in the kernel:
-
- $UOUT/tools/fit_info -f image.fit -n /images/kernel -p data
-NAME: kernel
-LEN: 7790938
-OFF: 168
-
-This tells us that the kernel starts at byte offset 168 (decimal) in image.fit
-and extends for about 7MB. Try changing a byte at 0x2000 (say) and run
-fit_check_sign again. You should see something like:
-
-Verifying Hash Integrity ... sha1,rsa2048:dev+
-## Loading kernel from FIT Image at 7f5a39571000 ...
- Using 'conf-1' configuration
- Verifying Hash Integrity ...
-sha1,rsa2048:dev+
-OK
-
- Trying 'kernel' kernel subimage
- Description: unavailable
- Created: Sun Jun 1 13:09:21 2014
- Type: Kernel Image
- Compression: lzo compressed
- Data Size: 7790938 Bytes = 7608.34 kB = 7.43 MB
- Architecture: ARM
- OS: Linux
- Load Address: 0x80008000
- Entry Point: 0x80008000
- Hash algo: sha1
- Hash value: c94364646427e10f423837e559898ef02c97b988
- Verifying Hash Integrity ...
-sha1 error
-Bad hash value for 'hash-1' hash node in 'kernel' image node
-Bad Data Hash
-
-## Loading fdt from FIT Image at 7f5a39571000 ...
- Using 'conf-1' configuration
- Trying 'fdt-1' fdt subimage
- Description: beaglebone-black
- Created: Sun Jun 1 13:09:21 2014
- Type: Flat Device Tree
- Compression: uncompressed
- Data Size: 31547 Bytes = 30.81 kB = 0.03 MB
- Architecture: ARM
- Hash algo: sha1
- Hash value: cb09202f889d824f23b8e4404b781be5ad38a68d
- Verifying Hash Integrity ...
-sha1+
-OK
-
- Loading Flat Device Tree ... OK
-
-## Loading ramdisk from FIT Image at 7f5a39571000 ...
- Using 'conf-1' configuration
-Could not find subimage node
-
-Signature check Bad (error 1)
-
-
-It has detected the change in the kernel.
-
-You can also be sneaky and try to switch images, using the libfdt utilities
-that come with dtc (package name is device-tree-compiler but you will need a
-recent version like 1.4:
-
- dtc -v
-Version: DTC 1.4.0
-
-First we can check which nodes are actually hashed by the configuration:
-
- fdtget -l image.fit /
-images
-configurations
-
- fdtget -l image.fit /configurations
-conf-1
-fdtget -l image.fit /configurations/conf-1
-signature-1
-
- fdtget -p image.fit /configurations/conf-1/signature-1
-hashed-strings
-hashed-nodes
-timestamp
-signer-version
-signer-name
-value
-algo
-key-name-hint
-sign-images
-
- fdtget image.fit /configurations/conf-1/signature-1 hashed-nodes
-/ /configurations/conf-1 /images/fdt-1 /images/fdt-1/hash /images/kernel
/images/kernel/hash-1
-
-This gives us a bit of a look into the signature that mkimage added. Note you
-can also use fdtdump to list the entire device tree.
-
-Say we want to change the kernel that this configuration uses
-(/images/kernel). We could just put a new kernel in the image, but we will
-need to change the hash to match. Let's simulate that by changing a byte of
-the hash:
-
- fdtget -tx image.fit /images/kernel/hash-1 value
-c9436464 6427e10f 423837e5 59898ef0 2c97b988
- fdtput -tx image.fit /images/kernel/hash-1 value c9436464 6427e10f
423837e5 59898ef0 2c97b981
-
-Now check it again:
-
- $UOUT/tools/fit_check_sign -f image.fit -k am335x-boneblack-pubkey.dtb
-Verifying Hash Integrity ... sha1,rsa2048:devrsa_verify_with_keynode: RSA
failed to verify: -13
-rsa_verify_with_keynode: RSA failed to verify: -13
--
-Failed to verify required signature 'key-dev'
-Signature check Bad (error 1)
-
-This time we don't even get as far as checking the images, since the
-configuration signature doesn't match. We can't change any hashes without the
-signature check noticing. The configuration is essentially locked. U-Boot has
-a public key for which it requires a match, and will not permit the use of any
-configuration that does not match that public key. The only way the
-configuration will match is if it was signed by the matching private key.
-
-It would also be possible to add a new signature node that does match your new
-configuration. But that won't work since you are not allowed to change the
-configuration in any way. Try it with a fresh (valid) image if you like by
-running the mkimage link again. Then:
-
- fdtput -p image.fit /configurations/conf-1/signature-1 value fred
- $UOUT/tools/fit_check_sign -f image.fit -k am335x-boneblack-pubkey.dtb
-Verifying Hash Integrity ... -
-sha1,rsa2048:devrsa_verify_with_keynode: RSA failed to verify: -13
-rsa_verify_with_keynode: RSA failed to verify: -13
--
-Failed to verify required signature 'key-dev'
-Signature check Bad (error 1)
-
-
-Of course it would be possible to add an entirely new configuration and boot
-with that, but it still needs to be signed, so it won't help.
-
-
-6. Put the public key into U-Boot's image
------------------------------------------
-
-Having confirmed that the signature is doing its job, let's try it out in
-U-Boot on the board. U-Boot needs access to the public key corresponding to
-the private key that you signed with so that it can verify any kernels that
-you sign.
-
- cd $UBOOT
- make O=b/am335x_boneblack_vboot EXT_DTB=${WORK}/am335x-boneblack-pubkey.dtb
-
-Here we are overriding the normal device tree file with our one, which
-contains the public key.
-
-Now you have a special U-Boot image with the public key. It can verify can
-kernel that you sign with the private key as in step 5.
-
-If you like you can take a look at the public key information that mkimage
-added to U-Boot's device tree:
-
- fdtget -p am335x-boneblack-pubkey.dtb /signature/key-dev
-required
-algo
-rsa,r-squared
-rsa,modulus
-rsa,n0-inverse
-rsa,num-bits
-key-name-hint
-
-This has information about the key and some pre-processed values which U-Boot
-can use to verify against it. These values are obtained from the public key
-certificate by mkimage, but require quite a bit of code to generate. To save
-code space in U-Boot, the information is extracted and written in raw form for
-U-Boot to easily use. The same mechanism is used in Google's Chrome OS.
-
-Notice the 'required' property. This marks the key as required - U-Boot will
-not boot any image that does not verify against this key.
-
-
-7. Put U-Boot and the kernel onto the board
--------------------------------------------
-
-The method here varies depending on how you are booting. For this example we
-are booting from an micro-SD card with two partitions, one for U-Boot and one
-for Linux. Put it into your machine and write U-Boot and the kernel to it.
-Here the card is /dev/sde:
-
- cd $WORK
- export UDEV=/dev/sde1 # Change thes two lines to the correct device
- export KDEV=/dev/sde2
- sudo mount $UDEV /mnt/tmp && sudo cp $UOUT/u-boot-dtb.img /mnt/tmp/u-boot.img &&
sleep 1 && sudo umount $UDEV
- sudo mount $KDEV /mnt/tmp && sudo cp $WORK/image.fit /mnt/tmp/boot/image.fit &&
sleep 1 && sudo umount $KDEV
-
-
-8. Try it
----------
-
-Boot the board using the commands below:
-
- setenv bootargs console=ttyO0,115200n8 quiet root=/dev/mmcblk0p2 ro
rootfstype=ext4 rootwait
- ext2load mmc 0:2 82000000 /boot/image.fit
- bootm 82000000
-
-You should then see something like this:
-
-U-Boot# setenv bootargs console=ttyO0,115200n8 quiet root=/dev/mmcblk0p2 ro
rootfstype=ext4 rootwait
-U-Boot# ext2load mmc 0:2 82000000 /boot/image.fit
-7824930 bytes read in 589 ms (12.7 MiB/s)
-U-Boot# bootm 82000000
-## Loading kernel from FIT Image at 82000000 ...
- Using 'conf-1' configuration
- Verifying Hash Integrity ... sha1,rsa2048:dev+ OK
- Trying 'kernel' kernel subimage
- Description: unavailable
- Created: 2014-06-01 19:32:54 UTC
- Type: Kernel Image
- Compression: lzo compressed
- Data Start: 0x820000a8
- Data Size: 7790938 Bytes = 7.4 MiB
- Architecture: ARM
- OS: Linux
- Load Address: 0x80008000
- Entry Point: 0x80008000
- Hash algo: sha1
- Hash value: c94364646427e10f423837e559898ef02c97b988
- Verifying Hash Integrity ... sha1+ OK
-## Loading fdt from FIT Image at 82000000 ...
- Using 'conf-1' configuration
- Trying 'fdt-1' fdt subimage
- Description: beaglebone-black
- Created: 2014-06-01 19:32:54 UTC
- Type: Flat Device Tree
- Compression: uncompressed
- Data Start: 0x8276e2ec
- Data Size: 31547 Bytes = 30.8 KiB
- Architecture: ARM
- Hash algo: sha1
- Hash value: cb09202f889d824f23b8e4404b781be5ad38a68d
- Verifying Hash Integrity ... sha1+ OK
- Booting using the fdt blob at 0x8276e2ec
- Uncompressing Kernel Image ... OK
- Loading Device Tree to 8fff5000, end 8ffffb3a ... OK
-
-Starting kernel ...
-
-[ 0.582377] omap_init_mbox: hwmod doesn't have valid attrs
-[ 2.589651] musb-hdrc musb-hdrc.0.auto: Failed to request rx1.
-[ 2.595830] musb-hdrc musb-hdrc.0.auto: musb_init_controller failed with
status -517
-[ 2.606470] musb-hdrc musb-hdrc.1.auto: Failed to request rx1.
-[ 2.612723] musb-hdrc musb-hdrc.1.auto: musb_init_controller failed with
status -517
-[ 2.940808] drivers/rtc/hctosys.c: unable to open rtc device (rtc0)
-[ 7.248889] libphy: PHY 4a101000.mdio:01 not found
-[ 7.253995] net eth0: phy 4a101000.mdio:01 not found on slave 1
-systemd-fsck[83]: Angstrom: clean, 50607/218160 files, 306348/872448 blocks
-
-.---O---.
-| | .-. o o
-| | |-----.-----.-----.| | .----..-----.-----.
-| | | __ | ---'| '--.| .-'| | |
-| | | | | |--- || --'| | | ' | | | |
-'---'---'--'--'--. |-----''----''--' '-----'-'-'-'
- -' |
- '---'
-
-The Angstrom Distribution beaglebone ttyO0
-
-Angstrom v2012.12 - Kernel 3.14.1+
-
-beaglebone login:
-
-At this point your kernel has been verified and you can be sure that it is one
-that you signed. As an exercise, try changing image.fit as in step 5 and see
-what happens.
-
-
-Further Improvements
---------------------
-
-Several of the steps here can be easily automated. In particular it would be
-capital if signing and packaging a kernel were easy, perhaps a simple make
-target in the kernel.
-
-Some mention of how to use multiple .dtb files in a FIT might be useful.
-
-U-Boot's verified boot mechanism has not had a robust and independent security
-review. Such a review should look at the implementation and its resistance to
-attacks.
-
-Perhaps the verified boot feature could could be integrated into the Amstrom
-distribution.
-
-
-Simon Glass
-s...@chromium.org
-2-June-14
diff --git a/doc/uImage.FIT/signature.txt b/doc/uImage.FIT/signature.txt
deleted file mode 100644
index 21eb3894aada..000000000000
--- a/doc/uImage.FIT/signature.txt
+++ /dev/null
@@ -1,707 +0,0 @@
-U-Boot FIT Signature Verification
-=================================
-
-Introduction
-------------
-FIT supports hashing of images so that these hashes can be checked on
-loading. This protects against corruption of the image. However it does not
-prevent the substitution of one image for another.
-
-The signature feature allows the hash to be signed with a private key such
-that it can be verified using a public key later. Provided that the private
-key is kept secret and the public key is stored in a non-volatile place,
-any image can be verified in this way.
-
-See verified-boot.txt for more general information on verified boot.
-
-
-Concepts
---------
-Some familiarity with public key cryptography is assumed in this section.
-
-The procedure for signing is as follows:
-
- - hash an image in the FIT
- - sign the hash with a private key to produce a signature
- - store the resulting signature in the FIT
-
-The procedure for verification is:
-
- - read the FIT
- - obtain the public key
- - extract the signature from the FIT
- - hash the image from the FIT
- - verify (with the public key) that the extracted signature matches the
- hash
-
-The signing is generally performed by mkimage, as part of making a firmware
-image for the device. The verification is normally done in U-Boot on the
-device.
-
-
-Algorithms
-----------
-In principle any suitable algorithm can be used to sign and verify a hash.
-U-Boot supports a few hashing and verification algorithms. See below for
-details.
-
-While it is acceptable to bring in large cryptographic libraries such as
-openssl on the host side (e.g. mkimage), it is not desirable for U-Boot.
-For the run-time verification side, it is important to keep code and data
-size as small as possible.
-
-For this reason the RSA image verification uses pre-processed public keys
-which can be used with a very small amount of code - just some extraction
-of data from the FDT and exponentiation mod n. Code size impact is a little
-under 5KB on Tegra Seaboard, for example.
-
-It is relatively straightforward to add new algorithms if required. If
-another RSA variant is needed, then it can be added with the
-U_BOOT_CRYPTO_ALGO() macro. If another algorithm is needed (such as DSA) then
-it can be placed in a directory alongside lib/rsa/, and its functions added
-using U_BOOT_CRYPTO_ALGO().
-
-
-Creating an RSA key pair and certificate
-----------------------------------------
-To create a new public/private key pair, size 2048 bits:
-
-$ openssl genpkey -algorithm RSA -out keys/dev.key \
- -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:65537
-
-To create a certificate for this containing the public key:
-
-$ openssl req -batch -new -x509 -key keys/dev.key -out keys/dev.crt
-
-If you like you can look at the public key also:
-
-$ openssl rsa -in keys/dev.key -pubout
-
-
-Device Tree Bindings
---------------------
-The following properties are required in the FIT's signature node(s) to
-allow the signer to operate. These should be added to the .its file.
-Signature nodes sit at the same level as hash nodes and are called
-signature-1, signature-2, etc.
-
-- algo: Algorithm name (e.g. "sha1,rsa2048")
-
-- key-name-hint: Name of key to use for signing. The keys will normally be in
-a single directory (parameter -k to mkimage). For a given key <name>, its
-private key is stored in <name>.key and the certificate is stored in
-<name>.crt.
-
-When the image is signed, the following properties are added (mandatory):
-
-- value: The signature data (e.g. 256 bytes for 2048-bit RSA)
-
-When the image is signed, the following properties are optional:
-
-- timestamp: Time when image was signed (standard Unix time_t format)
-
-- signer-name: Name of the signer (e.g. "mkimage")
-
-- signer-version: Version string of the signer (e.g. "2013.01")
-
-- comment: Additional information about the signer or image
-
-- padding: The padding algorithm, it may be pkcs-1.5 or pss,
- if no value is provided we assume pkcs-1.5
-
-For config bindings (see Signed Configurations below), the following
-additional properties are optional:
-
-- sign-images: A list of images to sign, each being a property of the conf
-node that contains then. The default is "kernel,fdt" which means that these
-two images will be looked up in the config and signed if present.
-
-For config bindings, these properties are added by the signer:
-
-- hashed-nodes: A list of nodes which were hashed by the signer. Each is
- a string - the full path to node. A typical value might be:
-
- hashed-nodes = "/", "/configurations/conf-1", "/images/kernel",
- "/images/kernel/hash-1", "/images/fdt-1",
- "/images/fdt-1/hash-1";
-
-- hashed-strings: The start and size of the string region of the FIT that
- was hashed
-
-Example: See sign-images.its for an example image tree source file and
-sign-configs.its for config signing.
-
-
-Public Key Storage
-------------------
-In order to verify an image that has been signed with a public key we need to
-have a trusted public key. This cannot be stored in the signed image, since
-it would be easy to alter. For this implementation we choose to store the
-public key in U-Boot's control FDT (using CONFIG_OF_CONTROL).
-
-Public keys should be stored as sub-nodes in a /signature node. Required
-properties are:
-
-- algo: Algorithm name (e.g. "sha1,rsa2048" or "sha256,ecdsa256")
-
-Optional properties are:
-
-- key-name-hint: Name of key used for signing. This is only a hint since it
-is possible for the name to be changed. Verification can proceed by checking
-all available signing keys until one matches.
-
-- required: If present this indicates that the key must be verified for the
-image / configuration to be considered valid. Only required keys are
-normally verified by the FIT image booting algorithm. Valid values are
-"image" to force verification of all images, and "conf" to force verification
-of the selected configuration (which then relies on hashes in the images to
-verify those).
-
-Each signing algorithm has its own additional properties.
-
-For RSA the following are mandatory:
-
-- rsa,num-bits: Number of key bits (e.g. 2048)
-- rsa,modulus: Modulus (N) as a big-endian multi-word integer
-- rsa,exponent: Public exponent (E) as a 64 bit unsigned integer
-- rsa,r-squared: (2^num-bits)^2 as a big-endian multi-word integer
-- rsa,n0-inverse: -1 / modulus[0] mod 2^32
-
-For ECDSA the following are mandatory:
-- ecdsa,curve: Name of ECDSA curve (e.g. "prime256v1")
-- ecdsa,x-point: Public key X coordinate as a big-endian multi-word integer
-- ecdsa,y-point: Public key Y coordinate as a big-endian multi-word integer
-
-These parameters can be added to a binary device tree using parameter -K of the
-mkimage command::
-
- tools/mkimage -f fit.its -K control.dtb -k keys -r image.fit
-
-Here is an example of a generated device tree node::
-
- signature {
- key-dev {
- required = "conf";
- algo = "sha256,rsa2048";
- rsa,r-squared = <0xb76d1acf 0xa1763ca5 0xeb2f126
- 0x742edc80 0xd3f42177 0x9741d9d9
- 0x35bb476e 0xff41c718 0xd3801430
- 0xf22537cb 0xa7e79960 0xae32a043
- 0x7da1427a 0x341d6492 0x3c2762f5
- 0xaac04726 0x5b262d96 0xf984e86d
- 0xb99443c7 0x17080c33 0x940f6892
- 0xd57a95d1 0x6ea7b691 0xc5038fa8
- 0x6bb48a6e 0x73f1b1ea 0x37160841
- 0xe05715ce 0xa7c45bbd 0x690d82d5
- 0x99c2454c 0x6ff117b3 0xd830683b
- 0x3f81c9cf 0x1ca38a91 0x0c3392e4
- 0xd817c625 0x7b8e9a24 0x175b89ea
- 0xad79f3dc 0x4d50d7b4 0x9d4e90f8
- 0xad9e2939 0xc165d6a4 0x0ada7e1b
- 0xfb1bf495 0xfc3131c2 0xb8c6e604
- 0xc2761124 0xf63de4a6 0x0e9565f9
- 0xc8e53761 0x7e7a37a5 0xe99dcdae
- 0x9aff7e1e 0xbd44b13d 0x6b0e6aa4
- 0x038907e4 0x8e0d6850 0xef51bc20
- 0xf73c94af 0x88bea7b1 0xcbbb1b30
- 0xd024b7f3>;
- rsa,modulus = <0xc0711d6cb 0x9e86db7f 0x45986dbe
- 0x023f1e8c9 0xe1a4c4d0 0x8a0dfdc9
- 0x023ba0c48 0x06815f6a 0x5caa0654
- 0x07078c4b7 0x3d154853 0x40729023
- 0x0b007c8fe 0x5a3647e5 0x23b41e20
- 0x024720591 0x66915305 0x0e0b29b0
- 0x0de2ad30d 0x8589430f 0xb1590325
- 0x0fb9f5d5e 0x9eba752a 0xd88e6de9
- 0x056b3dcc6 0x9a6b8e61 0x6784f61f
- 0x000f39c21 0x5eec6b33 0xd78e4f78
- 0x0921a305f 0xaa2cc27e 0x1ca917af
- 0x06e1134f4 0xd48cac77 0x4e914d07
- 0x0f707aa5a 0x0d141f41 0x84677f1d
- 0x0ad47a049 0x028aedb6 0xd5536fcf
- 0x03fef1e4f 0x133a03d2 0xfd7a750a
- 0x0f9159732 0xd207812e 0x6a807375
- 0x06434230d 0xc8e22dad 0x9f29b3d6
- 0x07c44ac2b 0xfa2aad88 0xe2429504
- 0x041febd41 0x85d0d142 0x7b194d65
- 0x06e5d55ea 0x41116961 0xf3181dde
- 0x068bf5fbc 0x3dd82047 0x00ee647e
- 0x0d7a44ab3>;
- rsa,exponent = <0x00 0x10001>;
- rsa,n0-inverse = <0xb3928b85>;
- rsa,num-bits = <0x800>;
- key-name-hint = "dev";
- };
- };
-
-
-Signed Configurations
----------------------
-While signing images is useful, it does not provide complete protection
-against several types of attack. For example, it it possible to create a
-FIT with the same signed images, but with the configuration changed such
-that a different one is selected (mix and match attack). It is also possible
-to substitute a signed image from an older FIT version into a newer FIT
-(roll-back attack).
-
-As an example, consider this FIT:
-
-/ {
- images {
- kernel-1 {
- data = <data for kernel1>
- signature-1 {
- algo = "sha1,rsa2048";
- value = <...kernel signature 1...>
- };
- };
- kernel-2 {
- data = <data for kernel2>
- signature-1 {
- algo = "sha1,rsa2048";
- value = <...kernel signature 2...>
- };
- };
- fdt-1 {
- data = <data for fdt1>;
- signature-1 {
- algo = "sha1,rsa2048";
- value = <...fdt signature 1...>
- };
- };
- fdt-2 {
- data = <data for fdt2>;
- signature-1 {
- algo = "sha1,rsa2048";
- value = <...fdt signature 2...>
- };
- };
- };
- configurations {
- default = "conf-1";
- conf-1 {
- kernel = "kernel-1";
- fdt = "fdt-1";
- };
- conf-2 {
- kernel = "kernel-2";
- fdt = "fdt-2";
- };
- };
-};
-
-Since both kernels are signed it is easy for an attacker to add a new
-configuration 3 with kernel 1 and fdt 2:
-
- configurations {
- default = "conf-1";
- conf-1 {
- kernel = "kernel-1";
- fdt = "fdt-1";
- };
- conf-2 {
- kernel = "kernel-2";
- fdt = "fdt-2";
- };
- conf-3 {
- kernel = "kernel-1";
- fdt = "fdt-2";
- };
- };
-
-With signed images, nothing protects against this. Whether it gains an
-advantage for the attacker is debatable, but it is not secure.
-
-To solve this problem, we support signed configurations. In this case it
-is the configurations that are signed, not the image. Each image has its
-own hash, and we include the hash in the configuration signature.
-
-So the above example is adjusted to look like this:
-
-/ {
- images {
- kernel-1 {
- data = <data for kernel1>
- hash-1 {
- algo = "sha1";
- value = <...kernel hash 1...>
- };
- };
- kernel-2 {
- data = <data for kernel2>
- hash-1 {
- algo = "sha1";
- value = <...kernel hash 2...>
- };
- };
- fdt-1 {
- data = <data for fdt1>;
- hash-1 {
- algo = "sha1";
- value = <...fdt hash 1...>
- };
- };
- fdt-2 {
- data = <data for fdt2>;
- hash-1 {
- algo = "sha1";
- value = <...fdt hash 2...>
- };
- };
- };
- configurations {
- default = "conf-1";
- conf-1 {
- kernel = "kernel-1";
- fdt = "fdt-1";
- signature-1 {
- algo = "sha1,rsa2048";
- value = <...conf 1 signature...>;
- };
- };
- conf-2 {
- kernel = "kernel-2";
- fdt = "fdt-2";
- signature-1 {
- algo = "sha1,rsa2048";
- value = <...conf 1 signature...>;
- };
- };
- };
-};
-
-
-You can see that we have added hashes for all images (since they are no
-longer signed), and a signature to each configuration. In the above example,
-mkimage will sign configurations/conf-1, the kernel and fdt that are
-pointed to by the configuration (/images/kernel-1, /images/kernel-1/hash-1,
-/images/fdt-1, /images/fdt-1/hash-1) and the root structure of the image
-(so that it isn't possible to add or remove root nodes). The signature is
-written into /configurations/conf-1/signature-1/value. It can easily be
-verified later even if the FIT has been signed with other keys in the
-meantime.
-
-
-Details
--------
-The signature node contains a property ('hashed-nodes') which lists all the
-nodes that the signature was made over. The image is walked in order and each
-tag processed as follows:
-- DTB_BEGIN_NODE: The tag and the following name are included in the signature
- if the node or its parent are present in 'hashed-nodes'
-- DTB_END_NODE: The tag is included in the signature if the node or its parent
- are present in 'hashed-nodes'
-- DTB_PROPERTY: The tag, the length word, the offset in the string table, and
- the data are all included if the current node is present in 'hashed-nodes'
- and the property name is not 'data'.
-- DTB_END: The tag is always included in the signature.
-- DTB_NOP: The tag is included in the signature if the current node is present
- in 'hashed-nodes'
-
-In addition, the signature contains a property 'hashed-strings' which contains
-the offset and length in the string table of the strings that are to be
-included in the signature (this is done last).
-
-IMPORTANT: To verify the signature outside u-boot, it is vital to not only
-calculate the hash of the image and verify the signature with that, but also to
-calculate the hashes of the kernel, fdt, and ramdisk images and check those
-match the hash values in the corresponding 'hash*' subnodes.
-
-
-Verification
-------------
-FITs are verified when loaded. After the configuration is selected a list
-of required images is produced. If there are 'required' public keys, then
-each image must be verified against those keys. This means that every image
-that might be used by the target needs to be signed with 'required' keys.
-
-This happens automatically as part of a bootm command when FITs are used.
-
-For Signed Configurations, the default verification behavior can be changed by
-the following optional property in /signature node in U-Boot's control FDT.
-
-- required-mode: Valid values are "any" to allow verified boot to succeed if
-the selected configuration is signed by any of the 'required' keys, and "all"
-to allow verified boot to succeed if the selected configuration is signed by
-all of the 'required' keys.
-
-This property can be added to a binary device tree using fdtput as shown in
-below examples::
-
- fdtput -t s control.dtb /signature required-mode any
- fdtput -t s control.dtb /signature required-mode all
-
-
-Enabling FIT Verification
--------------------------
-In addition to the options to enable FIT itself, the following CONFIGs must
-be enabled:
-
-CONFIG_FIT_SIGNATURE - enable signing and verification in FITs
-CONFIG_RSA - enable RSA algorithm for signing
-CONFIG_ECDSA - enable ECDSA algorithm for signing
-
-WARNING: When relying on signed FIT images with required signature check
-the legacy image format is default disabled by not defining
-CONFIG_LEGACY_IMAGE_FORMAT
-
-
-Testing
--------
-An easy way to test signing and verification is to use the test script
-provided in test/vboot/vboot_test.sh. This uses sandbox (a special version
-of U-Boot which runs under Linux) to show the operation of a 'bootm'
-command loading and verifying images.
-
-A sample run is show below:
-
-$ make O=sandbox sandbox_config
-$ make O=sandbox
-$ O=sandbox ./test/vboot/vboot_test.sh
-
-
-Simple Verified Boot Test
-=========================
-
-Please see doc/uImage.FIT/verified-boot.txt for more information
-
-/home/hs/ids/u-boot/sandbox/tools/mkimage -D -I dts -O dtb -p 2000
-Build keys
-do sha1 test
-Build FIT with signed images
-Test Verified Boot Run: unsigned signatures:: OK
-Sign images
-Test Verified Boot Run: signed images: OK
-Build FIT with signed configuration
-Test Verified Boot Run: unsigned config: OK
-Sign images
-Test Verified Boot Run: signed config: OK
-check signed config on the host
-Signature check OK
-OK
-Test Verified Boot Run: signed config: OK
-Test Verified Boot Run: signed config with bad hash: OK
-do sha256 test
-Build FIT with signed images
-Test Verified Boot Run: unsigned signatures:: OK
-Sign images
-Test Verified Boot Run: signed images: OK
-Build FIT with signed configuration
-Test Verified Boot Run: unsigned config: OK
-Sign images
-Test Verified Boot Run: signed config: OK
-check signed config on the host
-Signature check OK
-OK
-Test Verified Boot Run: signed config: OK
-Test Verified Boot Run: signed config with bad hash: OK
-
-Test passed
-
-
-Software signing: keydir vs keyfile
------------------------------------
-
-In the simplest case, signing is done by giving mkimage the 'keyfile'. This is
-the path to a file containing the signing key.
-
-The alternative is to pass the 'keydir' argument. In this case the filename of
-the key is derived from the 'keydir' and the "key-name-hint" property in the
-FIT. In this case the "key-name-hint" property is mandatory, and the key must
-exist in "<keydir>/<key-name-hint>.<ext>" Here the extension "ext" is
-specific to the signing algorithm.
-
-
-Hardware Signing with PKCS#11 or with HSM
------------------------------------------
-
-Securely managing private signing keys can challenging, especially when the
-keys are stored on the file system of a computer that is connected to the
-Internet. If an attacker is able to steal the key, they can sign malicious FIT
-images which will appear genuine to your devices.
-
-An alternative solution is to keep your signing key securely stored on hardware
-device like a smartcard, USB token or Hardware Security Module (HSM) and have
-them perform the signing. PKCS#11 is standard for interfacing with these crypto
-device.
-
-Requirements:
-Smartcard/USB token/HSM which can work with some openssl engine
-openssl
-
-For pkcs11 engine usage:
-libp11 (provides pkcs11 engine)
-p11-kit (recommended to simplify setup)
-opensc (for smartcards and smartcard like USB devices)
-gnutls (recommended for key generation, p11tool)
-
-For generic HSMs respective openssl engine must be installed and locateable by
-openssl. This may require setting up LD_LIBRARY_PATH if engine is not installed
-to openssl's default search paths.
-
-PKCS11 engine support forms "key id" based on "keydir" and with
-"key-name-hint". "key-name-hint" is used as "object" name (if not defined in
-keydir). "keydir" (if defined) is used to define (prefix for) which PKCS11
source
-is being used for lookup up for the key.
-
-PKCS11 engine key ids:
- "pkcs11:<keydir>;object=<key-name-hint>;type=<public|private>"
-or, if keydir contains "object="
- "pkcs11:<keydir>;type=<public|private>"
-or
- "pkcs11:object=<key-name-hint>;type=<public|private>",
-
-Generic HSM engine support forms "key id" based on "keydir" and with
-"key-name-hint". If "keydir" is specified for mkimage it is used as a prefix in
-"key id" and is appended with "key-name-hint".
-
-Generic engine key ids:
- "<keydir><key-name-hint>"
-or
- "<key-name-hint>"
-
-In order to set the pin in the HSM, an environment variable "MKIMAGE_SIGN_PIN"
-can be specified.
-
-The following examples use the Nitrokey Pro using pkcs11 engine. Instructions
-for other devices may vary.
-
-Notes on pkcs11 engine setup:
-
-Make sure p11-kit, opensc are installed and that p11-kit is setup to use
opensc.
-/usr/share/p11-kit/modules/opensc.module should be present on your system.
-
-
-Generating Keys On the Nitrokey:
-
-$ gpg --card-edit
-
-Reader ...........: Nitrokey Nitrokey Pro (xxxxxxxx0000000000000000) 00 00
-Application ID ...: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-Version ..........: 2.1
-Manufacturer .....: ZeitControl
-Serial number ....: xxxxxxxx
-Name of cardholder: [not set]
-Language prefs ...: de
-Sex ..............: unspecified
-URL of public key : [not set]
-Login data .......: [not set]
-Signature PIN ....: forced
-Key attributes ...: rsa2048 rsa2048 rsa2048
-Max. PIN lengths .: 32 32 32
-PIN retry counter : 3 0 3
-Signature counter : 0
-Signature key ....: [none]
-Encryption key....: [none]
-Authentication key: [none]
-General key info..: [none]
-
-gpg/card> generate
-Make off-card backup of encryption key? (Y/n) n
-
-Please note that the factory settings of the PINs are
- PIN = '123456' Admin PIN = '12345678'
-You should change them using the command --change-pin
-
-What keysize do you want for the Signature key? (2048) 4096
-The card will now be re-configured to generate a key of 4096 bits
-Note: There is no guarantee that the card supports the requested size.
- If the key generation does not succeed, please check the
- documentation of your card to see what sizes are allowed.
-What keysize do you want for the Encryption key? (2048) 4096
-The card will now be re-configured to generate a key of 4096 bits
-What keysize do you want for the Authentication key? (2048) 4096
-The card will now be re-configured to generate a key of 4096 bits
-Please specify how long the key should be valid.
- 0 = key does not expire
- <n> = key expires in n days
- <n>w = key expires in n weeks
- <n>m = key expires in n months
- <n>y = key expires in n years
-Key is valid for? (0)
-Key does not expire at all
-Is this correct? (y/N) y
-
-GnuPG needs to construct a user ID to identify your key.
-
-Real name: John Doe
-Email address: john....@email.com
-Comment:
-You selected this USER-ID:
- "John Doe <john....@email.com>"
-
-Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
-
-
-Using p11tool to get the token URL:
-
-Depending on system configuration, gpg-agent may need to be killed first.
-
-$ p11tool --provider /usr/lib/opensc-pkcs11.so --list-tokens
-Token 0:
-URL:
pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29
-Label: OpenPGP card (User PIN (sig))
-Type: Hardware token
-Manufacturer: ZeitControl
-Model: PKCS#15 emulated
-Serial: 000xxxxxxxxx
-Module: (null)
-
-
-Token 1:
-URL:
pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%29
-Label: OpenPGP card (User PIN)
-Type: Hardware token
-Manufacturer: ZeitControl
-Model: PKCS#15 emulated
-Serial: 000xxxxxxxxx
-Module: (null)
-
-Use the portion of the signature token URL after "pkcs11:" as the keydir
argument (-k) to mkimage below.
-
-
-Use the URL of the token to list the private keys:
-
-$ p11tool --login --provider /usr/lib/opensc-pkcs11.so --list-privkeys \
-"pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29"
-Token 'OpenPGP card (User PIN (sig))' with URL
'pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29'
requires user PIN
-Enter PIN:
-Object 0:
-URL:
pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29;id=%01;object=Signature%20key;type=private
-Type: Private key
-Label: Signature key
-Flags: CKA_PRIVATE; CKA_NEVER_EXTRACTABLE; CKA_SENSITIVE;
-ID: 01
-
-Use the label, in this case "Signature key" as the key-name-hint in your FIT.
-
-Create the fitImage:
-$ ./tools/mkimage -f fit-image.its fitImage
-
-
-Sign the fitImage with the hardware key:
-
-$ ./tools/mkimage -F -k \
-"model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29"
\
--K u-boot.dtb -N pkcs11 -r fitImage
-
-
-Future Work
------------
-- Roll-back protection using a TPM is done using the tpm command. This can
-be scripted, but we might consider a default way of doing this, built into
-bootm.
-
-
-Possible Future Work
---------------------
-- More sandbox tests for failure modes
-- Passwords for keys/certificates
-- Perhaps implement OAEP
-- Enhance bootm to permit scripted signature verification (so that a script
-can verify an image but not actually boot it)
-
-
-Simon Glass
-s...@chromium.org
-1-1-13
diff --git a/doc/usage/cmd/source.rst b/doc/usage/cmd/source.rst
index a5c5204a28b8..697f644745b2 100644
--- a/doc/usage/cmd/source.rst
+++ b/doc/usage/cmd/source.rst
@@ -22,7 +22,7 @@ Two formats for script files exist:
* Flat Image Tree (FIT)
The benefit of the FIT images is that they can be signed and verifed as
-decribed in :download:`signature.txt <../../uImage.FIT/signature.txt>`.
+described in :doc:`../fit/signature`.
Both formats can be created with the mkimage tool.
diff --git a/doc/usage/fit/beaglebone_vboot.rst
b/doc/usage/fit/beaglebone_vboot.rst
new file mode 100644
index 000000000000..9851c445c1c9
--- /dev/null
+++ b/doc/usage/fit/beaglebone_vboot.rst
@@ -0,0 +1,607 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Verified Boot on the Beaglebone Black
+=====================================
+
+Introduction
+------------
+
+Before reading this, please read :doc:`verified-boot` and :doc:`signature`.
+These instructions are for mainline U-Boot from v2014.07 onwards.
+
+There is quite a bit of documentation in this directory describing how
+verified boot works in U-Boot. There is also a test which runs through the
+entire process of signing an image and running U-Boot (sandbox) to check it.
+However, it might be useful to also have an example on a real board.
+
+Beaglebone Black is a fairly common board so seems to be a reasonable choice
+for an example of how to enable verified boot using U-Boot.
+
+First a note that may to help avoid confusion. U-Boot and Linux both use
+device tree. They may use the same device tree source, but it is seldom useful
+for them to use the exact same binary from the same place. More typically,
+U-Boot has its device tree packaged with it, and the kernel's device tree is
+packaged with the kernel. In particular this is important with verified boot,
+since U-Boot's device tree must be immutable. If it can be changed then the
+public keys can be changed and verified boot is useless. An attacker can
+simply generate a new key and put his public key into U-Boot so that
+everything verifies. On the other hand the kernel's device tree typically
+changes when the kernel changes, so it is useful to package an updated device
+tree with the kernel binary. U-Boot supports the latter with its flexible FIT
+format (Flat Image Tree).
+
+
+Overview
+--------
+
+The steps are roughly as follows:
+
+#. Build U-Boot for the board, with the verified boot options enabled.
+
+#. Obtain a suitable Linux kernel
+
+#. Create a Image Tree Source file (ITS) file describing how you want the
+ kernel to be packaged, compressed and signed.
+
+#. Create a key pair
+
+#. Sign the kernel
+
+#. Put the public key into U-Boot's image
+
+#. Put U-Boot and the kernel onto the board
+
+#. Try it
+
+
+Step 1: Build U-Boot
+--------------------
+
+a. Set up the environment variable to point to your toolchain. You will need
+this for U-Boot and also for the kernel if you build it. For example if you
+installed a Linaro version manually it might be something like::
