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)

s390-tools                                          May 2022                                       GENPROTIMG(1)