<> ||<>|| = 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. 1. 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. 1. 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). 1. 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. 1. 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 1. Retrieve the binaries built from shim source, for both amd64 and arm64: * bootx64.efi * bootaa64.efi 1. Sign with a temporary key and add to '''shim-signed''', make sure the public cert is in shim-signed too. 1. Edit shim-signed enough to succesfully build for this testing. 1. Do another round of testing with the packages... 1. 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 1. File the request with the shim-review board: * File a '''github issue''' at https://github.com/rhboot/shim-review/issues 1. 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: ||<>|| 1.#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. 1. Upload '''shim-signed''' to '''ppa:ubuntu-uefi-team/ppa'''. 1. 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. 1. 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 1. 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. 1. Copy the shim-signed package. 1. Copy any other package that needs to go with them. 1. 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. 1. Track down a SRU team member to look at the packages in the ''unapproved'' queue. == Bug template == ||<>|| == 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 ' 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 | 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.