PVEBC(1)

💖 PVEBC(1) 💖

okay bestie, welcome to the EBC Management Manual — this is the page for pvebc, and yes it's a mouthful, it's the Protected Virtualization Early Boot Customization Tool. say that five times fast, I dare you. 🫶

---

✨ NAME ✨

pvebc — Protected Virtualization Early Boot Customization Tool. she does early boot customization and she does it securely. periodt. 💅

---

🌸 SYNOPSIS 🌸

pvebc [OPTIONS] --toc <FILE>

---

🦋 DESCRIPTION 🦋

So pvebc is the tool you use to process add-secret request files (that's toc.asr, keep up bestie) that define the root of early boot customization (EBC) resources for IBM Secure Execution for Linux (SEL) guests. Basically it validates the integrity and completeness of add-secret request (ASR) files using cryptographic verification, so nobody can tamper with them while they're flying across unsecured channels. it's giving trust issues, but make it cryptography. 😭

🎀 the three files it vibes with

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). main character energy tbh.
• 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.

🔐 how the integrity protection mechanism works (aka the chain of trust glow-up)

1. Each add-secret request file includes an AES-GCM authentication tag (the 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.

💀 what this structure stops attackers from doing

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

not them getting blocked on all four counts 💀🚫

👑 how pvebc validates the entire chain of trust

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 two modes (choose your fighter)

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; super useful for verification on non-SEL systems.

---

💅 OPTIONS 💅

• -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 a SHA-512 hash, ensuring the integrity of the complete EBC structure. no pressure or anything. 🎀
• --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. it's giving "look with your eyes, not your hands" 🙈
• --version — Print version information and exit. short king behavior. 👑
• -h, --help — Print help information.

---

🍓 FILES 🍓

The pvebc tool operates on the following file types (heads up, 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.

---

⭐ EXIT STATUS ⭐

pvebc returns the following exit codes:

• 0 — Success. All validations passed and secrets were added (if not in dry-run mode). we love a clean exit. 🎉
• 1 — Failure. An error occurred during validation or secret addition. Error details are printed to stderr. not the vibe. 😭

---

🧚 NOTES 🧚

• All file paths in a policy reference must be relative to the directory that contains the referencing file. no absolute-path shenanigans, bestie. 🙅
• On z/Architecture systems, the tool requires access to the ultravisor device (/dev/uv) to add secrets.

ok quick content warning: if you're on z/Architecture and you can't touch /dev/uv, the secret-adding part literally cannot happen. dry-run still vibes though. 💜

---

🫶 SEE ALSO 🫶

• pvsecret(1)
• pvsecret-create(1)
• pvsecret-add(1)

these are the besties. go read them next. iykyk. ✨

---

mwah, that's the whole page. shipped as part of s390-tools, dated 2026-03-24 — stay validated, stay unmodified, and never let anyone tamper with your chain of trust. 🦋💖