From: Andrea Bolognani Date: Wed, 22 Jun 2022 10:08:04 +0000 (+0200) Subject: docs: Add kbase page for Secure Boot X-Git-Tag: v8.6.0-rc1~149 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7d285059f497c3f38dc8465555c1eb908ae62e6b;p=thirdparty%2Flibvirt.git docs: Add kbase page for Secure Boot Provide simple recipes for the most common high-level tasks. Signed-off-by: Andrea Bolognani Reviewed-by: Michal Privoznik --- diff --git a/docs/kbase/index.rst b/docs/kbase/index.rst index 8b710db85a..896ececdf2 100644 --- a/docs/kbase/index.rst +++ b/docs/kbase/index.rst @@ -61,6 +61,9 @@ Usage `Snapshots `__ Details about snapshotting a VM +`Secure Boot `__ + Enable and disable the Secure Boot feature + Debugging --------- diff --git a/docs/kbase/meson.build b/docs/kbase/meson.build index eb9c9544d6..c7eae3738f 100644 --- a/docs/kbase/meson.build +++ b/docs/kbase/meson.build @@ -15,6 +15,7 @@ docs_kbase_files = [ 'qemu-passthrough-security', 'rpm-deployment', 's390_protected_virt', + 'secureboot', 'secureusage', 'snapshots', 'systemtap', diff --git a/docs/kbase/secureboot.rst b/docs/kbase/secureboot.rst new file mode 100644 index 0000000000..ebd9d56da8 --- /dev/null +++ b/docs/kbase/secureboot.rst @@ -0,0 +1,102 @@ +=========== +Secure Boot +=========== + +.. contents:: + +Quick configuration +=================== + +If you have libvirt 8.6.0 or newer, when creating a new VM you can +ask for Secure Boot to be enabled with + +:: + + + + + + + +and for it to be disabled with + +:: + + + + + + + +These configuration will cause unsigned guest operating systems to +be rejected and allowed respectively. + + +Older libvirt versions +====================== + +If your libvirt version is older than 8.6.0 but newer than 7.2.0, +then enabling Secure Boot requires a slightly more verbose XML +snippet: + +:: + + + + + + + + +Versions older than 7.2.0 require manually providing all information +about the firmware and are not covered here. Plese refer to `the +relevant documentation +<../formatdomain.html#operating-system-booting>`__ for details. + + +Changing an existing VM +======================= + +Once the VM has been created, updating the XML configuration as +described above is **not** enough to change the Secure Boot status: +the NVRAM file associated with the VM has to be regenerated from its +template as well. + +In order to do that, update the XML and then start the VM with + +:: + + $ virsh start $vm --reset-nvram + +This option is only available starting with libvirt 8.1.0, so if your +version of libvirt is older than that you will have to delete the +NVRAM file manually before starting the VM. + +Most guest operating systems will be able to cope with the NVRAM file +being reinitialized, but in some cases the VM will be unable to boot +after the change. + + +Additional information +====================== + +There are two parts to enabling Secure Boot: the firmware supporting +the feature, and it being active. + +Most host operating systems ship a build of EDKII (the open source +EFI implementation used for QEMU VMs) that supports the Secure Boot +feature, but simply using such a build will not result in unsigned +guest operating systems being rejected: for that to happen, keys that +can be used to validate the operating system signature need to be +provided as well. + +Asking for the ``enrolled-keys`` firmware feature to be enabled will +cause libvirt to initialize the NVRAM file associated with the VM +from a template that contains a suitable set of keys. These keys +being present will cause the firmware to enforce the Secure Boot +signing requirements. + +The opposite configuration, where the feature is explicitly disabled, +will result in no keys being present in the NVRAM file. Unable to +verify signatures, the firmware will allow even unsigned operating +systems to run.