docs/system/s390x: Add secure IPL documentation
Add documentation for secure IPL Signed-off-by: Collin Walling <walling@linux.ibm.com> Signed-off-by: Zhuoying Cai <zycai@linux.ibm.com> Reviewed-by: Joshua Daley <jdaley@linux.ibm.com> Reviewed-by: Matthew Rosato <mjrosato@linux.ibm.com> Link: https://lore.kernel.org/qemu-devel/20260730214624.2328883-34-zycai@linux.ibm.com Signed-off-by: Eric Farman <farman@linux.ibm.com>
Zhuoying Cai committed
Jul 30, 2026 at 17:46 UTC
18916df8b6222341bee60aee7b886c3c6e9c740c
1 file changed
+103
docs/system/s390x/secure-ipl.rst
+103
@@ -1,5 +1,22 @@
1
.. SPDX-License-Identifier: GPL-2.0-or-later
2
3
+s390 Secure IPL
4
+===============
5
+
6
+Secure IPL, also known as secure boot, enables s390-ccw virtual machines to
7
+verify the integrity of guest kernels.
8
+
9
+For technical details of this feature, see the
10
+:doc:`specs document </specs/s390x-secure-ipl>`.
11
+
12
+This document explains how to use secure IPL with s390x in QEMU. It covers
13
+the command line options for providing certificates and enabling secure IPL,
14
+the different IPL modes (Normal, Audit, and Secure), and system requirements.
15
+
16
+A quickstart guide is provided to demonstrate how to generate certificates,
17
+sign images, and start a guest in Secure Mode.
18
+
19
+
20
Secure IPL Command Line Options
21
-------------------------------
22
@@ -79,3 +96,89 @@ Configuration:
96
.. code-block:: shell
97
98
qemu-system-s390x -machine s390-ccw-virtio,secure-boot=on,boot-certs.0.path=/.../qemu/certs,boot-certs.1.path=/another/path/cert.pem ...
99
+
100
+
101
+Constraints
102
+-----------
103
+
104
+The following constraints apply when attempting to boot an s390x guest in secure
105
+mode:
106
+
107
+- z16 or "qemu" CPU model
108
+- certificates must be in X.509 PEM format
109
+- only support for SCSI scheme of virtio-blk/virtio-scsi devices
110
+- a boot device must be specified
111
+- any unsupported devices (e.g., ECKD and VFIO) or non-eligible devices (e.g.,
112
+ network) will cause the entire boot process to terminate early, with an error
113
+ logged to the console.
114
+
115
+
116
+Secure IPL Quickstart
117
+---------------------
118
+
119
+Build QEMU with gnutls enabled
120
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
121
+
122
+.. code-block:: shell
123
+
124
+ ./configure … --enable-gnutls
125
+
126
+Generate certificate (e.g. via certtool)
127
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
128
+
129
+A private key is required before generating a certificate. This key must be kept
130
+secure and confidential.
131
+
132
+Use an RSA private key for signing.
133
+
134
+.. code-block:: shell
135
+
136
+ certtool --generate-privkey > key.pem
137
+
138
+A self-signed certificate requires the organization name. Use the ``cert.info``
139
+template to pre-fill values and avoid interactive prompts from certtool.
140
+
141
+.. code-block:: shell
142
+
143
+ cat > cert.info <<EOF
144
+ cn = "My Name"
145
+ expiration_days = 365
146
+ cert_signing_key
147
+ EOF
148
+
149
+ certtool --generate-self-signed \
150
+ --load-privkey key.pem \
151
+ --template cert.info \
152
+ --hash=SHA256 \
153
+ --outfile cert.pem
154
+
155
+Sign Images (e.g. via sign-file)
156
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
157
+
158
+- signing must be performed on a guest filesystem
159
+- sign-file script used in the example below is located within the kernel source
160
+ repo
161
+
162
+.. code-block:: shell
163
+
164
+ ./sign-file sha256 key.pem cert.pem /boot/vmlinuz-…
165
+ ./sign-file sha256 key.pem cert.pem /usr/lib/s390-tools/stage3.bin
166
+
167
+Note: re-signing a component will not verify correctly; the existing signature
168
+must be stripped before a new one is applied.
169
+
170
+Run zipl with secure boot enabled
171
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
172
+
173
+- zipl must be performed on a guest filesystem
174
+
175
+.. code-block:: shell
176
+
177
+ zipl --secure 1 -V
178
+
179
+Command line options for starting the guest
180
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
181
+
182
+.. code-block:: shell
183
+
184
+ qemu-system-s390x -machine s390-ccw-virtio,secure-boot=on,boot-certs.0.path=cert.pem ...