Secure Boot Guide

What Secure Boot Changes

These modules are built by DKMS and signed with a local key the kernel does not know yet. It refuses them until you enroll that key. Run sudo dkms status to see the ones on your system.

Before You Start

• This guide is for an installed Kodachi on UEFI firmware. A machine booted in BIOS mode has no Secure Boot.
• Installing from a current image sets up the boot chain for you, encrypted or not.
• A live session keeps nothing after a reboot, so it has no key to enroll. With Secure Boot on, a live session runs without these modules. If you need one there, turn Secure Boot off for that session.
• You must be at the machine. The last step is a screen at boot, and it cannot be done over SSH.

Check Your Boot Chain

Secure Boot starts Kodachi through a signed shim and a signed GRUB. Check that they are on your disk.

sudo sh -c 'ls /boot/efi/EFI/*/shimx64.efi'

If it prints a path, check which file the firmware boot entry starts:

sudo efibootmgr -v | grep -i kodachi

If the Kodachi line ends in shimx64.efi), go on to the next section. If it ends in grubx64.efi), the shim is on your disk but the firmware skips it and starts GRUB directly, and Secure Boot stops it with a security violation. If the first command found nothing, this system was installed before Kodachi set them up, with the same result. In both cases, if the system is not encrypted, run the repair, then reboot once with Secure Boot still off and check that Kodachi starts.

sudo kodachi-install-shim-chain --online

It needs the internet and takes a few minutes. If the command is not found, update Kodachi first. If it answers that the shim is already present and the ESP needs nothing while the entry still ends in grubx64.efi), your copy of the repair is older than this fix: update Kodachi and run it again. It installs the signed packages, writes the boot files on the EFI partition, and sets the firmware boot entry to start the shim. If it cannot finish, it says why and puts back the boot files, the firmware entries and GRUB's modules. Packages it installed stay installed, and the message names them. A power cut or a forced kill leaves its copy and its record of the firmware entries on the EFI partition, and the next run finishes the restore before it does anything else. The restore of firmware entries has only been run against a simulated firmware, not a real board.

If it says it does not know what the firmware boot entry points at, the boot files stay in place and the state of the firmware entry is unknown. If Secure Boot is off, keep it off, and ask on the public Discord: the support page has the link.

It does not run on an encrypted system. That case has not been proven, and a failed boot there stops at a grub> prompt. An encrypted system from before this change stays with Secure Boot off, or gets the boot chain from a fresh install of a current image.

Check Your Firmware Keys

The signed shim is trusted through the keys your board came with. If those keys were cleared, the firmware shows PK unloaded or Setup Mode, and Secure Boot cannot turn on.

• Open the Secure Boot page in your firmware settings and find Key Management.
• Restore the factory or default keys. Boards call this Install Default Secure Boot Keys or Restore Factory Keys.
• Do not choose Clear Secure Boot Keys or Reset To Setup Mode.
• Save and leave. Clearing or restoring these keys changes the firmware only, not your disk.

On many ASUS boards Secure Boot has no on and off switch. Set OS Type to Windows UEFI mode to turn it on, and to Other OS to turn it off. The name is only a label: Kodachi does not need Windows.

Enroll Your Signing Key

1. Check that this machine has its own key. Kodachi images ship without a private signing key, on purpose. The first module rebuild on your machine creates one.

   sudo ls -l /var/lib/dkms/mok.key
   

   If the file is missing, rebuild the modules for the kernel you are running. This creates the key and signs them with it, and it takes about 10 minutes on a two-core machine. A plain dkms autoinstall is not enough: it skips modules that are already built, so it creates no key. Modules of any other installed kernel keep their old signature, so run this again after you first boot that kernel.

   sudo sh -c 'dkms status -k "$(uname -r)" | cut -d, -f1 | sort -u | while read -r m; do dkms build "$m" --force && dkms install "$m" --force; done'
   

2. Ask for the key to be enrolled. You choose a one-time password here. You type it once, at the next boot.

   sudo mokutil --import /var/lib/dkms/mok.pub
   sudo mokutil --list-new
   

   The second command shows the waiting key, named CN=DKMS module signing key.

3. Reboot and confirm. A blue MOK manager screen appears before Kodachi starts. Press a key when it asks, choose Enroll MOK, then Continue and Yes, type the password and reboot. If you miss the screen, Kodachi boots as usual: run step 2 again.
4. Turn on Secure Boot in your firmware settings, after the two checks above.
5. Check the result after Kodachi starts.

   mokutil --sb-state
   sudo mokutil --test-key /var/lib/dkms/mok.pub
   health-control tirdad-status
   

   You should see SecureBoot enabled and /var/lib/dkms/mok.pub is already enrolled.

After You Enroll

• Kernel updates need nothing from you. DKMS signs the modules for each new kernel with the same key.
• Keep the private key on this machine. /var/lib/dkms/mok.key is readable by root only. Whoever holds it can sign a module your kernel trusts, so never copy or share it.
• Enroll only a certificate made on this machine. Never enroll one you downloaded or were sent.

Troubleshooting

Related Documentation

• Health Control Guide, hardening, boot checks and Tirdad.
• Health Control CLI Reference, exact generated syntax and examples.
• Desktop Version Guide, what the installed desktop includes.
• Debian Secure Boot, the Debian reference for the same steps.