| 1 | .. SPDX-License-Identifier: GPL-2.0-or-later |
| 2 | |
| 3 | s390 Secure IPL |
| 4 | =============== |
| 5 | |
| 6 | Secure IPL, also known as secure boot, enables s390-ccw virtual machines to |
| 7 | verify the integrity of guest kernels. |
| 8 | |
| 9 | For technical details of this feature, see the |
| 10 | :doc:`specs document </specs/s390x-secure-ipl>`. |
| 11 | |
| 12 | This document explains how to use secure IPL with s390x in QEMU. It covers |
| 13 | the command line options for providing certificates and enabling secure IPL, |
| 14 | the different IPL modes (Normal, Audit, and Secure), and system requirements. |
| 15 | |
| 16 | A quickstart guide is provided to demonstrate how to generate certificates, |
| 17 | sign images, and start a guest in Secure Mode. |
| 18 | |
| 19 | |
| 20 | Secure IPL Command Line Options |
| 21 | ------------------------------- |
| 22 | |
| 23 | The s390-ccw-virtio machine type supports secure IPL. These parameters allow |
| 24 | users to provide certificates and enable secure IPL directly via the command |
| 25 | line. |
| 26 | |
| 27 | Providing Certificates |
| 28 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 29 | |
| 30 | The certificate store can be populated by supplying a list of X.509 certificate |
| 31 | file paths or directories containing certificate files on the command-line: |
| 32 | |
| 33 | Note: certificate files must have a .pem extension. |
| 34 | |
| 35 | .. code-block:: shell |
| 36 | |
| 37 | qemu-system-s390x -machine s390-ccw-virtio,boot-certs.0.path=/.../qemu/certs,boot-certs.1.path=/another/path/cert.pem ... |
| 38 | |
| 39 | Enabling Secure IPL |
| 40 | ^^^^^^^^^^^^^^^^^^^ |
| 41 | |
| 42 | Secure IPL is enabled by explicitly setting ``secure-boot=on``; if not |
| 43 | specified, secure boot is considered off. |
| 44 | |
| 45 | .. code-block:: shell |
| 46 | |
| 47 | qemu-system-s390x -machine s390-ccw-virtio,secure-boot=on|off |
| 48 | |
| 49 | |
| 50 | IPL Modes |
| 51 | --------- |
| 52 | |
| 53 | Multiple IPL modes are available to differentiate between the various IPL |
| 54 | configurations. These modes are mutually exclusive and enabled based on specific |
| 55 | combinations of the ``secure-boot`` and ``boot-certs`` options on the QEMU |
| 56 | command line. |
| 57 | |
| 58 | Normal Mode |
| 59 | ^^^^^^^^^^^ |
| 60 | |
| 61 | The absence of both certificates and the ``secure-boot`` option will attempt to |
| 62 | IPL a guest without secure IPL operations. No checks are performed, and no |
| 63 | warnings/errors are reported. This is the default mode, and can be explicitly |
| 64 | enabled with ``secure-boot=off``. |
| 65 | |
| 66 | Configuration: |
| 67 | |
| 68 | .. code-block:: shell |
| 69 | |
| 70 | qemu-system-s390x -machine s390-ccw-virtio ... |
| 71 | |
| 72 | Audit Mode |
| 73 | ^^^^^^^^^^ |
| 74 | |
| 75 | When the certificate store is populated with at least one certificate |
| 76 | and no additional secure IPL parameters are provided on the command |
| 77 | line, then secure IPL will proceed in "audit mode". All secure IPL |
| 78 | operations will be performed with signature verification errors reported |
| 79 | as non-disruptive warnings. |
| 80 | |
| 81 | Configuration: |
| 82 | |
| 83 | .. code-block:: shell |
| 84 | |
| 85 | qemu-system-s390x -machine s390-ccw-virtio,boot-certs.0.path=/.../qemu/certs,boot-certs.1.path=/another/path/cert.pem ... |
| 86 | |
| 87 | Secure Mode |
| 88 | ^^^^^^^^^^^ |
| 89 | |
| 90 | When the ``secure-boot=on`` option is set and certificates are provided, |
| 91 | a secure boot is performed with error reporting enabled. The boot process aborts |
| 92 | if any error occurs. |
| 93 | |
| 94 | Configuration: |
| 95 | |
| 96 | .. code-block:: shell |
| 97 | |
| 98 | qemu-system-s390x -machine s390-ccw-virtio,secure-boot=on,boot-certs.0.path=/.../qemu/certs,boot-certs.1.path=/another/path/cert.pem ... |
| 99 | |
| 100 | |
| 101 | Constraints |
| 102 | ----------- |
| 103 | |
| 104 | The following constraints apply when attempting to boot an s390x guest in secure |
| 105 | mode: |
| 106 | |
| 107 | - z16 or "qemu" CPU model |
| 108 | - certificates must be in X.509 PEM format |
| 109 | - only support for SCSI scheme of virtio-blk/virtio-scsi devices |
| 110 | - a boot device must be specified |
| 111 | - any unsupported devices (e.g., ECKD and VFIO) or non-eligible devices (e.g., |
| 112 | network) will cause the entire boot process to terminate early, with an error |
| 113 | logged to the console. |
| 114 | |
| 115 | |
| 116 | Secure IPL Quickstart |
| 117 | --------------------- |
| 118 | |
| 119 | Build QEMU with gnutls enabled |
| 120 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 121 | |
| 122 | .. code-block:: shell |
| 123 | |
| 124 | ./configure … --enable-gnutls |
| 125 | |
| 126 | Generate certificate (e.g. via certtool) |
| 127 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 128 | |
| 129 | A private key is required before generating a certificate. This key must be kept |
| 130 | secure and confidential. |
| 131 | |
| 132 | Use an RSA private key for signing. |
| 133 | |
| 134 | .. code-block:: shell |
| 135 | |
| 136 | certtool --generate-privkey > key.pem |
| 137 | |
| 138 | A self-signed certificate requires the organization name. Use the ``cert.info`` |
| 139 | template to pre-fill values and avoid interactive prompts from certtool. |
| 140 | |
| 141 | .. code-block:: shell |
| 142 | |
| 143 | cat > cert.info <<EOF |
| 144 | cn = "My Name" |
| 145 | expiration_days = 365 |
| 146 | cert_signing_key |
| 147 | EOF |
| 148 | |
| 149 | certtool --generate-self-signed \ |
| 150 | --load-privkey key.pem \ |
| 151 | --template cert.info \ |
| 152 | --hash=SHA256 \ |
| 153 | --outfile cert.pem |
| 154 | |
| 155 | Sign Images (e.g. via sign-file) |
| 156 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 157 | |
| 158 | - signing must be performed on a guest filesystem |
| 159 | - sign-file script used in the example below is located within the kernel source |
| 160 | repo |
| 161 | |
| 162 | .. code-block:: shell |
| 163 | |
| 164 | ./sign-file sha256 key.pem cert.pem /boot/vmlinuz-… |
| 165 | ./sign-file sha256 key.pem cert.pem /usr/lib/s390-tools/stage3.bin |
| 166 | |
| 167 | Note: re-signing a component will not verify correctly; the existing signature |
| 168 | must be stripped before a new one is applied. |
| 169 | |
| 170 | Run zipl with secure boot enabled |
| 171 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 172 | |
| 173 | - zipl must be performed on a guest filesystem |
| 174 | |
| 175 | .. code-block:: shell |
| 176 | |
| 177 | zipl --secure 1 -V |
| 178 | |
| 179 | Command line options for starting the guest |
| 180 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 181 | |
| 182 | .. code-block:: shell |
| 183 | |
| 184 | qemu-system-s390x -machine s390-ccw-virtio,secure-boot=on,boot-certs.0.path=cert.pem ... |