---
title: Secure Boot Setup
description: Set up secure boot with sbctl after installing CachyOS
---

import ImageComponent from '~/components/image-component.astro';

# sbctl

[sbctl](https://github.com/Foxboron/sbctl) is a user-friendly secure boot key manager capable of setting up secure boot,
offering key management capabilities, and keeping track of files that need to be signed in the boot chain.

## Installing sbctl

```bash
sudo pacman -S sbctl
```

## Pre-setup

### GRUB Boot Manager

If you are using GRUB, run the following command to enable secure boot support on GRUB using CA Keys.

```bash
sudo grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=cachyos --modules="tpm" --disable-shim-lock
```

:::note
Loading unnecessary modules in your boot manager has the potential to present a security risk.
Only run this command if you actually need secure boot.
:::

### Entering Setup Mode in UEFI
Firstly, we need to go to firmware settings and set secure boot mode to "Setup Mode". You can reboot from an
already running system to firmware settings with following command.

```bash
systemctl reboot --firmware-setup
```

<br />
<ImageComponent imgsrc={import('~/assets/images/ideapad-bios-secure-boot.jpg')} />

This is how the BIOS looks like on a Lenovo Ideapad 5 Pro. Reset to setup mode or restore factory keys and reboot back
to the system.

However, some MSI motherboards don't have a setup mode. To achieve the same effect, follow the two steps from the image below:
<br />
<ImageComponent imgsrc={import('~/assets/images/MSI-bios-secure-boot.jpg')} />

## Setting Up sbctl

```bash
sudo sbctl status # If setup mode is enabled we can proceed to the next step
Installed:      ✘ sbctl is not installed
Setup Mode:     ✘ Enabled
Secure Boot     ✘ Disabled

sudo sbctl create-keys # Create your custom secure boot keys
Created Owner UUID a9fbbdb7-a05f-48d5-b63a-08c5df45ee70
Creating secure boot keys...✔
Secure boot keys created!

# Enroll your keys with Microsoft's and the OEM firmware's built-in keys
sudo sbctl enroll-keys --microsoft --firmware-builtin
Enrolling keys to EFI variables...✔
Enrolled keys to the EFI variables!

sudo sbctl status
# sbctl should now be installed, we can proceed to signing the kernel images and boot manager
Installed:      ✔ sbctl is installed
Owner GUID:     a9fbbdb7-a05f-48d5-b63a-08c5df45ee70
Setup Mode:     ✔ Disabled
Secure Boot     ✘ Disabled
Vendor Keys:    microsoft
```

## Signing the Kernel Image and Boot Manager

CachyOS provides [sbctl-batch-sign](https://github.com/CachyOS/CachyOS-Settings/blob/master/usr/bin/sbctl-batch-sign),
a script that takes the list of files needed to be signed from `sudo sbctl verify` and signs them all.
Limine users should skip to [Limine](#limine).

:::caution
On systems with a separate `/boot` and `/boot/efi` partition layout, `sbctl` may only scan for EFI binaries in `/boot/efi`.
This causes kernel images that are in `/boot` to not be detected. `sbctl-batch-sign` works around this by **always** scanning
`/boot` for `vmlinuz-*` files.
:::

```bash
sudo sbctl verify
Verifying file database and EFI images in /boot...
✘ /boot/1c4b5246eef05ac3bc87339323cd5101/6.10.0-cn4.0.fc40.x86_64/linux is not signed
✘ /boot/EFI/BOOT/BOOTX64.EFI is not signed
✘ /boot/EFI/systemd/systemd-bootx64.efi is not signed
✘ /boot/1c4b5246eef05ac3bc87339323cd5101/0-rescue/linux is not signed
✘ /boot/1c4b5246eef05ac3bc87339323cd5101/6.10.0-cn3.0.fc40.x86_64/linux is not signed

sudo sbctl-batch-sign

sudo sbctl verify
Verifying file database and EFI images in /boot...
✔ /boot/1c4b5246eef05ac3bc87339323cd5101/6.10.0-cn4.0.fc40.x86_64/linux is signed
✔ /boot/EFI/BOOT/BOOTX64.EFI is signed
✔ /boot/EFI/systemd/systemd-bootx64.efi is signed
✔ /boot/1c4b5246eef05ac3bc87339323cd5101/0-rescue/linux is signed
✔ /boot/1c4b5246eef05ac3bc87339323cd5101/6.10.0-cn3.0.fc40.x86_64/linux is signed
```

Now that all the files are signed. **Reboot your system and go to your UEFI Settings to enable Secure Boot.**

Note that this is a one-time process as signing files with `-s` flag will save those files to `sbctl`'s database.

:::tip[Reminder]
`sbctl` ships with a [pacman hook](https://wiki.archlinux.org/title/Pacman_hook) meaning it will automatically
sign all new files upon a kernel or boot manager update.
:::

### systemd-boot

CachyOS uses `systemd-boot-update.service` provided by systemd to update the boot manager on reboot. This means that the `sbctl`
pacman hook will **not** sign the updated EFI binaries. As a workaround, we can sign the boot manager directly

```sh
sudo sbctl sign -s -o /usr/lib/systemd/boot/efi/systemd-bootx64.efi.signed /usr/lib/systemd/boot/efi/systemd-bootx64.efi
```

### Limine

Limine is a special boot manager that allows checking the hash of kernel
images and other files that Limine uses during boot. If this is enabled, any
sort of manual configuration done by the user, e.g. signing the image via
`sbctl-batch-sign`, will modify the hash of the corresponding files and
fail Limine's checksum verification.

However, signing these files isn't necessary on Limine because it has a special
boot process that bypasses EFI chainloading and signature checks. The only EFI
binaries that need to be signed are Limine itself.

:::caution[Limine >= 11.2.0]
Starting with Limine 11.2.0, Secure Boot policies are **strictly enforced** when UEFI Secure Boot is active:

- A BLAKE2B config checksum **must** be enrolled in the Limine EFI binary, otherwise Limine will panic with: `SECURE BOOT IS ACTIVE BUT NO CONFIG CHECKSUM IS ENROLLED`
- All file paths in `limine.conf` (kernel, initramfs, etc.) **must** have BLAKE2B hashes appended (e.g. `boot():/vmlinuz-linux#<hash>`)
- The config editor is unconditionally disabled
- Hash mismatches always cause a panic
:::

To enable automatic config checksum enrollment, set the following in `/etc/default/limine`:

```sh
ENABLE_ENROLL_LIMINE_CONFIG=yes
```

Then run:

```sh
# Use limine-enroll-config to enroll the config checksum and sign Limine's EFI binary
# This uses sbctl under the hood
sudo limine-enroll-config
sudo limine-update
```

## Verify that Secure Boot is Enabled

To check that secure boot is indeed enabled. You can run one of the following commands

```bash
sudo sbctl status
Installed:      ✓ sbctl is installed
Owner GUID:     a9fbbdb7-a05f-48d5-b63a-08c5df45ee70
Setup Mode:     ✓ Disabled
Secure Boot:    ✓ Enabled
Vendor Keys:    microsoft

bootctl
System:
      Firmware: UEFI 2.80 (INSYDE Corp. 28724.16435)
 Firmware Arch: x64
   Secure Boot: enabled (user)
  TPM2 Support: yes
  Measured UKI: no
  Boot into FW: supported
```

## Links and Credits

- [The Arch Wiki](https://wiki.archlinux.org/title/Unified_Extensible_Firmware_Interface/Secure_Boot#Assisted_process_with_sbctl)
laid the groundwork for this guide. Most of the stuff here was taken from there.
- [sbctl](https://github.com/Foxboron/sbctl) - This easy guide to enable secure boot support wouldn't have been possible if it weren't
for the amazing work done to create this piece of software.
- [Improving the Secure Boot Experience by Morten linderud](https://linderud.dev/blog/improving-the-secure-boot-user-experience/) - Blog post by Morten
"Foxboron" Linderud on how the secure boot experience was complicated before `sbctl`.
