# Secure Boot

> An option in the installer. Every computer makes its own start-up keys; at most one blue key screen, once, with the password boot.

Source: https://wolos.org/manual/secure-boot

## What it is

Secure Boot is the check, made by the computer's firmware, that lets only signed programs start. WolOS signs its boot images with keys made **on your computer, at install**. No image carries a shared WolOS key, and no two computers share one. In the installer it is a page you choose: **Use Secure Boot** is off unless you turn it on, and you can turn it on later in Settings > Privacy & Security > Startup Security.

Think of it as a seal on a jar: at every start the computer checks that the seal is unbroken, which means nobody changed WolOS while the computer was off. The seal is made with a key that only your computer has.

## Why

A vendor key that signs every copy of a system is one secret that, once leaked, unlocks every copy. A key per computer has no such single point ([the decision: Signed boot with this computer's keys](/reference/adr-0025)). The price is that the computer signs its own updates, so its key lives on it, encrypted to the TPM chip when there is one. The other price is the blue key screen: your firmware has never seen this computer's key, so it asks you once.

## How

### Which path your computer takes

The installer picks the simplest path your firmware allows (`wol boot detect` shows which) and the Secure Boot page says what On and Off mean for it:

| Your firmware | What happens when Secure Boot is on |
|---|---|
| In *Setup Mode* | WolOS puts its own keys next to Microsoft's. "Nothing to click". |
| Microsoft's third-party certificate present (most PCs), Secure Boot on or off | A signed, unmodified first stage starts WolOS's loader. "One blue screen after the restart" asks you to confirm the key **once**. If Secure Boot is already on in the firmware you cannot leave it off here (WolOS would only start after a trip to the startup settings), so the page just says one blue screen will come. |
| Secure Boot on and the firmware trusts only Windows | A firmware setting has to change first. The installer's sheet "Change One Startup Setting First" says: after installing, open the startup settings (often F2, F10, F12 or Delete) and allow third-party certificates (sometimes called *Microsoft UEFI CA* or *Other OS*). Then the blue screen asks once. |
| None of the above | WolOS starts without signatures and Settings says so. |

![The installer's Secure Boot page with Use Secure Boot turned on: under the switch it lists the steps of the one blue screen.](/img/manual/installer-secure-boot.png)

On a computer that trusts WolOS only through its firmware keys, Secure Boot switches itself to the stronger setup after the key has been enrolled.

### The key screen on the installed system, step by step

After the restart a blue screen appears: the key screen. It comes from your computer's firmware, not from WolOS, and it waits for you. It looks like an old computer screen: blue, white letters, a short menu. **The mouse does not work there:** use the arrow keys and Enter.

1. **Press a key.**
   You see a short menu that includes *Enroll MOK*.

   ![The firmware's blue key screen on an installed WolOS, captured in a virtual machine: Perform MOK management, with Continue boot, Enroll MOK, Enroll key from disk and Enroll hash from disk.](/img/manual/vm-install-mok-menu.png)
2. **Choose Enroll MOK, then Continue, then Yes.**
   You see a prompt for a password.
3. **Type `boot`.** Nothing shows while you type. Press Enter.
4. **Choose Reboot.**
   WolOS starts. You will not see this screen again.

The word comes from `wol boot password`. The blog post [The blue screen at first start](/blog/the-blue-screen) tells the story of this screen.

### The live USB stick with Secure Boot on

The live stick boots with Secure Boot on. Its first-stage loader, boot loader and kernel image are signed with the WolOS live-image key. The first start from the stick asks once to enrol that key. The certificate is on the stick as `ENROL_THIS_KEY_FOR_WOLOS.cer` (also `EFI/wolos/`), with a `README.txt` that says the same as these steps:

1. **If a screen says "Verification failed", press Enter.**

   ![The firmware's blue ERROR box from the live stick, captured in a virtual machine: Verification failed: (0x1A) Security Violation, with one OK button.](/img/manual/vm-live-secureboot-verification-failed.png)
2. **At "Press any key", press a key within 10 seconds.**
   You see the same kind of blue menu.

   ![Perform MOK management: Continue boot, Enroll key from disk, Enroll hash from disk.](/img/manual/vm-live-secureboot-key-menu.png)
3. **Choose Enroll key from disk**, then the volume that holds `ENROL_THIS_KEY_FOR_WOLOS.cer` (your USB stick, often the last one in the list; if you see `EFI\Microsoft`, press **Esc** and pick the next one), then the file.

   ![Select Key: the list of volumes the firmware can read; here only one, the USB stick.](/img/manual/vm-live-secureboot-key-volumes.png)

   ![The files on the stick: the folders EFI, loader and wolos, and the file ENROL_THIS_KEY_FOR_WOLOS.cer.](/img/manual/vm-live-secureboot-key-files.png)
4. **Choose Continue, then Yes.**

   ![Enroll MOK: View key 0 and Continue.](/img/manual/vm-live-secureboot-key-enroll.png)

   ![Enroll the key(s)?: No and Yes.](/img/manual/vm-live-secureboot-key-confirm.png)
5. **Choose Reboot.**
   WolOS starts and the blue screen does not come back.

   ![Perform MOK management after the key was enrolled, with Reboot selected.](/img/manual/vm-live-secureboot-key-reboot.png)

Missed the 10 seconds? Start from the stick again: the screen comes back. This key starts the WolOS **stick** only. An installed WolOS uses its own key, and the installer says what to expect before its restart. With Secure Boot **off** in the firmware, none of this is read and the stick starts straight away.

When the install put WolOS's own keys into the firmware (Setup Mode), the stick is not signed with those keys and will no longer start on that computer. Remove it when the screen goes dark.

### Checking and repeating it

| Command or place | Does |
|---|---|
| `wol boot status` | Prints how well this computer is protected at start: the Secure Boot level, the security chip, kernel lockdown and the state of the system seal. Settings reads the same facts. |
| Settings > Privacy & Security > Startup Security | Shows how this computer starts. If a key is waiting it says "This computer's key is queued: a blue screen asks once at the next restart", and **Finish Secure Boot setup** finishes it (it runs once, then the page reads the facts again). |
| `wol boot enroll` (administrator) | Queues this computer's key for the key screen again. Restart. |

![Startup Security in Settings: Secure Boot, keys, kernel lockdown, the security chip, measured startup, the sealed system and the release number, one row each.](/img/manual/settings-startup-security.png)

### What signing protects

When WolOS starts signed, the kernel runs locked down and accepts only signed drivers. The seal on the system files and a version number are part of what is signed, so an older, retired copy of the system cannot be started again. The key that opens your disk follows signed kernels: updates keep unlocking the disk, while a kernel that someone changed does not. The boot menu can no longer be edited at start.

What it costs: a locked-down kernel does not hibernate, and extra drivers from outside WolOS, such as NVIDIA's, need the same key screen once.

## A worked example

Alice installs WolOS with **Use Secure Boot** on. Her computer trusts the usual third-party certificate, so the installer says "One blue screen after the restart". After the first restart a blue screen appears. She presses a key, uses the arrow keys to choose *Enroll MOK*, then *Continue*, then *Yes*, types `boot` (nothing shows while she types) and presses Enter, then chooses *Reboot*. WolOS starts, and the blue screen never comes back. Total time: under a minute.

## If something goes wrong

| What you see | What to do |
|---|---|
| I missed the blue screen, or the computer started without asking | WolOS starts without the key and asks again at the next start (`wolos-mok-enroll.service` repeats it until the key is enrolled). Or run `wol boot enroll` and restart. |
| The password `boot` seems wrong | Nothing shows while you type, so type it and press Enter. If the screen refuses it, run `wol boot enroll`, restart and try again. `wol boot password` prints the word. |
| The blue screen comes back at every start | The key was not enrolled: you chose a different option or did not finish. Repeat the steps, ending with **Reboot**. |
| Windows asks for its BitLocker recovery key after the Secure Boot step | Expected once when Secure Boot keys change; the installer warned you. Key location: `account.microsoft.com/devices/recoverykey`. See [Installing next to Windows](/manual/dual-boot). |
| The disk asks for a password (or the recovery key) after a Secure Boot or firmware change | The security chip refused because the measured state changed. Type your account password; the next start is automatic again because the chip is sealed again (`wol encrypt reseal` runs on its own). See [Recovery](/manual/recovery). |
| The stick says "Verification failed" and nothing else | Follow the live-stick steps above, or turn Secure Boot off in the firmware for the first start. |
| WolOS will not start at all with Secure Boot on | Open the firmware's startup menu and pick the other slot, or turn Secure Boot off. Settings > Privacy & Security > Startup Security says what the installed system expects. |
| Settings says the computer starts without signatures | The firmware was neither in Setup Mode nor trusting Microsoft's third-party certificate when you installed, so WolOS started unsigned and said so. If you change that setting later, Startup Security is where you finish the setup. |
| A virtual machine such as VirtualBox | Turn *Enable Secure Boot* off to start the stick unless you enrol its key; after the install you can turn it on and follow the key screen. See [Download](/download#virtualbox). |