PVIMG-CREATE(1)

NAME
pvimg-create - Create an IBM Secure Execution image

SYNOPSIS
pvimg create [OPTIONS] --kernel <FILE> --output <FILE> --host-key-document <FILE> <--no-verify|--cert <FILE>>

DESCRIPTION

Use pvimg 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

-i, --kernel, --image <FILE>
    Use the content of FILE as a raw binary Linux kernel. The Linux kernel must be a raw binary s390x Linux kernel. The ELF format is not supported.

-r, --ramdisk <FILE>
    Use the content of FILE as the Linux initial RAM disk.

-p, --parmfile <FILE>
    Use the content of FILE as the Linux kernel command line. The Linux kernel command line must be shorter than the maximum kernel command line size supported by the given Linux kernel.

-o, --output <FILE>
    Write the generated Secure Execution boot image to FILE.

-k, --host-key-document <FILE>
    Use FILE as a host-key document. Can be specified multiple times and must be specified at least once.

--no-verify
    Disable the host-key document verification. Does not require the host-key documents to be valid. Do not use for a production request unless you verified the host-key document beforehand.

-C, --cert <FILE>
    Use FILE as a certificate to verify the host-key or keys. The certificates are 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).

--crl <FILE>
    Use FILE as a certificate revocation list (CRL). The list is used to check whether a certificate of the chain of trust is revoked. Specify this option multiple times to use multiple CRLs.

--offline
    Make no attempt to download CRLs.

--root-ca <ROOT_CA>
    Use FILE as the root-CA certificate for the verification. If omitted, the system wide-root CAs installed on the system are used. Use this only if you trust the specified certificate.

--no-component-check
    Disable all input component checks. For example, for the Linux kernel, it tests if the given kernel looks like a raw binary s390x kernel.

--overwrite
    Overwrite an existing Secure Execution boot image.

--cck, --comm-key <FILE>
    Use the content of FILE as the customer-communication key (CCK). The file must contain exactly 32 bytes of data. In previous versions, this option was called --comm-key.

--hdr-key <FILE>
    Use the content of FILE as the Secure Execution header protection key. The file must contain exactly 32 bytes of data. If the option is not specified, the Secure Execution header protection key is a randomly generated key.

--image-key <FILE>
    Use the content of FILE as the image encryption key. The file must contain exactly 64 bytes of data.

--enable-dump
    Enable Secure Execution guest dump support. This option requires the --cck or --enable-cck-update option.

--disable-dump
    Disable Secure Execution guest dump support (default).

--enable-cck-extension-secret
    Add-secret requests must provide an extension secret that matches the CCK-derived extension secret. This option requires the --cck option.

--disable-cck-extension-secret
    Add-secret requests don't have to provide the CCK-derived extension secret (default).

--enable-cck-update
    Enable CCK update support. Requires z17 or up. This option cannot be used in conjunction with the --enable-cck-extension-secret option.

--disable-cck-update
    Disable CCK update support (default).

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

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

--enable-pckmo-hmac
    Enable the support for the HMAC PCKMO key encryption function.

--disable-pckmo-hmac
    Disable the support for the HMAC PCKMO key encryption function (default).

--enable-backup-keys
    Enable the support for backup target keys.

--disable-backup-keys
    Disable the support for backup target keys (default).

--enable-image-encryption
    Enable encryption of the image components (default). The image components are: the kernel, ramdisk, and kernel command line.

--disable-image-encryption
    Disable encryption of the image components. The image components are: the kernel, ramdisk, and kernel command line. Use only if the components used do not contain any confidential content (for example, secrets like non-public cryptographic keys).

-h, --help
    Print help (see a summary with -h).

EXIT STATUS

0 - Program finished successfully
    The command was executed successfully.

1 - Generic error
    Something went wrong during the operation. Refer to the error message.

2 - Usage error
    The command was used incorrectly, for example: unsupported command line flag, or wrong number of arguments.

EXAMPLES
These are examples of how to generate an IBM Secure Execution image in /boot/secure-linux, using the kernel file /boot/vmlinuz, the initrd in /boot/initrd.img, 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 when creating a Secure Execution image with guest dump support enabled in the second example.

Generate an IBM Secure Execution image:

pvimg create -i /boot/vmlinuz -r /boot/initrd.img -p parmfile -k host_key.crt -C ibm-z-host-key-signing.crt -C DigiCertCA.crt -o /boot/secure-linux

Generate an IBM Secure Execution image with Secure Execution guest dump support:

pvimg create -i /boot/vmlinuz -r /boot/initrd.img -p parmfile -k host_key.crt -C ibm-z-host-key-signing.crt -C DigiCertCA.crt -o /boot/secure-linux --enable-dump --cck comm-key

NOTES

1.  The genprotimg(1) command is a symbolic link to the pvimg-create(1) command.

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

3.  Remember to re-run zipl after updating an IBM Secure Execution image.

SEE ALSO

pvimg(1) zipl(8) qemu(1)