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

Announce Secure Boot changes #328

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Announce Secure Boot changes #328

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
61 changes: 56 additions & 5 deletions docs/guides/guest-UEFI-Secure-Boot.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,49 @@ How to configure UEFI Secure boot?

Enabling UEFI Secure Boot for guests ensures that XCP-ng VMs will only execute trusted binaries at boot. In practice, these are the binaries released by the operating system (OS) vendor for the OS running in the VM (Microsoft Windows, Debian, RHEL, Alpine, etc.).

## Upcoming changes in Secure Boot

The default Secure Boot keys in XCP-ng are changing.

Previously, XCP-ng only shipped with the PK included by default; Secure Boot variables had to be installed using `secureboot-certs`.
New versions of XCP-ng `varstored` (from version 1.2.0-2.4 and newer) now comes with a complete set of Secure Boot variables (PK/KEK/db/dbx) by default, meaning that guest Secure Boot will now work without needing further pool configuration.

Our defaults now include the 2023 Microsoft `KEK` and `db` certificates, ensuring Windows compatibility beyond 2026 (which is when the previous 2011 certificates expire).

### What this change means for you

You will not be affected in most cases.

* Existing VMs will not be affected unless you use the ["Propagate certificates"](#propagate-pool-certificates-to-a-vm) feature in Xen Orchestra (which has always had the effect of resetting VM Secure Boot variables to that of the pool).
* If you followed our previous guides and used `secureboot-certs install` to install the default Secure Boot variables into your pool, these variables will not be changed.

The only VMs affected by these changes are **newly created VMs** with Secure Boot enabled, running on pools where `secureboot-certs install` have not been executed.
Previously, these VMs will execute all UEFI binaries even with Secure Boot enabled (due to an empty dbx variable); however, going forward, revoked UEFI binaries (e.g. from an outdated media) will no longer boot on such VMs with Secure Boot enabled.

To continue booting outdated media on these VMs, you can either:

- Disable Secure Boot;
- Or erase the VM's dbx variable with the command `varstore-rm <vm uuid> d719b2cb-3d3a-4596-a3bc-dad00e67656f dbx`

Once your VM has completed installing, it should be able to manage its own Secure Boot variables (db/dbx) via its update mechanism.

## Requirements

* XCP-ng >= 8.2.1.
* UEFI Secure Boot Certificates installed on the pool (this is detailed below).
* A UEFI guest VM.
* For Windows, ensure the VM has at least 2 vCPUs.

:::warning
Until we can re-sign XCP-ng's PV drivers for Windows, you will need the PV drivers from XenServer before enabling Secure Boot for a Windows VM. See [Setup Secure Boot for Windows VMs](#setup-secure-boot-for-windows-vms).
:::

Note: it's not necessary that the XCP-ng host boots in UEFI mode for Secure Boot to be enabled on VMs.

## Quick Start
## 8.3 with varstored >= 1.2.0-2.4

Secure Boot is ready to use without extra configuration. Simply activate Secure Boot on your VMs, and they will be provided with an appropriate set of default Secure Boot variables.

## Quick Start (8.2.1 and 8.3 with varstored < 1.2.0-2.4)

We believe that reading this guide will provide you with useful knowledge about the way Guest Secure Boot is handled in XCP-ng, and let you avoid mistakes.

Expand Down Expand Up @@ -91,24 +120,46 @@ For custom certificates (advanced use), see [Install Custom UEFI Certificates](#

### Install the Default UEFI Certificates

:::info
This procedure is not necessary if you're using varstored 1.2.0-2.4 and newer. However, the
:::

`secureboot-certs` supports installing a default set of certificates across the pool.

Except the `PK` key which is already provided by XCP-ng, all certificates are downloaded from official sources (`microsoft.com` and `uefi.org`).

The default certificates are sourced as follows:

**With varstored < 1.2.0-2.4:**

| Certificate | Source | CLI Arg |
|-------------|-------------------------------------------------------------------------------------------------------------------|-----------|
| PK | Provided by XCP-ng, already present on disk. | `default` |
| KEK | [Microsoft Corporation UEFI KEK CA 2011](https://www.microsoft.com/pkiops/certs/MicCorKEKCA2011_2011-06-24.crt) | `default` |
| KEK | [Microsoft Corporation KEK CA 2011](https://www.microsoft.com/pkiops/certs/MicCorKEKCA2011_2011-06-24.crt) | `default` |
| db | [Microsoft Corporation UEFI CA 2011](https://www.microsoft.com/pkiops/certs/MicCorUEFCA2011_2011-06-27.crt) and [Microsoft Windows Production PCA 2011](https://www.microsoft.com/pkiops/certs/MicWinProPCA2011_2011-10-19.crt) | `default` |
| dbx | [UEFI Revocation List](https://uefi.org/sites/default/files/resources/dbxupdate_x64.bin) | `latest` |

To install these certificates from the command line interface:
**With varstored >= 1.2.0-2.4:**

All keys are built into varstored-tools and present on disk. There's no need to configure them except for custom Secure Boot scenarios.

Certificate and revocation lists provided by [microsoft/secureboot_objects](https://github.com/microsoft/secureboot_objects).

| Certificate | Source | CLI Arg |
|-------------|-------------------------------------------------------------------------------------------------------------------|-----------|
| PK | Provided by XCP-ng. | `default` |
| KEK | Microsoft Corporation KEK CA 2011 and Microsoft Corporation KEK 2K CA 2023 | `default` |
| db | Microsoft Windows Production PCA 2011, Windows UEFI CA 2023, Microsoft Corporation UEFI CA 2011, Microsoft UEFI CA 2023 and Microsoft Option ROM UEFI CA 2023 | `default` |
| dbx | Image hashes provided by microsoft/secureboot_objects (can specify `latest` to download latest dbx instead) | `default` |

To install these variables from the command line interface:

```
# Download and install PK/KEK/db/dbx certificates
# Download and install PK/KEK/db/dbx certificates (varstored < 1.2.0-2.4)
secureboot-certs install default default default latest

# Reinstall built-in PK/KEK/db/dbx variables (varstored >= 1.2.0-2.4)
secureboot-certs install default default default default
```

This can be shortened to:
Expand Down