genprotimg - Generate an IBM Secure Execution image

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

Command availability

If your distribution does not contain the genprotimg command, you can either copy the kernel and initial RAM file to an environment that includes genprotimg and build the secure image there, or build the command yourself from the source on GitHub:
https://github.com/ibm-s390-tools/s390-tools/tree/master/genprotimg

genprotimg syntax

Read syntax diagramSkip visual syntax diagramgenprotimg -k  <host_key_document> --cert <certificate>--crl= <revoked_certs> -i  <image> -r <ram_disk>-p <parm_ file> -o <output_image> --enable-cck-extension-secret----comm-key= <cck_file>--enable-pckmo--disable-pckmo-V--no-verify

Parameters

-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.

--crl=<revoked_certs>
Optional: specifies a list of revoked certificates.
-i <image> or --image=<image>
Specifies the Linux® kernel image.
Note: The genprotimg 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.
--enable-cck-extension-secret ----comm-key=<cck_file>
Requires that the extension secret that is used for add-secret requests is based on the customer communication key (CCK).
--disable-pckmo

Disables the Permit CPACF Key Management Operations (PCKMO) support.

The PCKMO options configure key management operations on the virtual server. If enabled, keys can be created that use the DEA, TDEA, AES, or ECC algorithms.

--enable-pckmo

Enables the PCKMO support. This option is the default.

Interface change:
For genprotimg versions with the --enable-pckmo option, PCKMO key operations are enabled by default. To confirm that --enable-pckmo is available on your distribution, issue:
# genprotimg -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:
# genprotimg ... --x-pcf '0xe0'
-V or --verbose
Prints more runtime information.
--no-verify
Specifies that the host key document is not verified.
Warning: The genprotimg 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.
-v or --version
Displays the version information for the command.
-h or --help
Displays out a short help text, then exits. To view the man page, enter man genprotimg.
--help-experimental
Displays experimental usage information, then exits.
--help-all
Displays all help text, then exits.

Example: Using genprotimg to generate an IBM Secure Execution image

Assume that you have an Ubuntu guest that you would like to convert into an IBM Secure Execution 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
  1. Verify the host key document, see Verifying the host key document.
  2. Create a parameter file called parmfile. Copy the content of the parameter that specifies the root device.
  3. 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
  4. Generate an IBM Secure Execution image in /boot/secure-linux with the command:
    # genprotimg -i /boot/vmlinuz -r /boot/initrd.img -p parmfile  
-k HKD-8651-00020089A8.crt --cert SigningKey.crt --cert DigiCertCA.crt -o /boot/secure-linux