Home | History | Annotate | Download | only in vboot_reference
      1 This directory contains a reference implementation for Chrome OS
      2 verified boot in firmware.
      3 
      4 ----------
      5 Directory Structure
      6 ----------
      7 
      8 The source is organized into distinct modules -
      9 
     10 firmware/
     11 
     12   Contains ONLY the code required by the BIOS to validate the secure boot
     13   components. There shouldn't be any code in here that signs or generates
     14   images. BIOS should require ONLY this directory to implement secure boot.
     15   Refer to firmware/README for futher details.
     16 
     17 cgpt/
     18 
     19   Utility to read/write/modify GPT partitions. Similar to GNU parted or any
     20   other GPT tool, but this has support for Chrome OS extensions.
     21 
     22 host/
     23 
     24   Miscellaneous functions needed by userland utilities.
     25 
     26 futility/
     27 
     28   The "firmware utility" tool, used to create, sign, and validate Chrome OS
     29   images.
     30 
     31 utility/
     32 
     33   Random other utilities, not necesssarily related to verified boot as such.
     34 
     35 tests/
     36 
     37   User-land tests and benchmarks that test the reference implementation.
     38   Please have a look at these if you'd like to understand how to use the
     39   reference implementation.
     40 
     41 build/
     42 
     43   The output directory where the generated files will be placed, and where
     44   tests are run.
     45 
     46 scripts/
     47 
     48   Tools and scripts used to generate and use new signing keypairs. These are
     49   typically used only on a secure machine.
     50 
     51 
     52 --------------------
     53 Building and testing
     54 --------------------
     55 
     56 The suite can be built on the host or in the chroot environment.
     57 
     58 Building on the host could fail if certain packages are not installed. If
     59 there are host environment build problems due to missing .h files, try
     60 researching what packages the files belong to and install the missing packages
     61 before reporting a problem.
     62 
     63 
     64 The commands are the more-or-less expected ones:
     65 
     66   make
     67   make runtests
     68   make install [ DESTDIR=/usr/local ]
     69 
     70 
     71 
     72 ----------
     73 Some useful utilities:
     74 ----------
     75 
     76 futility vbutil_key         Convert a public key into .vbpubk format
     77 futility vbutil_keyblock    Wrap a public key inside a signature and checksum
     78 futility vbutil_firmware    Create a .vblock with signature info for a
     79                               firmware image
     80 futility vbutil_kernel      Pack a kernel image, bootloader, and config into
     81                               a signed binary
     82 
     83 dumpRSAPublicKey            Dump RSA Public key (from a DER-encoded X509
     84                             certificate) in a format suitable for use by
     85                             RSAVerify* functions in crypto/.
     86 
     87 verify_data.c               Verify a given signature on a given file.
     88 
     89 
     90 
     91 ----------
     92 Generating a signed firmware image:
     93 ----------
     94 
     95 * Step 0: Build the tools, install them somewhere.
     96 
     97 * Step 1: Generate RSA root and signing keys.
     98 
     99   The root key is always 8192 bits.
    100 
    101     $ openssl genrsa -F4 -out root_key.pem 8192
    102 
    103   The signing key can be between 1024-8192 bits.
    104 
    105     $ openssl genrsa -F4 -out signing_key.pem <1024|2048|4096|8192>
    106 
    107   Note: The -F4 option must be specified to generate RSA keys with a public
    108   exponent of 65535. RSA keys with 3 as a public exponent (the default)
    109   won't work.
    110 
    111 * Step 2: Generate pre-processed public versions of the above keys using
    112           dumpRSAPublicKey. This utility expects an x509 certificate as
    113           input, and emits an intermediate representation for further
    114           processing.
    115 
    116     $ openssl req -batch -new -x509 -key root_key.pem -out root_key.crt
    117     $ openssl req -batch -new -x509 -key signing_key.pem -out signing_key.crt
    118     $ dumpRSAPublicKey root_key.crt > root_key.keyb
    119     $ dumpRSAPublicKey signing_key.crt > signing_key.keyb
    120 
    121 ************** TODO: STUFF PAST HERE IS OUT OF DATE ***************
    122 
    123 At this point we have all the requisite keys needed to generate a signed
    124 firmware image.
    125 
    126 .pem   RSA Public/Private Key Pair
    127 .crt   X509 Key Certificate
    128 .keyb  Pre-processed RSA Public Key
    129 
    130 
    131 * Step 3: Use utility/firmware_utility to generate a signed firmare blob.
    132 
    133 $ utility/firmware_utility --generate \
    134   --root_key root_key.pem \
    135   --firmware_sign_key signing_key.pem \
    136   --firmware_sign_key_pub signing_key.keyb \
    137   --firmware_sign_algorithm <algoid> \
    138   --firmware_key_version 1 \
    139   --firmware_version 1 \
    140   --in <firmware blob file> \
    141   --out <output file>
    142 
    143 Where <algoid> is based on the signature algorithm to use for firmware
    144 signining. The list of <algoid> specifications can be output by running
    145 'utility/firmware_utility' without any arguments.
    146 
    147 Note: --firmware_key_version and --firmware_version are part of a signed
    148       image and are used to prevent rollbacks to older version. For testing,
    149       they can just be set to valid values.
    150 
    151 
    152 * Step 4: Verify that this image verifies.
    153 
    154 $ utility/firmware_utility --verify \
    155                          --in <signed firmware image>
    156                          --root_key_pub root_key.keyb
    157 Verification SUCCESS.
    158 
    159 
    160 Note: The verification functions expects a pointer to the
    161       pre-processed public root key as input. For testing purposes,
    162       root_key.keyb can be stored in RW part of the firmware. For the
    163       final firmware, this will be a fixed public key which cannot be
    164       changed and must be stored in RO firmware.
    165 
    166 ----------
    167 Generating a signed kernel image:
    168 ----------
    169 
    170 The steps for generating a signed kernel image are similar to that of
    171 a firmware image. Since verification is chained - RO firmware verifies
    172 RW firmware which verifies the kernel, only the keys change. An additional
    173 kernel signing key must be generated. The firmware signing generated above
    174 is the root key equivalent for signed kernel images.
    175