Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

rm: security: add UEFI PXE provisioning clarification #751

Merged
merged 1 commit into from
Sep 18, 2024
Merged

rm: security: add UEFI PXE provisioning clarification #751

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
32 changes: 26 additions & 6 deletions source/reference-manual/security/secure-boot-uefi.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,9 +137,14 @@
UEFI Secure Boot Provisioning
-----------------------------

LmP includes and distributes ``LockDown.efi``, a UEFI application from the ``efitools`` suite. This application contains the necessary certificates to configure and activate Secure Boot. When executed, it validates and installs the certificates into non-volatile memory, enables Secure Boot, and restarts the system.
LmP includes and distributes ``LockDown.efi``, a UEFI application from the ``efitools`` suite. This application contains the necessary certificates to configure and activate Secure Boot. When executed, it validates and installs the certificates into non-volatile memory, attempts to enable Secure Boot, and restarts the system.

LmP provides access to the application through a systemd-boot menu. Simply selecting it during boot initiates the provisioning process. After the reboot, the system will verify image signatures, and booting will be blocked if the signature verification fails.
Be aware that some OEMs (Original Equipment Manufacturers) may require users to access the **Setup utility** to enable **Secure Boot** after programming the certificates.

.. note::
LockDown.efi requires that the platform be booted in Setup Mode. The method for entering this mode depends on the OEM.

Check warning on line 145 in source/reference-manual/security/secure-boot-uefi.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'OEM' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.

Raw Output:
{"message": "[Fio-docs.expand-acronyms] 'OEM' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/reference-manual/security/secure-boot-uefi.rst", "range": {"start": {"line": 145, "column": 119}}}, "severity": "WARNING"}

LmP provides access to the application through a systemd-boot menu. Simply selecting it during boot initiates the provisioning process. After the reboot, the system will verify image signatures, and booting will be blocked if the signature verification fails.

.. figure:: secure-boot-uefi/uefi-lockdown-provisioning.png
:alt: UEFI Secure Boot Provisioning
Expand All @@ -152,28 +157,40 @@

An easy way to do this, as QEMU includes PXE support, is to run the application standalone in the UEFI environment.

In the snippet below, QEMU fetches `LockDown.efi` from the `/tmp` directory using its PXE capabilities.
In the snippet below, QEMU fetches `LockDown.efi` from the `/tmp` directory using its PXE capabilities. Note that **OVMF** boots directly in **Setup Mode**, so it does not require initialization for this mode. This is in accordance with what is described in section 32.3, `Creating Trust Relationships`_, of the UEFI specification.

Check warning on line 160 in source/reference-manual/security/secure-boot-uefi.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'PXE' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.

Raw Output:
{"message": "[Fio-docs.expand-acronyms] 'PXE' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/reference-manual/security/secure-boot-uefi.rst", "range": {"start": {"line": 160, "column": 87}}}, "severity": "WARNING"}

Check warning on line 160 in source/reference-manual/security/secure-boot-uefi.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'OVMF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.

Raw Output:
{"message": "[Fio-docs.expand-acronyms] 'OVMF' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/reference-manual/security/secure-boot-uefi.rst", "range": {"start": {"line": 160, "column": 117}}}, "severity": "WARNING"}

.. prompt::

qemu-system-x86_64 \
-device virtio-net-pci,netdev=net0,mac=52:54:00:12:35:02 \
-netdev user,id=net0,tftp=/tmp/,bootfile=/LockDown.efi \
-object rng-random,filename=/dev/urandom,id=rng0 -device virtio-rng-pci,rng=rng0 \
-drive if=pflash,format=qcow2,file=/tmp/ovmf.secboot.qcow2 --no-reboot\
-drive if=pflash,format=qcow2,file=/tmp/ovmf.secboot.qcow2 --no-reboot \
-drive if=pflash,format=qcow2,file=/tmp/ovmf.vars.qcow2 \
-nographic -m 4096 \
-boot nc

After provisioning the system using PXE boot with QEMU, you can boot the secure image. Ensure that you set ``bootindex=0`` on the device from which you want to boot.

Check warning on line 173 in source/reference-manual/security/secure-boot-uefi.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'PXE' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.

Raw Output:
{"message": "[Fio-docs.expand-acronyms] 'PXE' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/reference-manual/security/secure-boot-uefi.rst", "range": {"start": {"line": 173, "column": 37}}}, "severity": "WARNING"}

Check warning on line 173 in source/reference-manual/security/secure-boot-uefi.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.help-not-ensure] Consider 'help' instead of 'Ensure'

Raw Output:
{"message": "[Fio-docs.help-not-ensure] Consider 'help' instead of 'Ensure'", "location": {"path": "source/reference-manual/security/secure-boot-uefi.rst", "range": {"start": {"line": 173, "column": 88}}}, "severity": "INFO"}

.. prompt::

-drive if=none,id=hd,file=/tmp/lmp-mini-image-intel-corei7-64.wic,format=raw \
-device virtio-scsi-pci,id=scsi -device scsi-hd,drive=hd,bootindex=0 \

You can also boot a wic image in QEMU and select the Secure Boot Provisioning menu using the following command:

.. prompt::

qemu-system-x86_64 -device virtio-net-pci,netdev=net0,mac=52:54:00:12:35:02 \
qemu-system-x86_64 \
-device virtio-net-pci,netdev=net0,mac=52:54:00:12:35:02 \
-netdev user,id=net0,hostfwd=tcp::5522-:22 \
-object rng-random,filename=/dev/urandom,id=rng0 -device virtio-rng-pci,rng=rng0 \
-drive if=none,id=hd,file=/tmp/lmp-mini-image-intel-corei7-64.wic,format=raw \
-device virtio-scsi-pci,id=scsi -device scsi-hd,drive=hd \
-drive if=pflash,format=qcow2,file=/tmp/ovmf.secboot.qcow2 -no-reboot \
-drive if=pflash,format=qcow2,file=/tmp/ovmf.vars.qcow2
-drive if=pflash,format=qcow2,file=/tmp/ovmf.vars.qcow2 \
-nographic -m 4096


After selecting the menu, you can expect the following output, after which the system will reset.

Expand Down Expand Up @@ -317,3 +334,6 @@

.. _systemd-boot:
https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/

.. _Creating Trust Relationships:
https://uefi.org/specs/UEFI/2.10_A/32_Secure_Boot_and_Driver_Signing.html#firmware-os-key-exchange-creating-trust-relationships
Loading