Skip to content

Fix Route B's enrolment mechanism; add internal-CA and HTTPS follow-ups - #87

Merged
mastacontrola merged 2 commits into
masterfrom
docs-secure-boot-followups
Aug 3, 2026
Merged

Fix Route B's enrolment mechanism; add internal-CA and HTTPS follow-ups#87
mastacontrola merged 2 commits into
masterfrom
docs-secure-boot-followups

Conversation

@darksidemilk

Copy link
Copy Markdown
Member

Summary

Follow-up to the Secure Boot signing guide merged in #84. One real bug fix
and two additions surfaced during review, none of which made it into that
PR.

Route B was wrong, not just imprecise

The guide said to "PXE-boot the shim, and use Enroll key from disk from
the MokManager menu." That doesn't work: shim only hands control to
MokManager when a pending MOK enrolment request already exists (normally
staged by mokutil --import, which is what Route A does). A plain PXE
boot through the shim boots straight through to snponly.efi — MokManager
never appears, however long you wait. Verified against shim's own source
(mok.c's check_mok_request(), MokManager.c's unconditional menu).

Corrected to point at secureboot/mmx64.efi directly — either via the new
"Enroll Secure Boot Key" PXE menu item
(fogproject#976), or
for FOG versions that predate it, by temporarily repointing DHCP at that
file by hand. The adjacent !!! danger "If MokManager does not appear"
callout was telling readers to check they were going through a shim,
which is backwards for this route — fixed to match.

Two additions from review

  • Using an internal CA instead of a fresh self-signed key. shim
    validates the enrolled certificate's chain, not an exact match, so
    enrolling a CA once and signing with any leaf under it means a leaf can
    be reissued or rotated without another physical visit. FOG's automation
    doesn't do this directly today (_resignKernels/build.sh --sign-cert
    assume the signing cert is also the one to publish for enrolment), so
    it's documented as a manual --addcert variant of Step 3b.
  • HTTPS isn't simply "not supported." The signed snponly.efi ships
    with a pinned iPXE root CA that cross-signs the standard public CA list
    at connect time
    (ipxe/ipxe#606), so a FOG
    server with a genuinely publicly-trusted certificate (not FOG's usual
    self-signed one) might validate over HTTPS with the stock signed binary.
    Documented as an explicitly unverified possibility to test and
    report on
    fogproject#960,
    not a supported configuration — most FOG deployments use a self-signed
    cert on an isolated imaging VLAN, neither of which this helps.

Verified

  • mkdocs build produces the same 8 pre-existing RoamLinksPlugin
    warnings (false positives on bash [[ ]] syntax elsewhere in the docs,
    unrelated to this page) before and after this change — no new warnings,
    no broken anchors.
  • Obsidian callout syntax (>[!tip], >[!danger]) matches the existing
    callouts on this page.

Refs #84, fogproject#960, fogproject#976


Generated by Claude Code

claude and others added 2 commits August 2, 2026 18:50
Route B, as written, doesn't work: shim only hands control to MokManager
when a pending MOK request already exists (staged by mokutil --import,
which is what Route A does) -- a plain PXE boot through the shim never
shows it, contrary to what this page said. Corrected to point at
secureboot/mmx64.efi directly, either via the new "Enroll Secure Boot
Key" PXE menu item (fogproject#976) or, for older FOG versions, by
temporarily repointing DHCP at it by hand. Fixed the adjacent "If
MokManager does not appear" callout to match.

Also folds in two pieces of research from review, both already
mentioned in passing but not written down:

  - Using an internal CA instead of a fresh self-signed key -- shim
    validates the enrolled certificate's chain (not an exact match), so
    a CA enrolled once lets leaves be reissued without another visit.
    FOG's automation does not support this directly yet; documented as
    a manual Step 3b variant.
  - HTTPS is not simply unsupported: the signed snponly.efi ships with
    a pinned iPXE root CA used to cross-sign the public CA list at
    connect time (ipxe/ipxe#606), so a publicly-trusted server
    certificate might validate today. Flagged as unverified, not a
    recommendation -- most FOG deployments use a self-signed cert and
    an isolated imaging VLAN, neither of which this helps.

Verified: mkdocs build produces the same 8 pre-existing RoamLinksPlugin
warnings (false positives on bash [[ ]] syntax elsewhere in the docs)
before and after this change -- no new warnings or broken anchors.

Refs #84, fogproject#960, fogproject#976
PR #89 landed first and rewrote Route B around the new Enroll Secure Boot
Key menu item, with verified step-by-step. This branch had rewritten the
same section from the other direction: diagnosing WHY a plain shim boot
never reaches MokManager. Both are right; the conflict was purely that
they occupied the same prose.

Kept #89's structure and steps -- they are the verified ones, run end to
end on a VM with no MOK enrolled -- and folded this branch's diagnosis in
as a callout, since it answers the question #89's steps leave open.

Three corrections made while resolving, all in this branch's text:

1. "secureboot/arm64-efi/mmx64.efi" does not exist and never has. arm64's
   MokManager is mmaa64.efi. This is the exact mistake bootmenu.class.php
   carries a comment about, having broken every arm64 client once already.

2. Dropped the "point DHCP straight at mmx64.efi" fallback entirely. It
   cannot work: mmx64.efi is signed by iPXE, not Microsoft, and the
   firmware checks the FIRST binary against db alone -- which this page
   already says two sections earlier. It boots from the menu only because
   iPXE loads it through shim's verification protocol. Replaced with the
   accurate statement that pre-1.6.0 has no PXE route to MokManager, so
   Route A is the answer there.

3. This branch said Route A first, #89 said Route B first. Kept #89's --
   it is newer, verified, and explicitly accounts for the firmware-hang
   risk that motivated the older advice.

Also retargeted the "If MokManager does not appear" callout, which after
(2) was still offering the impossible boot-file route.

The two additions unique to this branch -- the internal-CA tip and the
iPXE cross-signing note on HTTPS -- did not overlap #89 and carried over
untouched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@mastacontrola

Copy link
Copy Markdown
Member

Reviewed and merged with master (which now carries #89). Route B is the one place the two overlapped, and both were right from different directions — #89 rewrote it around the new Enroll Secure Boot Key menu item with verified steps, this branch diagnosed why a plain shim boot never reaches MokManager. Kept #89's structure and steps (they're the ones run end to end on a VM with no MOK enrolled) and folded the diagnosis in as a callout, since it answers the question those steps otherwise leave open.

Three corrections made to this branch's text while resolving:

1. secureboot/arm64-efi/mmx64.efi doesn't exist. arm64's MokManager is mmaa64.efi. Confirmed against the published v2.0.0-fog.3 asset set (arm64-efi/ contains mmaa64.efi, no mmx64.efi) and against bootmenu.class.php, which carries a comment about this exact mistake having broken every arm64 client once already.

2. Dropped the "point DHCP straight at mmx64.efi" fallback. It can't work. sbverify --list on the staged binary:

subject: /CN=iPXE Secure Boot Code Signing G2A
issuer:  /CN=iPXE Secure Boot Intermediate G1A

Signed by iPXE, not Microsoft — and the firmware checks the first binary against db alone, which this page already states two sections earlier under "The chain you are building". It would fail with a Security Policy Violation. It boots from the menu only because iPXE loads it through shim's verification protocol, which is the mechanism #89 documents. Replaced with the accurate statement that FOG versions predating the menu item have no PXE route to MokManager at all, so Route A is the answer there.

3. Route ordering. This branch said reach for Route A first; #89 says Route B first with A as fallback. Kept #89's — newer, verified, and it explicitly accounts for the Enroll key from disk firmware-hang risk that motivated the older advice.

Also retargeted the "If MokManager does not appear" callout, which after (2) was still offering the impossible boot-file route.

The two additions unique to this branch — the internal-CA tip and the iPXE cross-signing note on HTTPS — didn't overlap #89 and carried over untouched. The HTTPS one is good work; flagging it as explicitly unverified with a pointer to fogproject#960 is the right call rather than presenting it as supported.

@mastacontrola
mastacontrola merged commit 9ee4f98 into master Aug 3, 2026
@mastacontrola
mastacontrola deleted the docs-secure-boot-followups branch August 3, 2026 15:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants