mirror of
https://github.com/ibm-s390-linux/s390-tools.git
synced 2026-08-05 02:14:52 +00:00
c04a0919f6
Add pvebc tool for parsing and verifying EBC Add-Secret-Request structures Introduce pvebc, a CLI tool that parses and verifies the integrity of Add-Secret-Request (ASR) structures used in Early Boot Customization for SEL guests. The tool processes an integrity-protected ASR structure consisting of: - toc.asr: Meta secret that links to toc.pol via relative filepath and SHA512 hash, integrity-protected by its AES GCM authentication tag - toc.pol: Policy file containing AES GCM authentication tags (last 16 bytes) of all user-provided ASRs - User ASRs: Individual Add-Secret-Requests containing encrypted secrets This structure guarantees: - Prevents ASR removal: toc.pol lists all expected ASR authentication tags - Prevents ASR insertion: Unlisted ASRs are rejected - Prevents ASR modification: AES GCM authentication tags provide cryptographic integrity - Prevents toc.pol tampering: toc.asr's integrity protection secures the link The tool verifies completeness by checking that all ASRs listed in toc.pol are present and their AES GCM authentication tags match. This prevents attackers from removing, inserting, or modifying ASRs during transport over unsecured channels. After verification, pvebc adds all ASRs to the Ultravisor (UV), which decrypts them using the guest's secret key and makes them available to the guest during early boot. Assisted-by: IBM Bob:1.0.1 Acked-by: Holger Dengler <dengler@linux.ibm.com> Reviewed-by: Steffen Eiden <seiden@linux.ibm.com> Signed-off-by: Finn Callies <fcallies@linux.ibm.com> Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>
166 lines
5.1 KiB
Groff
166 lines
5.1 KiB
Groff
.\" 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 "PVEBC" "1" "2026-03-24" "s390-tools" "EBC Management Manual"
|
|
.nh
|
|
.ad l
|
|
.SH NAME
|
|
pvebc \- Protected Virtualization Early Boot Customization Tool
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.fam C
|
|
pvebc [OPTIONS] \-\-toc <FILE>
|
|
.fam C
|
|
.fi
|
|
.SH DESCRIPTION
|
|
Use the \fBpvebc\fR tool to process add-secret request files (\fBtoc.asr\fR)
|
|
that define the root of early boot customization (EBC) resources for
|
|
IBM Secure Execution for Linux (SEL) guests. The tool validates the
|
|
integrity and completeness of add-secret request (ASR) files using
|
|
cryptographic verification to prevent tampering during transmission
|
|
over unsecured channels.
|
|
|
|
The tool operates on a structure consisting of three types of files:
|
|
.RS 4
|
|
\- \fBtoc.asr\fP: The root add\-secret request file that references the table of contents (TOC policy).
|
|
|
|
\- \fBtoc.pol\fP: The table of contents policy file that contains a list of AES\-GCM authentication tags (MAC tags)
|
|
|
|
\- \fBASR files\fP: Individual add-secret request files to be added to the guest
|
|
|
|
.RE
|
|
The integrity protection mechanism works as follows:
|
|
.RS 4
|
|
.IP "1." 3
|
|
Each add-secret request file includes an AES\-GCM authentication tag (last 16 bytes), which provides integrity
|
|
protection for the file.
|
|
.IP "2." 3
|
|
The toc.pol file lists the expected message authentication code (MAC) tags of all add-secret request files.
|
|
.IP "3." 3
|
|
The toc.asr file contains a cryptographically protected reference to toc.pol, consisting
|
|
of the relative file path and a SHA\-512 hash of the policy file.
|
|
.IP "4." 3
|
|
The AES\-GCM authentication tag of toc.asr protects the integrity of this reference.
|
|
.RE
|
|
|
|
This structure prevents attackers from:
|
|
.RS 4
|
|
\- Removing add-secret request files from the set
|
|
|
|
\- Inserting unauthorized add-secret request files
|
|
|
|
\- Modifying existing add-secret request files
|
|
|
|
\- Altering the policy file
|
|
|
|
.RE
|
|
\fBpvebc\fR validates the entire chain of trust by:
|
|
.RS 4
|
|
\- Verifying that the SHA\-512 hash of toc.pol matches the reference stored in toc.asr
|
|
|
|
\- Checking that all MAC tags listed in toc.pol correspond to existing add-secret request files
|
|
|
|
\- Ensuring that all add-secret request files are present and unmodified
|
|
|
|
.RE
|
|
The tool can run in one of two modes:
|
|
.RS 4
|
|
\- \fBNormal mode\fP: Validates add\-secret requests and adds the defined secrets to the SEL guest (z/Architecture only)
|
|
|
|
\- \fBDry\-run mode\fP: Validates the request structure without adding secrets; useful for verification on non\-SEL systems
|
|
|
|
.RE
|
|
.SH OPTIONS
|
|
.PP
|
|
\-t, \-\-toc <FILE>
|
|
.RS 4
|
|
Specify the table\-of\-contents add\-secret request file toc.asr, which serves as the root of the EBC
|
|
resources. This file must contain a reference to toc.pol in its user data field,
|
|
as generated by \fBpvsecret\fR with the \fB\-\-policy\fR option. The toc.asr
|
|
file cryptographically links to the policy file by using a relative path and
|
|
SHA\-512 hash, ensuring the integrity of the complete EBC structure.
|
|
.RE
|
|
.RE
|
|
.PP
|
|
\-\-dry\-run
|
|
.RS 4
|
|
Validate the EBC structure without adding the add\-secret requests to the
|
|
ultravisor. Use this option to verify the integrity of the generated
|
|
policy file and the links between add\-secret request files and the policy.
|
|
This mode can be run on non\-SEL guests to validate the
|
|
structure before deployment. When \fB\-\-dry\-run\fR is specified, the tool
|
|
performs all cryptographic verifications but skips the actual addition of
|
|
secrets to the ultravisor secret store.
|
|
.RE
|
|
.RE
|
|
.PP
|
|
\-\-version
|
|
.RS 4
|
|
Print version information and exit.
|
|
.RE
|
|
.RE
|
|
.PP
|
|
\-h, \-\-help
|
|
.RS 4
|
|
Print help information.
|
|
.RE
|
|
.RE
|
|
|
|
.SH FILES
|
|
.PP
|
|
The \fBpvebc\fR tool operates on the following file types (actual names may
|
|
differ):
|
|
.PP
|
|
\fBtoc.asr\fR
|
|
.RS 4
|
|
The root add\-secret request file that contains a reference to the table\-of\-content \fBtoc.pol\fR in its
|
|
user data field. This file is generated by using \fBpvsecret create\fR with the
|
|
\fB\-\-policy\fR option.
|
|
.RE
|
|
.PP
|
|
\fBtoc.pol\fR
|
|
.RS 4
|
|
The policy file containing a newline\-separated list of AES\-GCM authentication
|
|
tags (MAC tags) in hexadecimal format. Each entry corresponds to one
|
|
add\-secret request file.
|
|
This file is generated by using \fBpvsecret create\fR with the
|
|
\fB\-\-toc\-policy\fR option.
|
|
.RE
|
|
.PP
|
|
\fB*.asr\fR
|
|
.RS 4
|
|
Individual add\-secret request files that contain the actual secrets to be added to
|
|
the SEL guest. Each add\-secret request file includes an AES\-GCM authentication tag (the last 16 bytes), which
|
|
provides integrity protection.
|
|
.RE
|
|
|
|
.SH EXIT STATUS
|
|
.PP
|
|
\fBpvebc\fR returns the following exit codes:
|
|
.PP
|
|
\fB0\fR
|
|
.RS 4
|
|
Success. All validations passed and secrets were added (if not in dry\-run mode).
|
|
.RE
|
|
.PP
|
|
\fB1\fR
|
|
.RS 4
|
|
Failure. An error occurred during validation or secret addition. Error details
|
|
are printed to stderr.
|
|
.RE
|
|
|
|
.SH NOTES
|
|
.PP
|
|
\- All file paths in a policy reference must be relative to the directory
|
|
that contains the referencing file.
|
|
.PP
|
|
\- On z/Architecture systems, the tool requires access to the ultravisor device
|
|
(\fB/dev/uv\fR) to add secrets.
|
|
.PP
|
|
|
|
.SH "SEE ALSO"
|
|
.sp
|
|
\fBpvsecret\fR(1), \fBpvsecret\-create\fR(1), \fBpvsecret\-add\fR(1)
|