On 7/1/26 4:49 PM, Zhuoying Cai wrote: > Add documentation for secure IPL > > Signed-off-by: Collin Walling <[email protected]> > Signed-off-by: Zhuoying Cai <[email protected]> > --- > docs/specs/s390x-secure-ipl.rst | 55 +++++++++++++++++++++++++++++++++ > 1 file changed, 55 insertions(+) > > diff --git a/docs/specs/s390x-secure-ipl.rst b/docs/specs/s390x-secure-ipl.rst > index 0f92ff96b9..65a4b2f624 100644 > --- a/docs/specs/s390x-secure-ipl.rst > +++ b/docs/specs/s390x-secure-ipl.rst > @@ -1,5 +1,60 @@ > .. 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
s/emulations/emulation/ ? > +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 emulation is used ? > +been tampered with, convey data between QEMU and guest code, and set up > +the relevant secure IPL data structures with verification results. > + > +To find out more about using this feature, see > +:doc:`documentation </system/s390x/secure-ipl>`. > + > +Note that "guest code" will refer to the s390-ccw BIOS unless stated > +otherwise. > + > +Both QEMU and guest code work in cooperation to perform secure IPL. The > Secure > +Loading Attributes Facility (SCLAF) is used to check the Secure Code Secure 'Code' Loading Attributes Facility ? > +Loading Attribute Block (SCLAB) and ensure that secure IPL data has not > +been tampered with. DIAGNOSE 'X'320' is invoked by guest code to query > +the certificate store info and retrieve specific certificates from QEMU. > +DIAGNOSE 'X'508' is used by guest code to leverage qcrypto libraries to > +perform signature-verification in QEMU. Lastly, guest code 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 IPL Parameter Block (IPLB) ? > +verified entries. > + > +The logical steps are as follows: > + > +- guest code reads data payload from disk (e.g. stage3 boot loader, kernel) > +- guest code checks the validity of the SCLAB > +- guest code invokes DIAG 508 subcode 1 and provides it the payload drop the word 'it' > +- 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 'QEMU DIAG 508 handler' > + 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 > + > +- guest code responds to this operation: QEMU can't control what the guest will do. Maybe better to say something like... 'guest code is expected to respond to this operation by:' With those changes (please remember to stay within 80 columns): Reviewed-by: Matthew Rosato <[email protected]> > + > + - success: retrieves cert from store via DIAG 320 using returned index > + - failure: reports with warning (audit mode), aborts with error (secure > mode) > + > +- guest code appends IIRB at the end of the IPLB > +- guest code kicks off IPL > + > +More information regarding the respective DIAGNOSE commands and IPL data > +structures are outlined within this document. > + > + > s390 Certificate Store and Functions > ------------------------------------ >
