summaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
authorGaurav Shah <gauravsh@chromium.org>2010-03-31 14:09:31 -0700
committerGaurav Shah <gauravsh@chromium.org>2010-03-31 14:09:31 -0700
commitef7510fe405ffe3479890f9008730939987df240 (patch)
tree01f777b20aacbdf89895094b8c188310644367d3 /README
parentfc70d72aaab4d558e39ec43832375267603bfd93 (diff)
downloadvboot-ef7510fe405ffe3479890f9008730939987df240.tar.gz
Updated README
I clobbered my branch associated with the last CL. This is a new issue with the same change. Review URL: http://codereview.chromium.org/1584005
Diffstat (limited to 'README')
-rw-r--r--README70
1 files changed, 43 insertions, 27 deletions
diff --git a/README b/README
index cfe461d0..c2df44bf 100644
--- a/README
+++ b/README
@@ -5,23 +5,28 @@ verified boot in firmware.
Directory Structure
----------
-include/ - Contains all the code headers. firmware_image.h and
-kernel_image.h contains the structures that represent a verified boot
-firmware and kernel image. Note that the
+The source is organized into distinct modules -
cryptolib/ - Contains the implementation for the crypto library. This
includes implementations for SHA1, SHA256, SHA512, and RSA signature
verification (for PKCS #1 v1.5 signatures).
-common/ - Contains some utility functions and stub implementations for
-certain wrapper functions used in the verification code. Some of these
-(for example Free(), Malloc()) will need to be replaced with
-appropriate firmware-land equivalent.
+common/ - Utility functions and stub implementations for wrapper
+functions used in the verification code. These stub implementations
+will need to be replaced with appropriate firmware equivalents.
-utils/ - This contains the implementation of kernel and firmware image
-verification (see firmware_image.c and kernel_image.c) and some
-utilities (e.g. firmware_utility - for generating verified boot
-firmware images).
+misclibs/ - Miscellaneous functions used by userland utilities.
+
+utility/ - Utilities for generating and verifying signed
+firmware and kernel images, as well as arbitrary blobs.
+
+vfirmware/ and vkernel/ - The main firmware and kernel image
+verification modules. It has functions for verifying and manipulating
+signed firmware and kernel images. The main files of interest are:
+ vfirmware/firmware_image_fw.c (verification Functions used in Firmware)
+ vfirmware/firmware_image.c (functions for userland tools)
+ vkernel/kernel_image_fw.c (verification functions used in Firmware)
+ vkernel/kernel_image.c (functions for userland tools)
tests/ - User-land tests and benchmarks that test the reference
implementation. Please have a look at these if you'd like to
@@ -34,6 +39,8 @@ Some useful utilities:
firmware_utility.c To generate verified boot firmware images.
+kernel_utility.c To generate verified boot kernel images.
+
dumpRSAPublicKey.c Dump RSA Public key (from a DER-encoded X509
certificate) in a format suitable for
use by RSAVerify* functions in
@@ -43,20 +50,29 @@ verify_data.c Verify a given signature on a given file.
----------
-Here's what is required for a minimal verified boot implementation
+What is required for a minimal verified boot implementation
----------
-1) Crypto implementation from crypto/. The verified boot code should
-use the wrappers from rsa_utility.h and sha_utility.h - RSAVerify_f()
-and Digest*() functions.
+1) cryptolib/ - as a separate module since it will be used by others
+parts of the verified boot process.
+
+2) common/ - this contains the interface for dealing with memory allocation
+and interacting with the TPM. The stubs will need to be replaced with their
+firmware-level equivalents.
+
+3) Verified Firmware and Kernel image verification - This is the core
+of the verified boot implementation. They are implemented under vfirmware
+and vkernel (for firmware and kernel image verification respectively).
-2) Verified Firmware and Kernel image verification functions - only
-functions that work on binary blobs (VerifyFirmware() and
-VerifyKernel()) are required. The functions that work on Firmware and
-Kernel images (e.g. VerifyFirmwareImage()) are only useful for
-user-land utilities that manipulate signed firmware and kernel images.
+firmware_image_fw.c and kernel_image_fw.c : Contain verification logic
+ used in the firmware. Needed.
+firmware_image.c and kernel_image.c : High level functions used by userland
+ tools. NOT needed in the firmware.
+cryptolib/, common/, vfirmware/firmware_image_fw.c are part of the RO firmware.
+vkernel/kernel_image_fw.c is part of the RW firmware (it verifies the OS kernel).
+
----------
Generating a signed firmware image:
----------
@@ -74,13 +90,13 @@ Note: The -F4 option must be specified to generate RSA keys with
exponent (the default) won't work.
* Step 2: Generate pre-processed public versions of the above keys using
- utils/dumpRSAPublicKey
+ utility/dumpRSAPublicKey
# dumpRSAPublicKey expects an x509 certificate as input.
$ openssl req -batch -new -x509 -key root_key.pem -out root_key.crt
$ openssl req -batch -new -x509 -key signing_key.pem -out signing_key.crt
-$ utils/dumpRSAPublicKey root_key.crt > root_key.keyb
-$ utils/dumpRSAPublicKey signing_key.crt > signing_key.keyb
+$ utility/dumpRSAPublicKey root_key.crt > root_key.keyb
+$ utility/dumpRSAPublicKey signing_key.crt > signing_key.keyb
At this point we have all the requisite keys needed to generate a signed
firmware image.
@@ -90,9 +106,9 @@ firmware image.
.keyb Pre-processed RSA Public Key
-* Step 3: Use utils/firmware_utility to generate a signed firmare blob.
+* Step 3: Use utility/firmware_utility to generate a signed firmare blob.
-$ utils/firmware_utility --generate \
+$ utility/firmware_utility --generate \
--root_key root_key.pem \
--firmware_sign_key signing_key.pem \
--firmware_sign_key_pub signing_key.keyb \
@@ -104,7 +120,7 @@ $ utils/firmware_utility --generate \
Where <algoid> is based on the signature algorithm to use for firmware
signining. The list of <algoid> specifications can be output by running
-'utils/firmware_utility' without any arguments.
+'utility/firmware_utility' without any arguments.
Note: --firmware_key_version and --firmware_version are part of a signed
image and are used to prevent rollbacks to older version. For testing,
@@ -113,7 +129,7 @@ Note: --firmware_key_version and --firmware_version are part of a signed
* Step 4: Verify that this image verifies.
-$ utils/firmware_utility --verify \
+$ utility/firmware_utility --verify \
--in <signed firmware image>
--root_key_pub root_key.keyb
Verification SUCCESS.