On 09/05/2025 00.50, Zhuoying Cai wrote:
Add documentation for secure IPL.
Signed-off-by: Collin Walling <wall...@linux.ibm.com>
Signed-off-by: Zhuoying Cai <zy...@linux.ibm.com>
---
docs/system/s390x/secure-ipl.rst | 249 +++++++++++++++++++++++++++++++
1 file changed, 249 insertions(+)
create mode 100644 docs/system/s390x/secure-ipl.rst
diff --git a/docs/system/s390x/secure-ipl.rst b/docs/system/s390x/secure-ipl.rst
new file mode 100644
index 0000000000..4f80d7741e
--- /dev/null
+++ b/docs/system/s390x/secure-ipl.rst
@@ -0,0 +1,249 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+s390 Secure IPL
+===============
+
+Secure IPL, also known as secure boot, enables s390-ccw virtual machines to
+leverage qcrypto libraries and z/Arch implementations to verify the integrity
of
+guest kernels. These operations are rely on userspace invocations and QEMU
+interpretation.
I don't understand the last sentence. Could you please rephrase it?
The user provides one or more certificates via the command line
+options, which populates a certificate store. DIAGNOSE 'X'320' is invoked by
+userspace to query cert store info and retrieve specific certificates from
QEMU.
+DIAGNOSE 'X'508' is used by userspace to leverage qcrypto libraries to perform
+signature-verification in QEMU. Lastly, userspace generates and appends an
+IPL Information Report Block (IIRB) at the end of the IPL Parameter Block.
+
+The steps are as follows:
+
+- Userspace retrieves data payload from disk (e.g. stage3 boot loader, kernel)
+- Userspace checks the validity of the SCLAB
+- Userspace invokes DIAG 508 subcode 1 and provides it the payload
+- QEMU handles DIAG 508 request by reading the payload and retrieving the
+ certificate store
+- QEMU DIAG 508 utilizes qcrypto libraries to perform signature-verification on
+ the payload, attempting with each cert in the store (until success or
+ exhausted)
+- QEMU DIAG 508 returns:
+
+ - success: index of cert used to verify payload
+ - failure: error code
So this doc is rather meant as a specification, not as a documentation for
the end user? In that case it should maybe rather reside in docs/specs/ and
not in docs/system/s390x.
+- Userspace responds to this operation:
+
+ - success: retrieves cert from store via DIAG 320 using returned index
+ - failure: reports with warning (audit mode), aborts with error (secure mode)
+
+- Userspace appends IIRB at the end of the IPLB
+- Userspace kicks off IPL
+
+
+Constraints
+-----------
+
+The following constraints apply when attempting to secure IPL an s390 guest:
+
+- z16 CPU model
+- certificates must be in X.509 DER format
+- only sha256 encryption is supported
+- 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
+ logged to the console.
+
+
+s390 Certificate Store
+======================
+
+Secure boot relies on user certificates for signature-verification. Normally,
+these certificates would be stored somewhere on the LPAR. Instead, for virtual
+guests, a certificate store is implemented within QEMU. This store will read
+any certificates provided by the user via command-line, which are expected to
+be stored somewhere on the host file system. Once these certificates are
+stored, they are ready to be queried/requested by DIAGNOSE 'X'320' or used for
+verification by DIAGNOSE 'X'508'.
+
+The certificate store can be populated by supplying a comma-delimited list of
+certificates on the command-line:
+
+.. code-block:: shell
+
+ qemu-system-s390x -machine s390-ccw-virtio, \
+ boot-certificates=/.../qemu/certs:/another/path/cert.der
+
+
+DIAGNOSE function code 'X'320' - Certificate Store Facility
+-----------------------------------------------------------
+
+DIAGNOSE 'X'320' is used to provide support to query the certificate store.
+
+Subcode 0 - query installed subcodes
+ Returns a 256-bit installed subcodes mask (ISM) stored in the installed
+ subcodes block (ISB). This mask indicates which sucodes are currently
+ installed and available for use.
+
+Subcode 1 - query verification certificate storage information
+ Provides the information required to determine the amount of memory needed
to
+ store one or more verification-certificates (VCs) from the certificate
store (CS).
+
+ Upon successful completion, this subcode returns various storage size
values for
+ verification-certificate blocks (VCBs).
+
+ The output is returned in the verification-certificate-storage-size block
(VCSSB).
+
+Subcode 2 - store verification certificates
+ Provides VCs that are in the certificate store.
+
+ The output is provided in a VCB, which includes a common header followed
by zero
+ or more verification-certificate entries (VCEs).
+
+ The first-VC index and last-VC index fields of VCB specify the range of VCs
+ to be stored by subcode 2. Stored count and remained count fields specify
the
+ number of VCs stored and could not be stored in the VCB due to insufficient
+ storage specified in the VCB input length field.
+
+ VCE contains various information of a VC from the CS.
+
+
+IPL Modes
+=========
+
+Different IPL modes may be toggled with the following command line option:
+
+.. code-block:: shell
+
+ qemu-system-s390x -machine s390-ccw-virtio,secure-boot=on|off
+
+Additionally, the provision of certificates affect the mode.
+
+
+Normal Mode
+-----------
+
+The absence of both certificates and the ``secure-boot`` option will attempt to
+IPL a guest without secure IPL operations. No checks are performed, and no
+warnings/errors are reported. This is the default mode, and can be explicitly
+enabled with ``secure-boot=off``.
+
+
+Audit Mode
+----------
+
+With *only* the presence of certificates in the store, it is assumed that
secure
+boot operations should be performed with errors reported as warnings. As such,
+the secure IPL operations will be performed, and any errors that stem from
these
+operations will report a warning via the SCLP console.
+
+
+Secure Mode
+-----------
+
+With *both* the presence of certificates in the store and the
``secure-boot=on``
+option, it is understood that secure boot should be performed with errors
+reported and boot will abort.
+
+
+Secure IPL Functions
+====================
+
+IPL Information Report Block
+----------------------------
+
+The IPL Parameter Block (IPLPB), utilized for IPL operation, is extended with
an
+IPL Information Report Block (IIRB), which contains the results from secure IPL
+operations such as:
+
+* component data
+* verification results
+* certificate data
+
+
+Secure Code Loading Attributes Facility
+---------------------------------
+
+Secure Code Loading Attributes Facility (SCLAF) provides additional security
during IPL.
+
+When SCLAF is available, its behavior depends on the IPL Modes.
+
+* secure mode: IPL will terminate on any errors detected by this facility.
+* audit mode: IPL may proceed regardless of any errors detected by this
facility.
+
+Errors detected by the SCLAF are reported in IIRB.
+
+Unsigned components may only be loaded at absolute storage address x’2000’ or
higher.
+
+Signed components must include a Secure Code Loading Attribute Block (SCLAB),
+which is located at the very end of the signed component.
+
+**Secure Code Loading Attribute Block (SCLAB)**
+
+The SCLAB is located at the end of each signed component. It defines the code
loading
+attributes for the component and may:
+
+* Provide direction on how to process the rest of the component.
+
+* Provide further validation of information on where to load the signed binary
code
+ from the load device.
+
+* Specify where to start the execution of the loaded OS code.
+
+
+DIAGNOSE function code 'X'508' - KVM IPL extensions
+---------------------------------------------------
+
+DIAGNOSE 'X'508' is reserved for KVM guest use in order to facilitate
+communication of additional IPL operations that cannot be handled by userspace,
+such as signature verification for secure IPL.
+
+If the function code specifies 0x508, KVM IPL extension functions are
performed.
+These functions are meant to provide extended functionality for s390 guest boot
+that requires assistance from QEMU.
+
+Subcode 0 - query installed subcodes
+ Returns a 64-bit mask indicating which subcodes are supported.
+
+Subcode 1 - perform signature verification
+ Used to perform signature-verification on a signed component, leveraging
+ qcrypto libraries to perform this operation and pulling from the
certificate
+ store.
+
+
+Secure IPL Quickstart
+=====================
+
+Build QEMU with gnutls enabled:
+
+.. code-block:: shell
+
+ ./configure … --enable-gnutls
+
+Generate certificate (e.g. via openssl):
+
+.. code-block:: shell
+
+ openssl req -new -x509 -newkey rsa:2048 -keyout mykey.priv \
+ -outform DER -out mycert.der -days 36500 \
+ -subj "/CN=My Name/" -nodes
+
+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 mykey.priv mycert.der /boot/vmlinuz-…
+ ./sign-file sha256 mykey.priv mycert.der /usr/lib/s390-tools/stage3.bin
+
+Run zipl with secure boot enabled
+
+.. code-block:: shell
+
+ zipl --secure 1 -V
+
+Start Guest with Cmd Options:
+
+.. code-block:: shell
+
+ qemu-system-s390x -machine
s390-ccw-virtio,secure-boot=on,boot-certificates=mycert.der ...
So that quickstart section looks like it could be useful for the end user?
Maybe you could split your doc up into two part, one going into
docs/system/s390x/ for the normal users, and one going into docs/specs/ as
technical reference for the developers?
Thomas
