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

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.