README.md

   1 # shim, a first-stage UEFI bootloader
   2
   3 shim is a trivial EFI application that, when run, attempts to open and
   4 execute another application. It will initially attempt to do this via the
   5 standard EFI `LoadImage()` and `StartImage()` calls. If these fail (because Secure
   6 Boot is enabled and the binary is not signed with an appropriate key, for
   7 instance) it will then validate the binary against a built-in certificate. If
   8 this succeeds and if the binary or signing key are not forbidden then shim
   9 will relocate and execute the binary.
  10
  11 shim will also install a protocol which permits the second-stage bootloader
  12 to perform similar binary validation. This protocol has a GUID as described
  13 in the shim.h header file and provides a single entry point. On 64-bit systems
  14 this entry point expects to be called with SysV ABI rather than MSABI, so calls
  15 to it should not be wrapped.
  16
  17 On systems with a TPM chip enabled and supported by the system firmware,
  18 shim will extend various PCRs with the digests of the targets it is
  19 loading.  A full list is in the file [README.tpm](README.tpm) .
  20
  21 To use shim, simply place a DER-encoded public certificate in a file such as
  22 pub.cer and build with `make VENDOR_CERT_FILE=pub.cer`.
  23
  24 There are a couple of build options, and a couple of ways to customize the
  25 build, described in [BUILDING](BUILDING).
  26
  27 See the [test plan](testplan.txt), and file a ticket if anything fails!