Skip to content

Commit 5f1c2c2

Browse files
authored
docs(secure-boot): fix the key enrolment steps for VMware EFI firmware (#309)
The VM firmware's file browser reads only FAT file systems, so a plain ISO holding the certificate shows "No File System Found". Build a small FAT image holding the certificate and make it the CD's El Torito image, with the install commands for Linux and macOS. The file must keep a lowercase .der name: an upper-case 8.3 SB.DER is refused as an unsupported file type. Use the menu path of the ESXi 8 firmware (Custom Secure Boot Options > DB Options > Enroll DB > Enroll DB Using File), add govc equivalents, and a warning to remove uefi.allowAuthBypass once the certificate is enrolled. Signed-off-by: Bugs5382 <12115015+Bugs5382@users.noreply.github.com> Co-authored-by: Bugs5382 <12115015+Bugs5382@users.noreply.github.com>
1 parent 08b0260 commit 5f1c2c2

1 file changed

Lines changed: 103 additions & 11 deletions

File tree

‎docs/secure-boot.md‎

Lines changed: 103 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -142,20 +142,112 @@ stay.
142142

143143
### VMware vSphere / ESXi
144144

145-
A VM with EFI firmware and Secure Boot enabled starts with the Microsoft
146-
certificates in `db`, which do not cover your image. To add yours:
145+
A VM with EFI firmware and Secure Boot enabled starts with the Microsoft and
146+
VMware certificates in `db`, which do not cover your image. You add yours from
147+
the VM's own firmware setup, reading the certificate from a virtual CD. These
148+
steps were checked on ESXi 8.0.3.
147149

148-
1. Power the VM off. Under **VM Options > Advanced > Configuration
150+
#### Build the certificate CD
151+
152+
The firmware's file browser reads only FAT file systems. On a CD it finds one
153+
only as an El Torito boot image, so you put `sb.der` in a small FAT image and
154+
make that image the CD's El Torito image. No extra virtual disk is needed.
155+
156+
> [!CAUTION]
157+
> A plain ISO 9660 CD holding `sb.der` does not work: the firmware reports
158+
> `No File System Found`. Build the CD as below.
159+
160+
Install the tools:
161+
162+
**Linux (Debian or Ubuntu; on Fedora use `sudo dnf install mtools xorriso`)**
163+
164+
```bash
165+
sudo apt install mtools xorriso
166+
```
167+
168+
**macOS (Homebrew)**
169+
170+
```bash
171+
brew install mtools xorriso
172+
```
173+
174+
Then, in the directory that holds `sb.der`, build `sb-enrol.iso`. The commands
175+
are the same on Linux and macOS:
176+
177+
```bash
178+
mkdir sb-enrol
179+
mformat -i sb-enrol/sb-enrol.img -C -f 1440 -v SBCERT ::
180+
mcopy -i sb-enrol/sb-enrol.img sb.der ::/cryptos-sb.der
181+
xorriso -as mkisofs -o sb-enrol.iso -V SBCERT \
182+
-e sb-enrol.img -no-emul-boot sb-enrol
183+
```
184+
185+
`mformat -C -f 1440` creates a 1.44 MB FAT12 image, `mcopy` puts the
186+
certificate in it, and `xorriso -e ... -no-emul-boot` makes that image the
187+
CD's El Torito boot image.
188+
189+
> [!CAUTION]
190+
> The file on the image must end in a lowercase `.der` (or `.cer`). A name
191+
> stored only as an upper-case 8.3 name, such as `SB.DER`, is refused with
192+
> `Unsupported file type`. A name longer than eight characters, such as
193+
> `cryptos-sb.der`, keeps its lowercase long name on the FAT image.
194+
195+
Check the result before you upload it:
196+
197+
```bash
198+
mdir -i sb-enrol/sb-enrol.img ::/
199+
xorriso -indev sb-enrol.iso -report_el_torito plain
200+
```
201+
202+
> [!TIP]
203+
> `mdir` lists `cryptos-sb.der` in lowercase at the end of its line, and the
204+
> xorriso report has an `El Torito img path` line naming `/sb-enrol.img`.
205+
206+
#### Enroll the certificate
207+
208+
1. Upload `sb-enrol.iso` to a datastore the host can read.
209+
2. Power the VM off. Under **VM Options > Advanced > Configuration
149210
Parameters**, add `uefi.allowAuthBypass` = `TRUE`. This lets the VM's
150211
firmware setup accept a `db` entry that is not signed by a KEK.
151-
2. Put `sb.der` on a volume the firmware can read, for example a small
152-
FAT-formatted virtual disk attached to the VM.
153-
3. Power on into firmware setup (**VM Options > Boot Options > Force EFI setup**
154-
for the next boot), then go to **Secure Boot Configuration > DB Options >
155-
Enroll Signature**, pick `sb.der`, save and exit. Menu names differ slightly
156-
between ESXi releases.
157-
4. Power off, remove `uefi.allowAuthBypass` and the key disk, and confirm
158-
**Secure Boot** is still enabled under **VM Options > Boot Options**.
212+
3. Under **VM Options > Boot Options**, check that the firmware is **EFI** and
213+
turn **Secure Boot** on.
214+
4. Attach `sb-enrol.iso` to the VM's CD/DVD drive with **Connect At Power On**
215+
ticked.
216+
5. Under **VM Options > Boot Options**, tick **Force EFI setup**, then power
217+
the VM on. It stops in the **Boot Manager**.
218+
6. Choose **Enter setup**, then **Secure Boot Configuration > Custom Secure
219+
Boot Options > DB Options > Enroll DB > Enroll DB Using File**.
220+
7. In the **File Explorer**, pick the volume labelled `SBCERT` (its path ends
221+
in `CDROM(...)`), then `cryptos-sb.der`.
222+
8. Choose **Commit Changes and Exit**.
223+
9. To check, open **DB Options > Delete DB**. Your certificate's common name is
224+
listed next to the Microsoft and VMware entries. Leave with **Esc** without
225+
ticking anything, then shut the VM down from the Boot Manager (**Shut down
226+
the system**).
227+
228+
With govc, steps 2 to 5 are:
229+
230+
```bash
231+
govc vm.change -vm cryptos-node -e uefi.allowAuthBypass=TRUE
232+
govc device.boot -vm cryptos-node -firmware efi -secure=true
233+
govc device.cdrom.insert -vm cryptos-node -ds datastore1 ISO/sb-enrol.iso
234+
govc device.boot -vm cryptos-node -setup
235+
govc vm.power -on cryptos-node
236+
```
237+
238+
If the CD/DVD drive is not set to connect at power on, `govc device.ls -vm
239+
cryptos-node` names it (for example `cdrom-3000`), and `govc device.connect -vm
240+
cryptos-node cdrom-3000` connects it.
241+
242+
> [!WARNING]
243+
> Remove `uefi.allowAuthBypass` as soon as the certificate is in `db`. While it
244+
> is set, anyone with access to the VM's console can change `db` from firmware
245+
> setup without a KEK signature.
246+
247+
10. With the VM powered off, remove `uefi.allowAuthBypass` (with govc:
248+
`govc vm.change -vm cryptos-node -e uefi.allowAuthBypass=`), detach
249+
`sb-enrol.iso`, and confirm **Secure Boot** is still on under **VM Options
250+
> Boot Options**.
159251
160252
> [!IMPORTANT]
161253
> Do this before the first boot of the CryptOS installer image, for the reason

0 commit comments

Comments
 (0)