What is shim?

Shim is the pre-bootloader that runs on UEFI systems, meant to be a bit of code signed by Microsoft, that embeds our own certificate (which signs our grub binaries), so that it can load the "real" bootloader: GRUB.

Shim is periodically updated in the current development release and backported to all supported releases. This simplifies maintainance given the security-sensitive nature of this software.

If you have questions, ask cyphermox or vorlon or dannf.

How do I go about updating shim?

shim needs to be built separately in a PPA first (using an upstream release or a snapshot of the upstream tree, as appropriate), well-tested, and published alongside the shim-signed package.

1. First, file a SRU bug, using the template below, for the new shim release. Make sure to have its bug number closed in the changelog of both the shim and shim-signed packages that will be uploaded.

2. Prepare new package for 'shim' from github.com/rhboot/shim; Debian packaging is at https://code.launchpad.net/~ubuntu-core-dev/shim/+git/shim.

   • If using a snapshot, make sure versioning is clear (see previous shim releases)
   • Make sure COMMIT_ID is set in debian/rules, or the commit file is correct in the tarball.
3. You may wish to do some manual testing here; building shim locally and doing self-signing to make sure it looks good, especially when using a snapshot (see below).

4. Upload the package to a PPA. The ppa:ubuntu-uefi-team/ppa (previously ppa:canonical-foundations/shim) PPA is used for this purpose. If necessary to update shim or coordinate complex updates, other packages are built in that PPA.

   • While you're unsure it builds on all arches, prefer using a ~ version to not burn version numbers.
5. Once shim is uploaded to PPA and builds successfully; prepare a new shim-signed for testing:

   1. Retrieve package from https://code.launchpad.net/~ubuntu-core-dev/shim/+git/shim-signed

   2. Retrieve the binaries built from shim source, for both amd64 and arm64:
      • bootx64.efi
      • bootaa64.efi

   3. Sign with a temporary key and add to shim-signed, make sure the public cert is in shim-signed too.

   4. Edit shim-signed enough to succesfully build for this testing.
6. Do another round of testing with the packages...

7. Once built in the PPA and tested to a reasonable degree of certainty (see /TestPlan); a new signing request needs to be done: Prepare shim-review submission for initial review by the shim community:

   • Update https://github.com/CanonicalLtd/shim-review README file with the right information;

   • Push the new .efi binaries to the shim-review git tree;
   • Make sure README includes the SHA256SUM for the new binaries.
   • Push changes
8. File the request with the shim-review board:

   • File a github issue at https://github.com/rhboot/shim-review/issues

9. After the shim-review board has approved the submission; file a RT to have it submitted to Microsoft for the signing. Use the following template:

to: ubuntu-platform@rt.canonical.com
cc: Steve Langasek <steve.langasek@canonical.com>
cc: Dann Frazier <dann.frazier@canonical.com>
cc: Patricia Gaughen <patricia.gaughen@canonical.com>  
cc: Brian Murray <brian.murray@canonical.com>       

Hi,

A new version of the UEFI SecureBoot shim has been prepared for upload
to <ubuntu release>, and needs to be submitted to Microsoft for signing.

Attached are the files /usr/lib/shim/shimx64.efi and
/usr/lib/shimaa64.efi from the shim
<version> package.

The package where these binaries originate are:

amd64: <url to the build, ie. https://launchpad.net/~canonical-foundations/+archive/ubuntu/shim/+build/15261659>
arm64: <url to the build, ie. https://launchpad.net/~canonical-foundations/+archive/ubuntu/shim/+build/15261660>

The files to be signed are contained within the packages as
/usr/lib/shim/shim*.efi, with the following sha256sum:

amd64: <sha256sum of the binary>
arm64: <sha256sum of the binary>
< any other architectures for which shim binaries need to be signed >

Please submit them to Microsoft for UEFI signing.

Thanks,

<attach the relevant .efi files>

5. Once you have received the signed binaries back from Microsoft, update shim-signed with them.

   • If necessary, update the signing certificate from Microsoft, if they used a different one.

6. Upload shim-signed to ppa:ubuntu-uefi-team/ppa.

7. Test once more.
   • Here we want to make sure the packages are updating fine, that any postinst scripts are running correctly in the variety of scenarios they should run in, and that you do get the right shim binary installed to the ESP when the package is installed. Do another round of smoke tests to make sure shim works.
8. Make sure the shim in the package, as received from Microsoft, does work correctly. The Microsoft signtool utility is known to have the potential to modify the binary in a way that it will fail to boot. (see below)
   • Ensure the dependencies between the various affected packages
9. If smoke testing all passes, you can go ahead and copy the packages to -proposed for the devel release:

   1. Copy (with binary) the shim package.

   2. Copy the shim-signed package.
   3. Copy any other package that needs to go with them.
10. Once shim has been in the devel release for a bit, proceed with SRU (copy packages with binaries, etc.).
    • All supported releases should aim to have the same shim version for maintainability.

11. Track down a SRU team member to look at the packages in the unapproved queue.

Bug template

[Impact]
Shim needs to be updated for the latest fixes, security fixes, and new features
introduced upstream (see below). Shim is kept in sync across supported releases
to avoid subtle policy differences between releases, and because any upload
requires a round-trip of signing at Microsoft, which makes individual uploads
time-consuming.

[Test case]
Test plan is at http://wiki.ubuntu.com/UEFI/SecureBoot/ShimUpdateProcess/TestPlan

[Regression potential]
<describe what could possibly go wrong?>

---

Update shim in all supported releases of Ubuntu.

<describe upstream changes in the new shim>
<describe any other relevant information>

Common testing steps, above and beyond the test plan

• (for pre-MS testing) Add any temporary/testing key you've used to sign shim to the firmware of your test machine or VM.

• Run the tests described in /TestPlan

• Check 'objdump -h <efi file>' make sure offsets are at 0x200? intervals (this should never happen anymore, but is a guard against Microsoft's sign-file linker breaking our binaries as it has happened before)

• Run 'hexdump -Cv <efi file> | grep -A 3 -B 3 mmit' or a similar command to ensure the binary's commit ID is what it should be for this release/snapshot.