|
| 1 | +# Setup Sprout for openSUSE with Secure Boot |
| 2 | + |
| 3 | +**NOTE:** This guide may not function as written if the system validates hashes. |
| 4 | +If your system validates hashes in the shim, you will need to use MokManager to enroll the hashes |
| 5 | +of every EFI file involved, such as Sprout and any EFI drivers. |
| 6 | + |
| 7 | +## Prerequisites |
| 8 | + |
| 9 | +- Modern openSUSE release: tested on openSUSE Tumbleweed ARM64 |
| 10 | +- EFI System Partition mounted on `/boot/efi` (the default) |
| 11 | +- You will need the following packages installed: `openssl`, `shim`, `mokutil`, `sbsigntools` |
| 12 | + |
| 13 | +## Step 1: Generate and Install Secure Boot Key |
| 14 | + |
| 15 | +```bash |
| 16 | +# Create a directory to store the Secure Boot MOK key and certificates. |
| 17 | +$ mkdir -p /etc/sprout/secure-boot |
| 18 | +# Change to the created directory. |
| 19 | +$ cd /etc/sprout/secure-boot |
| 20 | +# Generate a MOK key and certificate. |
| 21 | +$ openssl req \ |
| 22 | + -newkey rsa:4096 -nodes -keyout mok.key \ |
| 23 | + -new -x509 -sha256 -days 3650 -subj '/CN=Sprout Secure Boot/' \ |
| 24 | + -out mok.crt |
| 25 | +# Generate a DER encoded certificate for enrollment. |
| 26 | +$ openssl x509 -outform DER -in mok.crt -out mok.cer |
| 27 | +# Import the certificate into the Secure Boot environment. |
| 28 | +# This will ask you to make a password that will be used during enrollment. |
| 29 | +$ mokutil --import mok.cer |
| 30 | +# Reboot your machine. |
| 31 | +# During boot, MOK enrollment should appear. If it doesn't, ensure you are booting into the shim. |
| 32 | +# Press any key to begin MOK management. Select "Enroll MOK". |
| 33 | +# Select "View key 0", and ensure the subject says "CN=Sprout Secure Boot". |
| 34 | +# If the subject does not match, something has gone wrong with MOK enrollment. |
| 35 | +# Press Enter to continue, then select the "Continue" option. |
| 36 | +# When it asks to enroll the key, select the "Yes" option. |
| 37 | +# Enter the password that you created during the mokutil --import step. |
| 38 | +# Select "Reboot" to boot back into your Operating System. |
| 39 | +``` |
| 40 | + |
| 41 | +## Step 2: Prepare the Secure Boot Environment |
| 42 | + |
| 43 | +```bash |
| 44 | +# Create a directory for Sprout EFI artifacts. |
| 45 | +$ mkdir -p /boot/efi/EFI/sprout |
| 46 | + |
| 47 | +# For x86_64, copy the following artifacts to the Sprout EFI directory. |
| 48 | +$ cp /usr/share/efi/x86_64/shim.efi /boot/efi/EFI/sprout/shim.efi |
| 49 | +$ cp /usr/share/efi/x86_64/MokManager.efi /boot/efi/EFI/sprout/MokManager.efi |
| 50 | +$ cp /usr/share/efi/x86_64/fallback.efi /boot/efi/EFI/sprout/fallback.efi |
| 51 | + |
| 52 | +# For aarch64, copy the following artifacts to the Sprout EFI directory. |
| 53 | +$ cp /usr/share/efi/aarch64/shim.efi /boot/efi/EFI/sprout/shim.efi |
| 54 | +$ cp /usr/share/efi/aarch64/MokManager.efi /boot/efi/EFI/sprout/MokManager.efi |
| 55 | +$ cp /usr/share/efi/aarch64/fallback.efi /boot/efi/EFI/sprout/fallback.efi |
| 56 | +``` |
| 57 | + |
| 58 | +## Step 3: Install Unsigned Sprout |
| 59 | + |
| 60 | +Download the latest sprout.efi release from the [GitHub releases page](https://github.com/edera-dev/sprout/releases). |
| 61 | +For x86_64 systems, download the `sprout-x86_64.efi` file, and for ARM64 systems, download the `sprout-aarch64.efi` |
| 62 | +file. |
| 63 | +Copy the downloaded `sprout.efi` file to `/boot/efi/EFI/sprout/sprout.unsigned.efi` on your EFI System Partition. |
| 64 | + |
| 65 | +## Step 4: Sign Sprout for Secure Boot |
| 66 | + |
| 67 | +```bash |
| 68 | +# Sign the unsigned Sprout artifact and name it grub.efi which is what the shim will call. |
| 69 | +$ sbsign \ |
| 70 | + --key /etc/sprout/secure-boot/mok.key \ |
| 71 | + --cert /etc/sprout/secure-boot/mok.crt \ |
| 72 | + --output /boot/efi/EFI/sprout/grub.efi \ |
| 73 | + /boot/efi/EFI/sprout/sprout.unsigned.efi |
| 74 | +``` |
| 75 | + |
| 76 | +## Step 5: Install and Sign EFI Drivers |
| 77 | + |
| 78 | +You will need a filesystem EFI driver if `/boot` is not FAT32 or ExFAT. |
| 79 | +If `/boot` is FAT32 or ExFAT, you can skip this step. |
| 80 | + |
| 81 | +Most Debian systems use an ext4 filesystem for `/boot`. |
| 82 | +You can download an EFI filesystem driver from [EfiFs releases](https://github.com/pbatard/EfiFs/releases). |
| 83 | +For ext4, download the `ext2` file for your platform. It should work for ext4 filesystems too. |
| 84 | + |
| 85 | +If you have an EFI driver, copy the driver to `/boot/efi/EFI/sprout/DRIVER_NAME.unsigned.efi` for signing. |
| 86 | + |
| 87 | +For example, the `ext4` driver, copy the `ext4.efi` file to `/boot/efi/EFI/sprout/ext4.unsigned.efi`. |
| 88 | + |
| 89 | +Then sign the driver with the Sprout Secure Boot key: |
| 90 | + |
| 91 | +```bash |
| 92 | +# Sign the ext4 driver at ext4.unsigned.efi, placing it at ext4.efi, which will be used in the configuration. |
| 93 | +$ sbsign \ |
| 94 | + --key /etc/sprout/secure-boot/mok.key \ |
| 95 | + --cert /etc/sprout/secure-boot/mok.crt \ |
| 96 | + --output /boot/efi/EFI/sprout/ext4.efi \ |
| 97 | + /boot/efi/EFI/sprout/ext4.unsigned.efi |
| 98 | +``` |
| 99 | + |
| 100 | +## Step 6: Create Sprout Configuration |
| 101 | + |
| 102 | +Write the following to the file `/boot/efi/sprout.toml`: |
| 103 | + |
| 104 | +```toml |
| 105 | +# sprout configuration: version 1 |
| 106 | +version = 1 |
| 107 | + |
| 108 | +# global values. |
| 109 | +[values] |
| 110 | +# your linux kernel command line. |
| 111 | +linux-options = "root=UUID=MY_ROOT_UUID" |
| 112 | + |
| 113 | +# load an ext4 EFI driver. |
| 114 | +# skip this if you do not have a filesystem driver. |
| 115 | +# if your filesystem driver is not named ext4, change accordingly. |
| 116 | +[drivers.ext4] |
| 117 | +path = "\\EFI\\sprout\\ext4.efi" |
| 118 | + |
| 119 | +# global options. |
| 120 | +[options] |
| 121 | +# enable autoconfiguration by detecting bls enabled filesystems |
| 122 | +# or linux kernels and generating boot entries for them. |
| 123 | +autoconfigure = true |
| 124 | +``` |
| 125 | + |
| 126 | +Ensure you add the signed driver paths to the configuration, not the unsigned ones. |
| 127 | +If you do not have any drivers, exclude the drivers section entirely. |
| 128 | + |
| 129 | +## Step 7: Configure Sprout Boot Entry |
| 130 | + |
| 131 | +In the following commands, replace /dev/ESP_PARTITION with the actual path to the ESP partition block device. |
| 132 | + |
| 133 | +```bash |
| 134 | +# Run this command to add Sprout as the default boot entry. |
| 135 | +$ efibootmgr -d /dev/ESP_PARTITION -c -L 'Sprout' -l '\EFI\sprout\shim.efi' |
| 136 | +``` |
| 137 | + |
| 138 | +Reboot your machine and it should boot into Sprout. |
| 139 | +If Sprout fails to boot, it should boot into the original bootloader. |
0 commit comments