GENPROTIMG(1)

NAME
genprotimg - Create a protected virtualization image

SYNOPSIS
genprotimg -k HOST_KEY_DOCUMENT... -C CERTIFICATE... -i VMLINUZ [-r RAMDISK] [-p PARMFILE] -o OUTFILE [OPTION]...

DESCRIPTION

Use genprotimg 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 --offline option and specify the certificate revocation lists (CRLs) by using the --crl 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.

Use this image file as a kernel image for zipl or for a direct kernel boot using QEMU.

OPTIONS

-h, --help
    Prints usage information, then exits.

--help-experimental
    Prints experimental usage information, then exits.

--help-all
    Prints all usage information, then exits.

-V, --verbose
    Provides more detailed output.

-k, --host-key-document=HOST_KEY_DOCUMENT
    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.

-C, --cert=FILE
    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. Ignored if --no-verify is specified.

-o, --output=OUTPUT_FILE
    Specifies the output file. Required.

-i, --image=VMLINUZ
    Specifies the Linux kernel image file. Required.

-r, --ramdisk=RAMDISK
    Specifies the RAM disk image. Optional.

-p, --parmfile=PARMFILE
    Specifies the kernel command line stored in PARMFILE. Optional.

--crl=FILE
    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.

--offline
    Specifies offline mode, in which no attempt is made to download CRLs. Optional.

--root-ca=FILE
    Specifies the root CA certificate for the verification. If omitted, the system wide root CAs installed on the system is used. Use this only if you trust the specified certificate. Optional.

--no-verify
    Does not require the host-key documents to be valid. Do not use for a production image unless you verified the host-key document before. Optional.

--comm-key=FILE
    Specifies the customer communication key (CCK). This key is used for the PV guest dump encryption and to derive the CCK-derived extension secret used for add-secret requests. Use a secure, random, plaintext AES-256 GCM key. Optional.

--enable-dump
    Enable PV guest dumps. Requires the --comm-key option. Optional.

--disable-dump
    Disable PV guest dumps. This is the default.

--enable-cck-extension-secret
    Add-secret requests must provide an extension secret that matches the CCK-derived extension secret. Requires the --comm-key option. Optional.

--disable-cck-extension-secret
    Add-secret requests don't have to provide an extension secret. This is the default.

--enable-pckmo
    Enable the support for the DEA, TDEA, AES, and ECC PCKMO key encryption functions. This is the default.

--disable-pckmo
    Disable the support for the DEA, TDEA, AES, and ECC PCKMO key encryption functions. Optional.

-v, --version
    Prints version information, then exits.

EXAMPLES

These are examples to generate a protected virtualization image in /boot/vmlinuz.pv, using the kernel file vmlinuz, the initrd in initramfs, the kernel parameters contained in parmfile, the intermediate CA in DigiCertCA.crt, the IBM Z signing key in ibm-z-host-key-signing.crt, and the host-key document in host_key.crt. An AES-256 GCM key is stored in comm-key, which is used for the PV guest dump support in the second example.

Generate a protected virtualization image:

genprotimg -i vmlinuz -r initramfs -p parmfile -k host_key.crt -C ibm-z-host-key-signing.crt -C DigiCertCA.crt -o /boot/vmlinuz.pv

Generate a protected virtualization image with PV guest dump support:

genprotimg -i vmlinuz -r initramfs -p parmfile -k host_key.crt -C ibm-z-host-key-signing.crt -C DigiCertCA.crt -o /boot/vmlinuz.pv --enable-dump --comm-key comm-key

NOTES

1.  An ELF file cannot be used as a Linux kernel image.

2.  Remember to re-run zipl after updating a protected virtualization image.

SEE ALSO
zipl(5), qemu(1)