Index: src/platform/vboot_reference/README |
diff --git a/src/platform/vboot_reference/README b/src/platform/vboot_reference/README |
index cfe461d0e3a8799bdb1d59c7f6d97a6b55f5ee72..c2df44bf3fe1b19330a77ec83259a7c63a45daed 100644 |
--- a/src/platform/vboot_reference/README |
+++ b/src/platform/vboot_reference/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. |