On 08/12/2025 22.32, Zhuoying Cai wrote:
Add documentation for secure IPL
Signed-off-by: Collin Walling <[email protected]>
Signed-off-by: Zhuoying Cai <[email protected]>
---
...
@@ -77,3 +93,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:
+
+- z16 CPU model
Should this mention the "qemu" CPU model, too?
+- 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.,
+ Net) will cause the entire boot process terminating early with an error
s/(e.g., Net)/(e.g. network)/
+ 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
+- sign-file script used in the example below is located within the kernel
source
+ repo
+
+.. code-block:: shell
+
+ ./sign-file sha256 key.pem cert.pem /boot/vmlinuz-…
+ ./sign-file sha256 key.pem cert.pem /usr/lib/s390-tools/stage3.bin
+
+Run zipl with secure boot enabled
+---------------------------------
+
+.. code-block:: shell
+
+ zipl --secure 1 -V
+
+Start Guest with Cmd Options
"Command line options for starting the guest" ?
+----------------------------
+
+.. code-block:: shell
+
+ qemu-system-s390x -machine
s390-ccw-virtio,secure-boot=on,boot-certs.0.path=cert.pem ...
Thomas
