First-Boot Secure Boot Setup

UEFI only. This page applies only to installs on UEFI hardware. If cache22-install reported Firmware mode: legacy BIOS during install, skip this entire page — BIOS has no Secure Boot mechanism, and the installed system will boot directly via GRUB without any first-boot setup.

cache22 ships with its own per-machine Secure Boot key. The key is generated by sbctl create-keys on the user’s machine during install and lives only on the encrypted root. There is no central CI signing key.

For the new key to be trusted by firmware, the firmware must enroll it. cache22 stages auto-enroll files during install. sd-boot performs the actual enrollment on first boot, but only when the firmware is in setup mode. Putting the firmware in setup mode is the user’s only manual step.

Why setup mode is required

UEFI firmware accepts new Platform Keys (PK), Key Exchange Keys (KEK), and signature database (db) entries only when the firmware is in setup mode. In normal user mode, modifying these requires a signed update from the existing PK holder, which is typically the OEM (Microsoft, HP, Dell, etc).

Setup mode is entered by either:

  • Disabling Secure Boot temporarily. Many firmwares delete or invalidate the PK when SB is disabled, putting them in setup mode automatically. Re-enabling SB after sd-boot enrollment puts the firmware back in user mode with cache22’s PK installed.
  • Clearing or resetting the Platform Key (PK) explicitly. Some firmwares offer a menu option named “Reset to Setup Mode”, “Erase All Secure Boot Settings”, “Clear Secure Boot Keys”, or similar.

Either action removes the existing PK. sd-boot then enrolls cache22’s PK + KEK + db plus the Microsoft DB keys (so dual-boot Windows continues to work) on first boot.

How to enter setup mode

Steps vary by firmware vendor. The general pattern:

  1. Reboot the machine after installation completes. Remove the USB installer drive when prompted.
  2. At power-on, press the firmware setup key. Common keys: F2 (Dell, ASUS, MSI, many laptops), DEL (most desktop boards), F1 (some Lenovo), F10 (HP), ESC (many laptops). The firmware typically displays which key to press during the POST splash screen.
  3. Navigate to the Secure Boot settings. Common locations: “Boot” tab, “Security” tab, or a dedicated “Secure Boot” submenu.
  4. Either:
    • Set Secure Boot to Disabled, save, and exit. (Many firmwares enter setup mode this way.)
    • Find an option named Reset to Setup Mode, Clear Secure Boot Keys, Erase Platform Key, or Restore Factory Keys to Default and select it.
  5. Save changes and exit. The machine will boot into cache22’s installed system.

For vendor-specific steps, consult your firmware vendor’s documentation or these references:

What happens on first boot

When cache22 boots in setup mode for the first time:

  1. sd-boot detects setup mode (firmware reports SetupMode = 1 in EFI variables).
  2. sd-boot reads loader/keys/auto/*.auth files staged by the installer at /efi/loader/keys/auto/.
  3. sd-boot enrolls those keys into firmware in this order: db keys, KEK, then PK. Enrolling the PK exits setup mode.
  4. The machine reboots once automatically.
  5. On the second boot, Secure Boot is enforced with cache22’s keys (and Microsoft DB keys) trusted. sd-boot verifies and loads the signed UKI.

Verification

After successful enrollment, log in and check Secure Boot state:

cache22-secureboot status

Expected output:

Secure Boot:           Enabled (enforcing)
Setup mode:            No
Platform key fingerprint: <local SHA-256 fingerprint>
Latest signed UKI:     /efi/EFI/Linux/cache22-<csum>.efi

If Secure Boot reports Disabled after first boot, sd-boot did not enroll the keys. Either the firmware did not enter setup mode, or sd-boot did not detect setup mode at boot. See Troubleshooting for recovery steps.

Skipping Secure Boot

cache22 works without Secure Boot. To run without SB enforcement:

  1. Leave Secure Boot disabled in firmware after install.
  2. Skip the setup-mode step above.
  3. cache22 boots normally. sd-boot does not attempt enrollment when SB is disabled.

cache22-secureboot status will report Secure Boot: Disabled in this configuration. UKIs are still signed (the signing happens regardless of whether anyone verifies it), but no firmware verification occurs at boot.

To enable SB later, run:

sudo cache22-secureboot enable

This generates the key if missing, regenerates the auto-enroll files, and instructs the user to reboot into setup mode.

What if I have other operating systems on the same machine

cache22 enrolls the Microsoft DB keys alongside its own keys during first-boot enrollment. Microsoft-signed bootloaders (Windows, most Linux distros that use shim) continue to verify and boot. Dual-boot is preserved.

To remove Microsoft keys later (loss of dual-boot for Windows and most signed-shim distros):

sudo cache22-secureboot disable    # Removes cache22's keys.
                                    # Microsoft keys are kept.
                                    # Re-run with --remove-microsoft to drop those too.

See cache22-secureboot for the full key management workflow.

What to do next

Continue to Updates and Reboots for the day-to-day update workflow.