mirror of
https://github.com/ibm-s390-linux/s390-tools.git
synced 2026-08-05 02:14:52 +00:00
ebc: Add new tool pvics
pvics (PV Image Customization Support) is a comprehensive tool for converting existing qcow2 KVM guest images to IBM Secure Execution for Linux (SEL) images with Early Boot Customization (EBC) support and encrypted root filesystems. The tool provides four main actions: - list: Retrieve information about boot loader entries in a base image - convert: Convert a base image to an EBC-ready SEL image - encrypt: Encrypt the root filesystem and prepare EBC resources - full: Perform both conversion and encryption in one operation Assisted-by: IBM Bob:1.0.1 Reviewed-by: Holger Dengler <dengler@linux.ibm.com> Reviewed-by: Jan Höppner <hoeppner@linux.ibm.com> Signed-off-by: Finn Callies <fcallies@linux.ibm.com> Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>
This commit is contained in:
Finn Callies
committed by
Jan Höppner
Jan Höppner
parent
3aa5c38714
commit
6a767408b3
@@ -52,6 +52,10 @@ Package contents
|
||||
Create an IBM Secure Execution (protected virtualization) image. The
|
||||
genprotimg command is a symbolic link to the `pvimg create` command.
|
||||
|
||||
* pvics:
|
||||
Convert a qcow2 image to a qcow2 image ready to boot as IBM Secure Execution
|
||||
for Linux guest.
|
||||
|
||||
* udev rules:
|
||||
- 59-dasd.rules: rules for unique DASD device nodes created in /dev/disk/.
|
||||
- 57-osasnmpd.rules: udev rules for osasnmpd.
|
||||
|
||||
@@ -1,9 +1,10 @@
|
||||
include ../common.mak
|
||||
|
||||
SCRIPTS = dbginfo.sh zfcpdbf zipl-switch-to-blscfg sclpdbf
|
||||
SCRIPTS = dbginfo.sh zfcpdbf zipl-switch-to-blscfg sclpdbf pvics
|
||||
# Helper scripts controlled by corresponding systemd services
|
||||
SD_HELPER_SCRIPTS = cpictl dumpconf
|
||||
MAN_PAGES = dbginfo.sh.8 zfcpdbf.8 zipl-switch-to-blscfg.8
|
||||
MAN_PAGES = dbginfo.sh.8 zfcpdbf.8 zipl-switch-to-blscfg.8 pvics.8
|
||||
FILE_MAN_PAGES = pvics.yaml.5
|
||||
|
||||
all:
|
||||
|
||||
@@ -33,6 +34,12 @@ install:
|
||||
$(DESTDIR)$(MANDIR)/man8; \
|
||||
done
|
||||
|
||||
@for i in $(FILE_MAN_PAGES); \
|
||||
do \
|
||||
$(INSTALL) -g $(GROUP) -o $(OWNER) -m 644 $$i \
|
||||
$(DESTDIR)$(MANDIR)/man5; \
|
||||
done
|
||||
|
||||
clean:
|
||||
|
||||
.zfcpdbf.ct: zfcpdbf
|
||||
|
||||
1579
scripts/pvics
Executable file
1579
scripts/pvics
Executable file
File diff suppressed because it is too large
Load Diff
340
scripts/pvics.8
Normal file
340
scripts/pvics.8
Normal file
@@ -0,0 +1,340 @@
|
||||
.\" Copyright IBM Corp.
|
||||
.\" s390-tools is free software; you can redistribute it and/or modify
|
||||
.\" it under the terms of the MIT license. See LICENSE for details.
|
||||
.\"
|
||||
.TH PVICS 8 "April 2026" "s390-tools"
|
||||
|
||||
.SH NAME
|
||||
pvics \- Convert qcow2 KVM guest images to EBC-ready SEL images
|
||||
|
||||
.SH SYNOPSIS
|
||||
.B pvics
|
||||
.I ACTION
|
||||
.RB [ \-h | \-\-help ]
|
||||
.RB [ \-c | \-\-config
|
||||
.IR CONFIG_FILE ]
|
||||
.RB [ \-i | \-\-image
|
||||
.IR BASE_IMAGE ]
|
||||
|
||||
.SH DESCRIPTION
|
||||
Use the \fBpvics\fR tool to convert existing QEMU Copy/-On/-Write version 2(qcow2) KVM
|
||||
guest images into images that are ready for Early Boot Customization (EBC) and Secure Execution for Linux (SEL).
|
||||
The tool encrypts the root file system and prepares all resources required for EBC.
|
||||
|
||||
The tool operates on a copy of the original base image and performs operations
|
||||
in three main phases:
|
||||
.IP \(bu 2
|
||||
Retrieving information about a given base image
|
||||
.IP \(bu 2
|
||||
Converting a base image according to a configuration
|
||||
.IP \(bu 2
|
||||
Encrypting the root file system and preparing EBC resources
|
||||
|
||||
All operations preserve the original base image. Logs are written to a
|
||||
temporary file, with the filename logged as the first message during runtime.
|
||||
Temporary artifacts are automatically cleaned up on completion or failure.
|
||||
|
||||
.SH ACTIONS
|
||||
.TP
|
||||
.B list
|
||||
Retrieve information about a given base image. This action displays available
|
||||
boot loader entries from \fB/boot/loader/entries\fR, along with kernel and
|
||||
initramfs hashes and the kernel command line. This is useful for:
|
||||
.RS
|
||||
.IP \(bu 2
|
||||
Determining valid values for the \fBboot-loader-entry\fR configuration option
|
||||
.IP \(bu 2
|
||||
Comparing components between base and converted images
|
||||
.IP \(bu 2
|
||||
Verifying image contents before conversion
|
||||
.RE
|
||||
|
||||
.TP
|
||||
.B convert
|
||||
Convert a base image according to the configuration file. This action:
|
||||
.RS
|
||||
.IP \(bu 2
|
||||
Fetches kernel, initramfs, and kernel command line from the specified boot
|
||||
loader entry
|
||||
.IP \(bu 2
|
||||
Builds a SEL image using \fBpvimg\fR(1)
|
||||
.IP \(bu 2
|
||||
Updates \fB/boot/bootmap\fR to boot into the SEL image
|
||||
.RE
|
||||
.IP
|
||||
The resulting image will be a SEL guest image. It requires encryption to be
|
||||
fully EBC-ready (unless \fBno-ebc\fR is enabled in the configuration).
|
||||
|
||||
.TP
|
||||
.B encrypt
|
||||
Encrypt the root file system and prepare EBC resources. This action:
|
||||
.RS
|
||||
.IP \(bu 2
|
||||
Generates secure defaults (CCK, extension secret, LUKS keys) if not provided
|
||||
.IP \(bu 2
|
||||
Encrypts the root file system using LUKS with PAES
|
||||
.IP \(bu 2
|
||||
Populates \fB/boot/sics/\fR with add/-secret requests
|
||||
.IP \(bu 2
|
||||
Creates \fBtoc.pol\fR and \fBtoc.asr\fR for integrity protection
|
||||
.RE
|
||||
.IP
|
||||
This action requires EBC. The guest can boot only by using PAES to open the root file system.
|
||||
|
||||
.TP
|
||||
.B full
|
||||
Perform both \fBconvert\fR and \fBencrypt\fR actions in sequence. This is
|
||||
equivalent to running \fBconvert\fR followed by \fBencrypt\fR, but in a single
|
||||
invocation.
|
||||
|
||||
.SH ARGUMENTS
|
||||
.TP
|
||||
.I ACTION
|
||||
The action to perform: \fBlist\fR, \fBconvert\fR, \fBencrypt\fR, or \fBfull\fR.
|
||||
|
||||
.SH OPTIONS
|
||||
.TP
|
||||
.BR \-h ", " \-\-help
|
||||
Display help message and exit.
|
||||
|
||||
.TP
|
||||
.BR \-c ", " \-\-config " " \fICONFIG_FILE\fR
|
||||
Path to the YAML configuration file. See \fBpvics.yaml\fR(5) for the
|
||||
configuration file format and options.
|
||||
.br
|
||||
Required for \fBconvert\fR, \fBencrypt\fR, and \fBfull\fR actions.
|
||||
.br
|
||||
Not required for the \fBlist\fR action.
|
||||
|
||||
.TP
|
||||
.BR \-i ", " \-\-image " " \fIBASE_IMAGE\fR
|
||||
Path to the base qcow2 image file to process. Required for all actions.
|
||||
|
||||
.SH CONVERSION PROCESS
|
||||
The conversion process consists of three phases:
|
||||
|
||||
.SS Component Fetching
|
||||
The tool retrieves the kernel, initramfs, and kernel command line from the
|
||||
boot loader entry specified in the configuration file. The components are
|
||||
validated to ensure they meet SEL EBC requirements.
|
||||
|
||||
The tool prepends \fBrd.sel-ebc\fR to the kernel command line to trigger the
|
||||
SEL EBC dracut module (unless \fBno-ebc\fR is enabled) and appends any
|
||||
user-provided kernel parameters from the configuration.
|
||||
|
||||
.SS SEL Image Build
|
||||
The SEL image is built using \fBpvimg\fR(1) with the fetched components.
|
||||
Additional options may be specified in the configuration file via
|
||||
\fB.convert.pvimg-create-options\fR.
|
||||
|
||||
.SS Bootmap Update
|
||||
The tool updates the bootmap to boot into the new SEL image:
|
||||
.IP \(bu 2
|
||||
Existing boot loader entries in \fB/boot/loader/entries/*.conf\fR are renamed
|
||||
to \fB*.conf.old\fR
|
||||
.IP \(bu 2
|
||||
A new entry \fBsel-ebc.conf\fR is created that points to \fB/boot/sel-ebc.img\fR
|
||||
.IP \(bu 2
|
||||
\fBzipl\fR(8) is run to update the bootmap.
|
||||
|
||||
The guest is temporarily started to update the bootmap using libvirt on z/Architecture
|
||||
or qemu on non-z/Architecture architectures. Failures are logged to
|
||||
\fB/var/log/sel-ebc-zipl.log\fR.
|
||||
|
||||
.SH ENCRYPTION PROCESS
|
||||
The encryption process consists of three phases:
|
||||
|
||||
.SS Secure Default Generation
|
||||
If not provided in the configuration, the following are generated from
|
||||
\fB/dev/random\fR:
|
||||
.IP \(bu 2
|
||||
Customer communication key (CCK)
|
||||
.IP \(bu 2
|
||||
Root file system LUKS encryption key
|
||||
.IP \(bu 2
|
||||
Extension secret for add/-secret requests
|
||||
.IP \(bu 2
|
||||
LUKS passphrase
|
||||
|
||||
.SS Root File System Encryption
|
||||
The root file system is encrypted using the following steps:
|
||||
.IP 1. 3
|
||||
Resize the qcow2 image to accommodate the LUKS header
|
||||
.IP 2. 3
|
||||
Resize the root partition (but not the file system) to fit the LUKS header
|
||||
.IP 3. 3
|
||||
Encrypt the root file system using LUKS
|
||||
.IP 4. 3
|
||||
Reformat the LUKS header from AES to PAES (Protected AES)
|
||||
|
||||
.SS AES to PAES Conversion
|
||||
The LUKS header is converted from standard AES encryption to protected AES (PAES).
|
||||
With PAES, encryption secrets are stored in the ultravisor secret store rather than directly in the LUKS header.
|
||||
|
||||
.SS SICS Population
|
||||
The SEL Image Customization Source directory (\fB/boot/sics\fR) is populated
|
||||
with the following secrets as add/-secret requests:
|
||||
.IP \(bu 2
|
||||
Customer communication key (CCK)
|
||||
.IP \(bu 2
|
||||
LUKS encryption key
|
||||
.IP \(bu 2
|
||||
LUKS passphrase
|
||||
.IP \(bu 2
|
||||
Any additional add/-secret requests specified in the configuration
|
||||
|
||||
All automatically built add/-secret requests are added to \fBtoc.pol\fR, which verifies the
|
||||
completeness of \fB/boot/sics\fR. User-supplied add/-secret requests from the configuration
|
||||
are also added. Finally, \fBtoc.asr\fR is built as a meta secret that links
|
||||
to \fBtoc.pol\fR for integrity protection.
|
||||
|
||||
.SH BUILDING SEL IMAGES WITHOUT EBC
|
||||
While the primary purpose of \fBpvics\fR is to create EBC-ready SEL images with
|
||||
encrypted root file systems, it can also build SEL images without EBC
|
||||
functionality using the \fBno-ebc\fR configuration option.
|
||||
|
||||
When \fBno-ebc: true\fR is set in the configuration:
|
||||
.IP \(bu 2
|
||||
The \fBconvert\fR action builds a SEL image without EBC-specific flags
|
||||
.IP \(bu 2
|
||||
The \fBencrypt\fR action is completely skipped
|
||||
.IP \(bu 2
|
||||
The \fBfull\fR action becomes equivalent to \fBconvert\fR only
|
||||
.IP \(bu 2
|
||||
The \fBrd.sel-ebc\fR kernel parameter is not added
|
||||
.IP \(bu 2
|
||||
\fB--enable-cck-update\fR and \fB--disable-image-encryption\fR flags are not
|
||||
passed to \fBpvimg\fR
|
||||
|
||||
This mode is useful for:
|
||||
.IP \(bu 2
|
||||
Single-party image creation where the same entity performs conversion,
|
||||
customization, and encryption
|
||||
.IP \(bu 2
|
||||
Testing SEL guest functionality without EBC complexity
|
||||
.IP \(bu 2
|
||||
Development and debugging scenarios
|
||||
.IP \(bu 2
|
||||
Simplified SEL image generation workflows
|
||||
|
||||
.SH OUTPUT FILES
|
||||
All output files are written to the directory specified by the \fBout\fR
|
||||
configuration option:
|
||||
|
||||
.TP
|
||||
\fB<out>/image.qcow2\fR
|
||||
The converted SEL image (after \fBconvert\fR or \fBfull\fR action)
|
||||
|
||||
.TP
|
||||
\fB<out>/cck.key\fR
|
||||
Customer communication key (generated if not provided)
|
||||
|
||||
.TP
|
||||
\fB<out>/extension.secret\fR
|
||||
Extension secret for add/-secret requests (generated if not provided)
|
||||
|
||||
.TP
|
||||
\fB<out>/rfs.key\fR
|
||||
Root file system LUKS encryption key (generated if not provided)
|
||||
|
||||
.TP
|
||||
\fB<out>/passphrase\fR
|
||||
LUKS passphrase (generated if not provided)
|
||||
|
||||
.TP
|
||||
\fB<out>/*.asr\fR
|
||||
Generated add-secret request files
|
||||
|
||||
.SH TEMPORARY FILES
|
||||
.TP
|
||||
\fB/tmp/tmp.*\fR
|
||||
Log file (filename logged at startup)
|
||||
|
||||
.SH EXIT STATUS
|
||||
.TP
|
||||
.B 0
|
||||
Success
|
||||
.TP
|
||||
.B 1
|
||||
General error (invalid arguments, missing files, operation failure)
|
||||
|
||||
.SH EXAMPLES
|
||||
.SS List Boot Loader Entries
|
||||
.nf
|
||||
pvics list \-\-image /path/to/base-image.qcow2
|
||||
.fi
|
||||
|
||||
.SS Convert Image Only
|
||||
.nf
|
||||
pvics convert \-\-config /path/to/config.yaml \-\-image /path/to/base-image.qcow2
|
||||
.fi
|
||||
|
||||
.SS Encrypt Image Only
|
||||
.nf
|
||||
pvics encrypt \-\-config /path/to/config.yaml \-\-image /path/to/converted-image.qcow2
|
||||
.fi
|
||||
|
||||
.SS Full Conversion and Encryption
|
||||
.nf
|
||||
pvics full \-\-config /path/to/config.yaml \-\-image /path/to/base-image.qcow2
|
||||
.fi
|
||||
|
||||
.SS Build SEL Image Without EBC
|
||||
.nf
|
||||
# config.yaml contains: no-ebc: true
|
||||
pvics convert \-\-config /path/to/config.yaml \-\-image /path/to/base-image.qcow2
|
||||
.fi
|
||||
|
||||
.SH FILES
|
||||
.TP
|
||||
\fB/boot/loader/entries/*.conf\fR
|
||||
Boot loader entry files in the base image
|
||||
|
||||
.TP
|
||||
\fB/boot/sel-ebc.img\fR
|
||||
The resulting SEL image file in the guest
|
||||
|
||||
.TP
|
||||
\fB/boot/sics/\fR
|
||||
SEL image-customization source directory that contains EBC resources
|
||||
|
||||
.TP
|
||||
\fB/boot/sics/toc.pol\fR
|
||||
Table-of-contents policy file that lists all add/-secret requests
|
||||
|
||||
.TP
|
||||
\fB/boot/sics/toc.asr\fR
|
||||
Meta secret for integrity protection of toc.pol
|
||||
|
||||
.TP
|
||||
\fB/var/log/sel-ebc-zipl.log\fR
|
||||
Log file for zipl bootmap update operations
|
||||
|
||||
.SH NOTES
|
||||
.IP \(bu 2
|
||||
All operations are performed on a copy of the original base image.
|
||||
.IP \(bu 2
|
||||
The tool requires root privileges for file-system operations.
|
||||
.IP \(bu 2
|
||||
The LUKS device is named \fBcryptroot\fR.
|
||||
.IP \(bu 2
|
||||
The temporary working directory is created at \fB/opt/sel-<UUID>\fR.
|
||||
.IP \(bu 2
|
||||
The \fBno-verify\fR option should not be used in production environments.
|
||||
.IP \(bu 2
|
||||
Generated secrets are written to the output directory and should be secured
|
||||
appropriately.
|
||||
|
||||
.SH SEE ALSO
|
||||
.BR pvics.yaml (5),
|
||||
.BR pvsecret (1),
|
||||
.BR pvimg (1),
|
||||
.BR pvebc (8),
|
||||
.BR zipl (8),
|
||||
.BR cryptsetup (8),
|
||||
.BR lsinitrd (1)
|
||||
.PP
|
||||
Linux on IBM Z and IBM LinuxONE: Secure Execution for Linux documentation
|
||||
|
||||
.SH AUTHOR
|
||||
IBM Corporation
|
||||
106
scripts/pvics.yaml
Normal file
106
scripts/pvics.yaml
Normal file
@@ -0,0 +1,106 @@
|
||||
# SPDX-License-Identifier: MIT
|
||||
#
|
||||
# Copyright IBM Corp.
|
||||
|
||||
|
||||
# OPTIONAL (default: false)
|
||||
no-verify: false
|
||||
# This option controls whether the --no-verify flag is used with the pv commands.
|
||||
|
||||
# OPTIONAL (default: false)
|
||||
no-ebc: false
|
||||
# This option controls whether to trigger the SEL EBC related systemd units.
|
||||
# It can be used to create a SEL guest image from an existing qcow2 image without utilizing SEL EBC.
|
||||
# Setting this to true will prevent the encrypt action from running.
|
||||
# In this case, the full action equals the convert action.
|
||||
# Setting this to true will prevent the default pvimg options (see below) from being added and instead
|
||||
# only add the user provided ones in .convert.pvimg-options.
|
||||
|
||||
# REQUIRED
|
||||
out: data/output
|
||||
# This specifies the local directory used for output.
|
||||
|
||||
# REQUIRED
|
||||
hkds:
|
||||
- data/*.hkd
|
||||
# These are the paths to all relevant Host-Key-Documents.
|
||||
# The paths may contain wildcard patterns.
|
||||
|
||||
# REQUIRED if .no-verify is false
|
||||
# UNUSED if .no-verify is true
|
||||
# This section contains all relevant files for verification of the certificate chain.
|
||||
# See man pvsecret for more detailed information about any of the keys in this section.
|
||||
certificate-chain:
|
||||
# The paths may contain wildcard patterns.
|
||||
certs:
|
||||
- data/*.cert
|
||||
|
||||
# The paths may contain wildcard patterns.
|
||||
crls:
|
||||
- data/*.crl
|
||||
|
||||
# This is the pvsecret create offline option.
|
||||
offline: true
|
||||
|
||||
# This is the root CA of the given certificates.
|
||||
root-ca: data/root.ca
|
||||
|
||||
# This section contains relevant information for the first phase: conversion.
|
||||
convert:
|
||||
# REQUIRED
|
||||
boot-loader-entry: boot_loader_entry_title
|
||||
# This is the boot loader entry name to be used for kernel, initramfs and kernel parameter.
|
||||
# You can list available boot loader entries with the list action.
|
||||
|
||||
# OPTIONAL
|
||||
sel-kernel-parameter: swiotlb=524288
|
||||
# These are additional kernel parameters for the resulting SEL image.
|
||||
# The parameter rd.sel-ebc will always be added.
|
||||
|
||||
# OPTIONAL (default: --enable-pckmo-hmac)
|
||||
pvimg-create-options: --enable-pckmo-hmac
|
||||
# These are additional pvimg options for the resulting SEL image.
|
||||
# The options --disable-image-encryption and --enable-update-cck are always used except when .no-ebc is true.
|
||||
|
||||
# This section contains relevant information for the second phase: encryption.
|
||||
encrypt:
|
||||
# OPTIONAL
|
||||
cck: data/cck.key
|
||||
# This is the local path to the CCK.
|
||||
# If none is supplied, one will be generated and written to .out/cck.key.
|
||||
|
||||
# OPTIONAL
|
||||
extension-secret: data/extension.secret
|
||||
# This is the local path to the extension secret for pvsecret create.
|
||||
# This is REQUIRED if .encrypt.add-secret-requests is used.
|
||||
# In this case, the extension secret must be the one from the supplied ASRs.
|
||||
# If none is supplied, one will be generated and written to .out/extension.secret.
|
||||
|
||||
# OPTIONAL
|
||||
luks-key: data/rfs.key
|
||||
# This is the local path to the LUKS encryption key.
|
||||
# If none is supplied, one will be generated and written to .out/rfs.key.
|
||||
|
||||
# OPTIONAL
|
||||
luks-passphrase: data/passphrase
|
||||
# This is the local path to a file containing the LUKS passphrase.
|
||||
# If none is supplied, one will be generated and written to .out/passphrase.
|
||||
|
||||
# OPTIONAL (default: rfs-luks-key)
|
||||
luks-key-asr-name: aes-xts-segment-key
|
||||
# This is the name of the ASR containing the LUKS encryption key.
|
||||
|
||||
# OPTIONAL (default: depending on .encrypt.luks-key)
|
||||
luks-key-size: 512
|
||||
# This is the key size of the LUKS encryption key (256 or 512).
|
||||
# If .encrypt.luks-key is supplied, this will default to a size depending on the key.
|
||||
# Otherwise, this will default to 512 and generate a matching key.
|
||||
# If this is supplied but no key is supplied, a key of the requested size will be generated.
|
||||
|
||||
# OPTIONAL
|
||||
add-secret-requests:
|
||||
- data/*.asr
|
||||
# These are additional secrets to be added during boot.
|
||||
# Using this will make .encrypt.extension-secret a required argument.
|
||||
# The supplied extension secret and the extension secret of supplied ASRs must be the same.
|
||||
# The paths may contain wildcard patterns.
|
||||
321
scripts/pvics.yaml.5
Normal file
321
scripts/pvics.yaml.5
Normal file
@@ -0,0 +1,321 @@
|
||||
.\" Copyright IBM Corp.
|
||||
.\" s390-tools is free software; you can redistribute it and/or modify
|
||||
.\" it under the terms of the MIT license. See LICENSE for details.
|
||||
.\"
|
||||
.TH PVICS.YAML 5 "April 2026" "s390-tools"
|
||||
|
||||
.SH NAME
|
||||
pvics.yaml \- Configuration file for pvics SEL EBC image conversion tool
|
||||
|
||||
.SH DESCRIPTION
|
||||
The \fBpvics.yaml\fR file is a YAML-formatted configuration file used by the
|
||||
\fBpvics\fR 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 \fBpvics\fR(8) for detailed information about the tool's actions and the
|
||||
conversion process.
|
||||
|
||||
.SH FILE FORMAT
|
||||
The configuration file uses YAML syntax with the following top-level sections:
|
||||
.TP
|
||||
\fBGlobal Options\fR
|
||||
General settings that apply to all actions
|
||||
.TP
|
||||
\fBCertificate Chain\fR
|
||||
Certificate verification configuration
|
||||
.TP
|
||||
\fBConversion Options\fR
|
||||
Settings specific to the \fBconvert\fR action
|
||||
.TP
|
||||
\fBEncryption Options\fR
|
||||
Settings specific to the \fBencrypt\fR action
|
||||
|
||||
.SH GLOBAL OPTIONS
|
||||
.TP
|
||||
\fBno-verify:\fR \fIboolean\fR
|
||||
Disables certificate chain verification for pv commands when set to true.
|
||||
Default: \fBfalse\fR.
|
||||
.br
|
||||
\fBWARNING:\fR Do not disable certificate chain verification in production environments.
|
||||
|
||||
.TP
|
||||
\fBno-ebc:\fR \fIboolean\fR
|
||||
Controls whether EBC functionality is used. When set to
|
||||
\fBtrue\fR, a SEL guest image is created without using EBC.
|
||||
Default: \fBfalse\fR.
|
||||
.br
|
||||
When enabled:
|
||||
.RS
|
||||
.IP \(bu 2
|
||||
The \fBencrypt\fR action is skipped
|
||||
.IP \(bu 2
|
||||
The \fBfull\fR action behaves the same as the \fBconvert\fR action
|
||||
.IP \(bu 2
|
||||
Default \fBpvimg\fR options are not added; only user-provided options specified in
|
||||
\fB.convert.pvimg-create-options\fR are used
|
||||
.IP \(bu 2
|
||||
The \fBrd.sel-ebc\fR kernel parameter is not added
|
||||
.RE
|
||||
|
||||
.TP
|
||||
\fBout:\fR \fIpath\fR
|
||||
\fB(REQUIRED)\fR Local directory path used for output files. All generated
|
||||
files (converted images, keys, ASRs) will be written to this directory.
|
||||
|
||||
.TP
|
||||
\fBhkds:\fR \fIlist\fR
|
||||
\fB(REQUIRED)\fR List of paths to host-key-documents (HKDs). Paths may contain
|
||||
wildcard patterns, for example \fBdata/*.hkd\fR.
|
||||
.br
|
||||
Example:
|
||||
.RS
|
||||
.nf
|
||||
hkds:
|
||||
- data/*.hkd
|
||||
- /path/to/specific.hkd
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.SH CERTIFICATE CHAIN
|
||||
The \fBcertificate-chain\fR section contains all relevant files for verification
|
||||
of the certificate chain. This section is \fBREQUIRED\fR if \fBno-verify\fR is
|
||||
\fBfalse\fR, and \fBUNUSED\fR if \fBno-verify\fR is \fBtrue\fR.
|
||||
|
||||
See \fBpvsecret\fR(1) for more detailed information about certificate chain
|
||||
verification.
|
||||
|
||||
.TP
|
||||
\fBcertificate-chain.certs:\fR \fIlist\fR
|
||||
List of paths to certificate files. Paths may contain wildcard patterns.
|
||||
.br
|
||||
Example:
|
||||
.RS
|
||||
.nf
|
||||
certs:
|
||||
- data/*.cert
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.TP
|
||||
\fBcertificate-chain.crls:\fR \fIlist\fR
|
||||
List of paths to certificate revocation list (CRL) files. Paths may contain
|
||||
wildcard patterns.
|
||||
.br
|
||||
Example:
|
||||
.RS
|
||||
.nf
|
||||
crls:
|
||||
- data/*.crl
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.TP
|
||||
\fBcertificate-chain.offline:\fR \fIboolean\fR
|
||||
Enables offline mode for the \fBpvsecret create\fR command. When \fBtrue\fR, no
|
||||
network access is attempted for certificate verification.
|
||||
|
||||
.TP
|
||||
\fBcertificate-chain.root-ca:\fR \fIpath\fR
|
||||
Path to the root Certificate Authority (CA) file for the certificate chain.
|
||||
|
||||
.SH CONVERSION OPTIONS
|
||||
The \fBconvert\fR section contains configuration options for the image
|
||||
conversion phase. These options are used only when running the \fBconvert\fR or
|
||||
\fBfull\fR actions and have no effect on other actions.
|
||||
|
||||
.TP
|
||||
\fBconvert.boot-loader-entry:\fR \fIstring\fR
|
||||
\fB(REQUIRED)\fR 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.
|
||||
.br
|
||||
Use the \fBlist\fR action to display available boot loader entries in the
|
||||
base image.
|
||||
|
||||
.TP
|
||||
\fBconvert.sel-kernel-parameter:\fR \fIstring\fR
|
||||
\fB(OPTIONAL)\fR Additional kernel parameters to append to the kernel command
|
||||
line of the resulting SEL image. The \fBrd.sel-ebc\fR parameter is always
|
||||
prepended automatically (unless \fBno-ebc\fR is \fBtrue\fR).
|
||||
.br
|
||||
Example:
|
||||
.RS
|
||||
.nf
|
||||
sel-kernel-parameter: swiotlb=524288
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.TP
|
||||
\fBconvert.pvimg-create-options:\fR \fIstring\fR
|
||||
\fB(OPTIONAL)\fR Additional options to pass to the \fBpvimg\fR command during
|
||||
SEL image creation.
|
||||
.br
|
||||
See \fBpvimg\fR(1) for available options.
|
||||
|
||||
.SH ENCRYPTION OPTIONS
|
||||
The \fBencrypt\fR section contains configuration options specific to the root filesystem
|
||||
encryption and EBC resource preparation phase. These options are only used when running
|
||||
the \fBencrypt\fR or \fBfull\fR actions and are ignored when \fBno-ebc\fR
|
||||
is \fBtrue\fR.
|
||||
|
||||
.TP
|
||||
\fBencrypt.cck:\fR \fIpath\fR
|
||||
\fB(OPTIONAL)\fR Path to the customer communication key (CCK) file. If not
|
||||
supplied, a CCK will be generated from \fB/dev/random\fR and written to
|
||||
\fB<out>/cck.key\fR.
|
||||
|
||||
.TP
|
||||
\fBencrypt.extension-secret:\fR \fIpath\fR
|
||||
\fB(OPTIONAL)\fR Path to the extension secret file used for \fBpvsecret create\fR
|
||||
commands. If not supplied, an extension secret will be generated from
|
||||
\fB/dev/random\fR and written to \fB<out>/extension.secret\fR.
|
||||
.br
|
||||
\fBREQUIRED\fR if \fBencrypt.add-secret-requests\fR is used. In this case, the
|
||||
extension secret must match the one used in the supplied add/-secret requests.
|
||||
|
||||
.TP
|
||||
\fBencrypt.luks-key:\fR \fIpath\fR
|
||||
\fB(OPTIONAL)\fR Path to the LUKS encryption key file for the root filesystem.
|
||||
If not supplied, a key will be generated from \fB/dev/random\fR and written to
|
||||
\fB<out>/rfs.key\fR.
|
||||
|
||||
.TP
|
||||
\fBencrypt.luks-passphrase:\fR \fIpath\fR
|
||||
\fB(OPTIONAL)\fR Path to a file that contains the LUKS passphrase. If not supplied,
|
||||
a passphrase will be generated from \fB/dev/random\fR and written to
|
||||
\fB<out>/passphrase\fR.
|
||||
|
||||
.TP
|
||||
\fBencrypt.luks-key-asr-name:\fR \fIstring\fR
|
||||
\fB(OPTIONAL)\fR Name of the add-secret request that contains the LUKS
|
||||
encryption key. Default: \fBrfs-luks-key\fR.
|
||||
|
||||
.TP
|
||||
\fBencrypt.luks-key-size:\fR \fIinteger\fR
|
||||
\fB(OPTIONAL)\fR Key size in bits for the LUKS encryption key. Valid values:
|
||||
\fB256\fR or \fB512\fR. If not specified, the size is determined from the
|
||||
supplied key file or a default size is used for generated keys.
|
||||
|
||||
.TP
|
||||
\fBencrypt.add-secret-requests:\fR \fIlist\fR
|
||||
\fB(OPTIONAL)\fR List of paths to additional add/-secret request files to
|
||||
be added during boot. Paths may contain wildcard patterns.
|
||||
.br
|
||||
When using this option:
|
||||
.RS
|
||||
.IP \(bu 2
|
||||
\fBencrypt.extension-secret\fR is \fBREQUIRED\fR
|
||||
.IP \(bu 2
|
||||
The supplied extension secret must match the extension secret used in all
|
||||
supplied add/-secret requests
|
||||
.RE
|
||||
.br
|
||||
Example:
|
||||
.RS
|
||||
.nf
|
||||
add-secret-requests:
|
||||
- data/*.asr
|
||||
- /path/to/custom.asr
|
||||
.fi
|
||||
.RE
|
||||
|
||||
.SH EXAMPLES
|
||||
.SS Minimal Configuration for EBC
|
||||
.nf
|
||||
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"
|
||||
.fi
|
||||
|
||||
.SS Configuration with Custom Encryption Keys
|
||||
.nf
|
||||
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
|
||||
.fi
|
||||
|
||||
.SS Configuration with Additional ASRs
|
||||
.nf
|
||||
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
|
||||
.fi
|
||||
|
||||
.SS SEL Image Without EBC
|
||||
.nf
|
||||
no-ebc: true
|
||||
out: /path/to/output
|
||||
hkds:
|
||||
- /path/to/*.hkd
|
||||
convert:
|
||||
boot-loader-entry: "My Boot Entry"
|
||||
.fi
|
||||
|
||||
.SH FILES
|
||||
.TP
|
||||
\fB/boot/loader/entries/*.conf\fR
|
||||
Boot loader entry files in the base image
|
||||
.TP
|
||||
\fB/boot/sel-ebc.img\fR
|
||||
The resulting SEL image file
|
||||
.TP
|
||||
\fB/boot/sics/\fR
|
||||
SEL Image customization source directory containing EBC resources
|
||||
.TP
|
||||
\fB/boot/sics/toc.pol\fR
|
||||
Table of contents policy file listing all add/-secret requests
|
||||
.TP
|
||||
\fB/boot/sics/toc.asr\fR
|
||||
Meta-secret for integrity protection of toc.pol
|
||||
.TP
|
||||
\fB/var/log/sel-ebc-zipl.log\fR
|
||||
Log file for zipl bootmap update operations
|
||||
|
||||
.SH SEE ALSO
|
||||
.BR pvics (8),
|
||||
.BR pvsecret (1),
|
||||
.BR pvimg (1),
|
||||
.BR zipl (8),
|
||||
.BR cryptsetup (8)
|
||||
.PP
|
||||
Linux on IBM Z and IBM LinuxONE: Secure Execution for Linux documentation
|
||||
Reference in New Issue
Block a user