From 66c2fee12e4fc14e828371f1e159be4ca5babf3e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Kr=C3=A1tk=C3=BD?= Date: Thu, 19 Sep 2024 15:46:12 +0200 Subject: [PATCH] Add UEFI/SecureBoot docs from Ubuntu wiki. --- .wokeignore | 2 + doc/.custom_wordlist.txt | 60 +- doc/.wokeignore | 4 - doc/custom_conf.py | 21 + doc/explanation/index.rst | 1 + doc/explanation/uefi-secureboot.rst | 290 ++++++ doc/howto/index.rst | 2 + doc/howto/uefi-secureboot-signing.rst | 54 ++ doc/howto/uefi-secureboot-testing.rst | 1222 +++++++++++++++++++++++++ doc/reference/autoinstall-schema.rst | 2 +- doc/reuse/substitutions.txt | 2 + 11 files changed, 1647 insertions(+), 13 deletions(-) create mode 100644 .wokeignore delete mode 100644 doc/.wokeignore create mode 100644 doc/explanation/uefi-secureboot.rst create mode 100644 doc/howto/uefi-secureboot-signing.rst create mode 100644 doc/howto/uefi-secureboot-testing.rst diff --git a/.wokeignore b/.wokeignore new file mode 100644 index 000000000..c33a429b0 --- /dev/null +++ b/.wokeignore @@ -0,0 +1,2 @@ +howto/uefi-secureboot-testing.rst +explanation/uefi-secureboot.rst diff --git a/doc/.custom_wordlist.txt b/doc/.custom_wordlist.txt index d95e6f6d3..6f0c67d60 100644 --- a/doc/.custom_wordlist.txt +++ b/doc/.custom_wordlist.txt @@ -2,41 +2,62 @@ AArch Autoinstall Autoinstalls Btrfs +COFF +DBX +DER DHCP +DKMS EFI -Esc ESP ESPs +Esc +FIXME GPT GUID +GUIDs GiB GiB +KEK Kylin -Libera LPAR LTS LUKS LV LVM +Libera LinuxONE +MOK Mantic MiB +MokManager NIC Netplan NoCloud OEM +OID +OIDs +OVMF OpenSSH -Petitboot -PgDn -PgUp +PCA +PER POST PPA +PPK PReP +PXE +Petitboot +PgDn +PgUp SSD Seagate Subiquity +TODO +TPM UEFI URI +Unenroll +VLAN +WIP Xubuntu Zdev amd @@ -44,16 +65,24 @@ authorized autoinstall autoinstaller autoinstalls +blocklist +blocklisted +blocklisting bootable bootloader bootloaders codecs -config conf +config +cryptographic curtin +dbx debconf debian +der dir +efi +efilinux el enablement flavor @@ -63,10 +92,15 @@ globbing hostname iSCSI init +keyring +keystore md oem openssh +partitioner passwd +pem +postinstall ppc pre preseed @@ -78,17 +112,27 @@ realname rootfs rsyslog runtime +sb +sbkeysync +sbkeysync +sbtools +sha snapd subvolume subvolumes superset sysfs -TPM traceback tty ubuntu udev +uefi +unenrol +unenrolled +unenrolling unformatted -VLAN +untrusted +userland +virtio webhook workdir diff --git a/doc/.wokeignore b/doc/.wokeignore deleted file mode 100644 index c64a60376..000000000 --- a/doc/.wokeignore +++ /dev/null @@ -1,4 +0,0 @@ -# the cheat sheets contain a link to a repository with a block word which we -# cannot avoid for now, ie -# https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html -doc-cheat-sheet* diff --git a/doc/custom_conf.py b/doc/custom_conf.py index 2344db80e..c57eb839f 100644 --- a/doc/custom_conf.py +++ b/doc/custom_conf.py @@ -177,3 +177,24 @@ extlinks = { 'manualpage': ( 'https://manpages.ubuntu.com/manpages/lunar/en/%s', '' ) } + +# Redefine the Sphinx 'command' role to behave/render like 'literal' +from docutils import nodes +from docutils.parsers.rst import roles +from sphinx.util.docutils import SphinxRole + +class CommandRole(SphinxRole): + def run(self): + text = self.text + node = nodes.literal(text, text) + return [node], [] + +def setup(app): + roles.register_local_role('command', CommandRole()) + +# Define a custom role for package-name formatting +def pkg_role(name, rawtext, text, lineno, inliner, options={}, content=[]): + node = nodes.literal(rawtext, text) + return [node], [] + +roles.register_local_role('pkg', pkg_role) diff --git a/doc/explanation/index.rst b/doc/explanation/index.rst index 11f9871a8..9a9c7cc4a 100644 --- a/doc/explanation/index.rst +++ b/doc/explanation/index.rst @@ -13,3 +13,4 @@ About the Server installer cloudinit-autoinstall-interaction zero-touch-autoinstall + uefi-secureboot diff --git a/doc/explanation/uefi-secureboot.rst b/doc/explanation/uefi-secureboot.rst new file mode 100644 index 000000000..4dcb41f0a --- /dev/null +++ b/doc/explanation/uefi-secureboot.rst @@ -0,0 +1,290 @@ +.. _uefi-secure-boot: + +UEFI Secure Boot +================ + +.. This content is from: +.. https://wiki.ubuntu.com/UEFI/SecureBoot + +.. important:: This article is for development purposes and a WIP. Don't use unless you know you're doing! + +UEFI (Unified Extensible Firmware Interface) Secure Boot is a verification mechanism for ensuring that code launched by firmware is trusted. + +In brief, Secure Boot works by placing the root of trust in firmware. While other implementations are possible, in practice, the chain of trust is achieved via x509 certificates. A root CA (Certificate Authority) is embedded in firmware such that it can then validate the signed bootloader. The signed bootloader can then validate the signed kernel or signed second-stage boot loader, and so on. + +Proper, secure use of UEFI Secure Boot requires that each binary loaded at boot is validated against known keys, located in firmware, that denote trusted vendors and sources for the binaries, or trusted specific binaries that can be identified via cryptographic hashing. + +Most x86 hardware comes from the factory pre-loaded with Microsoft keys. This means we can generally rely on the firmware on these systems to trust binaries that are signed by Microsoft, and the Linux community relies on this assumption for Secure Boot to work. This is the same process used by distributions from, for example, Red Hat and SUSE. + +Many ARM and other architectures also support UEFI Secure Boot but may not be pre-loading keys in firmware. On these architectures, it may be necessary to re-sign boot images with a certificate that is loaded in firmware by the owner of the hardware. + + +.. _key-databases: + +Key databases +------------- + +Various key databases are used to provide flexibility and maintain strong security: + +DB ('signature database') + Contains the trusted keys used for authenticating any applications or drivers executed in the UEFI environment. + +DBX ('forbidden signature database' or 'signature database blocklist') + Contains a set of explicitly untrusted keys and binary hashes. Any application or driver signed by these keys or matching these hashes is blocked from execution. + +KEK ('key exchange keys' database) + Contains the set of keys trusted for updating DB and DBX + +PK ('platform key') + While PK is often referred to simply as a single public key, it could be implemented as a database). Only updates signed with PK can update the KEK database. + +The suggested implementation by UEFI: + +- OEM (Original Equipment Manufacturer) key in PK. +- OS vendor keys in KEK and DB. OEM may also have a key in KEK and DB. + +Systems shipping with Windows 8 typically use the following: + +- OEM key in PK +- 'Microsoft Corporation KEK CA' key in KEK +- 'Microsoft Windows Production PCA' and 'Microsoft Corporation UEFI CA' keys in DB (note, the 'Microsoft Corporation UEFI CA' is not guaranteed to be present in DB -- while recommended, this is EFI firmware vendor/OEM dependent) + + +.. _how-uefi-secure-boot-works-on-ubuntu: + +How UEFI Secure Boot works on Ubuntu +------------------------------------ + +On Ubuntu, all pre-built binaries intended to be loaded as part of the boot process, with the exception of the ``initrd`` image, are signed by Canonical's UEFI certificate, which itself is implicitly trusted by being embedded in the shim loader, itself signed by Microsoft. + +On architectures or systems where pre-loaded signing certificates from Microsoft are not available or loaded in firmware, users may replace the existing signatures on shim or grub and load them as they wish, verifying against their own certificates imported in the system's firmware. + +As the system boots, firmware loads the shim binary as specified in firmware boot entry variables. Ubuntu installs its own boot entry at installation time and may update it any time the GRUB bootloader is updated. Since the shim binary is signed by Microsoft; it is validated and accepted by the firmware when verifying against certificates already present in firmware. As the shim binary embeds a Canonical certificate as well as its own trust database, further elements of the boot environment can, in addition to being signed by one of the acceptable certificates pre-loaded in firmware, be signed by Canonical's UEFI key. + +The next thing loaded by the shim is the second-stage image. This can be one of two things: + +- GRUB -- if the system is booting normally +- MokManager -- if key management is required, as configured by firmware variables (usually changed when the system was previously running) + + +Booting normally +~~~~~~~~~~~~~~~~ + +If booting normally, the GRUB binary (:file:`grub*.efi`) is loaded and its validation is attempted against all previously-known trusted sources. The GRUB binary for Ubuntu is signed by the Canonical UEFI key, so it is successfully validated, and the boot process continues. + + +Booting to perform key-management +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If booting to proceed with key management tasks, the MokManager binary (:file:`mm*.efi`) is loaded. This binary is explicitly trusted by the shim by being signed by an ephemeral key that only exists while the shim binary is being built. This means only the MokManager binary built with a particular shim binary is allowed to run, and it limits the possibility of a compromise from the use of compromised tools. + +MokManager allows any user present at the system console to enrol keys, remove trusted keys, enrol binary hashes and toggle Secure Boot validation at the shim level, but most tasks require a previously set password to be entered to confirm that the user at the console is indeed the person who requested changes. Such passwords only survive across a single run of the shim or MokManager. The passwords are cleared as soon as the process is completed or cancelled. Once key management is completed, the system is rebooted and does not simply continue with booting because the key management changes may be required to successfully complete the boot. + + +GRUB process +~~~~~~~~~~~~ + +Once the system continues booting to GRUB, the GRUB process loads any required configuration (usually loading configuration from the ESP (EFI System Partition) pointing to another configuration file on the root or boot partition), which points it to the kernel image to load. + +As EFI applications up to this point have full access to the system firmware, including access to changing trusted firmware variables, the kernel to load must also be validated against the trust database. Official Ubuntu kernels are signed by the Canonical UEFI key, so they are successfully validated, and control is handed over to the kernel. ``initrd`` images are not validated. + + +Booting unofficial kernels +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the case of unofficial kernels, or kernels built by users, additional steps need to be taken if users wish to load such kernels while retaining the full capabilities of UEFI Secure Boot. All kernels must be signed to be allowed to load by GRUB when UEFI Secure Boot is enabled, so the user is required to proceed with :ref:`their own signing `. + +Alternatively, users can: + +- Disable validation in the shim while booting with Secure Boot enabled on an official kernel: + + .. code:: none + + sudo mokutil --disable-validation + + Provide a password when prompted and reboot. + +- Disable Secure Boot in the firmware altogether. + +Up to this point, any failure to validate an image to load is met with a critical error, which stops the boot process. The system does not continue booting and may automatically reboot after a period of time given that other Boot Entry variables may contain boot paths that are valid and trusted. + +Once loaded, validated kernels disable the Boot Services of the firmware, thus dropping privileges and effectively switching to user mode where access to trusted variables is limited to read-only. + +Given the broad permissions afforded to kernel modules, any module not built into the kernel also needs to be validated upon loading. Modules built and shipped by Canonical with the official kernels are signed by the Canonical UEFI key and as such are trusted. + +Custom-built modules require the user to take the necessary steps to sign the modules before loading them is allowed by the kernel. This can be achieved by using the :command:`kmodsign` command (refer to :ref:`how-to-sign-your-own-uefi-binaries-for-secure-boot`). Given that many users require third-party modules for their systems to work properly or for some devices to function, and that these third-party modules require building locally on the system to be fitted to the running kernel, Ubuntu provides tooling to automate and simplify the signing process. + +Unsigned modules are refused by the kernel. Any attempt to insert them with :command:`insmod` or :command:`modprobe` fails with an error message. + + +Enrolling a PPA signing key +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Providers, including, for example, the Canonical Kernel team (`~~canonical-kernel-team `_), use PPA (Personal Package Archive) repositories on Launchpad to offer custom kernels with one-off fixes or for testing purposes. + +.. important:: Only enrol keys from trusted providers (PPA owners). Adding a signing key allows trusting any UEFI binary built and signed from a given PPA. + +#. Download the :file:`signed.tar.gz` file from the PPA: + + #. ``http://ppa.launchpad.net///ubuntu`` + #. Under ``dists//signed`` + #. The right name for the product, such as ``linux-amd64``. + +#. Verify the file integrity using the provided :file:`SHA256SUMS` file. +#. Extract the contents of the file. +#. Go to the :file:`/control` directory. +#. Convert the certificate from the PEM format to the DER format. +#. Enrol the :file:`uefi.crt` certificate. + + +Enrolling a signing key from a third-party archive +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Ask for the public certificate from the publisher of the package. + + +.. _ubuntu-chain-of-trust: + +Ubuntu chain of trust +--------------------- + +In order to boot on the widest range of systems, Ubuntu uses the following chain of trust: + +#. Microsoft signs Canonical's shim 1st-stage bootloader with their 'Microsoft Corporation UEFI CA'. When the system boots and Secure Boot is enabled, the firmware verifies that this 1st-stage bootloader (from the :pkg:`shim-signed` package) is signed with a key in DB (in this case 'Microsoft Corporation UEFI CA'). + +#. The second-stage bootloader (:pkg:`grub-efi-amd64-signed`) is signed with Canonical's 'Canonical Ltd. Secure Boot Signing' key. The shim 1st-stage bootloader verifies that the second-stage GRUB2 bootloader is properly signed. + +#. The second-stage GRUB2 bootloader boots an Ubuntu kernel (as of 2012/11, if the kernel (:pkg:`linux-signed`) is signed with the 'Canonical Ltd. Secure Boot Signing' key, then GRUB2 boots the kernel, which in turn applies quirks and calls ``ExitBootServices``. If the kernel is unsigned, GRUB2 calls ``ExitBootServices`` before booting the unsigned kernel). + +#. If signed kernel modules are supported, the signed kernel verifies them during kernel boot. + +As the above gives the ability to control boot to the OEM and Microsoft, users may want to: + +- Install their own key in PK, KEK, and DB, then re-sign GRUB2 and use it without a shim (and optionally sign the kernel with their own key). + +- Install their own key in PK and KEK: + + - 'Canonical Ltd. Master Certificate Authority' key in KEK and DB + - Microsoft keys in KEK (for updates to DBX) + + This gives some control of boot to Canonical but allows for the :pkg:`grub-efi-amd64-signed` and :pkg:`linux-signed` packages and any DB/DBX updates from Microsoft and Canonical to work without re-signing. + +- Install their own key in the shim's own keyring when testing only Canonical or user-signed GRUB2 or kernel and modules. + +When testing, a minimum shim boot, Canonical-signed GRUB2 boot, and user-signed GRUB2 boot should be covered. + +.. important:: + + Canonical's Secure Boot implementation in Ubuntu is primarily about hardware enablement, and this page focuses on how to test Secure Boot for common hardware-enablement configurations. The intent is not on enabling Secure Boot to harden your system. To use Secure Boot as a security mechanism, an appropriate solution is to use your own keys (optionally enrolling additional keys, see above) and update the bootloader to prohibit booting an unsigned kernel. Starting with Ubuntu 16.04 LTS, the system supports enforcing secure boot. + +Initial implementation plan: `Implementation Plan `_. + + +.. _supported-architectures: + +Supported architectures +----------------------- + +- **amd64**: A shim binary signed by Microsoft and a GRUB binary signed by Canonical are provided in the Ubuntu main archive as :pkg:`shim-signed` or :pkg:`grub-efi-amd64-signed`. + +- **arm64**: As of 20.04 ('focal'), a shim binary signed by Microsoft and a GRUB binary signed by Canonical are provided in the Ubuntu main archive as :pkg:`shim-signed` or :pkg:`grub-efi-arm64-signed`. + + +.. _testing-uefi-secure-boot: + +Testing UEFI Secure Boot +------------------------ + +For guidance on testing Secure Boot on your system, consult :ref:`testing-secure-boot`. + + +.. _how-can-i-do-non-automated-signing-of-drivers: + +How can I do non-automated signing of drivers? +---------------------------------------------- + +Some projects require the use of custom kernel drivers that are not set up to work with DKMS. In these cases, use the tools included in the :pkg:`shim-signed` package: the :command:`update-secureboot-policy` script is available to generate a new MOK (Machine-Owner Key) (if no DKMS-built modules have triggered generating one already). + +Use the following command to enrol an existing key into the shim: + +.. code:: none + + sudo update-secureboot-policy --enrol-key + +If no MOK exists, the script exits with a message to that effect. If the key is already enrolled, the script exits, doing nothing. If the key exists but is not shown to be enrolled, the user is prompted for a password to use after reboot, so that the key can be enrolled. + +To generate a new MOK, use: + +.. code:: none + + sudo update-secureboot-policy --new-key + +And then enrol the newly-generated key into the shim with the previously-mentioned command. + +Kernel modules can then be signed with the :command:`kmodsign` command (see :ref:`how-to-sign-your-own-uefi-binaries-for-secure-boot`) as part of their build process. + + +.. _security-implications-in-machine-owner-key-management: + +Security implications in Machine-Owner Key management +----------------------------------------------------- + +The MOK generated at installation time or on upgrade is machine-specific and only allowed by the kernel or the shim to sign kernel modules by the use of a specific OID (Object Identifier) (1.3.6.1.4.1.2312.16.1.2) denoting the limitations of the MOK. + +Recent shim versions include logic to follow the limitations of module-signing-only keys. These keys are allowed to be enrolled in the firmware in the shim trust database but are ignored when the shim or GRUB validate images to load in the firmware. + +The shim ``verify()`` function only successfully validates images signed by keys that do not include the "Module-signing only" (1.3.6.1.4.1.2312.16.1.2) OID. The Ubuntu kernels use the global trust database (which includes both shim and firmware OIDs) and accept any of the included keys as signing keys when loading kernel modules. + +Given the limitations imposed on the automatically generated MOK and the fact that users with superuser access to the system and access to the system console to enter the password required when enrolling keys already have high-level access to the system, the generated MOK key is kept on the file system as regular files owned by root with read-only permissions. + +This is deemed sufficient to limit access to the MOK for signing by malicious users or scripts, especially given that no MOK exists on the system unless it requires third-party drivers. This limits the possibility of a compromise from the misuse of a generated MOK key to signing a malicious kernel module. This is equivalent to a compromise of userland applications, which would already be possible with superuser access to the system, and securing this is out of the scope of UEFI Secure Boot. + +Previous systems may have had Secure Boot validation disabled in the shim. As part of the upgrade process, these systems will be migrated to re-enabling Secure Boot validation in the shim and enrolling a new MOK key when applicable. + + +.. _mok-generation-and-signing-process: + +MOK generation and signing process +---------------------------------- + +The key generation and signing process is slightly different based on whether dealing with a brand new installation or an upgrade of a system previously running Ubuntu. These two cases are clearly marked below. + +In all cases, if the system is not booting in UEFI mode, no special kernel-module signing steps or key generation happen. + +If Secure Boot is disabled, MOK generation and enrolment still happens, as the user may later enable Secure Boot. The system should work properly if that is the case. + + +.. _installing-ubuntu-on-a-new-system: + +Installing Ubuntu on a new system +--------------------------------- + +The user steps through the installer. Early on, when preparing to install and only if the system requires third-party modules to work, the user is prompted for a system password that is clearly marked as being required after the installation is complete. While the system is being installed, a new MOK is automatically generated without further user interaction. + +Third-party drivers or kernel modules required by the system are automatically built when the package is installed, and the build process includes a signing step. The signing step automatically uses the MOK generated earlier to sign the module, such that it can be immediately loaded once the system is rebooted and the MOK is included in the system trust database. + +Once the installation is complete and the system is restarted, the user is presented with the MokManager program on the first boot (part of the installed shim loader). MokManager is a set of text-mode panels that allow the user to enrol the generated MOK. The user selects :guilabel:`Enrol MOK`, is shown a fingerprint of the certificate to enrol, and is prompted to confirm the enrolment. Once confirmed, the new MOK is entered in the firmware, and the user is asked to reboot the system. + +When the system reboots, third-party drivers signed by the MOK just enrolled are loaded as necessary. + + +.. _release-upgrade-of-uefi-enabled-ubuntu-system-with-third-party-drivers: + +Release upgrade of UEFI-enabled Ubuntu system with third-party drivers +---------------------------------------------------------------------- + +On upgrade, the :pkg:`shim` and :pkg:`shim-signed` packages are upgraded. The post-install tasks of the :pkg:`shim-signed` package proceed to generate a new MOK and prompt the user for a password that is clearly mentioned as being required once the upgrade process is completed and the system rebooted. + +During the upgrade, the kernel packages and third-party modules are upgraded. Third-party modules are rebuilt for the new kernels, and their post-build process automatically signs them with the MOK. + +After upgrade, it is recommended to reboot the system. + +On reboot, the user is presented with the MokManager program (part of the installed shim loader). MokManager is a set of text-mode panels that allow the user to enrol the generated MOK. The user selects :guilabel:`Enrol MOK`, is shown a fingerprint of the certificate to enrol, and is prompted to confirm the enrolment. + +The user is also presented with a prompt to re-enable Secure Boot validation (in case it was found to be disabled), and MokManager again requires confirmation from the user. Once all steps are confirmed, shim validation is re-enabled, the new MOK is entered in the firmware, and the user is asked to reboot the system. + +When the system reboots, third-party drivers signed by the MOK just enrolled are loaded as necessary. + +In all cases, once the system is running with UEFI Secure Boot enabled and a recent version of the shim, the installation of any new DKMS module (third-party driver) signs the built module with the MOK. This happens without user interaction if a valid MOK key exists on the system and appears to already be enrolled. + +If no MOK exists or the existing MOK is not enrolled, a new key is automatically created just before signing and the user is prompted to enrol the key by providing a password, which is required upon reboot. diff --git a/doc/howto/index.rst b/doc/howto/index.rst index 8087d1f54..29b961f97 100644 --- a/doc/howto/index.rst +++ b/doc/howto/index.rst @@ -20,6 +20,8 @@ Getting started with autoinstall basic-server-installation configure-storage autoinstall-validation + Sign binaries for Secure Boot + Test Secure Boot Found a problem? ---------------- diff --git a/doc/howto/uefi-secureboot-signing.rst b/doc/howto/uefi-secureboot-signing.rst new file mode 100644 index 000000000..d2e59b4f1 --- /dev/null +++ b/doc/howto/uefi-secureboot-signing.rst @@ -0,0 +1,54 @@ +.. _how-to-sign-your-own-uefi-binaries-for-secure-boot: + +How to sign your own UEFI binaries for Secure Boot +================================================== + +.. This content is from: +.. https://wiki.ubuntu.com/UEFI/SecureBoot/Signing + +.. important:: This article is for development purposes and a WIP. Don't use unless you know you're doing! + +There are two options: + +- Using Ubuntu directly with :command:`sbsign` and :command:`kmodsign`. +- Using the "real" method used by Microsoft to sign binaries with a Windows-only application. + +For more details on signing binaries, see `Image Signing `_. + + +:command:`sbsign` and :command:`kmodsign` +----------------------------------------- + +:command:`sbsign` allows you to sign your own custom binaries (i.e. the files that would be loaded directly by firmware, be it a bootloader or a kernel). + +To sign a binary using :command:`sbsign`, you need both the private and public part of a certificate in PEM format (see `Key Generation `_). The source file will not be modified: + +.. code:: none + + sbsign --cert path/to/cert.crt --key path/to/cert.key \ + --output path/to/outputfile efi_binary + +To validate a signature, you still need the public part of the signing certificate in PEM form: + +.. code:: none + + sbverify --cert path/to/cert.crt efi_binary + +:command:`kmodsign` is used exclusively to sign kernel modules. It also requires the signing certificates to be in a different format than for :command:`sbsigntool`; for :command:`kmodsign`, the certificates need to be in the DER format. Conveniently, if you need to use DKMS modules, an appropriate certificate may already exist in :file:`/var/lib/shim-signed/mok`. + +To sign a custom module (in this example, the generated MOK is already available on a system): + +.. code:: none + + kmodsign sha512 \ + /var/lib/shim-signed/mok/MOK.priv \ + /var/lib/shim-signed/mok/MOK.der \ + module.ko + + +Using :command:`signfootl.exe` from Microsoft +--------------------------------------------- + +.. note:: This requires access to a system running Windows. + +Download :command:`signtool.exe` from Microsoft (it is a single binary), and run it. Refer to :command:`signtool /?` for help. diff --git a/doc/howto/uefi-secureboot-testing.rst b/doc/howto/uefi-secureboot-testing.rst new file mode 100644 index 000000000..2a7439a2f --- /dev/null +++ b/doc/howto/uefi-secureboot-testing.rst @@ -0,0 +1,1222 @@ +.. _testing-secure-boot: + +How to test Secure Boot +======================= + +.. This content is from: +.. https://wiki.ubuntu.com/UEFI/SecureBoot/Testing + +.. important:: This article is for development purposes and a WIP. Don't use unless you know you're doing! + +Testing infrastructure uses the Security team's `Testing environment `_. + + +.. _vm-installation-and-preparation: + +VM installation and preparation +------------------------------- + +#. Obtain an OVMF image capable of performing Secure Boot in one of the following ways: + + - Install the :pkg:`ovmf` package + - `Compile it yourself `_ + +#. Verify the symbolic link from :file:`/usr/share/ovmf/OVMF.fd` to :file:`/usr/share/qemu/OVMF.fd`. + +#. Install Ubuntu using the Secure Boot capable UEFI OVMF firmware (downloaded as :file:`bios.bin`): + + .. code:: none + + uvt new --loader=OVMF.fd --with-ovmf-uefi xenial amd64 sb + + This can also be performed with the :command:`virt-install` command: + + .. code:: none + + virt-install --connect=qemu:///system --name=sb-xenial-amd64 --arch=x86_64 --ram=2048 \ + --disk=path=/sb-xenial-amd64.qcow2,size=8,format=qcow2,bus=ide,sparse=True \ + --virt-type=kvm --accelerate --hvm --cdrom=/xenial-desktop-amd64.iso \ + --os-type=linux --os-variant=generic26 --graphics=vnc --network=network=default,model=virtio \ + --video=cirrus --noreboot --boot=loader=OVMF.fd + +Both of the above commands create the ``sb-xenial-amd64`` machine. Note that when using :command:`uvt`, there is a limitation in that a preseeded ISO cannot be used. :command:`uvt` skips the postinstall phase and you need to perform the installation manually. You know you are using the OVMF EFI image if the machine comes up with 'Try Ubuntu' (i.e., not the graphical installation). Using the manual partitioner to create a 250M EFI partition as the first partition and then setting up a :file:`/` and swap partition is known to work. + +Caveats: + +- The installer doesn't reboot after installation without pressing :kbd:`Enter`. +- On Ubuntu releases earlier than 16.04: on reboot and all boots, you must go into the EFI config screen to boot from a file off the disk. E.g., from the main EFI configuration screen: + + .. code:: none + + - Boot Maintenance Manager -> + - Boot From File -> + - NO VOLUME LABEL,[!PciRoot(0x0)/Pci(0x1,0x1)/Ata(Primary,Master,0x0)/HD(1,GPT,...)] -> + - -> + - -> + - grubx64.efi + + This behaviour can be changed by booting into the VM and then copying the appropriate files to :file:`/boot/efi/EFI/BOOT/BOOTX64.EFI`. E.g.: + + - For GRUB2 only, copy :file:`/boot/efi/EFI/ubuntu/grubx64.efi` to :file:`/boot/efi/EFI/BOOT/BOOTX64.EFI`. + + - For the shim, copy :file:`/boot/efi/EFI/ubuntu/shimx64.efi` to :file:`/boot/efi/EFI/BOOT/BOOTX64.EFI` and then copy :file:`/boot/efi/EFI/ubuntu/grubx64.efi` and :file:`grub.cfg` to :file:`/boot/efi/EFI/BOOT/`. Note that this document assumes you are using the 'Boot From File' method. + +- Suggested post-installation steps (as the postinstall is not running via :command:`uvt`): + + - Run: + + .. code:: none + + sudo apt-get install openssh-server screen vim gnome-panel + + - Use :command:`ssh-copy-id` to copy your key over. + - Optionally, update :file:`sources.list` for your mirror. + +- When using :command:`uvt`, the initial pristine snapshot is not created. After setting up, use: + + .. code:: none + + uvt snapshot sb-quantal-amd64 + +- As the firmware needs to be able to interact with the hardware and is limited in what it supports, the following are used when using :command:`uvt`: + + - IDE disks (can't use virtio) + - Cirrus video driver + +- The ``virtio`` network driver is used. If you want to try PXE booting via EFI, you may need to change this. + +See `OVMF `_ for other ways of using the :file:`OVMF` file. + + +.. _efi-shell: + +EFI shell +~~~~~~~~~ + +To go into the EFI shell, adjust the ``Boot Order`` in ``Boot options``: + +.. code:: none + + - Boot Maintenance Manager -> + - Boot Options -> + - Change Boot Order -> + - Highlight the list, press Enter, go to 'EFI Internal Shell' then press + '+' until it is above 'EFI Hard Drive'. Press Enter, then select + Commit Changes and Exit + +At this point, press :kbd:`Esc` until you get to the main EFI configuration menu and click :guilabel:`Continue`. This boots the shell. Enter ``exit`` to return to the EFI configuration menu. Useful commands: + +``Shell> ls fs0:\`` + Directory listing corresponding to :file:`/boot/efi` + +``Shell> ls fs0:\EFI\ubuntu\`` + Directory listing of where our bootloaders are + +``Shell> fs0:\EFI\ubuntu\grubx64.efi\`` + Launch GRUB2 bootloader + +``Shell> fs0:\EFI\ubuntu\shimx64.efi\`` + Launch shim bootloader + +``Shell> fs0:\EFI\ubuntu\efilinux.efi -f 0:\EFI\ubuntu\vmlinuz initrd=0:\EFI\ubuntu\initrd root=/dev/sda3 quiet splash`` + Launch efilinux bootloader + +.. note:: After booting the system via the EFI shell, the OVMF firmware defaults to EFI Hard Drive and does not allow access to the shell. You have to do a cold reboot to enter the shell again. + + +.. _keeping-the-vm-up-to-date: + +Keeping the VM up-to-date +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :command:`uvt update` command does not work because the boot process requires manual intervention. As such, keeping the VM up to date consists of the following steps: + +#. Start the VM: + + .. code:: none + + sudo uvt start [-rf] + +#. Select the image to boot: + + .. code:: none + + uvt cmd -r -p 'apt-get update && apt-get -y --force-yes dist-upgrade && apt-get autoremove --purge' + +#. + + .. code:: none + + uvt stop + +#. + + .. code:: none + + uvt snapshot + + +.. _assisted-secure-boot-vm-setup: + +Assisted Secure Boot VM setup +----------------------------- + + +.. _bootloader-signed-with-user-key: + +Bootloader signed with user key +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This emulates a configuration where a user or enterprise is using their own keys in PK, KEK, and DB and follow the procedures in `sbkeysync & maintaining uefi key databases `_ . This configuration allows the greatest flexibility in testing as we control PK and KEK, so we can update all aspects of Secure Boot as needed. The key database is configured with (each entry in firmware has the same GUID): + +- User key in PK +- User key in KEK +- User key in DB + +Steps to configure: + +#. Boot an OVMF virtual UEFI machine (see :ref:`vm-installation-and-preparation`). +#. Install required packages: + + .. code:: none + + sudo apt-get install sbsigntool openssl grub-efi-amd64-signed fwts linux-signed-generic + +#. Install the signed bootloader: + + .. code:: none + + sudo grub-install --uefi-secure-boot + +#. Reboot the VM and choose :guilabel:`Boot from File` as above (continue to use :file:`grubx64.efi`). + +#. **FIXME:** Download `sb-setup and keys `_ to :file:`/tmp/sb-setup` and :file:`/tmp/keys`. + +#. Enrol the user keys (output may vary): + + .. code:: none + + /tmp/sb-setup enroll + Creating keystore... + mkdir '/etc/secureboot/keys' + mkdir '/etc/secureboot/keys/PK' + mkdir '/etc/secureboot/keys/KEK' + mkdir '/etc/secureboot/keys/db' + mkdir '/etc/secureboot/keys/dbx' + done + + Creating keys... done + + Generating key updates for PK... + using GUID=1d5bd2fb-f597-4315-b3bc-dfe84b594ce7 + creating EFI_SIGNATURE_LIST (test-cert.der.siglist)... + creating signed update (test-cert.der.siglist.PK.signed)... + done + Generating key updates for KEK... + using GUID=1d5bd2fb-f597-4315-b3bc-dfe84b594ce7 + creating EFI_SIGNATURE_LIST (test-cert.der.siglist)... + creating signed update (test-cert.der.siglist.KEK.signed)... + done + Generating key updates for db... + using GUID=1d5bd2fb-f597-4315-b3bc-dfe84b594ce7 + creating EFI_SIGNATURE_LIST (test-cert.der.siglist)... + creating signed update (test-cert.der.siglist.db.signed)... + done + Initializing keystore... + adding to /etc/secureboot/keys/PK/ + adding to /etc/secureboot/keys/KEK/ + adding to /etc/secureboot/keys/db/ + done + + Filesystem keystore: + /etc/secureboot/keys/db/test-cert.der.siglist.db.signed [2116 bytes] + /etc/secureboot/keys/KEK/test-cert.der.siglist.KEK.signed [2116 bytes] + /etc/secureboot/keys/PK/test-cert.der.siglist.PK.signed [2116 bytes] + firmware keys: + PK: + KEK: + db: + dbx: + filesystem keys: + PK: + /CN=test-key + from /etc/secureboot/keys/PK/test-cert.der.siglist.PK.signed + KEK: + /CN=test-key + from /etc/secureboot/keys/KEK/test-cert.der.siglist.KEK.signed + db: + /CN=test-key + from /etc/secureboot/keys/db/test-cert.der.siglist.db.signed + dbx: + New keys in filesystem: + /etc/secureboot/keys/db/test-cert.der.siglist.db.signed + /etc/secureboot/keys/KEK/test-cert.der.siglist.KEK.signed + /etc/secureboot/keys/PK/test-cert.der.siglist.PK.signed + Commit to keystore? (y|N) y + Filesystem keystore: + /etc/secureboot/keys/db/test-cert.der.siglist.db.signed [2116 bytes] + /etc/secureboot/keys/KEK/test-cert.der.siglist.KEK.signed [2116 bytes] + /etc/secureboot/keys/PK/test-cert.der.siglist.PK.signed [2116 bytes] + firmware keys: + PK: + KEK: + db: + dbx: + filesystem keys: + PK: + /CN=test-key + from /etc/secureboot/keys/PK/test-cert.der.siglist.PK.signed + KEK: + /CN=test-key + from /etc/secureboot/keys/KEK/test-cert.der.siglist.KEK.signed + db: + /CN=test-key + from /etc/secureboot/keys/db/test-cert.der.siglist.db.signed + dbx: + New keys in filesystem: + /etc/secureboot/keys/db/test-cert.der.siglist.db.signed + /etc/secureboot/keys/KEK/test-cert.der.siglist.KEK.signed + /etc/secureboot/keys/PK/test-cert.der.siglist.PK.signed + Inserting key update /etc/secureboot/keys/db/test-cert.der.siglist.db.signed into db + Inserting key update /etc/secureboot/keys/KEK/test-cert.der.siglist.KEK.signed into KEK + Inserting key update /etc/secureboot/keys/PK/test-cert.der.siglist.PK.signed into PK + Signing '/boot/efi/EFI/ubuntu/grubx64.efi' + warning: overwriting existing signature + +#. Reboot and verify Secure Boot is enabled: + + .. code:: none + + - Device Manager -> + - Secure Boot Configuration -> + - Verify 'Attempt Secure Boot' is selected and 'Secure Boot Mode' is in + 'Standard Mode' ('Custom Mode' is also ok) + - Change 'Secure Boot Mode' to 'Custom Mode' by highlighting 'Standard + Mode' and pressing 'Enter' + - Select Custom Boot Options -> + - PK Options -> + - Verify 'Enroll PK' is grayed out. Delete PK should have '[ ]' (or + possibly a GUID). + - Press Esc + - KEK Options -> + - Delete KEK -> + - Verify GUID from sb-setup is listed + - Press 'Esc', twice + - DB Options + - Delete signature -> + - Verify GUID from sb-setup is listed + - Press 'Esc', twice + - DBX Options + - Delete signature -> + - Verify no [[GUIDs]] are listed + - Press 'Esc', twice + + +#. Press :kbd:`Esc` until at the main EFI configure screen, then :guilabel:`Boot from File` normally (notice now there is a :file:`grubx64.efi.bak` listed -- this is the :file:`grubx64.efi` as installed by :command:`sudo grub-install --uefi-secure-boot`. I.e., the one signed with Canonical's key). + +#. Verify the machine booted with Secure Boot (you can also use :command:`sbsigdb` from newer versions of ``sbsigntool`` if it is available): + + .. code:: none + + sudo fwts uefidump - | grep Secure + Name: [[SecureBoot]]. + Value: 0x01 (Secure Boot Mode On). + + In the above, a CA is setup in :file:`/etc/secureboot/key-material` (private key: :file:`test-key.rsa`, public pem: :file:`test-cert.pem`, public der: :file:`test-cert.der`). A keystore is created in :file:`/etc/secureboot/keys/` and signed updates (using the keys in :file:`/etc/secureboot/key-material`) are created for PK, KEK and DB. + + +.. _shim-bootloader-signed-with-microsoft-key: + +Shim bootloader signed with Microsoft key +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is the expected configuration for new machines with default hardware and has Microsoft keys in KEK and DB (user key still in PK and KEK). The key database configuration is with (user key in PK and KEK has the same GUID, each Microsoft key has a different GUID): + +- User key in PK +- User key and 'Microsoft Corporation KEK CA' key in KEK +- 'Microsoft Corporation UEFI CA' key and 'Microsoft Windows Production PCA' key in DB + +Steps to configure: + +#. Boot an OVMF virtual UEFI machine (see :ref:`vm-installation-and-preparation`). +#. Install some packages: + + .. code:: none + + sudo apt-get install sbsigntool openssl grub-efi-amd64-signed \ + fwts shim-signed linux-signed-generic + +#. Install the signed bootloader: + + .. code:: none + + sudo grub-install --uefi-secure-boot + +#. Reboot the VM and :guilabel:`Boot from File` as above, except choose :file:`shimx64.efi` instead of :file:`grubx64.efi`. + +#. **FIXME:** Download `sb-setup and keys `_ to :file:`/tmp/sb-setup` and :file:`/tmp/keys`. + +#. Enrol the keys (output may vary): + + .. code:: none + + /tmp/sb-setup enroll microsoft + Creating keystore... + mkdir '/etc/secureboot/keys' + mkdir '/etc/secureboot/keys/PK' + mkdir '/etc/secureboot/keys/KEK' + mkdir '/etc/secureboot/keys/db' + mkdir '/etc/secureboot/keys/dbx' + done + + Creating keys... done + + Generating key updates for PK... + using GUID=2b6a3c26-eeca-405d-bdc1-1e8c133253e1 + creating EFI_SIGNATURE_LIST (test-cert.der.siglist)... + creating signed update (test-cert.der.siglist.PK.signed)... + done + Generating key updates for KEK... + using GUID=2b6a3c26-eeca-405d-bdc1-1e8c133253e1 + creating EFI_SIGNATURE_LIST (test-cert.der.siglist)... + creating signed update (test-cert.der.siglist.KEK.signed)... + done + Generating key updates for KEK... + using GUID=dc072709-eb81-4b97-b1c1-3c48dc4202e1 + creating EFI_SIGNATURE_LIST (microsoft-kekca-public.der.siglist)... + creating signed update (microsoft-kekca-public.der.siglist.KEK.signed)... + done + Generating key updates for db... + using GUID=7fbf5694-f148-4051-8bd2-f36794ee2a54 + creating EFI_SIGNATURE_LIST (microsoft-pca-public.der.siglist)... + creating signed update (microsoft-pca-public.der.siglist.db.signed)... + done + Generating key updates for db... + using GUID=68386fb9-f8a6-4bfa-8868-adfd534a628a + creating EFI_SIGNATURE_LIST (microsoft-uefica-public.der.siglist)... + creating signed update (microsoft-uefica-public.der.siglist.db.signed)... + done + Initializing keystore... + adding to /etc/secureboot/keys/PK/ + adding to /etc/secureboot/keys/KEK/ + adding to /etc/secureboot/keys/db/ + done + + Filesystem keystore: + /etc/secureboot/keys/db/microsoft-pca-public.der.siglist.db.signed [2850 bytes] + /etc/secureboot/keys/db/microsoft-uefica-public.der.siglist.db.signed [2907 bytes] + /etc/secureboot/keys/KEK/test-cert.der.siglist.KEK.signed [2116 bytes] + /etc/secureboot/keys/KEK/microsoft-kekca-public.der.siglist.KEK.signed [2867 bytes] + /etc/secureboot/keys/PK/test-cert.der.siglist.PK.signed [2116 bytes] + firmware keys: + PK: + KEK: + db: + dbx: + filesystem keys: + PK: + /CN=test-key + from /etc/secureboot/keys/PK/test-cert.der.siglist.PK.signed + KEK: + /C=US/ST=Washington/L=Redmond/O=Microsoft Corporation/CN=Microsoft Corporation KEK CA 2011 + from /etc/secureboot/keys/KEK/microsoft-kekca-public.der.siglist.KEK.signed + /CN=test-key + from /etc/secureboot/keys/KEK/test-cert.der.siglist.KEK.signed + db: + /C=US/ST=Washington/L=Redmond/O=Microsoft Corporation/CN=Microsoft Corporation UEFI CA 2011 + from /etc/secureboot/keys/db/microsoft-uefica-public.der.siglist.db.signed + /C=US/ST=Washington/L=Redmond/O=Microsoft Corporation/CN=Microsoft Windows Production PCA 2011 + from /etc/secureboot/keys/db/microsoft-pca-public.der.siglist.db.signed + dbx: + New keys in filesystem: + /etc/secureboot/keys/db/microsoft-pca-public.der.siglist.db.signed + /etc/secureboot/keys/db/microsoft-uefica-public.der.siglist.db.signed + /etc/secureboot/keys/KEK/test-cert.der.siglist.KEK.signed + /etc/secureboot/keys/KEK/microsoft-kekca-public.der.siglist.KEK.signed + /etc/secureboot/keys/PK/test-cert.der.siglist.PK.signed + Commit to keystore? (y|N) y + Filesystem keystore: + /etc/secureboot/keys/db/microsoft-pca-public.der.siglist.db.signed [2850 bytes] + /etc/secureboot/keys/db/microsoft-uefica-public.der.siglist.db.signed [2907 bytes] + /etc/secureboot/keys/KEK/test-cert.der.siglist.KEK.signed [2116 bytes] + /etc/secureboot/keys/KEK/microsoft-kekca-public.der.siglist.KEK.signed [2867 bytes] + /etc/secureboot/keys/PK/test-cert.der.siglist.PK.signed [2116 bytes] + firmware keys: + PK: + KEK: + db: + dbx: + filesystem keys: + PK: + /CN=test-key + from /etc/secureboot/keys/PK/test-cert.der.siglist.PK.signed + KEK: + /C=US/ST=Washington/L=Redmond/O=Microsoft Corporation/CN=Microsoft Corporation KEK CA 2011 + from /etc/secureboot/keys/KEK/microsoft-kekca-public.der.siglist.KEK.signed + /CN=test-key + from /etc/secureboot/keys/KEK/test-cert.der.siglist.KEK.signed + db: + /C=US/ST=Washington/L=Redmond/O=Microsoft Corporation/CN=Microsoft Corporation UEFI CA 2011 + from /etc/secureboot/keys/db/microsoft-uefica-public.der.siglist.db.signed + /C=US/ST=Washington/L=Redmond/O=Microsoft Corporation/CN=Microsoft Windows Production PCA 2011 + from /etc/secureboot/keys/db/microsoft-pca-public.der.siglist.db.signed + dbx: + New keys in filesystem: + /etc/secureboot/keys/db/microsoft-pca-public.der.siglist.db.signed + /etc/secureboot/keys/db/microsoft-uefica-public.der.siglist.db.signed + /etc/secureboot/keys/KEK/test-cert.der.siglist.KEK.signed + /etc/secureboot/keys/KEK/microsoft-kekca-public.der.siglist.KEK.signed + /etc/secureboot/keys/PK/test-cert.der.siglist.PK.signed + Inserting key update /etc/secureboot/keys/db/microsoft-pca-public.der.siglist.db.signed into db + Inserting key update /etc/secureboot/keys/db/microsoft-uefica-public.der.siglist.db.signed into db + Inserting key update /etc/secureboot/keys/KEK/test-cert.der.siglist.KEK.signed into KEK + Inserting key update /etc/secureboot/keys/KEK/microsoft-kekca-public.der.siglist.KEK.signed into KEK + Inserting key update /etc/secureboot/keys/PK/test-cert.der.siglist.PK.signed into PK + Skipping bootloader signing for 'microsoft' + +#. Reboot and verify Secure Boot is enabled and configured like :ref:`bootloader-signed-with-user-key`, except with: + + - 2 different keys in KEK (should match GUIDs for KEK from sb-setup) + - 2 different keys in db (should match GUIDs for db from sb-setup) + +#. :guilabel:`Boot from File` normally (notice :file:`shimx64.efi` and :file:`grubx64.efi` are listed -- this is the :file:`grubx64.efi` as installed by :command:`sudo grub-install --uefi-secure-boot`. I.e., the one signed with Canonical's key). + +#. Verify the machine booted with Secure Boot (you can also use :command:`sbsigdb` from newer versions of ``sbsigntool`` if it is available): + + .. code:: none + + sudo fwts uefidump - | grep Secure + Name: [[SecureBoot]]. + Value: 0x01 (Secure Boot Mode On). + +#. Reboot and try to boot :file:`grubx64.efi` (i.e., the one signed with Canonical's key). This should fail to boot (when you press :kbd:`Enter` to select it, nothing happens). + + +.. _bootloader-signed-with-canonical-key: + +Bootloader signed with Canonical key +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This emulates a configuration that supports machines with Canonical's key in KEK and DB (user key still in PK and KEK). The key database is configured with (user key in PK and KEK has the same GUID, Canonical key in KEK and db has the same GUID): + +- User key in PK +- User key and 'Canonical Ltd. Master Certificate Authority' key in KEK +- 'Canonical Ltd. Master Certificate Authority' key in DB + +Steps to configure: + +#. Boot an OVMF virtual UEFI machine (see :ref:`vm-installation-and-preparation`). +#. Install required packages: + + .. code:: none + + sudo apt-get install sbsigntool openssl grub-efi-amd64-signed \ + fwts linux-signed-generic + +#. Install the signed bootloader: + + .. code:: none + + sudo grub-install --uefi-secure-boot + +#. Reboot the VM and :guilabel:`Boot from File` as above. + +#. **FIXME:** Download `sb-setup and keys `_ to :file:`/tmp/sb-setup` and :file:`/tmp/keys`. + +#. Enrol the keys (output may vary): + + .. code:: none + + /tmp/sb-setup enroll canonical + mkdir '/etc/secureboot/keys' + mkdir '/etc/secureboot/keys/PK' + mkdir '/etc/secureboot/keys/KEK' + mkdir '/etc/secureboot/keys/db' + mkdir '/etc/secureboot/keys/dbx' + done + + Creating keys... done + + Generating key updates for PK... + using GUID=55077d9d-6ca8-427a-9291-c60425c676e2 + creating EFI_SIGNATURE_LIST (test-cert.der.siglist)... + creating signed update (test-cert.der.siglist.PK.signed)... + done + Generating key updates for KEK... + using GUID=55077d9d-6ca8-427a-9291-c60425c676e2 + creating EFI_SIGNATURE_LIST (test-cert.der.siglist)... + creating signed update (test-cert.der.siglist.KEK.signed)... + done + Generating key updates for KEK... + using GUID=6a43e12f-b589-40c3-a332-a15eac86e3f5 + creating EFI_SIGNATURE_LIST (canonical-master-public.der.siglist)... + creating signed update (canonical-master-public.der.siglist.KEK.signed)... + done + Generating key updates for db... + using GUID=6a43e12f-b589-40c3-a332-a15eac86e3f5 + creating EFI_SIGNATURE_LIST (canonical-master-public.der.siglist)... + creating signed update (canonical-master-public.der.siglist.db.signed)... + done + Initializing keystore... + adding to /etc/secureboot/keys/PK/ + adding to /etc/secureboot/keys/KEK/ + adding to /etc/secureboot/keys/db/ + done + + Filesystem keystore: + /etc/secureboot/keys/db/canonical-master-public.der.siglist.db.signed [2431 bytes] + /etc/secureboot/keys/KEK/canonical-master-public.der.siglist.KEK.signed [2431 bytes] + /etc/secureboot/keys/KEK/test-cert.der.siglist.KEK.signed [2116 bytes] + /etc/secureboot/keys/PK/test-cert.der.siglist.PK.signed [2116 bytes] + firmware keys: + PK: + KEK: + db: + dbx: + filesystem keys: + PK: + /CN=test-key + from /etc/secureboot/keys/PK/test-cert.der.siglist.PK.signed + KEK: + /CN=test-key + from /etc/secureboot/keys/KEK/test-cert.der.siglist.KEK.signed + /C=GB/ST=Isle of Man/L=Douglas/O=Canonical Ltd./CN=Canonical Ltd. Master Certificate Authority + from /etc/secureboot/keys/KEK/canonical-master-public.der.siglist.KEK.signed + db: + /C=GB/ST=Isle of Man/L=Douglas/O=Canonical Ltd./CN=Canonical Ltd. Master Certificate Authority + from /etc/secureboot/keys/db/canonical-master-public.der.siglist.db.signed + dbx: + New keys in filesystem: + /etc/secureboot/keys/db/canonical-master-public.der.siglist.db.signed + /etc/secureboot/keys/KEK/canonical-master-public.der.siglist.KEK.signed + /etc/secureboot/keys/KEK/test-cert.der.siglist.KEK.signed + /etc/secureboot/keys/PK/test-cert.der.siglist.PK.signed + Commit to keystore? (y|N) y + Filesystem keystore: + /etc/secureboot/keys/db/canonical-master-public.der.siglist.db.signed [2431 bytes] + /etc/secureboot/keys/KEK/canonical-master-public.der.siglist.KEK.signed [2431 bytes] + /etc/secureboot/keys/KEK/test-cert.der.siglist.KEK.signed [2116 bytes] + /etc/secureboot/keys/PK/test-cert.der.siglist.PK.signed [2116 bytes] + firmware keys: + PK: + KEK: + db: + dbx: + filesystem keys: + PK: + /CN=test-key + from /etc/secureboot/keys/PK/test-cert.der.siglist.PK.signed + KEK: + /CN=test-key + from /etc/secureboot/keys/KEK/test-cert.der.siglist.KEK.signed + /C=GB/ST=Isle of Man/L=Douglas/O=Canonical Ltd./CN=Canonical Ltd. Master Certificate Authority + from /etc/secureboot/keys/KEK/canonical-master-public.der.siglist.KEK.signed + db: + /C=GB/ST=Isle of Man/L=Douglas/O=Canonical Ltd./CN=Canonical Ltd. Master Certificate Authority + from /etc/secureboot/keys/db/canonical-master-public.der.siglist.db.signed + dbx: + New keys in filesystem: + /etc/secureboot/keys/db/canonical-master-public.der.siglist.db.signed + /etc/secureboot/keys/KEK/canonical-master-public.der.siglist.KEK.signed + /etc/secureboot/keys/KEK/test-cert.der.siglist.KEK.signed + /etc/secureboot/keys/PK/test-cert.der.siglist.PK.signed + Inserting key update /etc/secureboot/keys/db/canonical-master-public.der.siglist.db.signed into db + Inserting key update /etc/secureboot/keys/KEK/canonical-master-public.der.siglist.KEK.signed into KEK + Inserting key update /etc/secureboot/keys/KEK/test-cert.der.siglist.KEK.signed into KEK + Inserting key update /etc/secureboot/keys/PK/test-cert.der.siglist.PK.signed into PK + Skipping bootloader signing for 'canonical' + +#. Reboot and verify Secure Boot is enabled and configured like 'Bootloader signed with user key' above, except with: + + - 2 different keys in KEK (should match GUIDs for KEK from sb-setup) + - 2 different keys in db (should match GUIDs for db from sb-setup) + +#. :guilabel:`Boot from File` normally (notice only :file:`grubx64.efi` listed -- this is the :file:`grubx64.efi` as installed by :command:`sudo grub-install --uefi-secure-boot`. I.e., the one signed with Canonical's key). + +#. Verify the machine booted with Secure Boot (note, can also use :command:`sbsigdb` from newer versions of ``sbsigntool`` if it is available): + + .. code:: none + + sudo fwts uefidump - | grep Secure + Name: [[SecureBoot]]. + Value: 0x01 (Secure Boot Mode On). + + +.. _efilinux-bootloader: + +efilinux bootloader +~~~~~~~~~~~~~~~~~~~ + +.. important:: It is highly recommended to use the shim and GRUB2 instead of efilinux for the bootloader. + +In theory, you should be able to do: + +.. code:: none + + sudo apt-get install efilinux efilinux-signed + sudo cp /usr/lib/efilinux/efilinux.efi /boot/efi/EFI/ubuntu + sudo cp /boot/vmlinuz-3.5.0-19-generic.efi.signed /boot/efi/EFI/ubuntu/vmlinuz + sudo cp /boot/initrd-3.5.0-19-generic /boot/efi/EFI/ubuntu/initrd + sudo cp /usr/lib/efilinux-signed/efilinux.efi.signed /boot/efi/EFI/ubuntu/efilinux-signed.efi + sudo sh -c 'cat > /boot/efi/EFI/ubuntu/efilinux.cfg << EOM + # efilinux menu 1 + EFILINUX MENU + Ubuntu EFILINUX + 0:\EFI\ubuntu\vmlinuz initrd=0:\EFI\ubuntu\initrd root=... ... + EOM + ' + +Then reboot, select one of :file:`efilinux.efi` or :file:`efilinux-signed.efi` from :guilabel:`Boot From File` and get a menu. Unfortunately, with current OVMF images, this does not work (though it apparently `works on USB installation images `_). + +The shim should try to boot anything named :file:`grubx64.efi`, so we can play a trick on the shim by naming :file:`efilinux.efi.signed` as :file:`grubx64.efi`: + +#. Boot an OVMF virtual UEFI machine (see :ref:`vm-installation-and-preparation`). +#. Install required packages: + + .. code:: none + + sudo apt-get install sbsigntool openssl grub-efi-amd64-signed fwts shim-signed linux-signed-generic efilinux-signed + +#. Install the signed bootloader (shim and GRUB2): + + .. code:: none + + sudo grub-install --uefi-secure-boot + +#. Backup GRUB2: + + .. code:: none + + sudo cp /boot/efi/EFI/ubuntu/grubx64.efi /boot/efi/EFI/ubuntu/grubx64-orig.efi + +#. Install the signed efilinux bootloader as :file:`grubx64.efi`: + + .. code:: none + + sudo cp /usr/lib/efilinux-signed/efilinux.efi.signed /boot/efi/EFI/ubuntu/efilinux-signed.efi + sudo cp /usr/lib/efilinux-signed/efilinux.efi.signed /boot/efi/EFI/ubuntu/grubx64.efi + sudo cp /boot/vmlinuz-3.5.0-19-generic.efi.signed /boot/efi/EFI/ubuntu/vmlinuz + sudo cp /boot/initrd-3.5.0-19-generic /boot/efi/EFI/ubuntu/initrd + sudo sh -c 'cat > /boot/efi/EFI/ubuntu/efilinux.cfg << EOM + # efilinux menu 1 + EFILINUX MENU + Ubuntu text boot + 0:\EFI\ubuntu\vmlinuz initrd=0:\EFI\ubuntu\initrd root=/dev/sda3 + Ubuntu graphical boot + 0:\EFI\ubuntu\vmlinuz initrd=0:\EFI\ubuntu\initrd root=/dev/sda3 quiet splash + Ubuntu recovery + 0:\EFI\ubuntu\vmlinuz initrd=0:\EFI\ubuntu\initrd root=/dev/sda3 single + EOM + ' + +#. Reboot the VM and :guilabel:`Boot from File` as above, except choose :file:`shimx64.efi` instead of :file:`grubx64.efi` + + Unfortunately, this doesn't work either, and it seems to be a bug in the OVMF implementation. Copying :file:`efilinux-signed.efi` to :file:`/boot/efi/EFI/BOOT/BOOTX64.EFI` (and :file:`efilinux.cfg` in :file:`/boot/efi/EFI/BOOT`) also doesn't work. With the above configuration, you can boot efilinux via the EFI shell: + + .. code:: none + + Shell> fs0:\EFI\ubuntu\efilinux-signed.efi + + However, you can't setup Secure Boot using :command:`sb-setup` since it requires a reboot, and you aren't able to boot into the EFI shell with a warm reboot. And a cold reboot resets the Secure Boot configuration. It should be possible to enlist the keys manually by copying the DER files into :file:`/boot/efi` and manually enlist them via the EFI configuration (but even then, it is only good for that one boot). + + +.. _miscellaneous: + +Miscellaneous +------------- + + +.. _disabling_secure_boot: + +Disabling Secure Boot +~~~~~~~~~~~~~~~~~~~~~ + +If you already committed your changes to the keystore (which enrols PK and toggles Secure Boot to enabled) and want to disable Secure Boot, you can reboot and go into the :guilabel:`Device Manager/Secure Boot Configuration` in the EFI firmware configuration, then :guilabel:`Unenroll PK` (highlight :guilabel:`[ ]` and press :kbd:`Enter`). You can then delete the signatures in KEK, DB, and DBX. You should also be able to unenrol PPK and disable Secure Boot with: + +.. code:: none + + /tmp/sb-setup reset + + +.. _disabling-secure-boot-validation-in-shim: + +Disabling Secure Boot validation in shim +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +With the VM installed, you can start a terminal and run the following commands, which ask you to choose a password: + +.. code:: none + + sudo mokutil --disable-validation + +To enable validation again use: + +.. code:: none + + sudo mokutil --enable-validation + +Reboot, and you will be starting in MokManager, a blue screen with prompts that walks you through enabling or disabling validation. You need to type in some of the characters of the password again. + + +.. _resetting-the-keystore: + +Resetting the keystore +~~~~~~~~~~~~~~~~~~~~~~ + +The keystore and key material are stored in :file:`/etc/secureboot`. If you have not committed your changes to the keystore, you can: + +.. code:: none + + sudo rm -rf /etc/secureboot + /tmp/sb-setup enroll ... + +If you have committed your changes to the keystore, disable Secure Boot (see :ref:`disabling-secure-boot-validation-in-shim`) and empty all the key databases in firmware. + +**Enabling Secure Boot after unenrolling PK**: if you unenrolled PK, you can re-enable it again with (uses existing keys): + +.. code:: none + + /tmp/sb-setup enroll microsoft + + +.. _converting-a-der-formatted-certificate-to-pem: + +Converting a DER formatted certificate to PEM +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:command:`sbverify` takes a PEM formatted certificate. You can convert the Canonical master DER formatted certificate: + +.. code:: none + + openssl x509 -inform DER -in ~/keys/canonical-master-public.der \ + -outform PEM -out ~/keys/canonical-master-public.pem + +and the Microsoft one: + +.. code:: none + + openssl x509 -inform DER -in ~/keys/microsoft-uefica-public.der \ + -outform PEM -out ~/keys/microsoft-uefica-public.pem + + +.. _creating-a-pem-certificate-chain-from-der-formatted-certificates: + +Creating a PEM certificate chain from DER formatted certificates +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To create a PEM certificate chain suitable for use with :command:`sbverify`, you convert all the DER certificates to PEM, then concatenate them in one certificate. E.g., to create the Canonical certificate chain file: + +.. code:: none + + openssl x509 -inform DER -in ~/keys/canonical-master-public.der \ + -outform PEM -out ~/keys/canonical-master-public.pem + openssl x509 -inform DER -in ~/keys/canonical-signing-public.der \ + -outform PEM -out ~/keys/canonical-signing-public.pem + cat ~/keys/canonical-master-public.pem ~/keys/canonical-signing-public.pem \ + > ~/keys/canonical-master-signing-public-chain.pem + + +.. _verifying-the-signature-on-a-signed-pe-coff-or-signed-kernel-image: + +Verifying the signature on a signed PE/COFF or signed kernel image +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To verify Microsoft's signature on the signed shim bootloader (must first create the PEM certificate, above): + +.. code:: none + + sbverify --cert ~/keys/microsoft-uefica-public.pem + /boot/efi/EFI/ubuntu/shimx64.efi Signature verification OK + +To verify Canonical's signature on the signed grub bootloader (must first create the PEM certificate, above): + +.. code:: none + + sbverify --cert ~/keys/canonical-master-public.pem + /boot/efi/EFI/ubuntu/grubx64.efi Signature verification OK + +To verify Ubuntu signature on the signed kernel, you must first extract the signature from the kernel image, then use :pkg:`sbverify` to verify the image with the detached signature (must first create the PEM certificate chain, above): + +.. code:: none + + sbattach --detach /tmp/vmlinuz-3.5.0-27-generic.efi.signature \ + /boot/vmlinuz-3.5.0-27-generic.efi.signed + + sbverify --cert ~/keys/canonical-master-signing-public-chain.pem \ + --detached /tmp/vmlinuz-3.5.0-27-generic.efi.signature \ + /boot/vmlinuz-3.5.0-27-generic.efi.signed + + Signature verification OK + + +.. _updating-key-databases: + +Updating key databases +---------------------- + + +.. _inserting-keys-in-shim-s-keyring: + +Inserting keys in shim's keyring +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To insert your own keys in the shim keyring, use: + +.. code:: none + + sudo mokutil --import + + +.. _removing-an-enrolled-key-from-shim-s-keyring: + +Removing an enrolled key from shim's keyring +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can remove certificates from the shim keyring if you still have access to the DER-format certificate by using: + +.. code:: none + + sudo mokutil --delete + +If you don't have access to the certificate, another option is to completely reset the shim keyring: + +.. code:: none + + sudo mokutil --reset + + +.. _certificates: + +Certificates +~~~~~~~~~~~~ + +To create an entry for a key database: + +#. Create a signature list variable with the thing you want to blocklist using :command:`sbsiglist`. +#. Sign the signature list variable with a key pair that is in KEK or PK using :command:`sbvarsign`. +#. Add the signed update to a keystore. +#. Use :command:`sbkeysync` to add the signed update to the key database. + +For example, if using the user key generated above, you can add a signed update to the blocklist database (dbx) for the Microsoft Corporation UEFI CA: + +.. code:: none + + guid=$(uuidgen) + sbsiglist --owner $guid --type x509 \ + --output microsoft_uefica_dbx-test.siglist \ + ~/keys/microsoft-uefica-public.der + sbvarsign --key /etc/secureboot/key-material/test-key.rsa \ + --cert /etc/secureboot/key-material/test-cert.pem \ + --output microsoft_uefica_dbx-test.siglist.signed \ + dbx \ + microsoft_uefica_dbx-test.siglist + + ls -1 + microsoft_uefica_dbx-test.siglist + microsoft_uefica_dbx-test.siglist.signed + + sudo cp microsoft_uefica_dbx-test.siglist.signed /etc/secureboot/keys/dbx + sudo sbkeysync --verbose + +If you have the :pkg:`secureboot-db` package installed, you can copy to the system wide updates keystore: + +.. code:: none + + sudo cp microsoft_uefica_dbx-test.siglist.signed /usr/share/secureboot/updates/dbx + sudo dpkg-reconfigure secureboot-db + Filesystem keystore: + /usr/share/secureboot/updates/dbx/microsoft_uefica_dbx-test.siglist.signed [2907 bytes] + firmware keys: + PK: + /CN=test-key + KEK: + /C=US/ST=Washington/L=Redmond/O=Microsoft Corporation/CN=Microsoft Corporation KEK CA 2011 + /CN=test-key + db: + /C=US/ST=Washington/L=Redmond/O=Microsoft Corporation/CN=Microsoft Corporation UEFI CA 2011 + /C=US/ST=Washington/L=Redmond/O=Microsoft Corporation/CN=Microsoft Windows Production PCA 2011 + dbx: + filesystem keys: + PK: + KEK: + db: + dbx: + /C=US/ST=Washington/L=Redmond/O=Microsoft Corporation/CN=Microsoft Corporation UEFI CA 2011 + from /usr/share/secureboot/updates/dbx/microsoft_uefica_dbx-test.siglist.signed + New keys in filesystem: + /usr/share/secureboot/updates/dbx/microsoft_uefica_dbx-test.siglist.signed + Inserting key update /usr/share/secureboot/updates/dbx/microsoft_uefica_dbx-test.siglist.signed into dbx + + +.. _sha256-hashes: + +sha256 hashes +~~~~~~~~~~~~~ + +**FIXME** + +**TODO (needs :pkg:`sbtools` support)**: Ultimately, this should be in ``sbsign`` since the hash of PE/COFF image is the hash of everything except the embedded signature. We'd like to do something like this, but it doesn't work because it doesn't exclude the embedded signature (and if it wasn't signed, there is no point blocklisting it): + +.. code:: none + + echo -n "0x`sha256sum grubx64.efi | cut -d ' ' -f 1`" | + | xxd -r -g 1 -c 64 > /tmp/sha256.bin + +Then we would create a signed update with: + +.. code:: none + + sbsiglist --owner $guid --type sha256 \ + --output /tmp/sha256.bin.siglist \ + /tmp/sha256.bin + sbvarsign --key /etc/secureboot/key-material/test-key.rsa \ + --cert /etc/secureboot/key-material/test-cert.pem \ + --output /tmp/sha256.bin.siglist.signed \ + dbx \ + /tmp/sha256.bin.siglist + + +.. _testing-signed-updates-via-secureboot-db: + +Testing signed updates via :pkg:`secureboot-db` +----------------------------------------------- + +Updates to ``db`` and ``dbx`` need to be performed as keys are rotated and things are blocklisted. This will be handled by the :pkg:`secureboot-db` package. In essence, :pkg:`secureboot-db` ships a keystore in :file:`/usr/share/secureboot/updates` for updating ``db`` and ``dbx``, and then in package ``postinst`` run: + +.. code:: none + + keystore=/usr/share/secureboot/updates \ + sbkeysync --no-default-keystores --keystore "$keystore" --verbose + +:command:`sbkeysync` only adds new updates, so the management of :pkg:`secureboot-db` is simple and updates primarily consist of adding the signed updates to the keystore. See :file:`debian/README.source` and :file:`debian/README.Debian` for details. + +.. note:: + + - Improperly updating :pkg:`secureboot-db` could result in all systems with Secure Boot enabled failing to boot. + + - When Secure Boot is enabled, updates to DB and DBX must be signed by something that verifies via the chain of trust to something in KEK. As a result, when testing :pkg:`secureboot-db`, expect :command:`sbkeysign` to complain when adding a signed update from Microsoft on a machine that does not have the Microsoft key in KEK but does have Secure Boot enabled. + + - :command:`sbkeysync` (and therefore :pkg:`secureboot-db`) add the updates to DB and DBX unconditionally when Secure Boot is disabled + + +.. _test-cases: + +Test cases +---------- + + +.. _functional-tests: + +Functional tests +~~~~~~~~~~~~~~~~ + +- Booting with Secure Boot disabled + + - for each of GRUB2-signed only and shim-signed + + - install bootloader + - reboot and verify the machine boots with Secure Boot disabled + +- Booting with Secure Boot enabled + + - for each of :pkg:`linux-generic` (unsigned) and :pkg:`linux-signed-generic` + + - for each of Microsoft/shim-signed, Canonical/GRUB2-signed and user signed + + * verify vendor's (or when test user keys, user's) keys are in KEK and DB and Secure Boot is enabled + * reboot and verify the machine still boots + * install updated :pkg:`secureboot-db`, verifying: + + * package installation succeeded + * :pkg:`secureboot-db` properly used 'Breaks' and pulled in necessary packages + * the updates were added to firmware (check EFI configuration, as well as output from :command:`sbkeysync`) + * reboot and verify the machine still boots + + +.. _verification-tests: + +Verification tests +~~~~~~~~~~~~~~~~~~ + +With Secure Boot enabled with the shim and using Microsoft keys. + +Shim validation +^^^^^^^^^^^^^^^ + +Tests firmware properly verifies our signed shim. + +Add a dbx entry for an old shim and try booting (should fail): + TODO + +Add a dbx entry for the 'Microsoft Corporation UEFI CA' and try booting (should fail): + .. code:: none + + guid=$(uuidgen) $ sbsiglist --owner $guid --type x509 \ + --output microsoft_uefica_dbx-test.siglist \ + ~/keys/microsoft-uefica-public.der + + sbvarsign --key /etc/secureboot/key-material/test-key.rsa \ + --cert /etc/secureboot/key-material/test-cert.pem \ + --output microsoft_uefica_dbx-test.siglist.signed \ + dbx \ + microsoft_uefica_dbx-test.siglist + + sudo cp microsoft_uefica_dbx-test.siglist.signed /etc/secureboot/keys/dbx + sudo sbkeysync --verbose + + Now try to :guilabel:`Boot from File` :file:`shimx64.efi` (succeed if Secure Boot is disabled, fail if enabled). To reset back to a working signed GRUB2, delete the signature from the DBX database in firmware, and then on reboot: + + .. code:: none + + sudo rm -f /etc/secureboot/keys/dbx/*signed + +Replace shim with unsigned shim (should fail): + .. code:: none + + sudo apt-get install shim + sudo cp /usr/lib/shim/shim.efi /boot/efi/EFI/ubuntu/ + + Now try to :guilabel:`Boot from File` :file:`shim.efi` (succeed if Secure Boot is disabled, fail if enabled). + +Replace shim with signed shim using a key not in DB (should fail): + .. code:: none + + sudo apt-get install shim + sudo sbsign --key /etc/secureboot/key-material/test-key.rsa \ + --cert /etc/secureboot/key-material/test-cert.pem \ + --output /boot/efi/EFI/ubuntu/shim_user-signed.efi \ + /usr/lib/shim/shim.efi + + Now try to :guilabel:`Boot from File` :file:`shimx64.efi` (succeed if Secure Boot is disabled, fail if enabled). + +OPTIONAL: replace signed shim with a bit-flipped/fuzzed shim (should fail). + |nbsp| + + +GRUB2 validation +^^^^^^^^^^^^^^^^ + +Tests shim properly verifies our bootloader. + +Try to boot GRUB2 directly, without shim (should fail). + |nbsp| + +Add a dbx entry for an old GRUB2 and try booting (should fail): + TODO + +Add a dbx entry for the 'Canonical Ltd. Master Certificate Authority' and try booting (should fail): + .. code:: none + + guid=$(uuidgen) + sbsiglist --owner $guid --type x509 \ + --output canonical_ca_dbx-test.siglist \ + ~/keys/canonical-master-public.der + + sbvarsign --key /etc/secureboot/key-material/test-key.rsa \ + --cert /etc/secureboot/key-material/test-cert.pem \ + --output canonical_ca_dbx-test.siglist.signed \ + dbx \ + canonical_ca_dbx-test.siglist + + sudo cp canonical_ca_dbx-test.siglist.signed /etc/secureboot/keys/dbx + sudo sbkeysync --verbose + + Now try to :guilabel:`Boot from File` :file:`shim_user-signed.efi` (succeed if Secure Boot is disabled, fail if enabled). To reset back to a working signed GRUB2, delete the signature from the DBX database in firmware and then on reboot: + + .. code:: none + + sudo rm -f /etc/secureboot/keys/dbx/*signed + +Add a dbx entry for the 'Canonical Ltd. Secure Boot Signing' key and try booting (should fail): + .. code:: none + + guid=$(uuidgen) + sbsiglist --owner $guid --type x509 \ + --output canonical_signing_dbx-test.siglist \ + ~/keys/canonical-signing-public.der + + sbvarsign --key /etc/secureboot/key-material/test-key.rsa \ + --cert /etc/secureboot/key-material/test-cert.pem \ + --output canonical_signing_dbx-test.siglist.signed \ + dbx \ + canonical_signing_dbx-test.siglist + + sudo cp canonical_signing_dbx-test.siglist.signed /etc/secureboot/keys/dbx + sudo sbkeysync --verbose + + Now try to :guilabel:`Boot from File` :file:`shimx64.efi` (succeed if Secure Boot is disabled, fail if enabled). To reset back to a working signed GRUB2, delete the signature from the DBX database in firmware, and then on reboot: + + .. code:: none + + sudo rm -f /etc/secureboot/keys/dbx/*signed + +Replace GRUB2 with unsigned GRUB2 (should fail): + .. code:: none + + sudo grub-install --no-uefi-secure-boot + + Now try to :guilabel:`Boot from File` :file:`shimx64.efi` (succeed if Secure Boot is disabled, fail if enabled). Run the following to reset to working signed GRUB2: + + .. code:: none + + sudo grub-install --uefi-secure-boot + + +Replace GRUB2 with signed GRUB2 using a key not in DB (should fail): + .. code:: none + + sudo grub-install --uefi-secure-boot + sudo sbsign --key /etc/secureboot/key-material/test-key.rsa \ + --cert /etc/secureboot/key-material/test-cert.pem \ + --output /boot/efi/EFI/ubuntu/grubx64.efi \ + /usr/lib/grub/x86_64-efi-signed/grubx64.efi.signed + + Now try to :guilabel:`Boot from File` :file:`shimx64.efi` (succeed if Secure Boot is disabled, fail if enabled). Run the following to reset to working signed GRUB2: + + .. code:: none + + sudo grub-install --uefi-secure-boot + +OPTIONAL: replace signed GRUB2 with a bit-flipped/fuzzed GRUB2 (should fail). + |nbsp| + + +Kernel +^^^^^^ + +Tests GRUB2 verification of kernel and fallback mechanism. + +Add a dbx entry for an old kernel and try booting (should fail): + TODO + +Replace kernel with unsigned kernel (should succeed): + .. code:: none + + sudo apt-get remove --purge linux-signed\* + + Now try to :guilabel:`Boot from File` :file:`shimx64.efi` (succeed if Secure Boot is disabled, fail if enabled). Run the following to reset to working signed kernel: + + .. code:: none + + sudo apt-get install linux-signed-generic + +Replace kernel with signed kernel using a key not in DB (should succeed): + .. code:: none + + sudo cp /boot/vmlinuz--generic.efi.signed \ + /boot/vmlinuz--generic.efi.signed.bak + + sudo sbsign --key /etc/secureboot/key-material/test-key.rsa \ + --cert /etc/secureboot/key-material/test-cert.pem \ + --output /boot/vmlinuz-generic.efi.signed \ + /boot/vmlinuz-generic.efi.signed.bak + + Now try to :guilabel:`Boot from File` :file:`shimx64.efi` (succeed if Secure Boot is disabled, fail if enabled). Run the following to reset to working signed GRUB2: + + .. code:: none + + sudo apt-get remove --purge linux-signed* + sudo apt-get install linux-signed-generic + +OPTIONAL: replace signed kernel with a bit-flipped/fuzzed kernel (should fail). + |nbsp| diff --git a/doc/reference/autoinstall-schema.rst b/doc/reference/autoinstall-schema.rst index f99a7479a..75c4d1759 100644 --- a/doc/reference/autoinstall-schema.rst +++ b/doc/reference/autoinstall-schema.rst @@ -10,7 +10,7 @@ The server installer validates the provided autoinstall configuration against a How the delivery is verified ---------------------------- -To ensure expected runtime behaviour after delivering the autoinstall config, the installer performs some sanity checks to ensure one delivery method is not confused for another. +To ensure expected runtime behaviour after delivering the autoinstall configuration, the installer performs some coherence checks to ensure one delivery method is not confused for another. cloud-config ^^^^^^^^^^^^ diff --git a/doc/reuse/substitutions.txt b/doc/reuse/substitutions.txt index 5d9ee6a5b..9158f4b4e 100644 --- a/doc/reuse/substitutions.txt +++ b/doc/reuse/substitutions.txt @@ -1,3 +1,5 @@ .. |ubuntu-latest-version| replace:: 23.10 .. |ubuntu-latest-codename| replace:: Mantic Minotaur .. role:: command(literal) +.. |nbsp| unicode:: 0xA0 + :trim: