blob: c2df44bf3fe1b19330a77ec83259a7c63a45daed [file] [log] [blame]
Gaurav Shah56c9f4d2010-03-03 13:15:53 -08001This directory contains a reference implementation for Chrome OS
2verified boot in firmware.
5Directory Structure
Gaurav Shahef7510f2010-03-31 14:09:31 -07008The source is organized into distinct modules -
Gaurav Shah56c9f4d2010-03-03 13:15:53 -08009
Gaurav Shahfc70d722010-03-31 13:26:55 -070010cryptolib/ - Contains the implementation for the crypto library. This
Gaurav Shah56c9f4d2010-03-03 13:15:53 -080011includes implementations for SHA1, SHA256, SHA512, and RSA signature
12verification (for PKCS #1 v1.5 signatures).
Gaurav Shahef7510f2010-03-31 14:09:31 -070014common/ - Utility functions and stub implementations for wrapper
15functions used in the verification code. These stub implementations
16will need to be replaced with appropriate firmware equivalents.
Gaurav Shah56c9f4d2010-03-03 13:15:53 -080017
Gaurav Shahef7510f2010-03-31 14:09:31 -070018misclibs/ - Miscellaneous functions used by userland utilities.
20utility/ - Utilities for generating and verifying signed
21firmware and kernel images, as well as arbitrary blobs.
23vfirmware/ and vkernel/ - The main firmware and kernel image
24verification modules. It has functions for verifying and manipulating
25signed 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 Shah56c9f4d2010-03-03 13:15:53 -080030
31tests/ - User-land tests and benchmarks that test the reference
32implementation. Please have a look at these if you'd like to
33understand how to use the reference implementation.
37Some useful utilities:
40firmware_utility.c To generate verified boot firmware images.
Gaurav Shahef7510f2010-03-31 14:09:31 -070042kernel_utility.c To generate verified boot kernel images.
Gaurav Shah56c9f4d2010-03-03 13:15:53 -080044dumpRSAPublicKey.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/.
49verify_data.c Verify a given signature on a given file.
Gaurav Shahef7510f2010-03-31 14:09:31 -070053What is required for a minimal verified boot implementation
Gaurav Shah56c9f4d2010-03-03 13:15:53 -080054----------
Gaurav Shahef7510f2010-03-31 14:09:31 -0700561) cryptolib/ - as a separate module since it will be used by others
57parts of the verified boot process.
Gaurav Shah56c9f4d2010-03-03 13:15:53 -080058
Gaurav Shahef7510f2010-03-31 14:09:31 -0700592) common/ - this contains the interface for dealing with memory allocation
60and interacting with the TPM. The stubs will need to be replaced with their
61firmware-level equivalents.
Gaurav Shah56c9f4d2010-03-03 13:15:53 -080062
Gaurav Shahef7510f2010-03-31 14:09:31 -0700633) Verified Firmware and Kernel image verification - This is the core
64of the verified boot implementation. They are implemented under vfirmware
65and vkernel (for firmware and kernel image verification respectively).
Gaurav Shah5b730c42010-03-29 12:50:09 -070066
Gaurav Shahef7510f2010-03-31 14:09:31 -070067firmware_image_fw.c and kernel_image_fw.c : Contain verification logic
68 used in the firmware. Needed.
70firmware_image.c and kernel_image.c : High level functions used by userland
71 tools. NOT needed in the firmware.
73cryptolib/, common/, vfirmware/firmware_image_fw.c are part of the RO firmware.
74vkernel/kernel_image_fw.c is part of the RW firmware (it verifies the OS kernel).
Gaurav Shah5b730c42010-03-29 12:50:09 -070076----------
77Generating a signed firmware image:
80* Step 1: Generate RSA root and signing keys.
82# Root key is always 8192 bits.
83$ openssl genrsa -F4 -out root_key.pem 8192
85# Signing key can be between 1024-8192 bits.
86$ openssl genrsa -F4 -out signing_key.pem <1024|2048|4096|8192>
88Note: 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.
92* Step 2: Generate pre-processed public versions of the above keys using
Gaurav Shahef7510f2010-03-31 14:09:31 -070093 utility/dumpRSAPublicKey
Gaurav Shah5b730c42010-03-29 12:50:09 -070094
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 Shahef7510f2010-03-31 14:09:31 -070098$ utility/dumpRSAPublicKey root_key.crt > root_key.keyb
99$ utility/dumpRSAPublicKey signing_key.crt > signing_key.keyb
Gaurav Shah5b730c42010-03-29 12:50:09 -0700100
101At this point we have all the requisite keys needed to generate a signed
102firmware image.
104.pem RSA Public/Private Key Pair
105.crt X509 Key Certificate
106.keyb Pre-processed RSA Public Key
Gaurav Shahef7510f2010-03-31 14:09:31 -0700109* Step 3: Use utility/firmware_utility to generate a signed firmare blob.
Gaurav Shah5b730c42010-03-29 12:50:09 -0700110
Gaurav Shahef7510f2010-03-31 14:09:31 -0700111$ utility/firmware_utility --generate \
Gaurav Shah5b730c42010-03-29 12:50:09 -0700112 --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>
121Where <algoid> is based on the signature algorithm to use for firmware
122signining. The list of <algoid> specifications can be output by running
Gaurav Shahef7510f2010-03-31 14:09:31 -0700123'utility/firmware_utility' without any arguments.
Gaurav Shah5b730c42010-03-29 12:50:09 -0700124
125Note: --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.
130* Step 4: Verify that this image verifies.
Gaurav Shahef7510f2010-03-31 14:09:31 -0700132$ utility/firmware_utility --verify \
Gaurav Shah5b730c42010-03-29 12:50:09 -0700133 --in <signed firmware image>
134 --root_key_pub root_key.keyb
135Verification SUCCESS.
138Note: 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.
145Generating a signed kernel image:
148The steps for generating a signed kernel image are similar to that of
149a firmware image. Since verification is chained - RO firmware verifies
150RW firmware which verifies the kernel, only the keys change. An additional
151kernel signing key must be generated. The firmware signing generated above
152is the root key equivalent for signed kernel images.