From 8a6f4dc19d11cb7f4f98df62cbf1376f5c957e6c Mon Sep 17 00:00:00 2001 From: Alex Zenla Date: Sun, 2 Nov 2025 18:08:57 -0500 Subject: [PATCH] chore(docs): add ubuntu secure boot setup guide --- README.md | 8 +- docs/ubuntu-secure-boot-setup.md | 126 +++++++++++++++++++++++++++++++ 2 files changed, 131 insertions(+), 3 deletions(-) create mode 100644 docs/ubuntu-secure-boot-setup.md diff --git a/README.md b/README.md index 2700097..5cfd8c4 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,7 @@ simplify installation and usage. ## Documentation +- [Ubuntu Secure Boot Setup Guide] - [Fedora Setup Guide] - [Generic Linux Setup Guide] - [Alpine Edge Setup Guide] @@ -61,12 +62,12 @@ simplify installation and usage. - [x] Load Linux initrd from disk - [x] Basic boot menu - [x] BLS autoconfiguration support -- [x] [Secure Boot support](https://github.com/edera-dev/sprout/issues/20): partial +- [x] [Secure Boot support](https://github.com/edera-dev/sprout/issues/20): beta +- [x] [Bootloader interface support](https://github.com/edera-dev/sprout/issues/21): beta +- [x] [BLS specification conformance](https://github.com/edera-dev/sprout/issues/2): beta ### Roadmap -- [ ] [Bootloader interface support](https://github.com/edera-dev/sprout/issues/21) -- [ ] [BLS specification conformance](https://github.com/edera-dev/sprout/issues/2) - [ ] [Full-featured boot menu](https://github.com/edera-dev/sprout/issues/1) - [ ] [UKI support](https://github.com/edera-dev/sprout/issues/6): partial - [ ] [multiboot2 support](https://github.com/edera-dev/sprout/issues/7) @@ -147,6 +148,7 @@ autoconfigure = true ``` [Edera]: https://edera.dev +[Ubuntu Secure Boot Setup Guide]: ./docs/ubuntu-secure-boot-setup.md [Fedora Setup Guide]: ./docs/fedora-setup.md [Generic Linux Setup Guide]: ./docs/generic-linux-setup.md [Alpine Edge Setup Guide]: ./docs/alpine-edge-setup.md diff --git a/docs/ubuntu-secure-boot-setup.md b/docs/ubuntu-secure-boot-setup.md new file mode 100644 index 0000000..4d6ba29 --- /dev/null +++ b/docs/ubuntu-secure-boot-setup.md @@ -0,0 +1,126 @@ +# Ubuntu Secure Boot Setup + +## Generate and Install Secure Boot Key + +```bash +# Create a directory to store the Secure Boot MOK key and certificates. +mkdir -p /etc/sprout/secure-boot +# Change to the created directory. +cd /etc/sprout/secure-boot +# Generate a MOK key and certificate. +$ openssl req \ + -newkey rsa:4096 -nodes -keyout mok.key \ + -new -x509 -sha256 -days 3650 -subj '/CN=Sprout Secure Boot/' \ + -out mok.crt +# Generate a DER encoded certificate for enrollment. +$ openssl x509 -outform DER -in mok.crt -out mok.cer +# Import the certificate into the Secure Boot environment. +# This will ask you to make a password that will be used during enrollment. +$ mokutil --import mok.cer +# Reboot your machine. +# During boot, MOK enrollment should appear. If it doesn't, ensure you are booting into the shim. +# Press any key to begin MOK management. Select "Enroll MOK". +# Select "View key 0", and ensure the subject says "CN=Sprout Secure Boot". +# If the subject does not match, something has gone wrong with MOK enrollment. +# Press Enter to continue, then select the "Continue" option. +# When it asks to enroll the key, select the "Yes" option. +# Enter the password that you created during the mokutil --import step. +# Select "Reboot" to boot back into your Operating System. +``` + +## Prepare Secure Boot Environment + +```bash +# Create a directory for Sprout EFI artifacts. +$ mkdir -p /boot/efi/EFI/sprout + +# For x86_64, copy the following artifacts to the Sprout EFI directory. +$ cp /usr/lib/shim/shimx64.efi.signed /boot/efi/EFI/sprout/shimx64.efi +$ cp /usr/lib/shim/mmx64.efi /boot/efi/EFI/sprout/mmx64.efi +$ cp /usr/lib/shim/fbx64.efi /boot/efi/EFI/sprout/fbx64.efi + +# For aarch64, copy the following artifacts to the Sprout EFI directory. +$ cp /usr/lib/shim/shimaa64.efi.signed /boot/efi/EFI/sprout/shimaa64.efi +$ cp /usr/lib/shim/mmaa64.efi /boot/efi/EFI/sprout/mmaa64.efi +$ cp /usr/lib/shim/fbaa64.efi /boot/efi/EFI/sprout/fbaa64.efi +``` + +## Install Unsigned Sprout + +Download the latest sprout.efi release from the [GitHub releases page](https://github.com/edera-dev/sprout/releases). +For x86_64 systems, download the `sprout-x86_64.efi` file, and for ARM64 systems, download the `sprout-aarch64.efi` file. +Copy the downloaded `sprout.efi` file to `/boot/efi/EFI/sprout/sprout.unsigned.efi` on your EFI System Partition. + +## Sign Sprout for Secure Boot + +```bash +# For x86_64, sign the unsigned Sprout artifact and name it grubaa64.efi which is what the shim will call. +$ sbsign \ + --key /etc/sprout/secure-boot/mok.key \ + --cert /etc/sprout/secure-boot/mok.crt \ + --output /boot/efi/EFI/sprout/grubx64.efi \ + /boot/efi/EFI/sprout/sprout.unsigned.efi + +# For aarch64, sign the unsigned Sprout artifact and name it grubaa64.efi which is what the shim will call. +$ sbsign \ + --key /etc/sprout/secure-boot/mok.key \ + --cert /etc/sprout/secure-boot/mok.crt \ + --output /boot/efi/EFI/sprout/grubaa64.efi \ + /boot/efi/EFI/sprout/sprout.unsigned.efi +``` + +## Sign EFI Drivers + +If you have an EFI driver, copy the driver to `/boot/efi/EFI/sprout/DRIVER_NAME.unsigned.efi` for signing. + +For example, the `ext4` driver, copy the `ext4.efi` file to `/boot/efi/EFI/sprout/ext4.unsigned.efi`. + +Then sign the driver with the Sprout Secure Boot key: + +```bash +# Sign the ext4 driver at ext4.unsigned.efi, placing it at ext4.efi, which will be used in the configuration. +$ sbsign \ + --key /etc/sprout/secure-boot/mok.key \ + --cert /etc/sprout/secure-boot/mok.crt \ + --output /boot/efi/EFI/sprout/ext4.efi \ + /boot/efi/EFI/sprout/ext4.unsigned.efi +``` + +## Create Sprout Configuration + +Write the following to the file `/boot/efi/sprout.toml`: + +```toml +# sprout configuration: version 1 +version = 1 + +# global values. +[values] +# your linux kernel command line. +linux-options = "root=UUID=MY_ROOT_UUID" + +# load an ext4 EFI driver. +[drivers.ext4] +path = "\\EFI\\sprout\\ext4.efi" + +# global options. +[options] +# enable autoconfiguration by detecting bls enabled +# filesystems and generating boot entries for them. +autoconfigure = true +``` + +Ensure you add the signed driver paths to the configuration, not the unsigned ones. +If you do not have any drivers, exclude the drivers section entirely. + +## Configure Sprout Boot Entry + +```bash +# In the following commands, replace /dev/ESP_PARTITION with the actual path to the ESP partition block device. + +# For x86_64, run this command to add Sprout as the default boot entry. +$ efibootmgr -d /dev/ESP_PARTITION -c -L 'Sprout' -l '\EFI\sprout\shimx64.efi' + +# For aarch64, run this command to add Sprout as the default boot entry. +$ efibootmgr -d /dev/ESP_PARTITION -c -L 'Sprout' -l '\EFI\sprout\shimaa64.efi' +```