• Home
  • History
  • Annotate
  • only in /external/vboot_reference/
NameDateSize

..10-Aug-201812 KiB

.gitignore10-Aug-2018248

Android.mk10-Aug-20185.3 KiB

cgpt/10-Aug-20184 KiB

emerge_test.sh10-Aug-20181.6 KiB

firmware/10-Aug-20184 KiB

futility/10-Aug-20184 KiB

host/10-Aug-20184 KiB

inherit-review-settings-ok10-Aug-20180

LICENSE10-Aug-20181.5 KiB

Makefile10-Aug-201843.2 KiB

MODULE_LICENSE_BSD10-Aug-20180

msc/10-Aug-20184 KiB

NOTICE10-Aug-20181.5 KiB

OWNERS10-Aug-201841

PRESUBMIT.cfg10-Aug-2018150

README10-Aug-20185.3 KiB

scripts/10-Aug-20184 KiB

tests/10-Aug-20184 KiB

utility/10-Aug-20184 KiB

vboot_host.pc.in10-Aug-2018253

WATCHLISTS10-Aug-2018380

README

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
51
52--------------------
53Building and testing
54--------------------
55
56The suite can be built on the host or in the chroot environment.
57
58Building on the host could fail if certain packages are not installed. If
59there are host environment build problems due to missing .h files, try
60researching what packages the files belong to and install the missing packages
61before reporting a problem.
62
63
64The commands are the more-or-less expected ones:
65
66  make
67  make runtests
68  make install [ DESTDIR=/usr/local ]
69
70
71
72----------
73Some useful utilities:
74----------
75
76futility vbutil_key         Convert a public key into .vbpubk format
77futility vbutil_keyblock    Wrap a public key inside a signature and checksum
78futility vbutil_firmware    Create a .vblock with signature info for a
79                              firmware image
80futility vbutil_kernel      Pack a kernel image, bootloader, and config into
81                              a signed binary
82
83dumpRSAPublicKey            Dump RSA Public key (from a DER-encoded X509
84                            certificate) in a format suitable for use by
85                            RSAVerify* functions in crypto/.
86
87verify_data.c               Verify a given signature on a given file.
88
89
90
91----------
92Generating a signed firmware image:
93----------
94
95* Step 0: Build the tools, install them somewhere.
96
97* Step 1: Generate RSA root and signing keys.
98
99  The root key is always 8192 bits.
100
101    $ openssl genrsa -F4 -out root_key.pem 8192
102
103  The signing key can be between 1024-8192 bits.
104
105    $ openssl genrsa -F4 -out signing_key.pem <1024|2048|4096|8192>
106
107  Note: The -F4 option must be specified to generate RSA keys with a public
108  exponent of 65535. RSA keys with 3 as a public exponent (the default)
109  won't work.
110
111* Step 2: Generate pre-processed public versions of the above keys using
112          dumpRSAPublicKey. This utility expects an x509 certificate as
113          input, and emits an intermediate representation for further
114          processing.
115
116    $ openssl req -batch -new -x509 -key root_key.pem -out root_key.crt
117    $ openssl req -batch -new -x509 -key signing_key.pem -out signing_key.crt
118    $ dumpRSAPublicKey root_key.crt > root_key.keyb
119    $ dumpRSAPublicKey signing_key.crt > signing_key.keyb
120
121************** TODO: STUFF PAST HERE IS OUT OF DATE ***************
122
123At this point we have all the requisite keys needed to generate a signed
124firmware image.
125
126.pem   RSA Public/Private Key Pair
127.crt   X509 Key Certificate
128.keyb  Pre-processed RSA Public Key
129
130
131* Step 3: Use utility/firmware_utility to generate a signed firmare blob.
132
133$ utility/firmware_utility --generate \
134  --root_key root_key.pem \
135  --firmware_sign_key signing_key.pem \
136  --firmware_sign_key_pub signing_key.keyb \
137  --firmware_sign_algorithm <algoid> \
138  --firmware_key_version 1 \
139  --firmware_version 1 \
140  --in <firmware blob file> \
141  --out <output file>
142
143Where <algoid> is based on the signature algorithm to use for firmware
144signining. The list of <algoid> specifications can be output by running
145'utility/firmware_utility' without any arguments.
146
147Note: --firmware_key_version and --firmware_version are part of a signed
148      image and are used to prevent rollbacks to older version. For testing,
149      they can just be set to valid values.
150
151
152* Step 4: Verify that this image verifies.
153
154$ utility/firmware_utility --verify \
155                         --in <signed firmware image>
156                         --root_key_pub root_key.keyb
157Verification SUCCESS.
158
159
160Note: The verification functions expects a pointer to the
161      pre-processed public root key as input. For testing purposes,
162      root_key.keyb can be stored in RW part of the firmware. For the
163      final firmware, this will be a fixed public key which cannot be
164      changed and must be stored in RO firmware.
165
166----------
167Generating a signed kernel image:
168----------
169
170The steps for generating a signed kernel image are similar to that of
171a firmware image. Since verification is chained - RO firmware verifies
172RW firmware which verifies the kernel, only the keys change. An additional
173kernel signing key must be generated. The firmware signing generated above
174is the root key equivalent for signed kernel images.
175