Secure Boot

Secure Boot

SynapseOS ships a policy tool, syn-secureboot, whose design rule is "assume Secure Boot is on, fall back safely if it is not." It manages kernel module signature enforcement (module.sig_enforce=1) and it will only ever turn enforcement on when doing so is provably safe — so a machine with no Secure Boot, or one where you later switched SB off, still boots and still loads its nvidia and synapse_kmod modules.

syn-secureboot status   # read-only, safe anywhere
syn-secureboot enroll   # guided key enrollment (real hardware)
syn-secureboot apply    # turn on enforcement iff trusted (runs each boot)

---

The rule: never enable Secure Boot first

Sign everything and verify it green while SB is still off, and only then flip SB on in firmware. That way the first boot with SB enabled is guaranteed to succeed rather than being the moment you find out something was unsigned.

You can always get back in. Secure Boot is a firmware toggle, never a permanent lockout. If a boot fails, enter firmware setup at power-on (Del / F2 — that always works regardless of SB), turn Secure Boot off, save, and you boot normally again. Keep a live USB as a second net anyway.

---

Setup Mode: the part that trips everyone

sbctl enroll-keys only works when the firmware is in Setup Mode, and:

Setup Mode means the firmware holds no Platform Key (PK).

That's the whole definition. With a PK present, the firmware rejects any key enrollment that isn't signed by that PK — so no tool running in Linux can talk its way in. You enter Setup Mode only by deleting the PK from inside firmware setup.

This matters because sbctl's own error message is misleading:

Your system is not in Setup Mode! Please reboot your machine and reset secure
boot keys before attempting to enroll the keys.

It reads as though rebooting is the fix. It is not, and it never can be — a reboot does not remove a Platform Key. You will reboot, get the identical error, and be exactly where you started. The "reset secure boot keys" it refers to happens in the BIOS menu, not in the OS.

syn-secureboot enroll checks this for you before printing anything else:

Firmware state:
  Secure Boot: off (correct for enrolling)
  Setup Mode:  DISABLED — the firmware still holds a Platform Key.

  ==> STOP. `sbctl enroll-keys` CANNOT succeed in this state, and REBOOTING
      WILL NOT CHANGE IT.

Confirming the state yourself

sbctl status     # "Setup Mode: ✓ Disabled" means NOT in setup mode (confusing wording)

# the ground truth, straight out of efivars — 1 = in Setup Mode, 0 = not:
od -An -t u1 -j4 /sys/firmware/efi/efivars/SetupMode-8be4df61-93ca-11d2-aa0d-00e098032b8c

If a PK-8be4df61-… variable exists and has real content (a few hundred bytes), a Platform Key is enrolled and you are not in Setup Mode.

Clearing the keys — ASUS (AMI BIOS)

1. Del at power-on → F7 for Advanced Mode.
2. Boot → Secure Boot → Key Management.
3. Clear Secure Boot Keys.
   • Not Restore Factory Keys — that re-installs the vendor PK and puts you straight back where you started. It is the opposite operation.
4. Still in the Secure Boot menu, set OS Type = Windows UEFI mode.
   • ASUS's "Other OS" silently disables SB enforcement. You would enroll keys, see no errors, and still boot unsigned — looking protected while protecting nothing.
5. F10 to save and reboot.

On other vendors the menu lives under Boot or Security and is called Key Management / Expert Key Management; you want whichever item erases / clears / deletes the keys.

---

Enrollment, start to finish

With Secure Boot off and Setup Mode enabled:

pacman -S sbctl
sbctl create-keys
sbctl enroll-keys -m          # -m ALSO enrolls Microsoft's UEFI CA

Do not skip -m on a machine with a discrete GPU. Microsoft's CA is what signs the nvidia GPU option ROM; without it the card may not initialise under Secure Boot and you get no display.

sbctl sign -s /boot/efi/EFI/SynapseOS/grubx64.efi
sbctl sign -s /boot/vmlinuz-linux
sbctl verify                  # EVERYTHING must show signed. This is the green light.

Only once sbctl verify is fully green: reboot into BIOS, enable Secure Boot, save. Back in SynapseOS:

syn-secureboot status         # should now show Secure Boot enabled
syn-secureboot apply          # enables module.sig_enforce=1 when trusted

Re-sign after every GRUB or kernel update (a pacman hook can automate this).

---

Module signature enforcement

Separate from boot signing. syn-secureboot apply turns on module.sig_enforce=1 only if Secure Boot is on and every currently loaded out-of-tree module carries a signature the kernel trusts. It decides the second half by reading TAINT_UNSIGNED_MODULE (bit 13 of /proc/sys/kernel/tainted): if that bit is clear, everything loaded so far was trusted, so enforcement will not lock anything out.

To get synapse_kmod and nvidia's DKMS modules trusted, import the DKMS key:

mokutil --import /var/lib/dkms/mok.pub   # reboot, enroll at the blue MOK screen

Skipping this is fine — Secure Boot still protects boot, and syn-secureboot simply holds module enforcement off, which is the safe fallback.

A note on this machine (dual-boot): it boots GRUB alongside batocera. Any other OS sharing the disk must also be Secure-Boot-signed or it stops booting once SB is on. That's why SB enablement here has been treated as optional and deferred rather than a default.

See also: Troubleshooting, synguard and synapse_kmod.