On s390x the secure-boot firmware feature sets the QEMU machine secure-boot property for Secure IPL rather than selecting a firmware build. Update formatdomain.rst accordingly and add a "Secure Boot on s390x" section to kbase/secureboot.rst.
Signed-off-by: Zhuoying Cai <[email protected]> --- docs/formatdomain.rst | 18 +++++++++--- docs/kbase/secureboot.rst | 60 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 74 insertions(+), 4 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 17b8e0431d..856c793917 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -194,10 +194,13 @@ harddisk, cdrom, network) determining where to obtain/find the boot image. </os> ... - <!-- QEMU s390x with boot certificates --> + <!-- QEMU s390x with boot certificates and Secure IPL --> ... <os> <type arch='s390x' machine='s390-ccw-virtio'>hvm</type> + <firmware> + <feature name='secure-boot' enabled='yes'/> + </firmware> <boot-certs> <path>/path/to/cert1.pem</path> <path>/path/to/cert2.pem</path> @@ -258,9 +261,16 @@ harddisk, cdrom, network) determining where to obtain/find the boot image. - ``enrolled-keys`` whether the selected nvram template has default certificate enrolled. Firmware with Secure Boot feature but without enrolled keys will successfully boot non-signed binaries as well. - Valid only for firmwares with Secure Boot feature. - - - ``secure-boot`` whether the firmware implements UEFI Secure boot feature. + Valid only for firmwares with Secure Boot feature. Not supported on + ``s390x``. + + - ``secure-boot`` whether the firmware implements Secure Boot. For + UEFI firmware architectures, this selects a firmware build with UEFI + Secure Boot support. For ``s390x``, this enables or disables the + QEMU machine ``secure-boot`` property for Secure IPL. When enabled, + boot certificates must be configured via ``<boot-certs>`` and the + s390x CCW firmware operates in secure mode, where verification errors + are reported and causes the boot process to abort. ``loader`` The optional ``loader`` tag refers to a firmware blob, which is specified by absolute path, used to assist the domain creation process. It is used by Xen diff --git a/docs/kbase/secureboot.rst b/docs/kbase/secureboot.rst index b411b65f00..133192dc4d 100644 --- a/docs/kbase/secureboot.rst +++ b/docs/kbase/secureboot.rst @@ -1,3 +1,5 @@ +.. role:: since + =========== Secure Boot =========== @@ -162,3 +164,61 @@ your own keys and securely run an operating system that you've built and signed yourself. If you are only planning to run existing, off-the-shelf operating system images, then the two configurations are functionally equivalent. + + +Secure Boot on s390x +==================== + +On s390x, the ``secure-boot`` firmware feature sets the QEMU machine +``secure-boot`` property to enable **Secure IPL** (Initial Program Load) +signature verification in the s390x CCW firmware. This differs from UEFI +architectures where it selects a firmware build: + +- No firmware binary selection, NVRAM, or varstore is involved. +- X.509 PEM certificates are supplied via ``<boot-certs>``. +- The ``enrolled-keys`` feature is not supported on s390x. + +:since:`Since 12.9.0 (QEMU and s390x only)` + +For more background on the QEMU-level mechanism, refer to the +`QEMU Secure IPL documentation +<https://www.qemu.org/docs/master/system/s390x/secure-ipl.html>`__. + + +Using Secure Boot on s390x +-------------------------- + +Set ``secure-boot`` to ``yes`` and provide signing certificates. The +``<boot-certs>`` element is required when ``secure-boot`` is enabled: + +:: + + <os> + <type arch='s390x' machine='s390-ccw-virtio'>hvm</type> + <firmware> + <feature name='secure-boot' enabled='yes'/> + </firmware> + <boot-certs> + <path>/path/to/cert1.pem</path> + <path>/path/to/cert2.pem</path> + </boot-certs> + <boot dev='hd'/> + </os> + +Providing ``<boot-certs>`` without specifying ``secure-boot``, or with +``secure-boot`` set to ``no``, enables **audit mode**, where all verifications +are performed and any failures are reported as warnings, but the boot process +continues. Setting ``secure-boot`` to ``yes`` enables **secure mode**, where any +verification failures are reported and cause the boot process to abort. + +You can verify QEMU support beforehand (see `Guest firmware +<../formatdomaincaps.html#guest-firmware>`__ for details on interpreting +the output): + +:: + + $ virsh domcapabilities --arch s390x --machine s390-ccw-virtio --virttype kvm + +The output should show ``<firmwareFeatures supported='yes'>`` with +``secureBoot`` listing ``yes`` and ``no`` as valid values, +and ``<bootCerts supported='yes'/>``. -- 2.56.0
