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