[PATCH v16 33/33] docs/system/s390x: Add secure IPL documentation
Add documentation for secure IPL Signed-off-by: Collin Walling Signed-off-by: Zhuoying Cai Reviewed-by: Joshua Daley Reviewed-by: Matthew Rosato --- docs/system/s390x/secure-ipl.rst | 103 +++ 1 file changed, 103 insertions(+) diff --git a/docs/system/s390x/secure-ipl.rst b/docs/system/s390x/secure-ipl.rst index c8fb887ac0..67de20f47a 100644 --- a/docs/system/s390x/secure-ipl.rst +++ b/docs/system/s390x/secure-ipl.rst @@ -1,5 +1,22 @@ .. 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 the +:doc:`specs document `. + +This document explains how to use secure IPL with s390x in QEMU. It covers +the 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 --- @@ -79,3 +96,89 @@ Configuration: .. code-block:: shell qemu-system-s390x -machine s390-ccw-virtio,secure-boot=on,boot-certs.0.path=/.../qemu/certs,boot-certs.1.path=/another/path/cert.pem ... + + +Constraints +--- + +The following constraints apply when attempting to boot an s390x guest in secure +mode: + +- z16 or "qemu" CPU model +- certificates must be in X.509 PEM format +- 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., + network) will cause the entire boot process to terminate 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 kept +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 <
[PATCH v16 33/33] docs/system/s390x: Add secure IPL documentation
Add documentation for secure IPL Signed-off-by: Collin Walling Signed-off-by: Zhuoying Cai Reviewed-by: Joshua Daley Reviewed-by: Matthew Rosato --- docs/system/s390x/secure-ipl.rst | 103 +++ 1 file changed, 103 insertions(+) diff --git a/docs/system/s390x/secure-ipl.rst b/docs/system/s390x/secure-ipl.rst index c8fb887ac0..67de20f47a 100644 --- a/docs/system/s390x/secure-ipl.rst +++ b/docs/system/s390x/secure-ipl.rst @@ -1,5 +1,22 @@ .. 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 the +:doc:`specs document `. + +This document explains how to use secure IPL with s390x in QEMU. It covers +the 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 --- @@ -79,3 +96,89 @@ Configuration: .. code-block:: shell qemu-system-s390x -machine s390-ccw-virtio,secure-boot=on,boot-certs.0.path=/.../qemu/certs,boot-certs.1.path=/another/path/cert.pem ... + + +Constraints +--- + +The following constraints apply when attempting to boot an s390x guest in secure +mode: + +- z16 or "qemu" CPU model +- certificates must be in X.509 PEM format +- 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., + network) will cause the entire boot process to terminate 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 kept +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 <
