# Secure Boot

Secure Boot is a security feature found in the UEFI standard, designed to add a layer of protection to the pre-boot process: by maintaining a cryptographically signed list of binaries authorized or forbidden to run at boot, it helps in improving the confidence that the machine core boot components (boot manager, kernel, initramfs) have not been tampered with. 

<p class="callout warning"><strong>ATTENTION:</strong> When using Secure Boot it's imperative to use it with disk encryption. If the storage device that stores the keys is not encrypted, anybody can read the keys and use them to sign bootable images, thereby defeating the purpose of using Secure Boot at all.</p>

## Preparations

To determine the current state of Secure Boot execute:

~~~bash
bootctl status
~~~

The output looks something like this:

~~~
System:
      Firmware: UEFI 2.70 (American Megatrends 5.17)
 Firmware Arch: x64
   Secure Boot: enabled (user)
  TPM2 Support: yes
  Measured UKI: yes
  Boot into FW: supported

...
~~~

In order to proceed you need to set your firmware's Secure Boot mode into "setup" mode to proceed. This can usually be achieved by wiping the key store of the firmware. Refer to your mainboard's user manual on how to do this.

## Installation

For the most straight-forward Secure Boot toolchain install `sbctl`:

~~~bash
pacman -S sbctl
~~~

It tremendously simplifies generating Secure Boot keys, loading keys into firmware and signing kernel images.

## Generating keys

<p class="callout info"><strong>SEE ALSO:</strong> <a href="https://blog.hansenpartnership.com/the-meaning-of-all-the-uefi-keys/">The Meaning of all the UEFI Keys</a></p>

Secure Boot implementations use these keys:

| Key Type                            | Description                                                                     |
|-------------------------------------|---------------------------------------------------------------------------------|
| Platform Key (PK)                   | Top-level key                                                                   |
| Key Exchange Key (KEK)              | Keys used to sign Signatures Database and Forbidden Signatures Database updates |
| Signature Database (db)             | Contains keys and/or hashes of allowed EFI binaries                             |
| Forbidden Signatures Database (dbx) | Contains keys and/or hashes of denylisted EFI binaries                          |

To generate new keys and store them under `/usr/share/secureboot/keys/`:

~~~bash
sbctl create-keys
~~~

## Unified Kernel Image

A unified kernel image (UKI) combines an EFI stub image, CPU microcode, kernel command line and an initramfs into a single file that can be read and executed by the machines UEFI firmware. It also makes it easier to sign for secure boot as there will be only a single file to sign.

Starting with v31 `mkinitcpio` is able to create UKIs out-of-the-box. The maintainers of `sbctl` also recommend using the system's initramfs generation tool instead of `sbctl bundle`.

To make `mkinitcpio` generate UKIs, edit the appropriate *.preset* file for your kernel in `/etc/mkinitcpio.d/`:

* uncomment the `default_uki` and `fallback_uki` lines
* point the file path to somewhere on your EFI System Partition (e.g. `/efi`, `/boot` or `/boot/efi`)

<p class="callout info"><strong>NOTE:</strong> <code>mkinitcpio</code> automatically sources <code>/etc/kernel/cmdline</code> for the included kernel command line arguments. If you want the fallback image to receive a different set of kernel command line arguments, specify a different file path in <code>fallback_options</code> with the <code>--cmdline</code> argument. It also sources drop-in files under <code>/etc/cmdline.d/</code> during UKI generation. However, the latter won't allow you to pass different command line arguments for the default and fallback image.</p>

<p class="callout info"><strong>NOTE:</strong> Placing the UKI under <code>/efi/EFI/Linux/</code> allows <code>systemd-boot</code> to automatically detect images and list them without having to specifically create boot entries for them.</p>

~~~bash
# mkinitcpio preset file for the 'linux' package

#ALL_config="/etc/mkinitcpio.conf"
ALL_kver="/boot/vmlinuz-linux"

PRESETS=('default' 'fallback')

#default_config="/etc/mkinitcpio.conf"
default_image="/boot/initramfs-linux.img"
default_uki="/efi/EFI/Linux/arch-linux.efi"                                # NEW
#default_options="--splash /usr/share/systemd/bootctl/splash-arch.bmp"

#fallback_config="/etc/mkinitcpio.conf"
fallback_image="/boot/initramfs-linux-fallback.img"
fallback_uki="/efi/EFI/Linux/arch-linux-fallback.efi"                      # NEW
fallback_options="-S autodetect --cmdline /etc/kernel/cmdline_fallback"    # NEW
~~~

## Kernel Command Line Parameters

As `mkinitcpio` sources command line parameters from a specific file by default, saving them to that file further streamlines the generation process.

First create the directory and open a new file in there:

~~~bash
mkdir /etc/kernel
nano /etc/kernel/cmdline
~~~

The parameters to include depend on the kind of initramfs used. You can use any of the [persistent block device naming](https://wiki.archlinux.org/title/Persistent_block_device_naming) schemes to pass the device. You also need to specify a mapper name under which the decrypted root file system should be made available for mounting.

You can obtain the block device identifier for the LUKS container, e.g. its UUID, with `blkid` (using `/dev/sda1` as an example):

<p class="callout info"><strong>NOTE:</strong> Pressing <code>Ctrl + T</code> inside <code>nano</code> allows you to paste the result of a command at the current cursor position.</p>

~~~bash
blkid -s UUID -o value /dev/sda1
~~~

Continue to specify additional kernel command line parameters you need. At minimum it should look like this:

* busybox:
  ~~~
  cryptdevice=UUID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX:cryptroot root=/dev/mapper/cryptroot rw
  ~~~
* systemd:
  ~~~
  rd.luks.name=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX=cryptroot root=/dev/mapper/cryptroot rw
  ~~~

<div class="callout info">
  <p><strong>TIP:</strong> You can further simplify this by using a systemd-based initramfs. Create a file named <code>/etc/crypttab.initramfs</code> and specify your encrypted devices in there (same syntax as regular <code>/etc/crypttab</code>, see <a href="https://man.archlinux.org/man/crypttab.5.en" target="_blank">crypttab(5)</a>):</p>
  <pre><code># &lt;name&gt;    &lt;device&gt;                                     &lt;passphrase&gt;    &lt;options&gt;
cryptroot   UUID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX                    discard</code></pre>
  <p>This allows you to omit any <code>rd.luks</code> parameters, which leaves you with a kernel command line that looks like this:</p>
  <pre><code>root=/dev/mapper/cryptroot rw</code></pre>
</div>

<p class="callout warning"><strong>ATTENTION:</strong> Keep the specialties of your chosen root file system in mind, e.g. if using btrfs you also need to supply the subvolume that should be mounted: <code>rootflags=subvol=@</code>.</p>

<div class="callout info">
  <p><strong>NOTE:</strong> By default, dm-crypt does not allow TRIM for SSDs for security reasons (information leak). To override this behavior:
  <ul>
    <li><strong>busybox:</strong> append <code>:allow-discards</code> after the device mapper name</li>
    <li><strong>systemd:</strong> do one of the following
      <ul>
        <li>add <code>rd.luks.options=discard</code> as an additional kernel command line parameter</li>
        <li>specify the <code>discard</code> option in <code>/etc/crypttab.initramfs</code> in the options field</li>
      </ul>
    </li>
  </ul>
</div>

## Enroll keys in firmware

<p class="callout danger"><strong>WARNING:</strong> Replacing the platform keys with your own can end up bricking your machine, making it impossible to get into the UEFI/BIOS settings to rectify the situation. This is due to the fact that some device firmware (OpROMs, e.g. GPU firmware), that gets executed during boot, may be signed using Microsoft's keys. Run <code>sbctl enroll-keys --microsoft</code> if you're unsure if this applies to you (enrolling Microsoft's Secure Boot keys alongside your own custom ones) or include the <a href="/books/arch-linux/page/trusted-platform-module">TPM</a> Event Log with <code>sbctl enroll-keys --tpm-eventlog</code> (if your machine has a TPM and you don't need or want Microsoft's keys) to prevent bricking your machine.</p>

<p class="callout warning"><strong>ATTENTION:</strong> Make sure your firmware's Secure Boot mode is set to <code>setup</code> mode! You can do this by going into your firmware settings and wiping the factory default keys. Additionally, keep an eye out for any setting that auto-restores the default keys on system start.</p>

<p class="callout info"><strong>TIP:</strong> If you plan to dual-boot Windows, run <code>sbctl enroll-keys --microsoft</code> to enroll Microsoft's Secure Boot keys along with your own custom keys.</p>

To enroll your keys, simply:

~~~bash
sbctl enroll-keys
~~~

## Automated signing of UKIs

Next, add the images to the list of files to be signed (one at a time):

~~~bash
sbctl sign --save /efi/EFI/Linux/arch-linux.efi
sbctl sign --save /efi/EFI/Linux/arch-linux-fallback.efi
~~~

The `sbctl` package comes with a pacman hook to execute `sbctl sign-all -g` on kernel upgrades or installs. The UKIs are ready to be booted directly by the UEFI firmware (EFISTUB booting) or via a bootloader like `grub`, `systemd-boot` or `rEFInd`.

<div class="callout warning">
  <p><strong>ATTENTION:</strong> Currently, the <code>sbctl</code> package also provides a post mkinitcpio hook which runs <code>sbctl</code> after every kernel build. This means with the default <code>linux</code> kernel installed, <code>sbctl</code> will run <strong>at least three times</strong>, twice for each time <code>mkinitcpio</code> runs during pacman package upgrades and once after pacman finishes. The usefulness of the hook has been <a href="https://github.com/Foxboron/sbctl/issues/284" target="_blank">disputed</a>. A patch has been <a href="https://github.com/Foxboron/sbctl/pull/285" target="_blank">submitted</a>.</p>
  <p>For the time being, comment out the line calling <code>sbctl sign-all -g</code> in the hook file: <code>/usr/lib/initcpio/post/sbctl</code></p>
</div>

## Signing the Bootloader

<p class="callout info"><strong>NOTE:</strong> This is the manual method. If you also want to automate the bootloader update process, skip to the section below.</p>

If you plan on using a boot loader, you will also need to add its `*.efi` executable(s) to the `sbctl` database, e.g. `systemd-boot`:

~~~bash
sbctl sign --save /efi/EFI/BOOT/BOOTX64.EFI
sbctl sign --save /efi/EFI/systemd/systemd-bootx64.efi
~~~

Upon system upgrades, `pacman` will call `sbctl` to re-sign the files listed in `sbctl`'s database.

### Automate `systemd-boot` updates and signing

`systemd` comes with a `systemd-boot-update.service` unit file to automate updating the bootloader whenever `systemd` is updated. However, it only updates the bootloader **after** a reboot, by which time `sbctl` has already run the signing process. This would necessitate manual intervention.

Recent versions of `bootctl` look for a `.efi.signed` file before a regular `.efi` file when copying bootloader files during `install` and `update` operations. So to integrate better with the auto-update functionality of `systemd-boot-update.service`, the bootloader needs to be signed ahead of time.

~~~bash
sbctl sign --save -o /usr/lib/systemd/boot/efi/systemd-bootx64.efi.signed /usr/lib/systemd/boot/efi/systemd-bootx64.efi
~~~

This will add the source and target file paths to `sbctl`'s database. The pacman hook included with `sbctl` will trigger whenever a file in `usr/lib/**/efi/*.efi*` changes, which will be the case when `systemd` is updated and a new version of the unsigned bootloader is written to disk at `/usr/lib/systemd/boot/efi/systemd-bootx64.efi`.

Finally, enable the `systemd-boot-update.service` unit:

~~~bash
systemctl enable systemd-boot-update
~~~

Now when `systemd` is updated the **signed** version of the `systemd-bootx64.efi` booloader will be copied to the ESP after a reboot, completely automating the bootloader update and signing process!