OvmfPkg/EnrollDefaultKeys: document the steps of the entry point function

The entry point function of EnrollDefaultKeys finishes with a sanity
check, verifying the values of the Secure Boot-related "control"
variables. Add a diagram to explain why we expect the values we do.

While at it, write comments on the rest of the entry point function.

Cc: Anthony Perard <anthony.perard@citrix.com>
Cc: Ard Biesheuvel <ard.biesheuvel@linaro.org>
Cc: Jordan Justen <jordan.l.justen@intel.com>
Cc: Julien Grall <julien.grall@arm.com>
Bugzilla: https://bugzilla.tianocore.org/show_bug.cgi?id=1747
Signed-off-by: Laszlo Ersek <lersek@redhat.com>
Reviewed-by: Philippe Mathieu-Daude <philmd@redhat.com>
Acked-by: Ard Biesheuvel <ard.biesheuvel@linaro.org>
Reviewed-by: Gary Lin <glin@suse.com>

diff --git a/OvmfPkg/EnrollDefaultKeys/EnrollDefaultKeys.c b/OvmfPkg/EnrollDefaultKeys/EnrollDefaultKeys.c
index 07297c631f3823e3adc200bcf26f031d317679d6..9c4a0f06fb4d6b22dfd88571daad2e503ef07e88 100644 (file)
--- a/OvmfPkg/EnrollDefaultKeys/EnrollDefaultKeys.c
+++ b/OvmfPkg/EnrollDefaultKeys/EnrollDefaultKeys.c
@@ -361,6 +361,9 @@ ShellAppMain (
   EFI_STATUS Status;\r
   SETTINGS   Settings;\r
 \r
+  //\r
+  // If we're not in Setup Mode, we can't do anything.\r
+  //\r
   Status = GetSettings (&Settings);\r
   if (EFI_ERROR (Status)) {\r
     return 1;\r
@@ -372,6 +375,10 @@ ShellAppMain (
     return 1;\r
   }\r
 \r
+  //\r
+  // Enter Custom Mode so we can enroll PK, KEK, db, and dbx without signature\r
+  // checks on those variable writes.\r
+  //\r
   if (Settings.CustomMode != CUSTOM_SECURE_BOOT_MODE) {\r
     Settings.CustomMode = CUSTOM_SECURE_BOOT_MODE;\r
     Status = gRT->SetVariable (EFI_CUSTOM_MODE_NAME, &gEfiCustomModeEnableGuid,\r
@@ -385,6 +392,9 @@ ShellAppMain (
     }\r
   }\r
 \r
+  //\r
+  // Enroll db.\r
+  //\r
   Status = EnrollListOfCerts (\r
              EFI_IMAGE_SECURITY_DATABASE,\r
              &gEfiImageSecurityDatabaseGuid,\r
@@ -396,6 +406,9 @@ ShellAppMain (
     return 1;\r
   }\r
 \r
+  //\r
+  // Enroll dbx.\r
+  //\r
   Status = EnrollListOfCerts (\r
              EFI_IMAGE_SECURITY_DATABASE1,\r
              &gEfiImageSecurityDatabaseGuid,\r
@@ -406,6 +419,9 @@ ShellAppMain (
     return 1;\r
   }\r
 \r
+  //\r
+  // Enroll KEK.\r
+  //\r
   Status = EnrollListOfCerts (\r
              EFI_KEY_EXCHANGE_KEY_NAME,\r
              &gEfiGlobalVariableGuid,\r
@@ -417,6 +433,9 @@ ShellAppMain (
     return 1;\r
   }\r
 \r
+  //\r
+  // Enroll PK, leaving Setup Mode (entering User Mode) at once.\r
+  //\r
   Status = EnrollListOfCerts (\r
              EFI_PLATFORM_KEY_NAME,\r
              &gEfiGlobalVariableGuid,\r
@@ -427,6 +446,10 @@ ShellAppMain (
     return 1;\r
   }\r
 \r
+  //\r
+  // Leave Custom Mode, so that updates to PK, KEK, db, and dbx require valid\r
+  // signatures.\r
+  //\r
   Settings.CustomMode = STANDARD_SECURE_BOOT_MODE;\r
   Status = gRT->SetVariable (EFI_CUSTOM_MODE_NAME, &gEfiCustomModeEnableGuid,\r
                   EFI_VARIABLE_NON_VOLATILE | EFI_VARIABLE_BOOTSERVICE_ACCESS,\r
@@ -437,6 +460,37 @@ ShellAppMain (
     return 1;\r
   }\r
 \r
+  //\r
+  // Final sanity check:\r
+  //\r
+  //                                 [SetupMode]\r
+  //                        (read-only, standardized by UEFI)\r
+  //                                /                \_\r
+  //                               0               1, default\r
+  //                              /                    \_\r
+  //                      PK enrolled                   no PK enrolled yet,\r
+  //              (this is called "User Mode")          PK enrollment possible\r
+  //                             |\r
+  //                             |\r
+  //                     [SecureBootEnable]\r
+  //         (read-write, edk2-specific, boot service only)\r
+  //                /                           \_\r
+  //               0                         1, default\r
+  //              /                               \_\r
+  //       [SecureBoot]=0                     [SecureBoot]=1\r
+  // (read-only, standardized by UEFI)  (read-only, standardized by UEFI)\r
+  //     images are not verified         images are verified, platform is\r
+  //                                      operating in Secure Boot mode\r
+  //                                                 |\r
+  //                                                 |\r
+  //                                           [CustomMode]\r
+  //                          (read-write, edk2-specific, boot service only)\r
+  //                                /                           \_\r
+  //                          0, default                         1\r
+  //                              /                               \_\r
+  //                      PK, KEK, db, dbx                PK, KEK, db, dbx\r
+  //                    updates are verified          updates are not verified\r
+  //\r
   Status = GetSettings (&Settings);\r
   if (EFI_ERROR (Status)) {\r
     return 1;\r