// 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.

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.