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