.. 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

b. 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@chromium.org>, 2-June-14