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 | |
Gaurav Shah | fc70d72 | 2010-03-31 13:26:55 -0700 | [diff] [blame] | 10 | cryptolib/ - Contains the implementation for the crypto library. This |
Gaurav Shah | 56c9f4d | 2010-03-03 13:15:53 -0800 | [diff] [blame] | 11 | includes implementations for SHA1, SHA256, SHA512, and RSA signature |
| 12 | verification (for PKCS #1 v1.5 signatures). |
| 13 | |
Gaurav Shah | ef7510f | 2010-03-31 14:09:31 -0700 | [diff] [blame^] | 14 | common/ - Utility functions and stub implementations for wrapper |
| 15 | functions used in the verification code. These stub implementations |
| 16 | will need to be replaced with appropriate firmware equivalents. |
Gaurav Shah | 56c9f4d | 2010-03-03 13:15:53 -0800 | [diff] [blame] | 17 | |
Gaurav Shah | ef7510f | 2010-03-31 14:09:31 -0700 | [diff] [blame^] | 18 | misclibs/ - Miscellaneous functions used by userland utilities. |
| 19 | |
| 20 | utility/ - Utilities for generating and verifying signed |
| 21 | firmware and kernel images, as well as arbitrary blobs. |
| 22 | |
| 23 | vfirmware/ and vkernel/ - The main firmware and kernel image |
| 24 | verification modules. It has functions for verifying and manipulating |
| 25 | signed firmware and kernel images. The main files of interest are: |
| 26 | vfirmware/firmware_image_fw.c (verification Functions used in Firmware) |
| 27 | vfirmware/firmware_image.c (functions for userland tools) |
| 28 | vkernel/kernel_image_fw.c (verification functions used in Firmware) |
| 29 | vkernel/kernel_image.c (functions for userland tools) |
Gaurav Shah | 56c9f4d | 2010-03-03 13:15:53 -0800 | [diff] [blame] | 30 | |
| 31 | tests/ - User-land tests and benchmarks that test the reference |
| 32 | implementation. Please have a look at these if you'd like to |
| 33 | understand how to use the reference implementation. |
| 34 | |
| 35 | |
| 36 | ---------- |
| 37 | Some useful utilities: |
| 38 | ---------- |
| 39 | |
| 40 | firmware_utility.c To generate verified boot firmware images. |
| 41 | |
Gaurav Shah | ef7510f | 2010-03-31 14:09:31 -0700 | [diff] [blame^] | 42 | kernel_utility.c To generate verified boot kernel images. |
| 43 | |
Gaurav Shah | 56c9f4d | 2010-03-03 13:15:53 -0800 | [diff] [blame] | 44 | dumpRSAPublicKey.c Dump RSA Public key (from a DER-encoded X509 |
| 45 | certificate) in a format suitable for |
| 46 | use by RSAVerify* functions in |
| 47 | crypto/. |
| 48 | |
| 49 | verify_data.c Verify a given signature on a given file. |
| 50 | |
| 51 | |
| 52 | ---------- |
Gaurav Shah | ef7510f | 2010-03-31 14:09:31 -0700 | [diff] [blame^] | 53 | What is required for a minimal verified boot implementation |
Gaurav Shah | 56c9f4d | 2010-03-03 13:15:53 -0800 | [diff] [blame] | 54 | ---------- |
| 55 | |
Gaurav Shah | ef7510f | 2010-03-31 14:09:31 -0700 | [diff] [blame^] | 56 | 1) cryptolib/ - as a separate module since it will be used by others |
| 57 | parts of the verified boot process. |
Gaurav Shah | 56c9f4d | 2010-03-03 13:15:53 -0800 | [diff] [blame] | 58 | |
Gaurav Shah | ef7510f | 2010-03-31 14:09:31 -0700 | [diff] [blame^] | 59 | 2) common/ - this contains the interface for dealing with memory allocation |
| 60 | and interacting with the TPM. The stubs will need to be replaced with their |
| 61 | firmware-level equivalents. |
Gaurav Shah | 56c9f4d | 2010-03-03 13:15:53 -0800 | [diff] [blame] | 62 | |
Gaurav Shah | ef7510f | 2010-03-31 14:09:31 -0700 | [diff] [blame^] | 63 | 3) Verified Firmware and Kernel image verification - This is the core |
| 64 | of the verified boot implementation. They are implemented under vfirmware |
| 65 | and vkernel (for firmware and kernel image verification respectively). |
Gaurav Shah | 5b730c4 | 2010-03-29 12:50:09 -0700 | [diff] [blame] | 66 | |
Gaurav Shah | ef7510f | 2010-03-31 14:09:31 -0700 | [diff] [blame^] | 67 | firmware_image_fw.c and kernel_image_fw.c : Contain verification logic |
| 68 | used in the firmware. Needed. |
| 69 | |
| 70 | firmware_image.c and kernel_image.c : High level functions used by userland |
| 71 | tools. NOT needed in the firmware. |
| 72 | |
| 73 | cryptolib/, common/, vfirmware/firmware_image_fw.c are part of the RO firmware. |
| 74 | vkernel/kernel_image_fw.c is part of the RW firmware (it verifies the OS kernel). |
| 75 | |
Gaurav Shah | 5b730c4 | 2010-03-29 12:50:09 -0700 | [diff] [blame] | 76 | ---------- |
| 77 | Generating a signed firmware image: |
| 78 | ---------- |
| 79 | |
| 80 | * Step 1: Generate RSA root and signing keys. |
| 81 | |
| 82 | # Root key is always 8192 bits. |
| 83 | $ openssl genrsa -F4 -out root_key.pem 8192 |
| 84 | |
| 85 | # Signing key can be between 1024-8192 bits. |
| 86 | $ openssl genrsa -F4 -out signing_key.pem <1024|2048|4096|8192> |
| 87 | |
| 88 | Note: The -F4 option must be specified to generate RSA keys with |
| 89 | a public exponent of 65535. RSA keys with 3 as a public |
| 90 | exponent (the default) won't work. |
| 91 | |
| 92 | * Step 2: Generate pre-processed public versions of the above keys using |
Gaurav Shah | ef7510f | 2010-03-31 14:09:31 -0700 | [diff] [blame^] | 93 | utility/dumpRSAPublicKey |
Gaurav Shah | 5b730c4 | 2010-03-29 12:50:09 -0700 | [diff] [blame] | 94 | |
| 95 | # dumpRSAPublicKey expects an x509 certificate as input. |
| 96 | $ openssl req -batch -new -x509 -key root_key.pem -out root_key.crt |
| 97 | $ 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^] | 98 | $ utility/dumpRSAPublicKey root_key.crt > root_key.keyb |
| 99 | $ utility/dumpRSAPublicKey signing_key.crt > signing_key.keyb |
Gaurav Shah | 5b730c4 | 2010-03-29 12:50:09 -0700 | [diff] [blame] | 100 | |
| 101 | At this point we have all the requisite keys needed to generate a signed |
| 102 | firmware image. |
| 103 | |
| 104 | .pem RSA Public/Private Key Pair |
| 105 | .crt X509 Key Certificate |
| 106 | .keyb Pre-processed RSA Public Key |
| 107 | |
| 108 | |
Gaurav Shah | ef7510f | 2010-03-31 14:09:31 -0700 | [diff] [blame^] | 109 | * Step 3: Use utility/firmware_utility to generate a signed firmare blob. |
Gaurav Shah | 5b730c4 | 2010-03-29 12:50:09 -0700 | [diff] [blame] | 110 | |
Gaurav Shah | ef7510f | 2010-03-31 14:09:31 -0700 | [diff] [blame^] | 111 | $ utility/firmware_utility --generate \ |
Gaurav Shah | 5b730c4 | 2010-03-29 12:50:09 -0700 | [diff] [blame] | 112 | --root_key root_key.pem \ |
| 113 | --firmware_sign_key signing_key.pem \ |
| 114 | --firmware_sign_key_pub signing_key.keyb \ |
| 115 | --firmware_sign_algorithm <algoid> \ |
| 116 | --firmware_key_version 1 \ |
| 117 | --firmware_version 1 \ |
| 118 | --in <firmware blob file> \ |
| 119 | --out <output file> |
| 120 | |
| 121 | Where <algoid> is based on the signature algorithm to use for firmware |
| 122 | signining. The list of <algoid> specifications can be output by running |
Gaurav Shah | ef7510f | 2010-03-31 14:09:31 -0700 | [diff] [blame^] | 123 | 'utility/firmware_utility' without any arguments. |
Gaurav Shah | 5b730c4 | 2010-03-29 12:50:09 -0700 | [diff] [blame] | 124 | |
| 125 | Note: --firmware_key_version and --firmware_version are part of a signed |
| 126 | image and are used to prevent rollbacks to older version. For testing, |
| 127 | they can just be set valid values. |
| 128 | |
| 129 | |
| 130 | * Step 4: Verify that this image verifies. |
| 131 | |
Gaurav Shah | ef7510f | 2010-03-31 14:09:31 -0700 | [diff] [blame^] | 132 | $ utility/firmware_utility --verify \ |
Gaurav Shah | 5b730c4 | 2010-03-29 12:50:09 -0700 | [diff] [blame] | 133 | --in <signed firmware image> |
| 134 | --root_key_pub root_key.keyb |
| 135 | Verification SUCCESS. |
| 136 | |
| 137 | |
| 138 | Note: The verification functions expects a pointer to the |
| 139 | pre-processed public root key as input. For testing purposes, |
| 140 | root_key.keyb can be stored in RW part of the firmware. For the |
| 141 | final firmware, this will be a fixed public key which cannot be |
| 142 | changed and must be stored in RO firmware. |
| 143 | |
| 144 | ---------- |
| 145 | Generating a signed kernel image: |
| 146 | ---------- |
| 147 | |
| 148 | The steps for generating a signed kernel image are similar to that of |
| 149 | a firmware image. Since verification is chained - RO firmware verifies |
| 150 | RW firmware which verifies the kernel, only the keys change. An additional |
| 151 | kernel signing key must be generated. The firmware signing generated above |
| 152 | is the root key equivalent for signed kernel images. |