pvebc - Man Page

pvebc [OPTIONS] --toc <FILE>

Use the pvebc tool to process add-secret request files (toc.asr) 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:

• toc.asr: The root add-secret request file that references the table of contents (TOC policy).
• toc.pol: The table of contents policy file that contains a list of AES-GCM authentication tags (MAC tags)
• ASR files: Individual add-secret request files to be added to the guest

The integrity protection mechanism works as follows:

1. Each add-secret request file includes an AES-GCM authentication tag (last 16 bytes), which provides integrity protection for the file.
2. The toc.pol file lists the expected message authentication code (MAC) tags of all add-secret request files.
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.
4. The AES-GCM authentication tag of toc.asr protects the integrity of this reference.

This structure prevents attackers from:

• Removing add-secret request files from the set
• Inserting unauthorized add-secret request files
• Modifying existing add-secret request files
• Altering the policy file

pvebc validates the entire chain of trust by:

• 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

The tool can run in one of two modes:

• Normal mode: Validates add-secret requests and adds the defined secrets to the SEL guest (z/Architecture only)
• Dry-run mode: Validates the request structure without adding secrets; useful for verification on non-SEL systems

-t,  --toc <FILE>

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 pvsecret with the --policy 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.

--dry-run

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 --dry-run is specified, the tool performs all cryptographic verifications but skips the actual addition of secrets to the ultravisor secret store.

--version

Print version information and exit.

-h,  --help

Print help information.

The pvebc tool operates on the following file types (actual names may differ):

toc.asr

The root add-secret request file that contains a reference to the table-of-content toc.pol in its user data field. This file is generated by using pvsecret create with the --policy option.

toc.pol

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 pvsecret create with the --toc-policy option.

*.asr

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.

pvebc returns the following exit codes:

0

Success. All validations passed and secrets were added (if not in dry-run mode).

1

Failure. An error occurred during validation or secret addition. Error details are printed to stderr.

- All file paths in a policy reference must be relative to the directory that contains the referencing file.

- On z/Architecture systems, the tool requires access to the ultravisor device (/dev/uv) to add secrets.

pvsecret(1), pvsecret-create(1), pvsecret-add(1)