Add documentation for secure IPL Signed-off-by: Collin Walling <wall...@linux.ibm.com> Signed-off-by: Zhuoying Cai <zy...@linux.ibm.com> --- 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 + +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. + +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. + +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 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 +--------------------------------- + +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. + + +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 + 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..83223ddd7c --- /dev/null +++ b/docs/system/s390x/secure-ipl.rst @@ -0,0 +1,156 @@ +.. 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. + +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. + +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 + +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 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. + +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 ... -- 2.49.0
