NAME

       genprotimg - Create a protected virtualization image

SYNOPSIS

        genprotimg -k HOST_KEY_DOCUMENT...  -C CERTIFICATE...  -i VMLINUZ [-r RAMDISK] [-p
        PARMFILE] -o OUTFILE [OPTION]...

DESCRIPTION

       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.

OPTIONS

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

EXAMPLES

       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

NOTES

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

       2.  Remember to re-run zipl after updating a protected virtualization image.

SEE ALSO

       zipl(5), qemu(1)