-
Notifications
You must be signed in to change notification settings - Fork 294
submitting
Here's a quick guide to the process for getting a shim build reviewed and signed. Other docs here:
If anything here or in the submission templates is not clear, please ask for help before you spend a lot of time on an incorrect path.
These may sound like odd questions!
Are you 100% sure that you need a shim build including your vendor key? Not everybody needs this; for small deployments it's often possible (and easier!) to add public keys directly into firmware on the machines involved. If you're a hardware vendor and you have control over the firmware on machines that you ship, install your keys into the other keyrings by preference. If you expect your software to be directly used on a larger number of machines from multiple hardware vendors, then shim is a more reasonable path to follow.
Before you start working with shim, you should also plan for how to support your build in the long run. As a minimum, reviewers will need two sets of contact details for people who will be responsible for it going forwards. We may need to get in touch as and when security issues appear in future. Depending on the nature of such issues, you may need to revoke signatures and keys and/or build a new version of shim with new patches included. If you are not sure you will be able to commit to this, then shim may not be a good option for you.
If you're sure you need your own shim binary signed by Microsoft, first go and create an account etc. with them. Check Microsoft's signing policies for all their specific requirements.
Start with the current stable release of shim, and check for any further recommended patches that you might need. Configure and build,
Check that you understand how to handle various things: embedding keys, revoking the ability to load further binaries (both by signature and by checksum).
Test your shim build as much as you can - this is important. Early testing is possible in VMs, and this is recommended as it's much quicker and easier than fighting with real hardware. Of course, you will also want to test that things work well on a range of real-world hardware before you submit.
Once you're happy that your build works, it's time to prepare for submitting it. This may seem long-winded, but the better you make your submission the easier it will be for reviewers to mark your build as accepted.
More details to follow
Reviewers will need to validate that they can reproduce your shim build. This is critically important - nobody will trust and sign a binary that is not reproducible.
The best recommendation here is for you to create a Dockerfile that will do the right thing to reproduce your build. This is not mandatory, but not following the normal path here makes it harder for reviewers.
If you are a Linux distribution developer, please try to have this docker image set up your normal build environment and build just like you would for your distribution; it'll make it easier to compare results that way. Be careful with the choice of compiler etc. here also - if you're tracking an "unstable" or "rolling" distribution then a different compiler version may cause your binary to not match the binary that a reviewer builds a week later.
If you are a tool developer needing a signed shim, pick a stable base image to use for your Dockerfile and make it easy for reviewers.
If you absolutely cannot use a container image for some reason, find another similar way to proceed and write clear easy docs for the reviewer to follow.
In all cases, make things as straightforward as possible for your reviewer and they'll be much happier to help you!
-
Please have a docker build use a standard setup:
docker build .is easy for reviewers. If you need a wrapper script to do things, call that from the Dockerfile. -
Please have your build script print the checksum(s) of your shim binaries, both the newly-built shim and the binary you're including in your submission.
Again, make sure that you're using the current stable release of shim. If you're not, reviewers will simply reject your submission and ask you to start again.
Check that you have picked up any upstream patches recommended for your use cases. If you add any patches like this, again please make it easy for reviewers to verify what the patches are. ```git format-patch`` is your friend here - patch file names, commit hashes and commit messages will all help the reviewer here.
If you have your own patches to shim, these will of course take more time and effort for review. In all cases, please try to open upstream PRs for them and/or discuss them on the EFI mailing list first! If you have non-trivial changes, make sure that you explain exactly what your changes are and why you need them. Shim is security-critical and reviewers will need to understand your changes and verify that they do not cause security regressions.