blob: e350be65a23e9fd5e233eaeb133be5ef14b66a5c [file] [log] [blame]
Gaurav Shah56c9f4d2010-03-03 13:15:53 -08001This directory contains a reference implementation for Chrome OS
2verified boot in firmware.
3
4----------
5Directory Structure
6----------
7
Gaurav Shahef7510f2010-03-31 14:09:31 -07008The source is organized into distinct modules -
Gaurav Shah56c9f4d2010-03-03 13:15:53 -08009
Bill Richardson0b8f35c2010-05-26 09:18:38 -070010vboot_firmware/ - Contains ONLY the code required by the BIOS to validate
11the secure boot components. There shouldn't be any code in here that signs
12or generates images. BIOS should require ONLY this directory to implement
13secure boot. Refer to vboot_firmware/README for futher details.
Gaurav Shah56c9f4d2010-03-03 13:15:53 -080014
Bill Richardson0b8f35c2010-05-26 09:18:38 -070015cgptlib/ - Work in progress for handling GPT headers. Parts of this will no
16doubt be migrated into vboot_firmware/
Gaurav Shah56c9f4d2010-03-03 13:15:53 -080017
Gaurav Shahef7510f2010-03-31 14:09:31 -070018misclibs/ - Miscellaneous functions used by userland utilities.
19
20utility/ - Utilities for generating and verifying signed
21firmware and kernel images, as well as arbitrary blobs.
22
Bill Richardson0b8f35c2010-05-26 09:18:38 -070023vfirmware/ and vkernel/ - Functions for generating, verifying, and
24manipulating signed firmware and kernel images.
Gaurav Shah56c9f4d2010-03-03 13:15:53 -080025
26tests/ - User-land tests and benchmarks that test the reference
27implementation. Please have a look at these if you'd like to
28understand how to use the reference implementation.
29
30
31----------
32Some useful utilities:
33----------
34
35firmware_utility.c To generate verified boot firmware images.
36
Gaurav Shahef7510f2010-03-31 14:09:31 -070037kernel_utility.c To generate verified boot kernel images.
38
Gaurav Shah56c9f4d2010-03-03 13:15:53 -080039dumpRSAPublicKey.c Dump RSA Public key (from a DER-encoded X509
40 certificate) in a format suitable for
41 use by RSAVerify* functions in
42 crypto/.
43
44verify_data.c Verify a given signature on a given file.
45
46
Gaurav Shahef7510f2010-03-31 14:09:31 -070047
Gaurav Shah5b730c42010-03-29 12:50:09 -070048----------
49Generating a signed firmware image:
50----------
51
52* Step 1: Generate RSA root and signing keys.
53
54# Root key is always 8192 bits.
55$ openssl genrsa -F4 -out root_key.pem 8192
56
57# Signing key can be between 1024-8192 bits.
58$ openssl genrsa -F4 -out signing_key.pem <1024|2048|4096|8192>
59
60Note: The -F4 option must be specified to generate RSA keys with
61 a public exponent of 65535. RSA keys with 3 as a public
62 exponent (the default) won't work.
63
64* Step 2: Generate pre-processed public versions of the above keys using
Gaurav Shahef7510f2010-03-31 14:09:31 -070065 utility/dumpRSAPublicKey
Gaurav Shah5b730c42010-03-29 12:50:09 -070066
67# dumpRSAPublicKey expects an x509 certificate as input.
68$ openssl req -batch -new -x509 -key root_key.pem -out root_key.crt
69$ openssl req -batch -new -x509 -key signing_key.pem -out signing_key.crt
Gaurav Shahef7510f2010-03-31 14:09:31 -070070$ utility/dumpRSAPublicKey root_key.crt > root_key.keyb
71$ utility/dumpRSAPublicKey signing_key.crt > signing_key.keyb
Gaurav Shah5b730c42010-03-29 12:50:09 -070072
73At this point we have all the requisite keys needed to generate a signed
74firmware image.
75
76.pem RSA Public/Private Key Pair
77.crt X509 Key Certificate
78.keyb Pre-processed RSA Public Key
79
80
Gaurav Shahef7510f2010-03-31 14:09:31 -070081* Step 3: Use utility/firmware_utility to generate a signed firmare blob.
Gaurav Shah5b730c42010-03-29 12:50:09 -070082
Gaurav Shahef7510f2010-03-31 14:09:31 -070083$ utility/firmware_utility --generate \
Gaurav Shah5b730c42010-03-29 12:50:09 -070084 --root_key root_key.pem \
85 --firmware_sign_key signing_key.pem \
86 --firmware_sign_key_pub signing_key.keyb \
87 --firmware_sign_algorithm <algoid> \
88 --firmware_key_version 1 \
89 --firmware_version 1 \
90 --in <firmware blob file> \
91 --out <output file>
92
93Where <algoid> is based on the signature algorithm to use for firmware
94signining. The list of <algoid> specifications can be output by running
Gaurav Shahef7510f2010-03-31 14:09:31 -070095'utility/firmware_utility' without any arguments.
Gaurav Shah5b730c42010-03-29 12:50:09 -070096
97Note: --firmware_key_version and --firmware_version are part of a signed
98 image and are used to prevent rollbacks to older version. For testing,
99 they can just be set valid values.
100
101
102* Step 4: Verify that this image verifies.
103
Gaurav Shahef7510f2010-03-31 14:09:31 -0700104$ utility/firmware_utility --verify \
Gaurav Shah5b730c42010-03-29 12:50:09 -0700105 --in <signed firmware image>
106 --root_key_pub root_key.keyb
107Verification SUCCESS.
108
109
110Note: The verification functions expects a pointer to the
111 pre-processed public root key as input. For testing purposes,
112 root_key.keyb can be stored in RW part of the firmware. For the
113 final firmware, this will be a fixed public key which cannot be
114 changed and must be stored in RO firmware.
115
116----------
117Generating a signed kernel image:
118----------
119
120The steps for generating a signed kernel image are similar to that of
121a firmware image. Since verification is chained - RO firmware verifies
122RW firmware which verifies the kernel, only the keys change. An additional
123kernel signing key must be generated. The firmware signing generated above
124is the root key equivalent for signed kernel images.