mirror of
https://github.com/ibm-s390-linux/s390-tools.git
synced 2026-08-05 02:14:52 +00:00
Marc Hartmayer
5394cd363c
Sometimes dumping a virtual machine from the outside is the only way to get the data that is needed. This can be the case if a dumping mechanism like kdump hasn't been configured or data needs to be fetched at a specific point. Dumping a protected guest from the outside without help from FW/HW doesn't yield sufficient data to be useful. Hence we now introduce Protected Virtualization (PV) dump support. The PV dump support works by integrating the firmware into the dump process. New Ultravisor calls are used to initiate the dump process, dump cpu data, dump memory state and lastly complete the dump process. The guest's data is fully encrypted and can only be decrypted by the entity that owns the customer communication key for the dumped guest. Also dumping needs to be allowed via a flag in the SE header. This patch adds support for PV guest dumps to genprotimg. To prepare a PV image in order that the PV guest can later be dumped from the outside, the user has to provide a customer communication key used for the dump process and he has to set the corresponding control flag. For specifying the customer communication key a new command line option `--comm-key` is added and for enabling/disabling the control flag the command line options `--enable-dump` and `--disable-dump` are added. Signed-off-by: Marc Hartmayer <mhartmay@linux.ibm.com> Reviewed-by: Steffen Eiden <seiden@linux.ibm.com> Acked-by: Viktor Mihajlovski <mihajlov@linux.ibm.com> Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>
147 lines
5.4 KiB
Plaintext
147 lines
5.4 KiB
Plaintext
.\" Copyright 2020 IBM Corp.
|
|
.\" s390-tools is free software; you can redistribute it and/or modify
|
|
.\" it under the terms of the MIT license. See LICENSE for details.
|
|
.\"
|
|
.TH GENPROTIMG 8 "November 2020" "s390-tools"
|
|
.SH NAME
|
|
genprotimg \- Create a protected virtualization image
|
|
|
|
.SH SYNOPSIS
|
|
.SY
|
|
.B genprotimg
|
|
\fB\-k\fR \fIHOST_KEY_DOCUMENT\fR...
|
|
\fB\-C\fR \fICERTIFICATE\fR...
|
|
\fB\-i\fR \fIVMLINUZ\fR
|
|
[\fB\-r\fR \fIRAMDISK\fR]
|
|
[\fB\-p\fR \fIPARMFILE\fR]
|
|
\fB\-o\fR \fIOUTFILE\fR
|
|
[\fIOPTION\fR]...
|
|
.YS
|
|
|
|
.SH DESCRIPTION
|
|
.PP
|
|
Use \fBgenprotimg\fR to generate a single bootable image file with
|
|
encrypted and integrity-protected parts. The command requires a kernel
|
|
image, a host-key document, certificates for the host-key document
|
|
verification, and an output file name. Optionally, specify an initial
|
|
RAM filesystem, and a file containing the kernel parameters. If the
|
|
command should be run offline, use the \fB\-\-offline\fR option and
|
|
specify the certificate revocation lists (CRLs) by using the
|
|
\fB\-\-crl\fR option. Should special circumstances require it, you can
|
|
optionally specify your own keys for the encryption by using the
|
|
experimental options. For all certificates, CRLs, and host-key
|
|
documents, both the PEM and DER input formats are supported. In the
|
|
resulting image file, a plain text boot loader, the encrypted
|
|
components for kernel, initial RAM disk, kernel parameters, and the
|
|
encrypted and integrity-protected header are concatenated. The header
|
|
contains metadata necessary for running the guest in protected mode.
|
|
.PP
|
|
Use this image file as a kernel image for zipl or for a direct kernel
|
|
boot using QEMU.
|
|
|
|
.SH OPTIONS
|
|
.TP
|
|
\fB\-h\fR, \fB\-\-help\fR
|
|
Prints usage information, then exits.
|
|
.TP
|
|
\fB\-\-help-experimental\fR
|
|
Prints experimental usage information, then exits.
|
|
.TP
|
|
\fB\-\-help-all\fR
|
|
Prints all usage information, then exits.
|
|
.TP
|
|
\fB\-V\fR, \fB\-\-verbose\fR
|
|
Provides more detailed output.
|
|
.TP
|
|
\fB\-k\fR, \fB\-\-host-key-document\fR=\fI\,HOST_KEY_DOCUMENT\/\fR
|
|
Specifies a host-key document. At least one is required. Specify this
|
|
option multiple times to enable the image to run on more than one
|
|
host.
|
|
.TP
|
|
\fB\-C\fR, \fB\-\-cert\fR=\fI\,FILE\/\fR
|
|
Specifies the certificate that is used to establish a chain of trust
|
|
for the verification of the host-key documents. Specify this option
|
|
twice to specify the IBM Z signing key and the intermediate CA
|
|
certificate (signed by the root CA). Required.
|
|
.TP
|
|
\fB\-o\fR, \fB\-\-output\fR=\fI\,OUTPUT_FILE\/\fR
|
|
Specifies the output file. Required.
|
|
.TP
|
|
\fB\-i\fR, \fB\-\-image\fR=\fI\,VMLINUZ\/\fR
|
|
Specifies the Linux kernel image file. Required.
|
|
.TP
|
|
\fB\-r\fR, \fB\-\-ramdisk\fR=\fI\,RAMDISK\/\fR
|
|
Specifies the RAM disk image. Optional.
|
|
.TP
|
|
\fB\-p\fR, \fB\-\-parmfile\fR=\fI\,PARMFILE\/\fR
|
|
Specifies the kernel command line stored in \fI\,PARMFILE\/\fR. Optional.
|
|
.TP
|
|
\fB\-\-crl\fR=\fI\,FILE\/\fR
|
|
Specifies the revocation list that is used to check whether a
|
|
certificate of the chain of trust is revoked. Specify this option
|
|
multiple times to use multiple CRLs. Optional.
|
|
.TP
|
|
\fB\-\-offline\fR
|
|
Specifies offline mode, in which no attempt is made to download
|
|
CRLs. Optional.
|
|
.TP
|
|
\fB\-\-root\-ca\fR=\fI\,FILE\/\fR
|
|
Specifies the root CA certificate for the verification. If omitted,
|
|
the DigiCert root CA certificate installed on the system is used. Use
|
|
this only if you trust the specified certificate. Optional.
|
|
.TP
|
|
\fB\-\-no-verify\fR
|
|
Do not require the host-key documents to be valid. For testing
|
|
purposes, do not use for a production image. Optional.
|
|
.TP
|
|
\fB\-\-comm\-key\fR=\fI\,FILE\/\fR
|
|
Specifies the encryption key you want to use for the PV guest dump. Use a
|
|
secure, random, plaintext AES-256 GCM key. Optional.
|
|
.TP
|
|
\fB\-\-enable\-dump\fR
|
|
Enable PV guest dumps. Requires the \fB\-\-comm-key\fR option. Optional.
|
|
.TP
|
|
\fB\-\-disable\-dump\fR
|
|
Disable PV guest dumps. This is the default. Optional.
|
|
.TP
|
|
\fB\-\-enable\-pckmo\fR
|
|
Enable the support for the DEA, TDEA, AES, and ECC PCKMO key encryption
|
|
functions. This is the default. Optional.
|
|
.TP
|
|
\fB\-\-disable\-pckmo\fR
|
|
Disable the support for the DEA, TDEA, AES, and ECC PCKMO key encryption
|
|
functions. Optional.
|
|
.TP
|
|
\fB\-v\fR, \fB\-\-version\fR
|
|
Prints version information, then exits.
|
|
|
|
.SH EXAMPLES
|
|
|
|
These are examples to generate a protected virtualization image in
|
|
\fI\,/boot/vmlinuz.pv\/\fR, using the kernel file \fI\,vmlinuz\/\fR, the
|
|
initrd in \fI\,initramfs\/\fR, the kernel parameters contained in
|
|
\fI\,parmfile\/\fR, the intermediate CA in \fI\,DigiCertCA.crt\/\fR, the
|
|
IBM Z signing key in \fI\,ibm-z-host-key-signing.crt\/\fR, and the
|
|
host-key document in \fI\,host_key.crt\/\fR. An AES-256 GCM key is stored in
|
|
\fI\,comm-key\/\fR, which is used for the PV guest dump support in the second
|
|
example.
|
|
|
|
Generate a protected virtualization image:
|
|
|
|
.PP
|
|
.B genprotimg \-i \fI\,vmlinuz\/\fR \-r \fI\,initramfs\/\fR \-p \fI\,parmfile\/\fR \-k \fI\,host_key.crt\/\fR \-C \fI\,ibm-z-host-key-signing.crt\/\fR \-C \fI\,DigiCertCA.crt\fR \-o \fI\,/boot/vmlinuz.pv\/\fR
|
|
|
|
Generate a protected virtualization image with PV guest dump support:
|
|
.PP
|
|
.B genprotimg \-i \fI\,vmlinuz\/\fR \-r \fI\,initramfs\/\fR \-p \fI\,parmfile\/\fR \-k \fI\,host_key.crt\/\fR \-C \fI\,ibm-z-host-key-signing.crt\/\fR \-C \fI\,DigiCertCA.crt\fR \-o \fI\,/boot/vmlinuz.pv\/\fR \-\-enable\-dump \-\-comm\-key \fI\,comm-key\fR
|
|
|
|
.SH NOTES
|
|
.IP "1." 4
|
|
An ELF file cannot be used as a Linux kernel image.
|
|
.IP "2." 4
|
|
Remember to re-run \fBzipl\fR after updating a protected
|
|
virtualization image.
|
|
|
|
.SH SEE ALSO
|
|
\&\fBzipl\fR\|(5), \fBqemu\fR\|(1)
|