1This directory contains a reference implementation for Chrome OS 2verified boot in firmware. 3 4---------- 5Directory Structure 6---------- 7 8The source is organized into distinct modules - 9 10firmware/ 11 12 Contains ONLY the code required by the BIOS to validate the secure boot 13 components. There shouldn't be any code in here that signs or generates 14 images. BIOS should require ONLY this directory to implement secure boot. 15 Refer to firmware/README for futher details. 16 17cgpt/ 18 19 Utility to read/write/modify GPT partitions. Similar to GNU parted or any 20 other GPT tool, but this has support for Chrome OS extensions. 21 22host/ 23 24 Miscellaneous functions needed by userland utilities. 25 26futility/ 27 28 The "firmware utility" tool, used to create, sign, and validate Chrome OS 29 images. 30 31utility/ 32 33 Random other utilities, not necesssarily related to verified boot as such. 34 35tests/ 36 37 User-land tests and benchmarks that test the reference implementation. 38 Please have a look at these if you'd like to understand how to use the 39 reference implementation. 40 41build/ 42 43 The output directory where the generated files will be placed, and where 44 tests are run. 45 46scripts/ 47 48 Tools and scripts used to generate and use new signing keypairs. These are 49 typically used only on a secure machine. 50 51rust/ 52 53 Rust bindings for vboot_reference. See rust/README.md for more details. 54 55-------------------- 56Building and testing 57-------------------- 58 59The suite can be built on the host or in the chroot environment. 60 61Building on the host could fail if certain packages are not installed. If 62there are host environment build problems due to missing .h files, try 63researching what packages the files belong to and install the missing packages 64before reporting a problem. 65 66 67The commands are the more-or-less expected ones: 68 69 make 70 make runtests 71 make install [ DESTDIR=/usr/local ] 72 73 74 75---------- 76Some useful utilities: 77---------- 78 79futility vbutil_key Convert a public key into .vbpubk format 80futility vbutil_keyblock Wrap a public key inside a signature and checksum 81futility sign Sign a blob. Supported operations include: 82 * Create a .vblock with signature info for a 83 firmware image 84 * Re-sign a firmware image 85 * Pack a vmlinuz image, bootloader and config into a 86 kernel partition 87futility verify Verify a blob such as a firmware image or a kernel 88 partition 89 90dumpRSAPublicKey Dump RSA Public key (from a DER-encoded X509 91 certificate) in a format suitable for use by 92 RSAVerify* functions in crypto/. 93 94 95 96---------- 97Generating a signed firmware image: 98---------- 99 100* Step 0: Build the tools, install them somewhere. 101 102* Step 1: Generate RSA root and signing keys. 103 104 The root key is always 8192 bits. 105 106 $ openssl genrsa -F4 -out root_key.pem 8192 107 108 The signing key can be between 1024-8192 bits. 109 110 $ openssl genrsa -F4 -out signing_key.pem <1024|2048|4096|8192> 111 112 Note: The -F4 option must be specified to generate RSA keys with a public 113 exponent of 65535. RSA keys with 3 as a public exponent (the default) 114 won't work. 115 116* Step 2: Generate pre-processed public versions of the above keys using 117 dumpRSAPublicKey. This utility expects an x509 certificate as 118 input, and emits an intermediate representation for further 119 processing. 120 121 $ openssl req -batch -new -x509 -key root_key.pem -out root_key.crt 122 $ openssl req -batch -new -x509 -key signing_key.pem -out signing_key.crt 123 $ dumpRSAPublicKey root_key.crt > root_key.keyb 124 $ dumpRSAPublicKey signing_key.crt > signing_key.keyb 125 126************** TODO: STUFF PAST HERE IS OUT OF DATE *************** 127 128At this point we have all the requisite keys needed to generate a signed 129firmware image. 130 131.pem RSA Public/Private Key Pair 132.crt X509 Key Certificate 133.keyb Pre-processed RSA Public Key 134 135 136* Step 3: Use utility/firmware_utility to generate a signed firmare blob. 137 138$ utility/firmware_utility --generate \ 139 --root_key root_key.pem \ 140 --firmware_sign_key signing_key.pem \ 141 --firmware_sign_key_pub signing_key.keyb \ 142 --firmware_sign_algorithm <algoid> \ 143 --firmware_key_version 1 \ 144 --firmware_version 1 \ 145 --in <firmware blob file> \ 146 --out <output file> 147 148Where <algoid> is based on the signature algorithm to use for firmware 149signining. The list of <algoid> specifications can be output by running 150'utility/firmware_utility' without any arguments. 151 152Note: --firmware_key_version and --firmware_version are part of a signed 153 image and are used to prevent rollbacks to older version. For testing, 154 they can just be set to valid values. 155 156 157* Step 4: Verify that this image verifies. 158 159$ utility/firmware_utility --verify \ 160 --in <signed firmware image> 161 --root_key_pub root_key.keyb 162Verification SUCCESS. 163 164 165Note: The verification functions expects a pointer to the 166 pre-processed public root key as input. For testing purposes, 167 root_key.keyb can be stored in RW part of the firmware. For the 168 final firmware, this will be a fixed public key which cannot be 169 changed and must be stored in RO firmware. 170 171---------- 172Generating a signed kernel image: 173---------- 174 175The steps for generating a signed kernel image are similar to that of 176a firmware image. Since verification is chained - RO firmware verifies 177RW firmware which verifies the kernel, only the keys change. An additional 178kernel signing key must be generated. The firmware signing generated above 179is the root key equivalent for signed kernel images. 180