PVSECRET-CREATE-RETRIEVABLE(1)

💅 pvsecret-create-retrievable(1) — the UV-Secret Manual, bestie edition ✨

okay so this is a page from the UV-Secret Manual (UV-Secret Manual — yes it's giving main character energy) and it's literally all about making a retrievable secret. buckle up 🎀

---

✨ NAME ✨

pvsecret-create-retrievable — create a retrievable secret 💖 (that's it, that's the vibe)

---

🦋 SYNOPSIS 🦋

pvsecret create retrievable [OPTIONS] --secret <SECRET-FILE> --type <TYPE> <NAME>
pvsecret create retr [OPTIONS] --secret <SECRET-FILE> --type <TYPE> <NAME>

two ways to spell it, one iconic command. the retr one is the ✨short king✨ version, iykyk.

---

🌸 DESCRIPTION 🌸

so bestie, a retrievable secret lives in the per-guest storage of the Ultravisor. an SE-guest can pull the secret out at runtime and actually use it — slay 🔥.

here's the tea though: every single retrievable secret except the plaintext one comes back as a wrapped/protected key object, and it's only usable inside the current, running SE-guest instance. so like, it's very much "you had to be there" energy 🫶.

the input file can hold up to 8190 bytes for the plaintext secret, no cap.

for the symmetric keys (AES, AES-XTS, HMAC) the file must contain a byte pattern for the key, and the key-size has to equal the file size. periodt.

for the EC private keys the file must be either in PEM or DER format and contain an EC PRIVATE KEY with one of these curves:

• secp256r1
• secp384r1
• secp521r1
• ed25519
• ed448

🧚 HMAC-SHA preprocessing 🧚

lowkey the most important part of this whole page. read it twice, bestie.

the HMAC-SHA key you drop in that plain bytes file is the key K_0 as of FIPS-198-1 — meaning it's the key K after any necessary pre-processing. and the pre-processing? yeah, that's on you, the user, to do before creating the retrievable secret. no shortcuts 🙈.

what pre-processing even means:

if the key K is shorter than the block size of the to-be-used HMAC digest, then the key must be padded with binary zeros to the right up to the block size. the block size of SHA-224 and SHA-256 is 512 bits (64 bytes), and the bock size of SHA-384 and SHA-512 is 1024 bits (128 bytes). (yes, the page says "bock size" — we're keeping it, it's iconic in its own way 😭)

such padding can for example be achieved by using the truncate command with the desired size in bytes, like:

truncate --size 64 <key-file>

for creating a K_0 key for HMAC-SHA-224 and HMAC-SHA-256.

and if the key is LONGER than the block size:

then key K must first be hashed with the to-be-used HMAC digest, and that result must then be padded with binary zeros to the right up to the block size of the digest. you do it with the following OpenSSL command followed by the truncate command:

openssl sha256 -binary -out <key2-file> <key-file>

and then:

truncate --size 64 <key2-file>

for creating a K_0 key for HMAC-SHA-256. yes bestie, we ate 💅.

ATTENTION: the digest used for hashing the key K must be the exact same as the later to-be-used HMAC digest! if the pre-processing and the HMAC calculation use different digests, then a wrong MAC is calculated! 💀 that's not a vibe. that's the opposite of a vibe.

---

🎀 OPTIONS 🎀

• <NAME> — a string that identifies the new secret.

the actual secret is set with --secret. the name gets saved in NAME.yaml with white-spaces mapped to _ (so like, spaces are not the moment, underscores are ✨).

• --stdout — print the hashed name to stdout.

the hashed name is not written to NAME.yaml in this case. so it's giving "look but don't keep" 🦋.

• --secret <SECRET-FILE> — use SECRET-FILE as the retrievable secret. simple as that 💖.
• --type <TYPE> — specify the secret type.

limitations to the input data apply depending on the secret type, so pay attention bestie 👑

possible values:

• plain: a plaintext secret. can be any file up to 8190 bytes long.
• aes: an AES key. must be a plain byte file 128, 192, or 256 bit long.
• aes-xts: an AES-XTS key. must be a plain byte file 256, or 512 bit long.
• hmac-sha: a HMAC-SHA key. must be a plain byte file 512, or 1024 bit long. special care is required when creating HMAC-SHA keys — for more information refer to the DESCRIPTION section of the man file (scroll up, it's all there 🫶).
• ec: an elliptic curve private key. must be a PEM or DER file.

• -h, --help — print help (see a summary with -h). the short version is the tl;dr, the long version is the full lore 📖.

---

🌈 SEE ALSO 🌈

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

go read those too, they're literally the sibling pages and they're slaying in their own right 👑

---

and that's the whole page, bestie! 🫶 this cutie pie of a man page ships with s390-tools, dated 2026-08-11 — so go forth, make your retrievable secrets, pre-process those HMAC keys correctly, and remember: same digest everywhere or the MAC is wrong 💜✨🎀