Add documentation for secure IPL Signed-off-by: Collin Walling <[email protected]> Signed-off-by: Zhuoying Cai <[email protected]> Reviewed-by: Matthew Rosato <[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 7a603eb956..82b21600af 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 emulation to verify the +integrity of signed kernels. The qcrypto libraries are used to perform +certificate validation and signature-verification, whereas the +z/Architecture emulation is used to ensure secure IPL data has not +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 +Code 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 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 (IPLB), which is used by the kernel to store signed and +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 the payload +- QEMU handles DIAG 508 request by reading the payload and retrieving the + certificate store +- QEMU DIAG 508 utilizes handler 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 + +- guest code is expected to respond to this operation by: + + - 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 ------------------------------------ -- 2.54.0
