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