diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 144 |
1 files changed, 144 insertions, 0 deletions
@@ -0,0 +1,144 @@ +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'. |