| 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. |
| |
| -- LICENSE |
| |
| This code is made available under the MIT License. See the LICENSE |
| file for more information. |
| |
| -- 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'. |