diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 141 |
1 files changed, 80 insertions, 61 deletions
@@ -1,30 +1,53 @@ This directory contains a reference implementation for Chrome OS verified boot in firmware. ----------- -Directory Structure +---------- +Directory Structure ---------- The source is organized into distinct modules - -firmware/ - Contains ONLY the code required by the BIOS to validate -the secure boot components. There shouldn't be any code in here that -signs or generates images. BIOS should require ONLY this directory to -implement secure boot. Refer to firmware/README for futher details. +firmware/ + + Contains ONLY the code required by the BIOS to validate the secure boot + components. There shouldn't be any code in here that signs or generates + images. BIOS should require ONLY this directory to implement secure boot. + Refer to firmware/README for futher details. + +cgpt/ + + Utility to read/write/modify GPT partitions. Similar to GNU parted or any + other GPT tool, but this has support for Chrome OS extensions. + +host/ + + Miscellaneous functions needed by userland utilities. + +futility/ + + The "firmware utility" tool, used to create, sign, and validate Chrome OS + images. + +utility/ + + Random other utilities, not necesssarily related to verified boot as such. + +tests/ -cgpt/ - Utility to read/write/modify GPT partitions. Much like the -gpt tool, but with support for Chrome OS extensiosn. + User-land tests and benchmarks that test the reference implementation. + Please have a look at these if you'd like to understand how to use the + reference implementation. -host/ - Miscellaneous functions used by userland utilities. +build/ -utility/ - Utilities for generating and verifying signed -firmware and kernel images, as well as arbitrary blobs. + The output directory where the generated files will be placed, and where + tests are run. -tests/ - User-land tests and benchmarks that test the reference -implementation. Please have a look at these if you'd like to -understand how to use the reference implementation. +scripts/ + + Tools and scripts used to generate and use new signing keypairs. These are + typically used only on a secure machine. -build/ - a directory where the generated files go to. -------------------- Building and testing @@ -37,67 +60,63 @@ there are host environment build problems due to missing .h files, try researching what packages the files belong to and install the missing packages before reporting a problem. -To build the software run - -make -in the top level directory. The build output is placed in the ./build -directory. +The commands are the more-or-less expected ones: -To run the tests either invoke + make + make runtests + make install [ DESTDIR=/usr/local/bin ] -RUNTESTS=1 make -in the top level directory or -cd tests -BUILD=../build make runtests +---------- +Some useful utilities: +---------- +futility vbutil_key Convert a public key into .vbpubk format +futility vbutil_keyblock Wrap a public key inside a signature and checksum +futility vbutil_firmware Create a .vblock with signature info for a + firmware image +futility vbutil_kernel Pack a kernel image, bootloader, and config into + a signed binary ----------- -Some useful utilities: ----------- +dumpRSAPublicKey Dump RSA Public key (from a DER-encoded X509 + certificate) in a format suitable for use by + RSAVerify* functions in crypto/. -vbutil_key Convert a public key into .vbpubk format -vbutil_keyblock Wrap a public key inside a signature and checksum -vbutil_firmware Create a .vblock with signature info for a - firmware image -vbutil_kernel Pack a kernel image, bootloader, and config into - a signed binary +verify_data.c Verify a given signature on a given file. -dumpRSAPublicKey Dump RSA Public key (from a DER-encoded X509 - certificate) in a format suitable for - use by RSAVerify* functions in - crypto/. -verify_data.c Verify a given signature on a given file. - - ----------- -Generating a signed firmware image: ---------- +Generating a signed firmware image: +---------- + +* Step 0: Build the tools, install them somewhere. * Step 1: Generate RSA root and signing keys. -# Root key is always 8192 bits. -$ openssl genrsa -F4 -out root_key.pem 8192 + The root key is always 8192 bits. + + $ openssl genrsa -F4 -out root_key.pem 8192 -# Signing key can be between 1024-8192 bits. -$ openssl genrsa -F4 -out signing_key.pem <1024|2048|4096|8192> + The signing key can be between 1024-8192 bits. -Note: The -F4 option must be specified to generate RSA keys with - a public exponent of 65535. RSA keys with 3 as a public - exponent (the default) won't work. + $ openssl genrsa -F4 -out signing_key.pem <1024|2048|4096|8192> + + Note: The -F4 option must be specified to generate RSA keys with a public + exponent of 65535. RSA keys with 3 as a public exponent (the default) + won't work. * Step 2: Generate pre-processed public versions of the above keys using - utility/dumpRSAPublicKey + dumpRSAPublicKey. This utility expects an x509 certificate as + input, and emits an intermediate representation for further + processing. -# dumpRSAPublicKey expects an x509 certificate as input. -$ openssl req -batch -new -x509 -key root_key.pem -out root_key.crt -$ openssl req -batch -new -x509 -key signing_key.pem -out signing_key.crt -$ utility/dumpRSAPublicKey root_key.crt > root_key.keyb -$ utility/dumpRSAPublicKey signing_key.crt > signing_key.keyb + $ openssl req -batch -new -x509 -key root_key.pem -out root_key.crt + $ openssl req -batch -new -x509 -key signing_key.pem -out signing_key.crt + $ dumpRSAPublicKey root_key.crt > root_key.keyb + $ dumpRSAPublicKey signing_key.crt > signing_key.keyb ************** TODO: STUFF PAST HERE IS OUT OF DATE *************** @@ -121,13 +140,13 @@ $ utility/firmware_utility --generate \ --in <firmware blob file> \ --out <output file> -Where <algoid> is based on the signature algorithm to use for firmware +Where <algoid> is based on the signature algorithm to use for firmware signining. The list of <algoid> specifications can be output by running 'utility/firmware_utility' without any arguments. -Note: --firmware_key_version and --firmware_version are part of a signed +Note: --firmware_key_version and --firmware_version are part of a signed image and are used to prevent rollbacks to older version. For testing, - they can just be set valid values. + they can just be set to valid values. * Step 4: Verify that this image verifies. @@ -144,8 +163,8 @@ Note: The verification functions expects a pointer to the final firmware, this will be a fixed public key which cannot be changed and must be stored in RO firmware. ----------- -Generating a signed kernel image: +---------- +Generating a signed kernel image: ---------- The steps for generating a signed kernel image are similar to that of |