// guide

Secure Boot

What Visor verifies, what the firmware verifies, and what neither does.

Behavior under Secure Boot

PE images (Windows Boot Manager, UKIs, EFI-stub kernels, chainloaded loaders): if shim is present, Visor asks its SHIM_LOCK protocol to verify the image and refuses the boot on failure. With or without shim, the firmware's own LoadImage verification still applies — an unsigned or untrusted image is rejected by the firmware itself.
Raw (non-PE) kernels boot through the EFI handover protocol, which bypasses firmware verification entirely — so under Secure Boot, Visor refuses them unless shim verifies them first.
With Secure Boot off, everything boots normally.

When the firmware rejects an image, Visor logs the exact EFI status code and says plainly that Secure Boot refused it (EFI_SECURITY_VIOLATION / EFI_ACCESS_DENIED), with a hint to sign/enroll the image or disable Secure Boot — no more guessing from a vague failure.

Getting a fully signed chain

Two workable models:

Your own keys (sbctl) — enroll custom keys, then sign visor_x64.efi, your kernels/UKIs, and any EfiFs driver. The installer offers this (install.sh --sign), and visor sign re-signs everything installed on the ESP, drivers included.
Shim — boot Visor via shimx64.efi; shim then validates your kernels against the enrolled db/MOK certificates, and Visor consults shim for every image it launches.

USB sticks: a hotplugged stick's loader must also be trusted. A Ventoy stick created without its Secure Boot option carries an unsigned GRUB that the firmware will (correctly) refuse — recreate the stick with Secure Boot support, sign its loader with sbctl sign, or disable Secure Boot for that boot.

Scope of the guarantee — read this part

Secure Boot / shim verification covers the kernel or UKI image only. It does not cover the initrd, the kernel command line, or boot.conf — an attacker with write access to the ESP could alter those without failing verification. (This is true of most boot managers; systemd-boot has the same property for non-UKI entries.) To close that gap:

Boot a UKI — kernel, initrd, and cmdline are one signed PE image, verified as a unit; or
pin the kernel hash with the sha256= entry key (boot refused on mismatch), and store the initrd as a VISORENC container — its HMAC-SHA256 check refuses tampered files.

Measured boot (TPM2)

When a EFI_TCG2_PROTOCOL is present Visor measures the on-disk boot.conf into PCR 5 and the exact kernel command line (NUL-inclusive) into PCR 12 via HashLogExtendEvent. The PCR 5 event uses EV_EVENT_TAG 0xf5bc582a so a Visor boot and an sd-boot boot land the same log entry; PCR 12 matches systemd's tpm_log_load_options layout so a LUKS2 sealed-key policy for PCR 12 stays portable.

The active PCR banks are published as volatile LoaderTpm2ActivePcrBanks and advertised in LoaderFeatures (TPM2_ACTIVE_PCR_BANKS). Configure with tpm=1 (default, alias measure) and tpm_pcr_config / tpm_pcr_cmdline (0–23, defaults 5 and 12). Set tpm=0 to skip entirely. The firmware log is checked — if the measured data would be silently ignored, Visor logs and continues rather than pretending to measure.

Tip — combine a UKI (signed, therefore verified) with a TPM-sealed LUKS key for PCR 12 and you cover both Secure Boot (the image) and measured boot (the cmdline) without extra tooling.

Other hardening in the load path

Image decode budgets: PNG/BMP dimensions capped (8192 per side, 16M pixels) so a crafted image cannot exhaust memory.
EfiFs driver downloads are pinned to a fixed upstream release and SHA-256 verified before install.
Config and directory parsing validate lengths and structures (no fixed line limits, no truncated device paths).
Decrypted buffers and captured passwords are wiped after use.