|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
| 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.
| 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.
| Unit tests for bvbtool.
| A tool written in Python for working with Brillo boot images.
| 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
|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 := 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