VBoot ReferenceL Add instructions to generate (self-)signed firmware images.

Review URL: http://codereview.chromium.org/1573001

1 files changed, 78 insertions, 0 deletions

diff --git a/README b/README
index fda6aaf4..94d6b2ed 100644
--- a/README
+++ b/README
@@ -56,3 +56,81 @@ 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.
 
+
+---------- 
+Generating a signed firmware image: 
+----------
+
+* Step 1: Generate RSA root and signing keys.
+
+# Root key is always 8192 bits. 
+$ openssl genrsa -F4 -out root_key.pem 8192
+
+# Signing key can be between 1024-8192 bits.
+$ openssl genrsa -F4 -out signing_key.pem <1024|2048|4096|8192>
+
+Note: The -F4 option must be specified to generate RSA keys with
+      a public exponent of 65535. RSA keys with 3 as a public
+      exponent (the default) won't work.
+
+* Step 2: Generate pre-processed public versions of the above keys using
+        utils/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
+
+At this point we have all the requisite keys needed to generate a signed
+firmware image.
+
+.pem   RSA Public/Private Key Pair
+.crt   X509 Key Certificate
+.keyb  Pre-processed RSA Public Key
+
+
+* Step 3: Use utils/firmware_utility to generate a signed firmare blob.
+
+$ utils/firmware_utility --generate \
+  --root_key root_key.pem \
+  --firmware_sign_key signing_key.pem \
+  --firmware_sign_key_pub signing_key.keyb \
+  --firmware_sign_algorithm <algoid> \
+  --firmware_key_version 1 \
+  --firmware_version 1 \
+  --in <firmware blob file> \
+  --out <output file>
+
+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.
+
+Note: --firmware_key_version and --firmware_version are part of a signed 
+      image and are used to prevent rollbacks to older version. For testing,
+      they can just be set valid values. 
+
+
+* Step 4: Verify that this image verifies.
+
+$ utils/firmware_utility --verify \
+                         --in <signed firmware image>
+                         --root_key_pub root_key.keyb
+Verification SUCCESS.
+
+
+Note: The verification functions expects a pointer to the
+      pre-processed public root key as input. For testing purposes,
+      root_key.keyb can be stored in RW part of the firmware. For the
+      final firmware, this will be a fixed public key which cannot be
+      changed and must be stored in RO firmware.
+
+---------- 
+Generating a signed kernel image: 
+----------
+
+The steps for generating a signed kernel image are similar to that of
+a firmware image. Since verification is chained - RO firmware verifies
+RW firmware which verifies the kernel, only the keys change. An additional
+kernel signing key must be generated. The firmware signing generated above
+is the root key equivalent for signed kernel images.