On 7/11/25 17:11, 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>
We should consider segmenting these documents by introducing the wording
with the same patch that introduces the relevant functionality. I'll
try to do my best here to give some guidance on how it should be broken
up, but I might miss a few things. Hopefully I've successfully conveyed
what I meant in my first sentence.
I'll organize my feedback here using XML tags to help encapsulate the
segments and provide a comment to which patch in this series they should
be merged with. E.g.
<segment>
Comment
Diff
</segment>
You do not need to provide my sign-off on the patches you merge the
documentation with.
> ---
> docs/specs/s390x-secure-ipl.rst | 159 +++++++++++++++++++++++++++++++
> docs/system/s390x/secure-ipl.rst | 156 ++++++++++++++++++++++++++++++
> 2 files changed, 315 insertions(+)
> create mode 100644 docs/specs/s390x-secure-ipl.rst
> create mode 100644 docs/system/s390x/secure-ipl.rst
>
> diff --git a/docs/specs/s390x-secure-ipl.rst b/docs/specs/s390x-secure-ipl.rst
> new file mode 100644
> index 0000000000..1ff69092e2
> --- /dev/null
> +++ b/docs/specs/s390x-secure-ipl.rst
> @@ -0,0 +1,159 @@
> +.. SPDX-License-Identifier: GPL-2.0-or-later
> +
<segment>
This can be introduced in a standalone patch at the end of the series
(basically this patch). You can keep my sign-off on that patch.
> +s390 Secure IPL
> +===============
> +
> +Secure IPL (a.k.a. secure boot) enables s390-ccw virtual machines to
> +leverage qcrypto libraries and z/Architecture emulations to verify the
> +integrity of signed kernels. The qcrypto libraries are used to perform
> +certificate validation and signature-verification, whereas the
> +z/Architecture emulations are used to ensure secure IPL data has not
> +been tampered with, convey data between QEMU and userspace, and set up
> +the relevant secure IPL data structures with verification results.
> +
> +To find out more about using this feature, see
> ``docs/system/s390x/secure-ipl.rst``.
> +
> +Note that "userspace" will refer to the s390-ccw BIOS unless stated
> +otherwise.
> +
> +Both QEMU and userspace work in tandem to perform secure IPL. The Secure
> +Loading Attributes Facility (SCLAF) is used to check the Secure Code
> +Loading Attribute Block (SCLAB) and ensure that secure IPL data has not
> +been tampered with. DIAGNOSE 'X'320' is invoked by userspace to query
> +the certificate 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, which is used by the kernel to store signed and
> +verified entries.
> +
> +The logical steps are as follows:
> +
> +- Userspace reads 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
> +
> +- 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
> +
> +More information regarding the respective DIAGNOSE commands and IPL data
> +structures are outlined within this document.
</segment>
<segment>
This should be merged with [PATCH v4 05/28] s390x/diag: Introduce DIAG
320 for certificate store facility
> +
> +s390 Certificate Store and Functions
> +====================================
> +
> +s390 Certificate Store
> +----------------------
> +
> +A certificate store is implemented for s390-ccw guests to retain within
> +memory all certificates provided by the user via the command-line, which
> +are expected to be stored somewhere on the host's file system. The store
> +will keep track of the number of certificates, their respective size,
> +and a summation of the sizes.
> +
> +DIAGNOSE function code 'X'320' - Certificate Store Facility
> +-----------------------------------------------------------
> +
> +DIAGNOSE 'X'320' is used to provide support for userspace to directly
> +query the s390 certificate store. Userspace may be the s390-ccw BIOS or
> +the guest kernel.
> +
> +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.
</segment>
<segment>
Merge with [PATCH v4 07/28] s390x/diag: Implement DIAG 320 subcode 1
> +
> +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).
> +
</segment>
<segment>
Merge with [PATCH v4 09/28] s390x/diag: Implement DIAG 320 subcode 2
> +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.
> +
> +
</segment>
<segment>
Merge with [PATCH v4 13/28] pc-bios/s390-ccw: Introduce IPL Information
Report Block (IIRB)
> +Secure IPL Data Structures, Facilities, and 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
> +
> +
</segment>
<segment>
Merge with [PATCH v4 21/28] s390x: Guest support for Secure-IPL Code
Loading Attributes Facility (SCLAF)
Though we may need to revisit if this documentation is valuable. SCLAF
has a lot of heavy technical information that may be better suited for
the PoPs.
For now, let's keep it.
> +Secure Code Loading Attributes Facility
> +---------------------------------
> +
> +The Secure Code Loading Attributes Facility (SCLAF) enhances system security
> during the
> +IPL by enforcing additional verification rules.
> +
> +When SCLAF is available, its behavior depends on the IPL mode. It introduces
> verification
> +of both signed and unsigned components to help ensure that only authorized
> code is loaded
> +during the IPL process. Any errors detected by SCLAF are reported in the
> IIRB.
> +
> +Unsigned components are restricted to load addresses at or above absolute
> storage address
> +``0x2000``.
> +
> +Signed components must include a Secure Code Loading Attribute Block
> (SCLAB), which is
> +appended at the very end of the component. The SCLAB defines security
> attributes for
> +handling the signed code. Specifically, it 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.
> +
> +
</segment>
<segment>
Merge with [PATCH v4 10/28] s390x/diag: Introduce DIAG 508 for secure
IPL operations
> +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.
> +
</segment>
<segment>
Merge with [PATCH v4 12/28] s390x/diag: Implement DIAG 508 subcode 1 for
signature verification
> +Subcode 1 - perform signature verification
> + Perform signature-verification on a signed component, using certificates
> + from the certificate store and leveraging qcrypto libraries to perform
> + this operation.
Add more detail here later to describe the data structures and
input/output, similar to how the documentation for 320 is laid out.
</segment>
[...]
<segment>
Introduce this as another standalone patch (not with the same standalone
as mentioned above)
> +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,
> +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
> +===============================
> +
> +New parameters have been introduced to s390-ccw-virtio machine type option
> +to support secure IPL. These parameters allow users to provide certificates
> +and enable secure IPL directly via the command line.
> +
</segment>
<segment>
Merge with [PATCH v4 01/28] Add boot-certificates to s390-ccw-virtio
machine type option
> +Providing Certificates
> +----------------------
> +
> +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.pem
> +
</segment>
<segment>
Merge with [PATCH v4 23/28] Add secure-boot to s390-ccw-virtio machine
type option
> +Enabling Secure IPL
> +-------------------
> +
> +Different IPL modes may be toggled with the following command line option:
> +
Change to: "Secure IPL is enabled by explicitly providing the
secure-boot='on' option. The absence of this option is equivalent to
setting this option to off.
(maybe reword it so "option" isn't used three times in one breath?)
> +.. code-block:: shell
> +
> + qemu-system-s390x -machine s390-ccw-virtio,secure-boot=on|off
> +
> +Additionally, the provision of certificates affect the mode.
> +
> +
Remove the line above. It'll be explained in the IPL Modes section.
</segment>
<segment>
Merge each mode below with the same patch that implements the respective
enum.
> +IPL Modes
> +=========
Let's add a quick description of what "IPL Mode" means:
"The concept of IPL Modes are introduced to differentiate between the
IPL configurations. These modes are mutually exclusive and enabled based
on specific combinations of the ``secure-boot`` and
``boot-certificates`` options on the QEMU command line."
> +
> +Normal Mode
> +-----------
> +
Configuration: ``qemu-system-s390x -machine s390-ccw-virtio ...``
> +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
> +----------
> +
Configuration: ``qemu-system-s390x -machine
s390-ccw-virtio,boot-certificates=path/to/cert.pem ...``
> +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
> +-----------
> +
Configuration: ``qemu-system-s390x -machine
s390-ccw-virtio,boot-certificates=path/to/cert.pem,secure-boot=on ...``
> +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.
> +
</segment>
<segment>
Include this with the standalone patch for this doc.
> +
> +Constraints
> +===========
> +
> +The following constraints apply when attempting to secure IPL an s390 guest:
> +
> +- z16 CPU model
> +- certificates must be in X.509 PEM 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.
> +
> +
> +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
> keypt secure
> +and confidential.
s/keypt/kept
> +
> +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
> +----------------------------
> +
> +.. code-block:: shell
> +
> + qemu-system-s390x -machine
> s390-ccw-virtio,secure-boot=on,boot-certificates=cert.pem ...
</segment>
--
Regards,
Collin
