---
name: "volume_key"
section: "8"
platform: "linux"
package: "volume_key"
version: "0.3.12-12"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/volume_key"
---

# volume\_key(8)

work with volume encryption secrets and escrow packets

## NAME

volume\_key - work with volume encryption secrets and escrow packets

## SYNOPIS

**volume\_key** \[*OPTION*\]... *OPERAND*...

## DESCRIPTION

**volume\_key** extracts "secrets" used for volume encryption (for example keys or passphrases) and stores them into separate encrypted "escrow packets", uses a previously created escrow packet to restore access to a volume (e.g. if the user forgets a passphrase), or manipulates the information in escrow packets.

The mode of operation and operands of **volume\_key** are determined by specifying one of the **--save**, **--restore**, **--setup-volume**, **--reencrypt**,  **--dump** or **--secrets** options. See the OPTIONS sections for details.

## OPTIONS

In all options described below, *VOLUME* is a LUKS device, not the plaintext device contained within:

**blkid -s TYPE** *VOLUME*

should report **TYPE="crypto\_LUKS"**.

The following options determine the mode of operation and expected operands of **volume\_key**:

- **--save**

  Expects operands *VOLUME* \[*PACKET*\]. Open *VOLUME*.  If *PACKET* is provided, load the secrets from it. Otherwise, extract secrets from *VOLUME*, prompting the user if necessary. In any case, store secrets in one or more output packets.

- **--restore**

  Expects operands *VOLUME* *PACKET*. Open *VOLUME* and use 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*. Open *VOLUME* and use 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*. Open *PACKET*, decrypting it if necessary, and store the information in one or more new output packets.

- **--dump**

  Expects operand *PACKET*. Open *PACKET*, decrypting it if necessary, and output the contents of *PACKET*. The secrets are not output by default.

- **--secrets**

  Expects operand *PACKET*. Open *PACKET*, decrypting it if necessary, and output secrets contained in *PACKET*.

- **--help**

  Show usage information.

- **--version**

  Show version of **volume\_key**.

The following options alter the behavior of the specified operation:

- **-b**, **--batch**

  Run in batch mode. Read passwords and passphrases from standard input, each terminated by a NUL character. If a packet does not match a volume exactly, fail instead of prompting the user.

- **-d**, **--nss-dir** *DIR*

  Use private keys in NSS database in *DIR* to decrypt public key-encrypted packets.

- **-o**, **--output** *PACKET*

  Write the default secret to *PACKET*.

  Which secret is the default depends on 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*

  Write the data encryption key (the key directly used to encrypt the actual volume data) to *PACKET*.

- **--output-passphrase** *PACKET*

  Write a passphrase that can be used to access the volume to *PACKET*.

- **--create-random-passphrase** *PACKET*

  Generate a random alphanumeric passphrase, add it to *VOLUME* (without affecting other passphrases) and store the random passphrase into *PACKET*.

- **-c**, **--certificate** *CERT*

  Load a certificate from the file specified by *CERT* and encrypt 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 that *CERT* is a certificate file name, not a NSS certificate nickname.

- **--output-format** *FORMAT*

  Use *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 dump the unencrypted parts of the packet, if any, with **--dump**. Do not require any passphrase or private key access.

- **--with-secrets**

  Include secrets in the output of **--dump**

## EXIT STATUS

**volume\_key** returns with exit status 0 on success, 1 on error.

## NOTES

The only currently supported volume format is LUKS.

## EXAMPLE

Typical usage of **volume\_key** proceeds as follows. During system installation or soon after, back up the default secret of a volume, and 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*

Store *PACKET\_DEFAULT* and *PACKET\_PASSPHRASE* outside of the computer.

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.)