On 12/02/2026 21.43, Zhuoying Cai wrote:
> Add documentation for secure IPL
>
> Signed-off-by: Collin Walling <walling@linux.ibm.com>
> Signed-off-by: Zhuoying Cai <zycai@linux.ibm.com>
> ---
> docs/system/s390x/secure-ipl.rst | 96 ++++++++++++++++++++++++++++++++
> 1 file changed, 96 insertions(+)
>
> diff --git a/docs/system/s390x/secure-ipl.rst b/docs/system/s390x/secure-ipl.rst
> index e0af086c38..275aa422c7 100644
> --- a/docs/system/s390x/secure-ipl.rst
> +++ b/docs/system/s390x/secure-ipl.rst
> @@ -1,5 +1,21 @@
> .. SPDX-License-Identifier: GPL-2.0-or-later
>
> +s390 Secure IPL
> +===============
> +
> +Secure IPL, also known as secure boot, enables s390-ccw virtual machines to
> +verify the integrity of guest kernels.
> +
> +For technical details of this feature, see ``docs/specs/s390x-secure-ipl.rst``.
> +
> +This document explains how to use secure IPL with s390x in QEMU. It covers
> +new command line options for providing certificates and enabling secure IPL,
s/new/the/
... the command line options are new right now, but in a couple of months,
this won't be true anymore.
> +the different IPL modes (Normal, Audit, and Secure), and system requirements.
> +
> +A quickstart guide is provided to demonstrate how to generate certificates,
> +sign images, and start a guest in Secure Mode.
> +
> +
> Secure IPL Command Line Options
> ===============================
>
> @@ -78,3 +94,83 @@ Configuration:
> .. code-block:: shell
>
> qemu-system-s390x -machine s390-ccw-virtio,secure-boot=on,boot-certs.0.path=/.../qemu/certs,boot-certs.1.path=/another/path/cert.pem ...
> +
> +
> +Constraints
> +===========
> +
> +The following constraints apply when attempting to secure IPL an s390 guest:
"when attempting to boot an s390x guest in secure mode".
Otherwise it sounds like "to secure" is the verb.
> +- z16 or "qemu" CPU model
> +- certificates must be in X.509 PEM format
> +- only support for SCSI scheme of virtio-blk/virtio-scsi devices
> +- a boot device must be specified
> +- any unsupported devices (e.g., ECKD and VFIO) or non-eligible devices (e.g.,
> + network) will cause the entire boot process terminating early with an error
> + logged to the console.
> +
> +
> +Secure IPL Quickstart
> +=====================
> +
> +Build QEMU with gnutls enabled
> +-------------------------------
> +
> +.. code-block:: shell
> +
> + ./configure … --enable-gnutls
> +
> +Generate certificate (e.g. via certtool)
> +----------------------------------------
> +
> +A private key is required before generating a certificate. This key must be kept
> +secure and confidential.
> +
> +Use an RSA private key for signing.
> +
> +.. code-block:: shell
> +
> + certtool --generate-privkey > key.pem
> +
> +A self-signed certificate requires the organization name. Use the ``cert.info``
> +template to pre-fill values and avoid interactive prompts from certtool.
> +
> +.. code-block:: shell
> +
> + cat > cert.info <<EOF
> + cn = "My Name"
> + expiration_days = 36500
> + cert_signing_key
> + EOF
> +
> + certtool --generate-self-signed \
> + --load-privkey key.pem \
> + --template cert.info \
> + --hash=SHA256 \
> + --outfile cert.pem
> +
> +Sign Images (e.g. via sign-file)
> +--------------------------------
> +
> +- signing must be performed on a KVM guest filesystem
I'd remove the "KVM" in above sentence. It is also supposed to work with
TCG, isn't it?
Thomas