doc: eficonfig: add description for UEFI Secure Boot Configuration

This commits adds the description for the UEFI Secure Boot
Configuration through the eficonfig menu.

Signed-off-by: Masahisa Kojima <masahisa.kojima@linaro.org>

Redacted the complete document.
Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>

1 files changed, 61 insertions, 29 deletions

diff --git a/doc/usage/cmd/eficonfig.rst b/doc/usage/cmd/eficonfig.rst
index 340ebc80db..30eb72bfd0 100644
--- a/doc/usage/cmd/eficonfig.rst
+++ b/doc/usage/cmd/eficonfig.rst
@@ -13,49 +13,43 @@ Synopsis
 Description
 -----------
 
-The "eficonfig" command uses U-Boot menu interface and provides
-a menu-driven UEFI variable maintenance feature.
-The "eficonfig" has the following menu entries.
+The "eficonfig" command uses the U-Boot menu interface to provide a
+menu-driven UEFI variable maintenance feature. These are the top level menu
+entries:
 
 Add Boot Option
-    Add new UEFI Boot Option.
-    User can edit description, file path, and optional_data.
+    Add a new UEFI Boot Option.
+    The user can edit description, file path, and optional_data.
+    The new boot opiton is appended to the boot order in the *BootOrder*
+    variable. The user may want to update the boot order using the
+    *Change Boot Order* menu entry.
 
 Edit Boot Option
-    Edit the existing UEFI Boot Option
-    User can edit description, file path, and optional_data.
+    Edit an existing UEFI Boot Option.
+    The User can edit description, file path, and optional_data.
 
 Change Boot Order
-    Change the order of UEFI BootOrder variable.
+    Change the boot order updating the UEFI BootOrder variable.
 
 Delete Boot Option
-    Delete the UEFI Boot Option
+    Delete a UEFI Boot Option
 
-Configuration
--------------
+Secure Boot Configuration
+    Edit the UEFI Secure Boot Configuration
 
-The "eficonfig" command is enabled by::
+How to boot the system with a newly added UEFI Boot Option
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
-    CONFIG_CMD_EFICONFIG=y
-
-If CONFIG_BOOTMENU_DISABLE_UBOOT_CONSOLE is enabled, user can not enter
-U-Boot console. In this case, bootmenu can be used to invoke "eficonfig"::
-
-    CONFIG_USE_PREBOOT=y
-    CONFIG_PREBOOT="setenv bootmenu_0 UEFI Maintenance Menu=eficonfig"
+The "eficonfig" command is used to set the UEFI boot options which are stored
+in the UEFI variable Boot#### where #### is a hexadecimal number.
 
-How to boot the system with newly added UEFI Boot Option
-''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+The command *bootefi bootmgr* can be used to boot by trying in sequence all
+boot options selected by the variable *BootOrder*.
 
-"eficonfig" command is responsible for configuring the UEFI variables,
-not directly handle the system boot.
-The new Boot Option added by "eficonfig" is appended at the last entry
-of UEFI BootOrder variable, user may want to change the boot order
-through "Change Boot Order".
 If the bootmenu is enabled, CONFIG_BOOTMENU_DISABLE_UBOOT_CONSOLE is enabled,
 and "eficonfig" is configured as preboot command, the newly added Boot Options
-are enumerated in the bootmenu when user exits from the eficonfig menu.
-User may select the entry in the bootmenu to boot the system, or follow
+are enumerated in the bootmenu when the user exits from the eficonfig menu.
+The user may select the entry in the bootmenu to boot the system, or follow
 the U-Boot configuration the system already has.
 
 Auto boot with the UEFI Boot Option
@@ -66,6 +60,44 @@ add "bootefi bootmgr" entry as a default or first bootmenu entry::
 
     CONFIG_PREBOOT="setenv bootmenu_0 UEFI Boot Manager=bootefi bootmgr; setenv bootmenu_1 UEFI Maintenance Menu=eficonfig"
 
+UEFI Secure Boot Configuration
+''''''''''''''''''''''''''''''
+
+The user can enroll the variables PK, KEK, db and dbx by selecting a file.
+The "eficonfig" command only accepts signed EFI Signature List(s) with an
+authenticated header, typically a ".auth" file.
+
+To clear the PK, KEK, db and dbx, the user needs to enroll a null value
+signed by PK or KEK.
+
+Configuration
+-------------
+
+The "eficonfig" command is enabled by::
+
+    CONFIG_CMD_EFICONFIG=y
+
+If CONFIG_BOOTMENU_DISABLE_UBOOT_CONSOLE is enabled, the user can not enter
+U-Boot console. In this case, the bootmenu can be used to invoke "eficonfig"::
+
+    CONFIG_USE_PREBOOT=y
+    CONFIG_PREBOOT="setenv bootmenu_0 UEFI Maintenance Menu=eficonfig"
+
+The only way U-Boot can currently store EFI variables on a tamper
+resistant medium is via OP-TEE. The Kconfig option that enables that is::
+
+    CONFIG_EFI_MM_COMM_TEE=y.
+
+It enables storing EFI variables on the RPMB partition of an eMMC device.
+
+The UEFI Secure Boot Configuration menu entry is only available if the following
+options are enabled::
+
+    CONFIG_EFI_SECURE_BOOT=y
+    CONFIG_EFI_MM_COMM_TEE=y
+
 See also
 --------
-* :doc:`bootmenu<bootmenu>` provides a simple mechanism for creating menus with different boot items
+
+* :doc:`bootmenu<bootmenu>` provides a simple mechanism for creating menus with
+  different boot items