volume_key(8)

💖 NAME 💖

volume_key — work with volume encryption secrets and escrow packets

✨ SYNOPSIS ✨

volume_key [OPTION]... OPERAND...

🦋 DESCRIPTION 🦋

okay so bestie, volume_key is the girl who handles the "secrets" your volume encryption runs on — keys, passphrases, the whole vibe — and tucks them safely into separate encrypted "escrow packets". She can also take a packet you built earlier and use it to restore access to a volume (classic scenario: user forgot their passphrase, tragic), or just manipulate the info sitting inside escrow packets.

Which mode she's in, and which operands she wants, is decided by whichever one of --save, --restore, --setup-volume, --reencrypt, --dump or --secrets you hand her. The OPTIONS section has the details, iykyk.

💅 OPTIONS 💅

quick vibe check before anything else: in every option below, VOLUME means a LUKS device — not the plaintext device chillin' inside it:

blkid -s TYPE VOLUME

should report TYPE="crypto_LUKS". no cap. 🫶

🌈 the mode options (these pick your operation AND your operands)

• --save — Expects operands VOLUME [PACKET]. Opens VOLUME. If PACKET is provided, it loads the secrets from it. Otherwise it extracts secrets from VOLUME, prompting the user if necessary. Either way, it stores secrets in one or more output packets. 💾
• --restore — Expects operands VOLUME PACKET. Opens VOLUME and uses the secrets in PACKET to make VOLUME accessible again, prompting the user if necessary (e.g. by letting the user enter a new passphrase). 💖
• --setup-volume — Expects operands VOLUME PACKET NAME. Opens VOLUME and uses the secrets in PACKET to set up VOLUME for use of the decrypted data as NAME.
  • Currently NAME is a name of a dm-crypt volume, and this operation makes the decrypted volume available as /dev/mapper/NAME.
  • This operation should not permanently alter VOLUME (e.g. by adding a new passphrase); the user can of course access and modify the decrypted volume, modifying VOLUME in the process.
• --reencrypt — Expects operand PACKET. Opens PACKET, decrypting it if necessary, and stores the information in one or more new output packets. 🔁
• --dump — Expects operand PACKET. Opens PACKET, decrypting it if necessary, and outputs the contents of PACKET. the secrets are not output by default — you gotta ask nicely.
• --secrets — Expects operand PACKET. Opens PACKET, decrypting it if necessary, and outputs secrets contained in PACKET. 🤫
• --help — Shows usage information.
• --version — Shows version of volume_key.

🎀 the options that tweak how your operation behaves

• -b, --batch — Run in batch mode. Reads passwords and passphrases from standard input, each terminated by a NUL character. And if a packet does not match a volume exactly, it fails instead of prompting the user. ✋
• -d, --nss-dir DIR — Uses private keys in the NSS database in DIR to decrypt public key-encrypted packets. 🔑
• -o, --output PACKET — Writes the default secret to PACKET.
  • Which secret counts as the default depends on the volume format: it should not be likely to expire, and it should allow restoring access to the volume using --restore. 💫
• --output-data-encryption-key PACKET — Writes the data encryption key (the key directly used to encrypt the actual volume data) to PACKET. 🔐
• --output-passphrase PACKET — Writes a passphrase that can be used to access the volume to PACKET.
• --create-random-passphrase PACKET — Generates a random alphanumeric passphrase, adds it to VOLUME (without affecting other passphrases) and stores the random passphrase into PACKET. 🎲
• -c, --certificate CERT — Loads a certificate from the file specified by CERT and encrypts all output packets using the public key contained in the certificate. If this option is not specified, all output packets are encrypted using a passphrase.
  • > note bestie: CERT is a certificate file name, not a NSS certificate nickname. don't mix those up, it's giving heartbreak 💀
• --output-format FORMAT — Uses FORMAT for all output packets. FORMAT can currently be one of asymmetric (use CMS to encrypt the whole packet, requires a certificate), asymmetric_wrap_secret_only (wrap only the secret, requires a certificate), passphrase (use GPG to encrypt the whole packet, requires a passphrase).
• --unencrypted — Only dumps the unencrypted parts of the packet, if any, with --dump. Does not require any passphrase or private key access. 🙈
• --with-secrets — Includes secrets in the output of --dump. 👀

🔥 EXIT STATUS 🔥

volume_key returns with exit status 0 on success, 1 on error. that's the whole chart, periodt.

🍓 NOTES 🍓

The only currently supported volume format is LUKS. fr fr, that's the one.

👑 EXAMPLE 👑

okay here's the typical volume_key storyline, bestie. During system installation, or soon after, you back up the default secret of a volume, and you add a system-specific random passphrase. Encrypt both using a certificate:

volume_key --save VOLUME -c CERT -o PACKET_DEFAULT
--create-random-passphrase PACKET_PASSPHRASE

Then store PACKET_DEFAULT and PACKET_PASSPHRASE outside of the computer. 🧚 keep them somewhere else, that's the whole point.

If the user forgets a passphrase, and you can access the computer, decrypt PACKET_DEFAULT using the certificate private key (which should never leave a secure machine):

volume_key --reencrypt -d NSS_DB PACKET_DEFAULT -o
PACKET_DEFAULT_PW

Then boot the computer (e.g. using a "rescue mode"), copy PACKET_DEFAULT_PW to it, and restore access to the volume:

volume_key --restore VOLUME PACKET_DEFAULT_PW

If the user forgets the passphrase, and you cannot access the computer, decrypt the backup passphrase:

volume_key --secrets PACKET_PASSPHRASE

and tell the backup passphrase to the user. (You can later generate a new backup passphrase.) 💅✨

that's a wrap, bestie — this was volume_key, living in section 8 of the System Manager's Manual, from the volume_key source, dated Jun 2011. go forth and escrow responsibly. 💜🌸