[PATCH 6/9] doc: Bring in FIT signature files
Heinrich Schuchardt
xypron.glpk at gmx.de
Fri Jun 23 09:33:09 CEST 2023
On 6/22/23 22:21, Simon Glass wrote:
> Bring these files into the documentation.
>
> Fix 'wtih' and 'it' typos and repeated 'could' while we are here.
>
> Signed-off-by: Simon Glass <sjg at 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
> -sjg at 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.doe at email.com
> -Comment:
> -You selected this USER-ID:
> - "John Doe <john.doe at 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
> -sjg at 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::
> +
> + 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 :doc:`signature` 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 be integrated into the Amstrom
> +distribution.
> +
> +
> +.. sectionauthor:: Simon Glass <sjg at chromium.org>, 2-June-14
> diff --git a/doc/usage/fit/index.rst b/doc/usage/fit/index.rst
> index 0635d06b811a..0576675ec001 100644
> --- a/doc/usage/fit/index.rst
> +++ b/doc/usage/fit/index.rst
> @@ -12,3 +12,6 @@ doc/uImage.FIT
>
> source_file_format
> x86-fit-boot
> + signature
> + verified-boot
> + beaglebone_vboot
> diff --git a/doc/usage/fit/signature.rst b/doc/usage/fit/signature.rst
> new file mode 100644
> index 000000000000..7d8292ece867
> --- /dev/null
> +++ b/doc/usage/fit/signature.rst
> @@ -0,0 +1,760 @@
> +.. SPDX-License-Identifier: GPL-2.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 :doc:`sign-images` 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 is 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:`verified-boot` 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.doe at email.com
> + Comment:
> + You selected this USER-ID:
> + "John Doe <john.doe at 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)
> +
> +
> +.. sectionauthor:: Simon Glass <sjg at chromium.org>, 1-1-13
> diff --git a/doc/uImage.FIT/verified-boot.txt b/doc/usage/fit/verified-boot.rst
> similarity index 54%
> rename from doc/uImage.FIT/verified-boot.txt
> rename to doc/usage/fit/verified-boot.rst
> index 41c9fa9e09f9..bef52ba36ffc 100644
> --- a/doc/uImage.FIT/verified-boot.txt
> +++ b/doc/usage/fit/verified-boot.rst
> @@ -1,8 +1,11 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> U-Boot Verified Boot
> ====================
>
> Introduction
> ------------
> +
> Verified boot here means the verification of all software loaded into a
> machine during the boot process to ensure that it is authorised and correct
> for that machine.
> @@ -21,6 +24,7 @@ memory, so that firmware can easily be upgraded in a secure manner.
>
> Signing
> -------
> +
> Verified boot uses cryptographic algorithms to 'sign' software images.
> Images are signed using a private key known only to the signer, but can
> be verified using a public key. As its name suggests the public key can be
> @@ -28,31 +32,31 @@ made available without risk to the verification process. The private and
> public keys are mathematically related. For more information on how this
> works look up "public key cryptography" and "RSA" (a particular algorithm).
>
> -The signing and verification process looks something like this:
> -
> -
> - Signing Verification
> - ======= ============
> -
> - +--------------+ *
> - | RSA key pair | * +---------------+
> - | .key .crt | * | Public key in |
> - +--------------+ +------> public key ----->| trusted place |
> - | | * +---------------+
> - | | * |
> - v | * v
> - +---------+ | * +--------------+
> - | |----------+ * | |
> - | signer | * | U-Boot |
> - | |----------+ * | signature |--> yes/no
> - +---------+ | * | verification |
> - ^ | * | |
> - | | * +--------------+
> - | | * ^
> - +----------+ | * |
> - | Software | +----> signed image -------------+
> - | image | *
> - +----------+ *
> +The signing and verification process looks something like this::
> +
> +
> + Signing Verification
> + ======= ============
> +
> + +--------------+ *
> + | RSA key pair | * +---------------+
> + | .key .crt | * | Public key in |
> + +--------------+ +------> public key ----->| trusted place |
> + | | * +---------------+
> + | | * |
> + v | * v
> + +---------+ | * +--------------+
> + | |----------+ * | |
> + | signer | * | U-Boot |
> + | |----------+ * | signature |--> yes/no
> + +---------+ | * | verification |
> + ^ | * | |
> + | | * +--------------+
Please, correct the layout.
Best regards
Heinrich
> + | | * ^
> + +----------+ | * |
> + | Software | +----> signed image -------------+
> + | image | *
> + +----------+ *
>
>
> The signature algorithm relies only on the public key to do its work. Using
> @@ -70,23 +74,25 @@ the verification is worthless.
>
> Chaining Images
> ---------------
> +
> The above method works for a signer providing images to a run-time U-Boot.
> It is also possible to extend this scheme to a second level, like this:
>
> -1. Master private key is used by the signer to sign a first-stage image.
> -2. Master public key is placed in read-only memory.
> -2. Secondary private key is created and used to sign second-stage images.
> -3. Secondary public key is placed in first stage images
> -4. We use the master public key to verify the first-stage image. We then
> -use the secondary public key in the first-stage image to verify the second-
> -state image.
> -5. This chaining process can go on indefinitely. It is recommended to use a
> -different key at each stage, so that a compromise in one place will not
> -affect the whole change.
> +#. Master private key is used by the signer to sign a first-stage image.
> +#. Master public key is placed in read-only memory.
> +#. Secondary private key is created and used to sign second-stage images.
> +#. Secondary public key is placed in first stage images
> +#. We use the master public key to verify the first-stage image. We then
> + use the secondary public key in the first-stage image to verify the second-
> + state image.
> +#. This chaining process can go on indefinitely. It is recommended to use a
> + different key at each stage, so that a compromise in one place will not
> + affect the whole change.
>
>
> Flattened Image Tree (FIT)
> --------------------------
> +
> The FIT format is already widely used in U-Boot. It is a flattened device
> tree (FDT) in a particular format, with images contained within. FITs
> include hashes to verify images, so it is relatively straightforward to
> @@ -96,9 +102,6 @@ The public key can be stored in U-Boot's CONFIG_OF_CONTROL device tree in
> a standard place. Then when a FIT is loaded it can be verified using that
> public key. Multiple keys and multiple signatures are supported.
>
> -See signature.txt for more information.
> -
> +See :doc:`signature` for more information.
>
> -Simon Glass
> -sjg at chromium.org
> -1-1-13
> +.. sectionauthor:: Simon Glass <sjg at chromium.org> 1-1-13
More information about the U-Boot
mailing list