shim: add docs/comments for the package, including details on how to …

…manually test

SPECS/shim/TESTING

@@ -0,0 +1,30 @@
+
+Any changes to the shim-unsigned package, or this package, may require
+manual testing of the resulting EFI binaries. This describes the
+manual process to perform the testing.
+
+Since the shim binary is externally signed, while the fb/mm binaries
+are signed (only) by our production pipelines, testing new versions
+will require manually signing the shim and mm/fb binaries with
+separate keys, and the public part of the key used to sign mm/fb
+binaries must be embedded into the shim during the shim-unsigned
+build.
+
+The first option for signing the mm/fb EFI binaries, if the dev has
+access to our production pipelines, is to simply use the pipelines to
+sign the mm/fb binaries using the Azure Linux signing key. This option
+does not require any new public key to be added into the shim during
+shim-unsigned build, since it already contains the Azure Linux signing
+(public) key. However, since signing mm/fb with the Azure Linux
+signing key makes the mm/fb binaries usable on actual production
+systems, so using the signing key for development work is *highly*
+discouraged. Generally this should only be done with an updated shim
+package after all other testing is complete, *only* to validate that
+the shim will still correctly load the mm/fb binaries using the Azure
+Linux signing key.
+
+The second option, which should be used during normal shim
+development, is to generate a local signing key and embed the public
+portion inside the shim.
+
+1) 

SPECS/shim/shim.spec

@@ -1,3 +1,24 @@
+#
+# This generates a shim-x64 (or shim-aa64 for arm) package which
+# contains all the necessary files located under /boot. The shim EFI
+# binary is not taken directly from the shim-unsigned package, but
+# instead must be externally reviewed and approved (by
+# https://github.com/rhboot/shim-review) and will then be externally
+# signed, and provided to this build as Source0. The fallback (fb) and
+# mokmanager (mm) EFI binaries are taken directly from the
+# shim-unsigned package, and are *not* signed when this package is
+# built.
+#
+# However, when building through the 'official' build pipelines, the
+# resulting binary rpm will be modified using rpm hackery by the
+# 'SPECS-SIGNED/shim-signed' packaging in combination with a special
+# signing ADO pipeline stage, to replace the 'fb' and 'mm' EFI
+# binaries with binaries that have been signed by the Azure Linux
+# signing key.
+#
+# To test secure boot after making changes to this, or the
+# shim-unsigned package, see the TESTING file.
+#
 
 %ifarch x86_64
 %global efiarch x64