docs/specs: Add secure IPL documentation
Add documentation for secure IPL Signed-off-by: Collin Walling <walling@linux.ibm.com> Signed-off-by: Zhuoying Cai <zycai@linux.ibm.com> Reviewed-by: Matthew Rosato <mjrosato@linux.ibm.com> Link: https://lore.kernel.org/qemu-devel/20260730214624.2328883-33-zycai@linux.ibm.com Signed-off-by: Eric Farman <farman@linux.ibm.com>
Zhuoying Cai committed
Jul 30, 2026 at 17:46 UTC
0b856091156f68552f2352443d636e1b54d4d33f
1 file changed
+55
docs/specs/s390x-secure-ipl.rst
+55
@@ -1,5 +1,60 @@
1
.. SPDX-License-Identifier: GPL-2.0-or-later
2
3
+s390 Secure IPL
4
+===============
5
+
6
+Secure IPL (a.k.a. secure boot) enables s390-ccw virtual machines to
7
+leverage qcrypto libraries and z/Architecture emulation to verify the
8
+integrity of signed kernels. The qcrypto libraries are used to perform
9
+certificate validation and signature-verification, whereas the
10
+z/Architecture emulation is used to ensure secure IPL data has not
11
+been tampered with, convey data between QEMU and guest code, and set up
12
+the relevant secure IPL data structures with verification results.
13
+
14
+To find out more about using this feature, see
15
+:doc:`documentation </system/s390x/secure-ipl>`.
16
+
17
+Note that "guest code" will refer to the s390-ccw BIOS unless stated
18
+otherwise.
19
+
20
+Both QEMU and guest code work in cooperation to perform secure IPL. The Secure
21
+Code Loading Attributes Facility (SCLAF) is used to check the Secure Code
22
+Loading Attribute Block (SCLAB) and ensure that secure IPL data has not
23
+been tampered with. DIAGNOSE 'X'320' is invoked by guest code to query
24
+the certificate store info and retrieve specific certificates from QEMU.
25
+DIAGNOSE 'X'508' is used by guest code to leverage qcrypto libraries to
26
+perform signature-verification in QEMU. Lastly, guest code generates and
27
+appends an IPL Information Report Block (IIRB) at the end of the IPL
28
+Parameter Block (IPLB), which is used by the kernel to store signed and
29
+verified entries.
30
+
31
+The logical steps are as follows:
32
+
33
+- guest code reads data payload from disk (e.g. stage3 boot loader, kernel)
34
+- guest code checks the validity of the SCLAB
35
+- guest code invokes DIAG 508 subcode 1 and provides the payload
36
+- QEMU handles DIAG 508 request by reading the payload and retrieving the
37
+ certificate store
38
+- QEMU DIAG 508 utilizes handler qcrypto libraries to perform
39
+ signature-verification on the payload, attempting with each cert in the store
40
+ (until success or exhausted)
41
+- QEMU DIAG 508 returns:
42
+
43
+ - success: index of cert used to verify payload
44
+ - failure: error code
45
+
46
+- guest code is expected to respond to this operation by:
47
+
48
+ - success: retrieves cert from store via DIAG 320 using returned index
49
+ - failure: reports with warning (audit mode), aborts with error (secure mode)
50
+
51
+- guest code appends IIRB at the end of the IPLB
52
+- guest code kicks off IPL
53
+
54
+More information regarding the respective DIAGNOSE commands and IPL data
55
+structures are outlined within this document.
56
+
57
+
58
s390 Certificate Store and Functions
59
------------------------------------
60