Secure EFI Loader
=================

The SELoader is designed to authenticate the non-PE files, such as grub
configuration, initrd, grub modules, which cannot be verified by the MOK
Verify Protocol registered by shim loader.

In order to conveniently authenticate the PE file with gBS->LoadImage()
and gBS->StartImage(), the SELoader hooks EFI Security2 Architectural
Protocol and employs MOK Verify Protocol to verify the PE file. If only
UEFI Secure Boot is enabled, the SELoader just simplily calls
gBS->LoadImage() and gBS->StartImage() to allow BIOS to verify PE file.

The SELoader publishes MOK2 Verify Protocol which provides a flexible
interface to allow the bootloader to verify the file, file buffer or
memory buffer without knowing the file format.

In order to establish the chain of trust, the SELoader is required to be
signed by a private key corresponding to a DB certificate, the shim
certificate, the vendor certificate or a shim MOK certificate. The specific
key is determined by the Secure Boot scheme you will use.

Using UEFI Secure Boot, MOK Verify Protocol and the SELoader together, the
boot process is completely trustworthy.

ESP Layout
----------
A typical ESP layout for x86-64 looks like below, e.g,

.
├── EFI
│   └── BOOT
│       ├── bootx64.efi
│       ├── grub.cfg
│       ├── grub.cfg.p7b
│       ├── grubx64.efi
│       ├── Hash2DxeCrypto.efi
│       ├── LockDown.efi
│       ├── mmx64.efi
│       ├── Pkcs7VerifyDxe.efi
│       ├── SELoaderx64.efi
│       └── x86_64-efi
│           ├── ...
│           ├── mok2verify.mod
│           └── ...
├── images
│   ├── bzImage
│   ├── bzImage.p7b
│   ├── initrd
│   └── initrd.p7b
└── startup.nsh

where:
- bootx64.efi
  The first stage shim loader, signed by DB key and authenticated by UEFI BIOS
  boot manager.
- SELoaderx64.efi
  The second stage loader, authenticated by the shim loader with the vendor
  certificate, shim certificate, MOK certificate or DB certificate.
- grubx64.efi
  The third stage loader, authenticated by the SELoader with the same objects
  as mentioned in SELoaderx64.efi.
- grub.cfg
  grub configuration file.
- grub.cfg.p7b
  The signature file of grub.cfg, authenticated by the SELoader.
- mok2verify.mod
  Providing MOK2 Verify Protocol support, allowing the grub loader to call
  SELoader to verify grub.cfg.p7b, bzImage.p7b and initrd.p7b.
- bzImage
  Linux kernel.
- bzImage.p7b
  The signature file of bzImage, authenticated by the SELoader.
- initrd
  initramfs image.
- initrd.p7b
  The signature file of initrd, authenticated by the SELoader.
- LockDown.efi
  Run the automatical certificate provision for UEFI Secure Boot.
- mmx64.efi
  MOK Secure Boot manager, authenticated by the shim loader.
- Pkcs7VerifyDxe.efi
  Providing EFI Pkcs7 Verify Protocol support, authenticated by the SELoader.
- Hash2DxeCrypto.efi
  Providing EFI Hash2 Protocol support, authenticated by the SELoader.
- startup.nsh
  UEFI shell bootstrap script.

All efi binaries are signed with either DB.key or vendor_cert.key per the
secure boot scheme you choose. Refer to meta-secure-env for practical secure
boot implementation, and the signing tool sbsigntool.

Note that the SELoader can be also used alone without the shim loader.

EFI Pkcs7 Verify Protocol
-------------------------
The SELoader employs EFI PKCS7 Verify Protocol available since UEFI
Specification version 2.5 to verify the signature to prove the integrity
of checked file.

If your BIOS doesn't support this protocol, it is recommended to update
the BIOS to the latest. If the latest still doesn't support the protocol,
the SELoader is able to load the Pkcs7VerifyDxe.efi driver if available.
Usually, the Pkcs7VerifyDxe.efi driver is located in the directory where
the SELoader resides on ESP.

You can build the Pkcs7VerifyDxe.efi driver from the scratch if you would
like to do it. Refer to Bin/README for the instructions.

Known Issues
------------
- The PKCS#7 detached signature format (.p7s) is not supported.

References
----------
libsign - the signing tool used to generate SELoader PKCS#7 signature
https://github.com/jiazhang0/libsign

grub - Mok2Verify patch to verify the grub.cfg, linux kernel and initrd
https://github.com/jiazhang0/meta-secure-core/blob/master/meta-efi-secure-boot/recipes-bsp/grub/grub-efi/mok2verify-support-to-verify-non-PE-file-with-PKCS-7.patch

shim - implement MOK verify protocol
https://github.com/rhboot/shim

meta-secure-core - a practical secure boot implementation based on oe-core
https://github.com/jiazhang0/meta-secure-core

SecureCore - a complete OpenEmbedded/Poky-compatible reference implementation based on meta-secure-core
https://github.com/jiazhang0/SecureCore