meta-efi-secure-boot/README.md: update

Signed-off-by: Lans Zhang <jia.zhang@windriver.com>

1 files changed, 162 insertions, 134 deletions

diff --git a/meta-efi-secure-boot/README.md b/meta-efi-secure-boot/README.md
index 12a0c3d..50f78ff 100644
--- a/meta-efi-secure-boot/README.md
+++ b/meta-efi-secure-boot/README.md
@@ -1,36 +1,35 @@
-### EFI secure boot feature
-This feature consists of two widely used secure boot technologies: UEFI Secure
-Boot and MOK Secure Boot.
-
-- UEFI Secure Boot is the industry standard defined in the UEFI spec, allowing the
-images loaded by UEFI BIOS to be verified with the certificates corresponding to
-the trusted keys.
-- MOK (Machine Owner Key) Secure Boot is based on UEFI Secure Boot, adding
-the shim bootloader to chainloader the next stage bootloader with the integrity
-check using the shim-managed certificates corresponding to another set of
-trusted keys which may be different than the trusted keys used by UEFI Secure
-Boot.
-
-In addition, this feature introduces the SELoader as the second-stage bootloader
+### Overview
+This layer consists of two widely used secure boot technologies: UEFI Secure
+Boot and MOK (Machine Owner Key) Secure Boot.
+
+- UEFI Secure Boot is the industry standard defined in the UEFI spec, allowing
+the images loaded by UEFI firmware to be verified with the certificates
+corresponding to the trusted keys.
+- MOK Secure Boot is based on UEFI Secure Boot, adding the shim bootloader to
+chainloader the next stage bootloader with the integrity check using the
+shim-managed certificates corresponding to another set of trusted keys, which
+may be different than the trusted keys used by UEFI Secure Boot.
+
+In addition, this layer introduces the SELoader as the second-stage bootloader
 and eventually chainliader to the third-stage bootloader "grub". With the
 extension provided by SELoader, grub configuration files, kernel (even without
 EFI stub support) and initrd can be authenticated. This capability is not
 available in the shim bootloader.
 
-Grub bootloader is enhanced to support lockdown mode. In this mode, the
+Grub bootloader is also enhanced to support lockdown mode. In this mode, the
 edit, rescue and command line are protected in order to prevent from
-tampering the kernel commandline or loading an unsigned boot component. Hence,
+tampering the kernel command line or loading an unsigned boot component. Hence,
 this lockdown protection can effectively defeat the attempts to disable the
-kernel security mechanisms. The flexibility is also provided if the user
-authentication is enabled. The user authenticated by a password check can enter
-into edit and command line.
+kernel security mechanisms, e.g, globally disable SELinux or IMA. The
+flexibility is also provided with the user authentication in grub. The user
+authenticated by a password check can enter into edit and command line.
 
-Therefore, using UEFI Secure Boot, SELoader, and grub lockdown together, the
-boot process is completely trustworthy.
+Therefore, using UEFI Secure Boot, shim, SELoader, and grub lockdown together,
+the boot process is completely trustworthy.
 
-A complete boot flow with this feature is:
+A complete boot flow looks like as following:
 
-- UEFI BIOS boot manager (UEFI Secure Boot enabled) ->
+- UEFI firmware boot manager (UEFI Secure Boot enabled) ->
   - shim (verified by a DB certificate) ->
     - SELoader (verified by a shim-managed certificate) ->
       - grub (verified by a shim-managed certificate) ->
@@ -38,38 +37,39 @@ A complete boot flow with this feature is:
         - kernel (verified by a shim-managed certificate)
         - initramfs (verified by a shim-managed certificate)
 
-### Quick start for the first boot
+### Quick Start For The First Boot
 - Deploy the rootfs
 
-- Boot up the target board
+- Power up the system
 
 - Enter to BIOS setup and remove the enrolled certificates
   * It is recommended to still turn on UEFI Secure Boot option if allowed.
 
-- Exit BIOS setup and automatically reboot
+- Exit BIOS setup
 
-- Manually launch a reboot via ctrl + alt + del again
+- Manually launch a reboot immediately via Ctrl + Alt + Del
   * Otherwise, a misleading error message about the verification failure
   will be displayed.
 
 - Automatically boot to the boot option "Automatic Certificate Provision" in
   grub boot menu.
 
-- (Optional) Enter into BIOS setup to turn on UEFI Secure Boot option
+- (Optional) Enter to BIOS setup to turn on UEFI Secure Boot option and then
+  exit BIOS setup
 
 - Boot to the system with the protection provided by UEFI and MOK Secure Boot
 
 ### Key Management
 Refer to meta-signing-key/README.md for the initial cognition about key
-management for UEFI Secure Boot.
+management.
 
 Note that the sample key and user key are the concepts in the key signing
 model according to the ownership and secrecy. In UEFI Secure Boot, a policy
-object such as PK, KEK, DB and DBX is mapped to a key managed by the key
-signing model.
+object such as PK, KEK, DB and DBX is always mapped to a key useed by the
+key signing model.
 
 #### Sample Keys
-This feature, by default, use **the sample keys** to sign and verify images for
+This layer, by default, use **the sample keys** to sign and verify images for
 the purpose of development and demonstration. **Please ensure you know what your
 risk is to use the sample keys in your product, because they are completely
 public.**
@@ -78,14 +78,14 @@ The sample keys used for UEFI Secure Boot are centrally placed under
 meta-signing-key/files/uefi_sb_keys/.
 
 - PK.crt  
-  The X509 certificate enrolled to UEFI BIOS, used to update/delete PK/KEK.
+  The X509 certificate enrolled to UEFI firmware, used to update/delete PK/KEK.
 
 - PK.key  
   The private key corresponding to PK.crt, used to sign the EFI signature
   list for PK/KEK enrollment.
 
 - KEK.crt  
-  The X509 certificate enrolled to UEFI BIOS, used to update/delete
+  The X509 certificate enrolled to UEFI firmware, used to update/delete
   DB/DBX.
 
 - KEK.key  
@@ -93,17 +93,17 @@ meta-signing-key/files/uefi_sb_keys/.
   list for DB/DBX enrollment.
 
 - DB.crt  
-  The X509 certificate enrolled to UEFI BIOS, used to verify the images
-  directly loaded by UEFI BIOS.
+  The X509 certificate enrolled to UEFI firmware, used to verify the images
+  directly loaded by UEFI firmware.
 
 - DB.key  
   The private key corresponding to DB.crt, used to sign the images directly
-  loaded by UEFI BIOS.
+  loaded by UEFI firmware.
 
 - DBX  
   This directory contains any number of X509 certificate enrolled to UEFI
-  BIOS, used to blacklist the revoked certificates. The revoked certificates
-  must be PEM-formatted.
+  firmware, used to blacklist the revoked certificates. Note the revoked
+  certificates must be PEM-formatted.
 
 The sample keys used for MOK Secure Boot are centrally placed under
 `meta-signing-key/files/mok_sb_keys/`.
@@ -117,13 +117,13 @@ The sample keys used for MOK Secure Boot are centrally placed under
   either directly or indirectly loaded by shim.
 
 - vendor_cert.crt  
-  Used in the same way as shim_cert.crt. In addition, vendor certificate
-  is the switch to enable shim verification protocol, which facilitates
-  the verification for the SELoader.
+  Act as the same way as shim_cert.crt. In addition, vendor certificate
+  is the switch to enable MOK Verify Protocol, which facilitates the
+  verification for the SELoader and MOK Manager.
 
 - vendor_cert.key  
-  The private key corresponding to vendor_cert.crt, Same fuction as
-  shim_cert.key.
+  The private key corresponding to vendor_cert.crt, acting as the same fuction
+  as shim_cert.key.
 
 - vendor_dbx  
   This directory contains any number of X509 certificate embedded in shim,
@@ -135,139 +135,160 @@ the keys owned by the end user.
 
 #### Automatic Certificate Provision
 The certificate provision is required to enable UEFI Secure Boot. By default,
-the target may be provisioned with the default certificates enrolled during the
-manufacture.
+the system may be already provisioned with default certificates enrolled during
+the manufacture.
 
 In order to use the bootloader and kernel signed by the sample or self-owned
-key to boot up the system, this feature provides a process of autmatic
-certificate provison for the convenience. Refer to the instructions listed in
-the section "Work Flow For The First Boot". The detailed descriptions are
+key to boot up the system, this layer provides a process of automatic
+certificate provison for the convenience. The detailed descriptions are
 given below.
 
 ##### Remove the enrolled certificates in BIOS setup
-The LockDown.efi application is used to run the provision. However,
-LockDown.efi cannot be launched if UEFI Secure Boot is already enabled. In
-addition, the enrolled certificates may be not the ones the user hopes to use.
+The EFI/BOOT/LockDown.efi is used to run the automatic certificate provision.
+However, LockDown.efi cannot be launched if UEFI Secure Boot is already
+enabled. In addition, the enrolled certificates may be not the ones the user
+hopes to use.
 
-The provisioned certificates can be removed in BIOS setup. The detailed steps
-may vary between the boards. Refer to BIOS manual for the details.
+The provisioned certificates can be removed through BIOS setup. The detailed
+steps may vary between the systems. Refer to the corresponding BIOS manual for
+the instructions.
 
-##### Launch the automatic provision
-Lockdown.efi will automatically provision UEFI Secure Boot after removing the
-the provisioned certificates in BIOS setup. More specifically, the PK, KEK,
-DB and DBX (if any) will be enrolled and begin to take affect after a reboot.
+##### Launch the automatic certificate provision
+The Lockdown.efi will automatically provision UEFI Secure Boot after removing
+the enrolled certificates in BIOS setup. More specifically, the new PK, KEK, DB
+and DBX (if any) will be enrolled and begin to take affect after a reboot.
+
+The new PK, KEK, DB and DBX (if any) were built into LockDown.efi during the
+build.
 
 ##### Turn on UEFI Secure Boot option
-If UEFI Secure Boot option is turned off, the user has to enter into BIOS setup
-after provision to manually turn on the option.
+If UEFI Secure Boot option was turned off, the user has to enter to BIOS setup
+again after the automatic certificate provision in order to manually turn on
+this option.
 
-If the option is already enabled when removing the enrolled certificates in
-BIOS setup, this step can be ignored.
+If this option was not turned off when removing the enrolled certificates in
+BIOS setup, this step is skippable.
 
-##### Re-trigger automatic provision
-By default, the "Automatic Certificate Provision" option is hidden in boot
-menu for the first boot. If the user would like to clear the certificates
-provisioned by the "Automatic Certificate Provision" option in BIOS setup, this
-hidden boot option will be shown in boot menu, allowing to re-trigger it when
-necessary.
+##### Re-trigger automatic certificate provision
+The boot option "Automatic Certificate Provision" is hidden in grub boot menu
+for the first boot. If the user would like to clear the certificates
+provisioned by the option "Automatic Certificate Provision" in BIOS setup, this
+hidden boot option will be shown, allowing to re-trigger it if necessary.
 
 ### Signing
 By default, the build system uses DB.key to sign shim, and uses vendor_cert.key
 to sign SELoader, grub, grub configuration file, kernel and initramfs image
 during the build.
 
-### Verficiation
+### Verification
 
-#### UEFI Secure Boot Verification
-UEFI BIOS will validate the integrity of shim bootloader with a certificate in
-DB before running it.
+#### UEFI firmware verification
+UEFI firmware will validate the integrity of shim bootloader with a certificate
+in DB before launching it.
 
-#### Bootloader Verification
-When the shim loads SELoader and SELoader loads grub, if both UEFI Secure Boot
-and MOK Secure Boot are already enabled, the upper bootloader uses a list of
-certificate to check the integrity of lower bootloader.
+#### Bootloader verification
+This layer employs 3-level bootloader for secure boot process. Each former
+bootloader must check the integrity e.g, when the
+SELoader loads grub, if both UEFI Secure Boot and MOK Secure Boot are already
+enabled, the former bootloader uses a list of certificate to check the
+integrity of the later bootloader.
 
 - Blacklist check
-  If the lower bootloader is signed with a key corresponding to a certificate
-  within any of a policy object below, the boot failure will occur.
+  If the later bootloader is signed with a key corresponding to a certificate
+  within any of a policy object below, the later bootloader is denied to
+  launch immediately, without the necessity to go through the following
+  processes.
 
   * Vendor DBX
   * DBX
-  * MokListX (MOK certificate blacklist)
+  * MokListX (the blacklist of MOK certificate)
 
 - Whitelist check
-  If the lower bootloader is signed with a key corresponding to a certificate
-  within any of a policy object below, the boot success will occur.
+  If the later bootloader is signed with a key corresponding to a certificate
+  within any of a policy object below, the later bootloader is granted to
+  launch.
 
   * DB
-  * MokList (MOK certificate whitelist)
+  * MokList (the whitelist of MOK certificate)
   * Shim certificate (only for PE image)
   * Vendor certificate
 
-If the lower bootloader is not signed or signed by a key not corresponding to
-any policy objects mentioned above, the boot failure will occur.
+If the later bootloader is not signed or signed by a key not corresponding to
+any policy objects mentioned above, the later bootloader is denied to launch.
 
-The benefit of these behaviors allow the end user to regulate the secure boot
-even without the ownership of DB on Microsoft certificated hardware.
+The benefit of showing this checklist allows the end user to use an
+appropriater way to manage the key and boot up the system, even without the
+ownership of a signing key, such as the DB key widely used on Microsoft
+certificated hardware.
 
-##### SELoader Verification
+##### SELoader verification
 The SELoader is designed to authenticate the non-PE files, such as grub.cfg,
-kernel (without EFI stub support) and initrd, which cannot be verified by
-the verification protocol registered by the shim loader.
+kernel (without EFI stub support) and initramfs, which cannot be verified by
+the MOK Verify Protocol registered by the 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 verification protocol provided by the shim loader to
-verify the PE file. If only UEFI Secure Boot is enabled, the SELoader just
-simplily calls gBS->LoadImage() and gBS->StartImage() to allow UEFI BIOS
-to verify the PE file.
+Protocol and employs MOK Verify Protocol to verify the PE file. If only
+UEFI Secure Boot is configured and enabled, the SELoader just simplily calls
+gBS->LoadImage() and gBS->StartImage() to allow UEFI firmware to verify the
+PE file.
 
-The SELoader publishes MOK2 verification protocol which provides a flexible
-interface to allow the bootloader to verify the file, file buffer or
-memory buffer without knowing the file format.
+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. This design allows the non-PE files to be
+verified by the same certificate used for authenticating PE files.
 
 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 MOK certificate. The specific
-key is determined by the secure boot scheme you will use.
+certificate, the vendor certificate or a MOK certificate mentioned above.
+The specific key used is determined by the secure boot scheme you will use.
 
-See more details about the SELoader in its README file.
+See more details about README in SELoader.
 
-#### Grub Configuration File Verification
-Grub can call the MOK2 verification protocol registered by the SELoader
-to validate the integrity of grub configuration file before parsing it.
+#### Grub configuration file verification
+Grub is enhanced to have the capability of calling MOK2 Verify Protocol
+registered by the SELoader to validate the integrity of grub configuration
+file before parsing it.
 
 This protection prevents from tampering the grub configuration file from
-disabling certains kernel security mechanism such as selinux, IMA and so on.
+globally disabling certains kernel security mechanism such as SELinux and IMA
+which are activated in kernel command line.
 
-#### Kernel Verification
-When SELoader loads the kernel image with the linux command, if both UEFI
+#### Kernel verification
+When grub loads the kernel image with the command "linux", if both UEFI
 Secure Boot and MOK Secure Boot are already enabled, grub will call the
-verification protocol installed by SELoader to validate the kernel image.
+MOK2 Verify Protocol installed by SELoader to validate the kernel image.
 
-Alternately, if grub loads the kernel image with the chainloader command,
-if both UEFI Secure Boot and MOK Secure Boot are already enabled, grub will
-call the verification protocol installed by shim to validate the kernel image.
+It is recommended to avoid using the command "chainloader" to load kernel
+image. The build system also avoids signing the kernel with EFI-stub
+bootloader.
 
-By default, the kernel image is signed by vendor certificate and then signed
-again to generate the .p7b signature file.
+By default, the kernel image is signed by vendor certificate and generate
+the .p7b signature file.
 
-#### Initramfs Verification
-When SELoader loads the kernel image with the initrd command, if both UEFI
+#### Initramfs verification
+When grub loads the kernel image with the command "initrd", if both UEFI
 Secure Boot and MOK Secure Boot are already enabled, grub will call the
-verification protocol installed by SELoader to validate the initramfs image.
+MOK2 Verify Protocol installed by SELoader to validate the initramfs image.
+
+By default, the initramfs image is signed by vendor certificate and generate
+the .p7b signature file.
 
-#### Verification Failure
+#### Verification failure
 Either situation will cause a failure of verification.
 - A boot component is not signed.
 - A boot component is signed by a key which doesn't correspond to any
-  certificate in whitelists such as DB and shim-managed certificates.
+  certificate in whitelists such as DB and shim-managed certificates as
+  mentioned above.
 - A boot component is signed by a key which corresponds to a certificate in
-  blacklist such as DBX and shim-managed certificates in MOKX.
+  blacklist such as DBX and shim-managed certificates in blacklist as
+  mentioned above.
 
 Each boot component may have different verification failure phenomenon.
-- If SELoader fails signature check, UEFI BIOS boot manager will print an error
-  message about the image authentication failure.
+- If shim fails signature check, UEFI firmware boot manager will print an
+  error message about the image authentication failure.
+- If SELoader fails signature check, shim will print an error message about
+  the security violation.
 - If grub fails signature check, an image authentication failure message is
   printed and the system hangs.
 - If a grub configuration file fails the signature check, an authentication
@@ -276,11 +297,11 @@ Each boot component may have different verification failure phenomenon.
 - If initrd fails signature check, grub returns back to the boot menu.
 
 ### MOK Secure Boot and the shim bootloader
-MOK (Machine Owner Key) Secure Boot is based on UEFI Secure Boot, adding
-the shim bootloader to chainloader the second-stage bootloader
-"SELoader" and eventually chainliader to the third-stage bootloader "grub".
+MOK Secure Boot is based on UEFI Secure Boot, adding the shim bootloader to
+chainloader the second-stage bootloader "SELoader" and eventually chainliader
+to the third-stage bootloader "grub".
 
-[ Quoting: https://github.com/rhinstaller/shim ]
+[ Quoting: https://github.com/rhboot/shim ]
 shim is a trivial EFI application that, when run, attempts to open and
 execute another application. It will initially attempt to do this via the
 standard EFI LoadImage() and StartImage() calls. If these fail (because secure
@@ -306,13 +327,13 @@ by Microsoft. Microsoft provides the signing service (not free), but only
 accept shim bootloader for Linux world. Refer to [Microsoft's signing policy](http://blogs.msdn.com/b/windows_hardware_certification/archive/2013/12/03/microsoft-uefi-ca-signing-policy-updates.aspx).
 
 It is allowed to remove all default certificates and use the self-owned keys to
-provision UEFI Secure Boot, but this is not practical for ODM/OEM devices
-during the manufacture phrase. See the section "Out-of-box Experience".
+provision UEFI firmware, but this is not practical for ODM/OEM devices during
+the manufacture phrase. See the section "Out-of-box Experience".
 
 For a good user experience, shim + SELoader + grub is an excellent combination
 to handle Microsoft certificated hardware. With this model, SELoader and grub
-are signed by a shim-managed certificate without being subject to the limit from
-Microsoft's signing policy, and the manual provision is thus unnecessary.
+are signed by a shim-managed certificate without being subject to the limit
+from Microsoft's signing policy, and the manual provision is thus unnecessary.
 
 #### mokutil and MOK Manager
 mokutil is a tool to import or delete the machines owner keys stored in the
@@ -423,23 +444,23 @@ options to change the operation target from MOK to the following options.
 --revoke-import
 --revoke-delete
 
-##### Handle MOK Secure Boot Failure with MOK Manager
+##### Handle MOK Secure Boot failure with MOK Manager
 If either grub or SELoader is not signed or signed with an unauthorized
-certificate, the shim will prompt the end user a UI called MOK manager to
+certificate, the shim will prompt the end user a UI called MOK Manager to
 guide the user to enroll the certificate or hash of the image.
 
 The policy of the selection between digest and certificate for next step is
 decided by whether the unauthorized grub or SELoader is signed or not.
 
 If the grub or SELoader is not signed at all, you have to always select
-the calculation of the digest based on the file. Note that once grub or SELoader
-is updated and its digest is changed, you have to relaunch the MOK manager
-to enroll the new digests.
+the calculation of the digest based on the file. Note that once grub or
+SELoader is updated and its digest is changed, you have to relaunch the MOK
+Manager to enroll the new digests.
 
 If the grub or SELoader is signed by an unauthorized certificate, enrolling the
 signing certificate is the preferred way. Copy the certificate to the boot
 drive and then select the certificate in MOK manager. Note that the
-certificate for the selection must be **DER formatted**.
+certificate for the selection must be **DER-formatted**.
 
 If doing so, the unauthorized grub or SELoader will be verified successfully
 after exiting MOK Manager.
@@ -458,6 +479,13 @@ Rescue mode is always disabled as long as UEFI Secure Boot is enabled.
 ### Known Issues
 - The 32-bit MOK Secure Boot is not validated. In other words, loading 32-bit
 shim, MOK manager, grub and kernel is not supported.
+- grub module is not supported by SELoader for the integrity check.
 
 ### Reference
-[OpenEmbedded layer for EFI secure boot features](https://github.com/jiazhang0/meta-efi-secure-boot)
+[shim - implement MOK Verify Protocol](https://github.com/rhboot/shim)
+
+[SELoader - implement MOK2 Verify Protocol](https://github.com/jiazhang0/SELoader)
+
+[grub - Mok2Verify patch](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)
+
+[SecureCore - a reference implementation based on OpenEmbedded](https://github.com/jiazhang0/SecureCore)