a27d3fb313
- docs/secureboot.md: MOK workflow (generate, build, enroll). - docs/building.md: image + install quickstart, new outputs, ARCLINE_SIGN. - docs/observability.md: vendor .debs are now the primary packaging path. - docs/editions.md: cloud ships a qcow2; qemu test command. - docs/architecture.md: full pipeline table incl. deploy/install; the four follow-up items are now implemented; new "on the horizon" list. - README: updated feature list, quickstart, and status.
62 lines
2.2 KiB
Markdown
62 lines
2.2 KiB
Markdown
# Secure boot (MOK-based)
|
|
|
|
Arcline can ship **self-signed** boot chains verified by your machine's own
|
|
secure-boot firmware. We use a **Machine Owner Key (MOK)** — the same approach
|
|
used to load custom kernels on Windows-certified laptops — rather than paying
|
|
for a Microsoft KEK signing cert. You own the key, you own the trust anchor.
|
|
|
|
```
|
|
MOK.priv ──(sbsign)──► vmlinuz, grubx64.efi, shimx64.efi
|
|
MOK.der ──(mokutil)──► enrolled into firmware MOK list (one-time prompt)
|
|
```
|
|
|
|
## Workflow
|
|
|
|
1. **Generate the key** (once, keep it secret):
|
|
|
|
```bash
|
|
scripts/secureboot/gen-keys.sh # → build/keys/{MOK.priv,MOK.pem,MOK.der}
|
|
```
|
|
|
|
2. **Build a signed image** (ISO or disk image):
|
|
|
|
```bash
|
|
ARCLINE_SIGN=1 make iso-server
|
|
ARCLINE_SIGN=1 make image-cloud
|
|
```
|
|
|
|
The build signs every kernel + EFI binary in the boot chain with the MOK
|
|
and ships the *public* `MOK.der` into the image at `/etc/arcline/MOK.der`.
|
|
|
|
3. **Enroll on first boot** — the `arcline-mok-enroll.service` unit imports the
|
|
key automatically the first time the system boots with secure boot enabled.
|
|
The firmware shows a one-time "Enroll MOK" prompt; confirm it, reboot, done.
|
|
The unit disables itself afterwards (and no-ops entirely when no key was
|
|
shipped — secure boot is off by default).
|
|
|
|
Manual alternative:
|
|
|
|
```bash
|
|
sudo mokutil --import /etc/arcline/MOK.der
|
|
sudo reboot # then confirm at the blue MOK manager screen
|
|
```
|
|
|
|
## What gets signed
|
|
|
|
- kernels (`vmlinuz*`) — in `/boot` for installed systems, `/live` for ISOs
|
|
- EFI binaries (`*.efi`) — grubx64, shimx64, mmx64, fbx64
|
|
|
|
GRUB `.mod` modules are not PE binaries and are not individually signed (GRUB
|
|
has its own module-signature mechanism, out of scope here). If you use the
|
|
shim-provided fallback loader, the Microsoft-signed shim validates grubx64.efi
|
|
against your MOK.
|
|
|
|
## Notes
|
|
|
|
- Requires `sbsigntool` on the build host and `mokutil` in the image
|
|
(`mokutil` is pulled in by the `shim-signed` package already in the package
|
|
lists).
|
|
- Losing `MOK.priv` means you cannot sign future updates — back it up.
|
|
- Full vendor CA / Microsoft KEK signing is intentionally not used; revisit
|
|
only if a commercial distribution is ever pursued.
|