This directory contains the specification for the Brillo Verified Boot
boot image, a reference implementation for verified boot and A/B
selection to be used in boot loaders, and a tool for generating and
signing boot images.

-- FILES AND DIRECTORIES

 refimpl/

   The reference implementation for boot image verification and A/B
   selection is in the refimpl sub-directory.

   Part of this code is considered internal to the reference
   implementation and should not be used outside it. This includes the
   bvb_rsa.[ch] and bvb_sha.[ch] files.

   System dependencies expected to be provided by the platform is
   defined in bvb_sysdeps.h. If the platform provides the standard C
   runtime bvb_sysdeps_stub.c can be used.

 Android.mk

   Build instructions for building the reference implementation and
   associated unit tests.

 bvb_util_unittest.cc, bvb_verify_unittest.cc, bvb_unittest_util.h

   Unit tests for the reference implementation.

 bvbtool_unittest.cc

   Unit tests for bvbtool.

 bvbtool

   A tool written in Python for working with Brillo boot images.

 test/

   Contains test data used in unit tests.

-- AUDIENCE AND PORTABILITY NOTES

This code is intended to be used in bootloaders in devices running
Brillo. The suggested approach is to copy the appropriate header and C
files mentioned in the previous section into the boot loader and
integrate as appropriate.

The reference implementation will evolve over time so integration
should be as non-invasive as possible. The intention is to keep the
API of the reference implementation stable however it will be broken
if necessary.

As for portability, the reference implementation is intended to be
highly portable, work on both little- and big-endian architectures and
32- and 64-bit. It's also intended to work in non-standard
environments without the standard C library and runtime.

If the BVB_ENABLE_DEBUG preprocessor symbol is set, the code will
include useful debug information and run-time checks. Production
builds should not use this.

The preprocessor symbol BVB_REFIMPL_COMPILATION should be set when
compiling the code. The code must be compiled into a separate library.

Applications using the compiled library must only include the
refimpl/bvb_refimpl.h file (which will include all public interfaces)
and must not have the BVB_REFIMPL_COMPILATION preprocessor symbol
set. This is to ensure that internal code that may be change in the
future (for example refimpl/bvb_sha.[ch] and refimpl/bvb_rsa.[ch])
will not be visible to application code.

-- COMPATIBILITY NOTES

The Brillo Boot Image structure (as defined in refimpl/bvb_boot_image.h)
guarantees forwards- and backwards-compatibility provided the major
version does not change.

When backwards-compatible changes are made - for example, when a new
field is added to BvbBootImageHeader - the minor version will be
bumped. At the same time, the reference implementation will also be
modified to test for the appropriate minor version before attempting
to access the newly added field. This ensures that version 1.N of the
reference implementation is able to read an old boot image header
produced with version 1.M where N > M.

The usual scenario is that the code parsing the BvbBootImageHeader
rarely changes (it's usually in the firmware of a device and this
firmware is rarely updated if ever), let's say it's fixed at version
1.N. At the same time, the version of the bvbtool used to produce the
boot image is rolling forward and is at version 1.M where M > N. The
problem with this scenario is that version 1.M may easily and
inadvertently introduce a seemingly compatible change that isn't. For
example, consider if a new verification algorithm is added - in this
case version 1.N of the reference implementation will fail at
verification time when validating the |algorithm_field| of a 1.M image
if it's set to the new algorithm.

The best approach for dealing with this problem is to always used a
pinned version of bvbtool (say, use version 1.N to generate images
targeted for devices running version 1.N) for generating and signing
images but sometimes this is not always possible nor
desirable. Therefore, to avoid this compatibility problem, bvbtool is
designed to always take such input as a command-line argument so it
can be kept constant by the caller. In other words, as long as you
keep your command-line options passed to the bvb tool the same, images
produced by newer versions of bvb will continue to work on the same
version of the reference implementation.

-- BUILD SYSTEM INTEGRATION NOTES

Brillo Verified Boot is enabled by the BOARD_BVB_ENABLE variable

 BOARD_BVB_ENABLE := true

By default, the algorithm SHA256_RSA4096 is used with a test key from
this directory. This can be overriden by the BOARD_BVB_ALGORITHM and
BOARD_BVB_KEY_PATH variables to use e.g. RSA-4096:

 BOARD_BVB_ALGORITHM := SHA512_RSA4096
 BOARD_BVB_KEY_PATH := /path/to/rsa_key_4096bits.pem

Remember that the public part of this key needs to be embedded in the
bootloader of the device expected to process resulting images. Use
'bvbtool extract_public_key' to do this.

To prevent rollback attakcs, the rollback index should be increased on
a regular basis. The rollback index can be set with the
BOARD_BVB_ROLLBACK_INDEX variable:

 BOARD_BVB_ROLLBACK_INDEX := 5

If this is not set, the rollback index defaults to 0.

Additionally, the variables BOARD_BVB_MAKE_BOOT_IMAGE_ARGS,
BOARD_BVB_SIGN_BOOT_IMAGE_ARGS, and BOARD_BVB_ADD_IMAGE_HASHES_ARGS
can be used to specify additional options passed to respectively
'bvbtool make_boot_image', 'bvbtool sign_boot_image', and 'bvbtool
add_image_hashes'.