Secure Boot

Security 2026-08-28

Shanios ships with its own MOK (Machine Owner Key) and signs all UKI images at install time. Secure Boot can be enabled after installation to ensure only verified OS images can boot.

How It Works

The full boot chain:

UEFI Firmware (verifies Shim via Microsoft CA)
  → Shim (verifies systemd-boot via MOK)
    → systemd-boot (verifies the UKI via MOK)
      → Unified Kernel Image (kernel + initramfs + cmdline, all signed together)

The MOK key pair is baked into the system image at build time — every machine installed from the same signed ISO shares the same key (the installer just verifies the keypair and re-signs with it; a fresh keypair is only generated on the spot as a fallback, if keys are missing or invalid)
Both UKIs (shanios-blue.efi, shanios-green.efi) are signed with this key
You enroll the public MOK in your firmware's MOK database
Enable Secure Boot in UEFI settings
Your firmware now verifies every Shanios UKI before booting it — unsigned or tampered images are rejected

The bootloader editor is disabled and the kernel command line is embedded in the UKI at build time, so it cannot be modified from the boot menu.

Each time shani-deploy runs an update, gen-efi rebuilds and re-signs the new slot's UKI before updating the boot entry.

Enrolling the MOK Key

Method 1: From the Live USB (Recommended)

On the first boot from the Shani OS USB, MokManager launches automatically:

Select "Enroll key from disk"
Navigate to the EFI partition and select EFI/BOOT/MOK.der
Confirm enrollment
Reboot and enable Secure Boot in BIOS

Method 2: From the Installed System

# Re-signs all EFI binaries, copies MOK.der to ESP, stages enrollment via mokutil
sudo gen-efi enroll-mok

# Reboot — MokManager appears automatically
# Confirm with the MOK password shown by the gen-efi configure flow
sudo reboot

After MokManager completes, enable Secure Boot in BIOS. Then clean up any stale keys from previous installations:

sudo gen-efi cleanup-mok

Verifying Secure Boot Status

# Check if Secure Boot is currently active
mokutil --sb-state

# List enrolled MOK keys
mokutil --list-enrolled | grep -i shani

# Verify a UKI is signed with the local MOK cert
sbverify --cert /etc/secureboot/keys/MOK.crt /boot/efi/EFI/shanios/shanios-blue.efi
sbverify --cert /etc/secureboot/keys/MOK.crt /boot/efi/EFI/shanios/shanios-green.efi

Key Files

File	Purpose
`/etc/secureboot/keys/MOK.key`	Private key — used by `gen-efi` to sign new UKIs (never leaves the device)
`/etc/secureboot/keys/MOK.crt`	PEM certificate — used by sbsign
`/etc/secureboot/keys/MOK.der`	DER-encoded public key — enrolled in firmware MOK database

Keys are stored in the /etc OverlayFS upper layer (inside @data) and persist across all updates and rollbacks.

Re-generating Keys

If gen-efi detects a missing or mismatched keypair, it regenerates the full pair automatically. To force re-enrollment after regeneration:

sudo gen-efi enroll-mok
# Reboot → complete MokManager enrollment → re-enable Secure Boot

Troubleshooting

Boot fails after enabling Secure Boot:

Reboot and disable Secure Boot temporarily
Verify MOK was enrolled: mokutil --list-enrolled | grep -i shani
Check UKI signature: sbverify --cert /etc/secureboot/keys/MOK.crt /boot/efi/EFI/shanios/shanios-blue.efi
Run sudo gen-efi configure blue to rebuild and re-sign, then retry enrollment

MokManager doesn't appear on reboot:

The firmware may have cleared the pending enrollment after timeout
Re-run sudo gen-efi enroll-mok and reboot again promptly

"Verification failed: (0x1A) Security Violation":

The UKI was not signed with an enrolled key
Disable Secure Boot, run sudo gen-efi configure blue, re-enroll with sudo gen-efi enroll-mok, and retry

MokManager asks for a password:

The enrollment password is not a fixed value — it is generated and displayed by the gen-efi configure/enroll flow when it stages enrollment. Use the password shanios printed at that point; if you no longer have it, re-run sudo gen-efi enroll-mok to stage a fresh enrollment.

TPM2 fails after Secure Boot change:

When you change Secure Boot settings, PCR 7 changes — re-enroll TPM2:

``bash sudo gen-efi cleanup-tpm2 sudo gen-efi enroll-tpm2 ``