PVICS.YAML(5)

NAME
pvics.yaml - Configuration file for pvics SEL EBC image conversion tool

DESCRIPTION
The pvics.yaml file is a YAML-formatted configuration file used by the pvics tool to control the conversion of existing qcow2 KVM guest images to EBC-ready Secure Execution for Linux (SEL) images. The configuration file specifies parameters for image conversion, root file system encryption, and early boot customization (EBC) resource preparation. See pvics(8) for detailed information about the tool's actions and the conversion process.

FILE FORMAT
The configuration file uses YAML syntax with the following top-level sections:

Global Options
    General settings that apply to all actions

Certificate Chain
    Certificate verification configuration

Conversion Options
    Settings specific to the convert action

Encryption Options
    Settings specific to the encrypt action

GLOBAL OPTIONS

no-verify: boolean
    Disables certificate chain verification for pv commands when set to true. Default: false.
    WARNING: Do not disable certificate chain verification in production environments.

no-ebc: boolean
    Controls whether EBC functionality is used. When set to true, a SEL guest image is created without using EBC. Default: false.
    When enabled:

    •   The encrypt action is skipped

    •   The full action behaves the same as the convert action

    •   Default pvimg options are not added; only user-provided options specified in .convert.pvimg-create-options are used

    •   The rd.sel-ebc kernel parameter is not added

out: path
    (REQUIRED) Local directory path used for output files. All generated files (converted images, keys, ASRs) will be written to this directory.

hkds: list
    (REQUIRED) List of paths to host-key-documents (HKDs). Paths may contain wildcard patterns, for example data/*.hkd.
    Example:
    hkds:
      - data/*.hkd
      - /path/to/specific.hkd

CERTIFICATE CHAIN
The certificate-chain section contains all relevant files for verification of the certificate chain. This section is REQUIRED if no-verify is false, and UNUSED if no-verify is true. See pvsecret(1) for more detailed information about certificate chain verification.

certificate-chain.certs: list
    List of paths to certificate files. Paths may contain wildcard patterns.
    Example:
    certs:
      - data/*.cert

certificate-chain.crls: list
    List of paths to certificate revocation list (CRL) files. Paths may contain wildcard patterns.
    Example:
    crls:
      - data/*.crl

certificate-chain.offline: boolean
    Enables offline mode for the pvsecret create command. When true, no network access is attempted for certificate verification.

certificate-chain.root-ca: path
    Path to the root Certificate Authority (CA) file for the certificate chain.

CONVERSION OPTIONS
The convert section contains configuration options for the image conversion phase. These options are used only when running the convert or full actions and have no effect on other actions.

convert.boot-loader-entry: string
    (REQUIRED) Title of an existing boot loader entry from the base image. This entry specifies which kernel, initramfs, and kernel command line to use for the SEL image.
    Use the list action to display available boot loader entries in the base image.

convert.sel-kernel-parameter: string
    (OPTIONAL) Additional kernel parameters to append to the kernel command line of the resulting SEL image. The rd.sel-ebc parameter is always prepended automatically (unless no-ebc is true).
    Example:
    sel-kernel-parameter: swiotlb=524288

convert.pvimg-create-options: string
    (OPTIONAL) Additional options to pass to the pvimg command during SEL image creation.
    See pvimg(1) for available options.

ENCRYPTION OPTIONS
The encrypt section contains configuration options specific to the root filesystem encryption and EBC resource preparation phase. These options are only used when running the encrypt or full actions and are ignored when no-ebc is true.

encrypt.cck: path
    (OPTIONAL) Path to the customer communication key (CCK) file. If not supplied, a CCK will be generated from /dev/random and written to <out>/cck.key.

encrypt.extension-secret: path
    (OPTIONAL) Path to the extension secret file used for pvsecret create commands. If not supplied, an extension secret will be generated from /dev/random and written to <out>/extension.secret.
    REQUIRED if encrypt.add-secret-requests is used. In this case, the extension secret must match the one used in the supplied add/-secret requests.

encrypt.luks-key: path
    (OPTIONAL) Path to the LUKS encryption key file for the root filesystem. If not supplied, a key will be generated from /dev/random and written to <out>/rfs.key.

encrypt.luks-passphrase: path
    (OPTIONAL) Path to a file that contains the LUKS passphrase. If not supplied, a passphrase will be generated from /dev/random and written to <out>/passphrase.

encrypt.luks-key-asr-name: string
    (OPTIONAL) Name of the add-secret request that contains the LUKS encryption key. Default: rfs-luks-key.

encrypt.luks-key-size: integer
    (OPTIONAL) Key size in bits for the LUKS encryption key. Valid values: 256 or 512. If not specified, the size is determined from the supplied key file or a default size is used for generated keys.

encrypt.add-secret-requests: list
    (OPTIONAL) List of paths to additional add/-secret request files to be added during boot. Paths may contain wildcard patterns.
    When using this option:

    •   encrypt.extension-secret is REQUIRED

    •   The supplied extension secret must match the extension secret used in all supplied add/-secret requests
Example:
    add-secret-requests:
      - data/*.asr
      - /path/to/custom.asr

EXAMPLES

  Minimal Configuration for EBC
out: /path/to/output
hkds:
  - /path/to/*.hkd
certificate-chain:
  certs:
    - /path/to/*.cert
  crls:
    - /path/to/*.crl
  offline: true
  root-ca: /path/to/root.ca
convert:
  boot-loader-entry: "My Boot Entry"

  Configuration with Custom Encryption Keys
out: /path/to/output
hkds:
  - /path/to/*.hkd
certificate-chain:
  certs:
    - /path/to/*.cert
  crls:
    - /path/to/*.crl
  offline: true
  root-ca: /path/to/root.ca
convert:
  boot-loader-entry: "My Boot Entry"
  sel-kernel-parameter: swiotlb=524288
  pvimg-create-options: --enable-pckmo-hmac
encrypt:
  cck: /path/to/cck.key
  luks-key: /path/to/rfs.key
  luks-passphrase: /path/to/passphrase
  luks-key-size: 512

  Configuration with Additional ASRs
out: /path/to/output
hkds:
  - /path/to/*.hkd
certificate-chain:
  certs:
    - /path/to/*.cert
  crls:
    - /path/to/*.crl
  offline: true
  root-ca: /path/to/root.ca
convert:
  boot-loader-entry: "My Boot Entry"
encrypt:
  extension-secret: /path/to/extension.secret
  add-secret-requests:
    - /path/to/*.asr

  SEL Image Without EBC
no-ebc: true
out: /path/to/output
hkds:
  - /path/to/*.hkd
convert:
  boot-loader-entry: "My Boot Entry"

FILES

/boot/loader/entries/*.conf
    Boot loader entry files in the base image

/boot/sel-ebc.img
    The resulting SEL image file

/boot/sics/
    SEL Image customization source directory containing EBC resources

/boot/sics/toc.pol
    Table of contents policy file listing all add/-secret requests

/boot/sics/toc.asr
    Meta-secret for integrity protection of toc.pol

/var/log/sel-ebc-zipl.log
    Log file for zipl bootmap update operations

SEE ALSO
pvics(8), pvsecret(1), pvimg(1), zipl(8), cryptsetup(8)

Linux on IBM Z and IBM LinuxONE: Secure Execution for Linux documentation