Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 35 additions & 20 deletions docs/kb/how-tos/local-esp-boot.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,29 +115,44 @@ KEK only control *who may change* `db`.

**How many variables you need depends on who performs the write.**

| Enrolling via | Variables needed | Why |
It is decided by **what the platform will accept a variable write from**, which
is a question about Setup/Custom Mode — not about `db`.

| Enrolling via | Variables you supply | Why |
| --- | --- | --- |
| The firmware's own tool, or a hypervisor setting, with the platform in Setup/Custom Mode | **`db` alone** | The write is unauthenticated, so nothing has to vouch for it |
| A running OS — FOG's enrolment task, a Linux tool, PowerShell's Secure Boot cmdlets | **PK, KEK and `db`** | In User Mode a `db` write must be authenticated by a KEK-signed update, and the machine only trusts FOG's KEK if FOG's PK is enrolled too |

Confirmed on the first row: `MOK.der` added to `db` by itself, no PK and no KEK,
then a FOG-signed binary booted directly with no shim. That is why an existing
machine's firmware UI asking for all three is not evidence that `db` depends on
them — it is offering the only write it can authenticate from a stranger, which is
replacing the whole chain. You do not have to accept that offer if you can write
`db` directly.

The second row is what FOG's own task does -- see
[[secure-boot-setup-mode-enrollment|Setup Mode enrollment]] -- and why the
| The firmware's own tool, or a hypervisor setting, with the platform in Setup/Custom Mode | **`db` alone** | In Setup Mode the firmware does not check *who signed* the update, so nothing has to vouch for `db`. The platform still has its own PK, and that is what keeps Secure Boot on |
| A running OS, platform in Setup/Custom Mode — FOG's enrolment task | **`db`, KEK and PK** | The same unchecked write, but nothing else is going to supply a PK. Without one the machine stays in Setup Mode with Secure Boot **off**; PK and KEK are also what let FOG update `db` again later |
| A running OS, platform in User Mode holding a PK you do not control | **none — the route is closed** | Every update to `db`, KEK and PK must be signed by a key already in KEK or PK. On a machine carrying a vendor PK you cannot write any of the three, and supplying all three is not a workaround |

The first row is confirmed twice: `MOK.der` added to `db` by itself on VMware,
then a FOG-signed binary booted with no shim; and FOG's own `db.auth` written
alone on EDK2/OVMF, which lands and survives a reboot. So an existing machine's
firmware UI asking for all three is not evidence that `db` depends on them — it is
offering the only write it can authenticate from a stranger, which is replacing
the whole chain. You do not have to accept that offer if you can write `db`
directly.

The second row is what FOG's own task does — see
[[secure-boot-setup-mode-enrollment|Setup Mode enrollment]] — and why the
`.auth` files exist.

>[!note] Not every firmware has been tested either way
>The routes above are confirmed on the hardware and hypervisors used during this
>work, not exhaustively. If yours behaves differently — `db` alone rejected at a
>firmware menu, or accepted from an OS tool — please report it, on the
>[FOG forums](https://forums.fogproject.org/) or on
>[issue 1267](https://github.com/FOGProject/fogproject/issues/1267), which is
>collecting exactly this. The table should be corrected, not trusted.
>[!warning] "Unauthenticated" means unverified, not unsigned
>Setup Mode skips the *signature check*. It does not accept a bare certificate:
>every write to `db`, KEK or PK must still be a properly formed authenticated
>variable update, and handing the raw `.esl`/`.der` bytes to `efivarfs` fails with
>`EINVAL` even in Setup Mode. A firmware file picker builds that wrapper for you,
>which is why it takes `MOK.der`; FOG's task cannot, which is why FOG ships
>`.auth` files.

>[!note] Measured on EDK2/OVMF, not on every firmware
>The table was re-measured in
>[issue 1267](https://github.com/FOGProject/fogproject/issues/1267) against
>edk2-ovmf under QEMU with SMM, in both Setup and User Mode, including a User Mode
>platform carrying Microsoft's PK. Physical firmware menus, PowerShell's
>`Set-SecureBootUEFI` and BitLocker/PCR 7 behaviour are still untested. If yours
>behaves differently — `db` alone rejected at a firmware menu, or a `db` write
>accepted from an OS tool on a machine whose PK you do not hold — please report it
>on the [FOG forums](https://forums.fogproject.org/) or on that issue.

`MOK.der` is the intermediate, and FOG's signatures carry it inside them, so this
one certificate covers every binary in the archive and the signing leaf can be
Expand Down
46 changes: 33 additions & 13 deletions docs/kb/how-tos/secure-boot-setup-mode-enrollment.md
Original file line number Diff line number Diff line change
Expand Up @@ -175,26 +175,46 @@ They are what FOS writes. A firmware file picker cannot read one. Hand it

**And at a firmware menu you only need `db`** — not PK, not KEK. `db` is what
firmware checks to verify a boot image; PK and KEK only control who may *change*
`db`. With the platform in Setup/Custom Mode that write is unauthenticated, so
nothing has to vouch for it. Confirmed: `MOK.der` added to `db` by itself, then a
FOG-signed binary booted directly with no shim.
`db`. With the platform in Setup/Custom Mode the firmware does not check who
signed the update, so nothing has to vouch for `db`. Confirmed: `MOK.der` added to
`db` by itself, then a FOG-signed binary booted directly with no shim.

An existing machine's UI often asks for all three anyway, because in User Mode a
`db` write must be authenticated by a KEK-signed update — so it offers the only
write it can authenticate from a stranger, which is replacing the whole chain. You
do not have to accept that if you can write `db` directly.

>[!warning] This does not generalise to OS-side enrolment
>The `db`-alone shortcut applies to the **firmware's own tool** and to hypervisor
>settings. Writing Secure Boot variables from a running OS — the task this page
>describes, a Linux tool, or PowerShell's Secure Boot cmdlets — is a User Mode
>write and must be authenticated, so **expect to need PK, KEK and `db` together**.
>That is precisely why the `.auth` files exist and why this page's task writes all
>three.
>[!warning] Why this page's task still writes all three
>The `db`-alone shortcut works because *someone else* — the firmware, or the
>hypervisor — is supplying the PK. This page's task is not in that position, and
>the reason is not that an OS-side write "needs three variables":
>
>Neither route has been tested exhaustively across firmwares. If yours behaves
>differently, please report it on the [FOG forums](https://forums.fogproject.org/)
>or the issue tracker.
>- **`db` alone, with no PK anywhere, leaves Secure Boot off.** Measured on
> EDK2/OVMF: FOG's `db.auth` written by itself lands and survives a reboot, and
> the platform stays in Setup Mode with `SecureBoot=0`. Writing PK is what turns
> Secure Boot on, and KEK is what lets FOG update `db` again later.
>- **In User Mode on a machine whose PK you do not hold, the route is closed
> entirely.** Every update to `db`, KEK and PK must be signed by a key already in
> KEK or PK. Against a platform carrying Microsoft's PK, all three writes were
> refused (`EACCES`); supplying all three is not a workaround. So this task needs
> the platform in Setup/Custom Mode — the same precondition as the firmware-menu
> route above.
>- **Once FOG's own PK and KEK are enrolled**, a later `db` update from the OS is
> accepted on a KEK-signed update alone. That is the case the `.auth` files buy
> you.

>[!warning] "Unauthenticated" means unverified, not unsigned
>Setup Mode skips the signature *check*; it does not accept a bare certificate.
>Writing the raw `.esl`/`.der` bytes to `efivarfs` fails with `EINVAL` even in
>Setup Mode — the update must still carry the authenticated-variable wrapper. A
>firmware file picker builds that for you, which is why it takes `MOK.der`, and
>FOG's task cannot, which is why FOG ships `.auth` files.

>[!note] Measured on EDK2/OVMF, not on every firmware
>See [issue 1267](https://github.com/FOGProject/fogproject/issues/1267) for the
>measurements and the rig. Physical firmware menus, PowerShell's
>`Set-SecureBootUEFI` and BitLocker/PCR 7 behaviour are still untested — reports
>welcome on the [FOG forums](https://forums.fogproject.org/) or that issue.

On VMware, put `MOK.der` in the VM's directory and add to the `.vmx`:

Expand Down