Re: [PATCH v3 28/28] docs: Add secure IPL documentation

[Collin Walling]

On 6/4/25 5:56 PM, 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/specs/s390x-secure-ipl.rst  | 145 +++++++++++++++++++++++++++++++
>  docs/system/s390x/secure-ipl.rst | 129 +++++++++++++++++++++++++++
>  2 files changed, 274 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..53de036dfa
> --- /dev/null
> +++ b/docs/specs/s390x-secure-ipl.rst
> @@ -0,0 +1,145 @@
> +.. 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
> +handling. 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.
> +

Let's reword the above to:

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.

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:
> +
> +  - on success: retrieves cert from store via DIAG 320 using returned index
> +  - on failure: reports with warning (audit mode), aborts with error (secure 
> mode)
> +
> +- Userspace appends IIRB at the end of the IPLB
> +- Userspace kicks off IPL
> +
> +

Add:

More information regarding the respective DIAGNOSE commands and IPL data
structures are outlined within this document.

Add header:

s390 Certificate Store and Functions
====================================

> +s390 Certificate Store
> +======================

Change:

To a sub header

> +
> +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'.

Reword the above to:

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 to query the certificate store.
> +

Reword the sentence above to:

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.
> +
> +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.
> +
> +
> +Secure IPL Functions

Change to:

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
> +
> +
> +Secure Code Loading Attributes Facility
> +---------------------------------
> +
> +Secure Code Loading Attributes Facility (SCLAF) provides additional security 
> during IPL.
> +

Feedback:

Can you provide a sentence or two describing how this "provides
additional security"?  What exactly does this do?

> +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.

Feedback:

These modes are described in the other document, and the error behavior
is covered there as well. You can remove the two lines above.

> +
> +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.
> +

Feedback:

I think it reads better by simply combining the SCLAF and SCLAB sections
(i.e. no sub sub header for SCLAB).  Simply have SCLAF reference that a
SCLAB will be generated, and go into detail what it contains and what
it's for.

The SCLAF/SCLAB section is a bit difficult to digest as to what exactly
it does for secure IPL... might be a bit *too* technical :)

> +
> +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.

Reword to:

Perform signature-verification on a signed component, using certificates
from the certificate store and leveraging qcrypto libraries to perform
this operation.

> diff --git a/docs/system/s390x/secure-ipl.rst 
> b/docs/system/s390x/secure-ipl.rst
> new file mode 100644
> index 0000000000..f94b21f9fd
> --- /dev/null
> +++ b/docs/system/s390x/secure-ipl.rst
> @@ -0,0 +1,129 @@
> +.. 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.

Add:

For technical details of this feature, see docs/specs/s390x-secure-ipl

> +
> +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.
> +
> +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.der
> +
> +Enabling Secure IPL
> +-------------------
> +
> +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.
> +
> +
> +IPL Modes
> +=========
> +
> +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.
> +
> +
> +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.
> +
> +
> +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 ...


-- 
Regards,
  Collin