Improve documentation to provide answers to Microsoft queries

[rhertzog]

Hello,

we recently went through the process of getting our shim signed by Microsoft and that entails answering many questions about the shim itself and what it can load. It would be nice if the shim documentation could provide enough information to be able to answer those questions without having to go read the source code.

You can see the questions and our own answers in https://gist.github.com/rhertzog/7efd1f78212e2708ba64d3dc3190095f

I list below the relevant questions and some comments about what I'd like to see in the doc:

Please provide a description of the purpose and functions of your submitted modules.

For this the README provide some reasonable answer.

Do any of the products in this submission load or execute any other code prior to
ExitBootServices()? If so, please explain how the code is loaded, authorized, and executed.

Some explanation of where the shim finds its next-stage bootloader would be nice (name the involved UEFI variables?). The doc should also explain under which conditions it would execute MokManager.efi and/or fallback.efi.

If the doc can point to further grub and/or linux documentation to learn more about what else is done before ExitBootServices that would be nice.

Do any of the products in this submission take any user input? If so, what input validation is performed?

Some description of MokManager.efi and its safety checks would be welcome to answer that question.

Do any of the products in this submission take any programmatic input (files on disk, UEFI variables, etc.)? If so, what input validation is performed?

Again, here we want to know what UEFI variables is looked up to figure out the next-stage bootloader, and some details about how you check the signature on that binary.

Do any of the products in this submission use OpenSSL? If so, which version?

A quick word about the codebase that you use to check signatures is welcome. At first I reported a wrong version because the git history shows Update to 1.1.0e and the revert to 1.0.2k uses a not very explicit commit message.

Is this code based on iPXE? Or does it use PXE? If so, describe in technical detail how the loaded images are validated.

Not quite sure whether that question is relevant but the "netboot" feature of shim should probably be documented somewhere.

What is the size of your key in bits? (2048, 3072, 4096, ...)

When we had to pick the size of the key to embed, we got recommendation to stick to 20248 bits because some firmware have troubles with bigger sizes. That advice could be shared more widely I guess (or

If your SHIM launches any other components, please provide further details on what is launched and how the component prevents execution of unauthenticated code.

Some reference to external projects that the shim often interacts with would be nice (thinking of fwupd.efi mainly at this point).

Does your SHIM load any loaders that support loading unsigned kernels (e.g. GRUB)?

Some explanations that to properly implement secure boot you need to boot into a locked grub would be nice. I don't know what this would look like. The grub documentation is rather sparse too.

Thank your for considering this request (for the benefits of others that might have to go through the same process).