genprotimg - Create a protected virtualization image
|
genprotimg -k HOST_KEY_DOCUMENT... -C
CERTIFICATE... -i VMLINUZ [-r RAMDISK]
[-p PARMFILE] -o OUTFILE
[OPTION]... |
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.
- -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.
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
- 1.
- An ELF file cannot be used as a Linux kernel image.
- 2.
- Remember to re-run zipl after updating a protected virtualization
image.