pvimg - Create and inspect IBM SEL images

Edit online

Use pvimg create to create an IBM® SEL image, which can be loaded using zipl or QEMU. pvimg can also be used to inspect existing SEL images.

Command availability

If your distribution does not contain the pvimg command, you can either copy the kernel and initial RAM file to an environment that includes pvimg and build the secure image there, or build the command yourself from the source on GitHub:

https://github.com/ibm-s390-linux/s390-tools/tree/master/rust/pvimg

pvimg syntax

Where:

pvimg create: Creates an IBM Secure Execution image, see pvimg create - Generate an IBM SEL image.
pvimg test: Tests different aspects of an existing IBM Secure Execution image, see pvimg test - Check on which hosts an image can run.
-v or --verbose: Prints more runtime information.
-q or --quiet: Provides less output.
--version: Prints version information and exit.
-h or --help: Prints help, for a summary use -h.

pvimg create - Generate an IBM SEL image

The pvimg create command builds an encrypted boot record from a given kernel, initial RAM disk, parameters, and public host-key document.

Where:

-k <host_key_document> or --host-key-document=<host_key_document>: Specifies the host key document. The document must match the host system for which the image is prepared. Specify multiple host key documents to enable the image to run on more than one host. The document is a plain text file with a name of the form: HKD-<type>-<serial>.crt
--cert <certificate>: 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 certificate (also called the host-key-signing-key certificate) and the intermediate CA certificate (signed by the root CA).
Ignored when --no-verify is specified.
--no-verify: Specifies that the host key document is not verified.
Warning: The pvimg as of s390-tools 2.17.0 automatically verifies the host key document. If you need to use the manual procedure (see Verifying the host key document) for verification, use the --no-verify option. Working with an unverified key makes your image vulnerable to man-in-the-middle attacks. Whoever gave you the host key document might be able to decrypt your image.
--crl=<revoked_certs>: Optional: specifies a list of revoked certificates.

-i <image> or --image=<image>

Specifies the Linux® kernel image.

Note: The pvimg create command cannot use an ELF file as a Linux kernel image.

-r <ramdisk> or --ramdisk=<ramdisk>

Specifies a RAM file system.

-p <parm_file>or --parmfile=<parm_file>

Provides a file with kernel parameters.

-o or --output

Specifies the target image name.

--offline

Make no attempt to download CRLs.

--root-ca <root_CA>

Pecifies the file to use 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, the command tests if the given kernel looks like a raw binary s390x kernel. This option disables the check.

--overwrite

Overwrites an existing IBM Secure Execution boot image.

--cck or --comm-key <cck_file>

Specifies a customer-communication key (CCK). The file must contain exactly 32 bytes of data.

--hdr-key <hdr_file>

Specifies an IBM Secure Execution header protection key. The file must contain exactly 32 bytes of data. If the option is not specified, the IBM Secure Execution header protection key is a randomly generated key.

--enable-dump

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

--disable-dump

Disable IBM SEL guest dump support. This is the default.

--disable-cck-extension-secret

Add-secret requests are not required to provide the CCK-derived extension secret (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.

--enable-cck-update

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

--disable-cck-update

Disables IBM Secure Execution guest dump support. This is the default.

--disable-pckmo

Disables the support for the DEA, TDEA, AES, and ECC PCKMO key encryption functions.

--enable-pckmo

Enables the DEA, TDEA, AES, and ECC PCKMO key encryption functions. This is the default.

Interface change:

For pvimg create versions with the --enable-pckmo option, PCKMO key operations are enabled by default. To confirm that --enable-pckmo is available on your distribution, issue:

# pvimg create -h

If the --enable-pckmo option is listed, no further action is needed to enable PCKMO operations. To return to the previous behavior, specify --disable-pckmo.

If no --enable-pckmo option is listed, and you want PCKMO operations, try:

# pvimg create ... --x-pcf '0xe0'

--enable-pckmo-hmac

Enables the support for the HMAC PCKMO key encryption function.

--disable-pckmo-hmac

Disables the support for the HMAC PCKMO key encryption function. This is the default.

--enable-backup-keys

Enables the support for backup target keys.

--disable-backup-keys

Disables the support for backup target keys. This is the default.

--enable-image-encryption

Enables encryption of the image components (default). The image components are: the kernel, RAM disk, and the kernel command line.

--disable-image-encryption

Disables encryption of the image components kernel, RAM disk, and kernel command line. Use this option only if the components used do not contain any confidential content, such as secrets like non-public cryptographic keys.

-h or --help

Displays out a short help text, then exits. To view the man page, enter man pvimg.

Example: Using pvimg to generate an IBM SEL image

Assume that you have an Ubuntu guest that you would like to convert into an IBM SEL guest. You have the following information ready:

The guest has the following zipl.conf:

[ubuntu]
target=/boot
image=/boot/vmlinuz
ramdisk=/boot/initrd.img
parameters=root=UUID=694fd9a4-4180-4c47-92e0-7aa4fe06d370 crashkernel=196M

A host key document called HKD-8651-00020089A8.crt,
The intermediate CA certificate, here DigiCert, in DigiCertCA.crt
The IBM Z signing-key certificate in SigningKey.crt

Verify the host key document, see Verifying the host key document.
Create a parameter file called parmfile. Copy the content of the parameter that specifies the root device.
Specify bounce buffers with a swiotlb parameter with a value of 262144.
The result is a parameter file with the following content:
```
root=UUID=694fd9a4-4180-4c47-92e0-7aa4fe06d370 crashkernel=196M swiotlb=262144
```

Generate an IBM SEL image in /boot/secure-linux with the command:

# pvimg create -i /boot/vmlinuz -r /boot/initrd.img -p parmfile \    
-k HKD-8651-00020089A8.crt --cert SigningKey.crt --cert DigiCertCA.crt -o /boot/secure-linux

pvimg test - Check on which hosts an image can run

Test different aspects of an existing IBM SEL image.

Where:

<SE_image>: Specifies the IBM SEL image to test.
-k or --host-key-document <hkd_file>: Specifies one or more host key documents. The command verifies that the image contains the host key hash of one of the specified host keys. The check fails if none of the host keys match the hash in the image. This parameter can be specified multiple times. Mutually exclusive with --key-hashes.
--key-hashes <hash_file>: Specifies a file with key hashes to check against the host key hashes provided by the ultravisor. If no hash file is specified, the file defaults to /sys/firmware/uv/keys/all. The default file is only available if the local system supports the Query Ultravisor Keys UVC. The command verifies that the image contains the host key hash of one of the specified hashes in the file. The check fails if none of the host keys match a hash. Mutually exclusive with -k.