Gaurav Shah | 56c9f4d | 2010-03-03 13:15:53 -0800 | [diff] [blame] | 1 | This directory contains a reference implementation for Chrome OS |
| 2 | verified boot in firmware. |
| 3 | |
| 4 | ---------- |
| 5 | Directory Structure |
| 6 | ---------- |
| 7 | |
Gaurav Shah | ef7510f | 2010-03-31 14:09:31 -0700 | [diff] [blame] | 8 | The source is organized into distinct modules - |
Gaurav Shah | 56c9f4d | 2010-03-03 13:15:53 -0800 | [diff] [blame] | 9 | |
Randall Spangler | 620c38c | 2010-06-17 14:45:22 -0700 | [diff] [blame] | 10 | firmware/ - Contains ONLY the code required by the BIOS to validate |
| 11 | the secure boot components. There shouldn't be any code in here that |
| 12 | signs or generates images. BIOS should require ONLY this directory to |
| 13 | implement secure boot. Refer to firmware/README for futher details. |
Gaurav Shah | 56c9f4d | 2010-03-03 13:15:53 -0800 | [diff] [blame] | 14 | |
Randall Spangler | 620c38c | 2010-06-17 14:45:22 -0700 | [diff] [blame] | 15 | cgpt/ - Utility to read/write/modify GPT partitions. Much like the |
| 16 | gpt tool, but with support for Chrome OS extensiosn. |
Gaurav Shah | 56c9f4d | 2010-03-03 13:15:53 -0800 | [diff] [blame] | 17 | |
Randall Spangler | 620c38c | 2010-06-17 14:45:22 -0700 | [diff] [blame] | 18 | host/ - Miscellaneous functions used by userland utilities. |
Gaurav Shah | ef7510f | 2010-03-31 14:09:31 -0700 | [diff] [blame] | 19 | |
| 20 | utility/ - Utilities for generating and verifying signed |
| 21 | firmware and kernel images, as well as arbitrary blobs. |
| 22 | |
Gaurav Shah | 56c9f4d | 2010-03-03 13:15:53 -0800 | [diff] [blame] | 23 | tests/ - User-land tests and benchmarks that test the reference |
| 24 | implementation. Please have a look at these if you'd like to |
| 25 | understand how to use the reference implementation. |
| 26 | |
vbendeb | 70e9509 | 2010-06-14 15:41:27 -0700 | [diff] [blame] | 27 | build/ - a directory where the generated files go to. |
| 28 | |
| 29 | -------------------- |
| 30 | Building and testing |
| 31 | -------------------- |
| 32 | |
| 33 | The suite can be built on the host or in the chroot environment. |
| 34 | |
| 35 | Building on the host could fail if certain packages are not installed. If |
| 36 | there are host environment build problems due to missing .h files, try |
| 37 | researching what packages the files belong to and install the missing packages |
| 38 | before reporting a problem. |
| 39 | |
| 40 | To build the software run |
| 41 | |
| 42 | make |
| 43 | |
| 44 | in the top level directory. The build output is placed in the ./build |
| 45 | directory. |
| 46 | |
| 47 | To run the tests either invoke |
| 48 | |
| 49 | RUNTESTS=1 make |
| 50 | |
| 51 | in the top level directory or |
| 52 | |
| 53 | cd tests |
| 54 | BUILD=../build make runtests |
| 55 | |
Gaurav Shah | 56c9f4d | 2010-03-03 13:15:53 -0800 | [diff] [blame] | 56 | |
| 57 | ---------- |
| 58 | Some useful utilities: |
| 59 | ---------- |
| 60 | |
Randall Spangler | 620c38c | 2010-06-17 14:45:22 -0700 | [diff] [blame] | 61 | vbutil_key Convert a public key into .vbpubk format |
| 62 | vbutil_keyblock Wrap a public key inside a signature and checksum |
| 63 | vbutil_firmware Create a .vblock with signature info for a |
| 64 | firmware image |
| 65 | vbutil_kernel Pack a kernel image, bootloader, and config into |
| 66 | a signed binary |
Gaurav Shah | 56c9f4d | 2010-03-03 13:15:53 -0800 | [diff] [blame] | 67 | |
Randall Spangler | 620c38c | 2010-06-17 14:45:22 -0700 | [diff] [blame] | 68 | dumpRSAPublicKey Dump RSA Public key (from a DER-encoded X509 |
| 69 | certificate) in a format suitable for |
| 70 | use by RSAVerify* functions in |
| 71 | crypto/. |
Gaurav Shah | 56c9f4d | 2010-03-03 13:15:53 -0800 | [diff] [blame] | 72 | |
| 73 | verify_data.c Verify a given signature on a given file. |
| 74 | |
| 75 | |
Gaurav Shah | ef7510f | 2010-03-31 14:09:31 -0700 | [diff] [blame] | 76 | |
Gaurav Shah | 5b730c4 | 2010-03-29 12:50:09 -0700 | [diff] [blame] | 77 | ---------- |
| 78 | Generating a signed firmware image: |
| 79 | ---------- |
| 80 | |
| 81 | * Step 1: Generate RSA root and signing keys. |
| 82 | |
| 83 | # Root key is always 8192 bits. |
| 84 | $ openssl genrsa -F4 -out root_key.pem 8192 |
| 85 | |
| 86 | # Signing key can be between 1024-8192 bits. |
| 87 | $ openssl genrsa -F4 -out signing_key.pem <1024|2048|4096|8192> |
| 88 | |
| 89 | Note: The -F4 option must be specified to generate RSA keys with |
| 90 | a public exponent of 65535. RSA keys with 3 as a public |
| 91 | exponent (the default) won't work. |
| 92 | |
| 93 | * Step 2: Generate pre-processed public versions of the above keys using |
Gaurav Shah | ef7510f | 2010-03-31 14:09:31 -0700 | [diff] [blame] | 94 | utility/dumpRSAPublicKey |
Gaurav Shah | 5b730c4 | 2010-03-29 12:50:09 -0700 | [diff] [blame] | 95 | |
| 96 | # dumpRSAPublicKey expects an x509 certificate as input. |
| 97 | $ openssl req -batch -new -x509 -key root_key.pem -out root_key.crt |
| 98 | $ openssl req -batch -new -x509 -key signing_key.pem -out signing_key.crt |
Gaurav Shah | ef7510f | 2010-03-31 14:09:31 -0700 | [diff] [blame] | 99 | $ utility/dumpRSAPublicKey root_key.crt > root_key.keyb |
| 100 | $ utility/dumpRSAPublicKey signing_key.crt > signing_key.keyb |
Gaurav Shah | 5b730c4 | 2010-03-29 12:50:09 -0700 | [diff] [blame] | 101 | |
Randall Spangler | 620c38c | 2010-06-17 14:45:22 -0700 | [diff] [blame] | 102 | ************** TODO: STUFF PAST HERE IS OUT OF DATE *************** |
| 103 | |
Gaurav Shah | 5b730c4 | 2010-03-29 12:50:09 -0700 | [diff] [blame] | 104 | At this point we have all the requisite keys needed to generate a signed |
| 105 | firmware image. |
| 106 | |
| 107 | .pem RSA Public/Private Key Pair |
| 108 | .crt X509 Key Certificate |
| 109 | .keyb Pre-processed RSA Public Key |
| 110 | |
| 111 | |
Gaurav Shah | ef7510f | 2010-03-31 14:09:31 -0700 | [diff] [blame] | 112 | * Step 3: Use utility/firmware_utility to generate a signed firmare blob. |
Gaurav Shah | 5b730c4 | 2010-03-29 12:50:09 -0700 | [diff] [blame] | 113 | |
Gaurav Shah | ef7510f | 2010-03-31 14:09:31 -0700 | [diff] [blame] | 114 | $ utility/firmware_utility --generate \ |
Gaurav Shah | 5b730c4 | 2010-03-29 12:50:09 -0700 | [diff] [blame] | 115 | --root_key root_key.pem \ |
| 116 | --firmware_sign_key signing_key.pem \ |
| 117 | --firmware_sign_key_pub signing_key.keyb \ |
| 118 | --firmware_sign_algorithm <algoid> \ |
| 119 | --firmware_key_version 1 \ |
| 120 | --firmware_version 1 \ |
| 121 | --in <firmware blob file> \ |
| 122 | --out <output file> |
| 123 | |
| 124 | Where <algoid> is based on the signature algorithm to use for firmware |
| 125 | signining. The list of <algoid> specifications can be output by running |
Gaurav Shah | ef7510f | 2010-03-31 14:09:31 -0700 | [diff] [blame] | 126 | 'utility/firmware_utility' without any arguments. |
Gaurav Shah | 5b730c4 | 2010-03-29 12:50:09 -0700 | [diff] [blame] | 127 | |
| 128 | Note: --firmware_key_version and --firmware_version are part of a signed |
| 129 | image and are used to prevent rollbacks to older version. For testing, |
| 130 | they can just be set valid values. |
| 131 | |
| 132 | |
| 133 | * Step 4: Verify that this image verifies. |
| 134 | |
Gaurav Shah | ef7510f | 2010-03-31 14:09:31 -0700 | [diff] [blame] | 135 | $ utility/firmware_utility --verify \ |
Gaurav Shah | 5b730c4 | 2010-03-29 12:50:09 -0700 | [diff] [blame] | 136 | --in <signed firmware image> |
| 137 | --root_key_pub root_key.keyb |
| 138 | Verification SUCCESS. |
| 139 | |
| 140 | |
| 141 | Note: The verification functions expects a pointer to the |
| 142 | pre-processed public root key as input. For testing purposes, |
| 143 | root_key.keyb can be stored in RW part of the firmware. For the |
| 144 | final firmware, this will be a fixed public key which cannot be |
| 145 | changed and must be stored in RO firmware. |
| 146 | |
| 147 | ---------- |
| 148 | Generating a signed kernel image: |
| 149 | ---------- |
| 150 | |
| 151 | The steps for generating a signed kernel image are similar to that of |
| 152 | a firmware image. Since verification is chained - RO firmware verifies |
| 153 | RW firmware which verifies the kernel, only the keys change. An additional |
| 154 | kernel signing key must be generated. The firmware signing generated above |
| 155 | is the root key equivalent for signed kernel images. |