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

rm: security: add UEFI provisioning #748

Merged
merged 1 commit into from
Sep 6, 2024
Merged

rm: security: add UEFI provisioning #748

Show file tree
Hide file tree
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
8 changes: 7 additions & 1 deletion source/glossary/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -162,7 +162,13 @@ Glossary
* :ref:`EdgeLock™ SE05x Reference Manual, Importing Secure Objects into PKCS #11 Tokens <ref-secure-element>`
* :ref:`Linux Disk Encryption Reference Manual, PKCS #11 Tokens <howto-linux-disk-encryption>`
* `TEE PKCS #11 Implementation (external) <https://github.com/OP-TEE/optee_os/tree/master/ta/pkcs11>`_


PXE
Preboot eXecution Environment,
Specification that describes a standardized client–server environment that boots a software assembly, retrieved from a network, on PXE-enabled clients.

* :ref:`Security, UEFI Secure Boot <ref-secure-boot-uefi>`

PKI
Public Key Infrastructure
How digital certificates and keys relate to their owners and can be trusted.
Expand Down
11 changes: 6 additions & 5 deletions source/reference-manual/linux/linux-disk-encryption.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,10 +140,6 @@
$ cat meta-subscriber-overrides/conf/machine/include/lmp-factory-custom.inc
DISTRO_FEATURES:append:intel-corei7-64 = " luks"

Then make sure to enroll the :ref:`UEFI Secure Boot Certificates <ref-secure-boot-uefi>`
to enable secure boot support. This is required as the LUKS2 TPM 2.0 token
leverages **PCR 7**, which tracks the secure boot state.

Now install ``swtpm`` on the host machine, and start the ``swtpm`` daemon.
This will be consumed by QEMU and act as the hardware TPM.

Expand All @@ -166,7 +162,12 @@
-chardev socket,id=chrtpm,path=/tmp/mytpm/swtpm-sock \
-tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-tis,tpmdev=tpm0

You should see the following during the first boot:

On the first boot, enroll the :ref:`UEFI Secure Boot Certificates <ref-secure-boot-uefi>` to enable secure boot support. This is required as the LUKS2 TPM 2.0 token leverages **PCR 7**, which tracks the secure boot state.

Check warning on line 166 in source/reference-manual/linux/linux-disk-encryption.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'UEFI' 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] 'UEFI' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/reference-manual/linux/linux-disk-encryption.rst", "range": {"start": {"line": 166, "column": 37}}}, "severity": "WARNING"}

Check warning on line 166 in source/reference-manual/linux/linux-disk-encryption.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'TPM' 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] 'TPM' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/reference-manual/linux/linux-disk-encryption.rst", "range": {"start": {"line": 166, "column": 152}}}, "severity": "WARNING"}

Check warning on line 166 in source/reference-manual/linux/linux-disk-encryption.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'PCR' 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] 'PCR' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/reference-manual/linux/linux-disk-encryption.rst", "range": {"start": {"line": 166, "column": 178}}}, "severity": "WARNING"}

To do this, select the UEFI Secure Boot systemd-boot menu as described in :ref:`UEFI Secure Boot Provisioning <ref-secure-boot-uefi-provisioning>`. The system will reset. Then run **the same command** again.

Check warning on line 168 in source/reference-manual/linux/linux-disk-encryption.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'UEFI' 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] 'UEFI' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/reference-manual/linux/linux-disk-encryption.rst", "range": {"start": {"line": 168, "column": 24}}}, "severity": "WARNING"}

Check warning on line 168 in source/reference-manual/linux/linux-disk-encryption.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.expand-acronyms] 'UEFI' 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] 'UEFI' has no definition, definition is missing capitalization, or is a variable name and should be written as a literal.", "location": {"path": "source/reference-manual/linux/linux-disk-encryption.rst", "range": {"start": {"line": 168, "column": 81}}}, "severity": "WARNING"}

You should see the following during this second boot:

.. code-block:: none

Expand Down
52 changes: 51 additions & 1 deletion 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 @@ -132,6 +132,57 @@
* ``UEFI_SIGN_ENABLE``
* If set to ``1`` the systemd-boot bootloader and Linux kernel binaries will be signed by with the DB key (``DB.key`` at ``UEFI_SIGN_KEYDIR``)

.. _ref-secure-boot-uefi-provisioning:

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 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


Testing UEFI Secure Boot Provisioning With QEMU
-----------------------------------------------

The ``LockDown.efi`` application can be tested in a virtual environment using QEMU.

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

Check warning on line 153 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": 153, "column": 42}}}, "severity": "WARNING"}

In the snippet below, QEMU fetches `LockDown.efi` from the `/tmp` directory using its PXE capabilities.

Check warning on line 155 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": 155, "column": 87}}}, "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\
-nographic -m 4096 \
-boot nc

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 \
-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 \
-drive if=pflash,format=qcow2,file=/tmp/ovmf.secboot.qcow2 -no-reboot \
-drive if=pflash,format=qcow2,file=/tmp/ovmf.vars.qcow2

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

.. figure:: secure-boot-uefi/uefi-lockdown-wic-qemu-trace.png
:alt: UEFI Secure Boot Provisioning Image QEMU trace.

Running the command again will boot the system with Secure Boot enabled, just as it would do on real hardware.


Backup Current UEFI Secure Boot Certificates
--------------------------------------------

Expand Down Expand Up @@ -159,7 +210,6 @@
----------------------------------------------

It is possible to enroll custom UEFI Secure Boot Certificates using your firmware's built-in setup utility, ``KeyTool`` (from ``efitools``).
You could also create a custom ``LockDown`` efi program with the certificates embedded into it.

By default, LmP installs the required certificates (via ``UEFI_SIGN_KEYDIR``) into the ESP image partition (under ``ESP/uefi_certs``).
This can be used when enrolling via the firmware's built-in setup utility.
Expand Down
Binary file added source/reference-manual/security/secure-boot-uefi/uefi-lockdown-provisioning.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added source/reference-manual/security/secure-boot-uefi/uefi-lockdown-wic-qemu-trace.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading