volume_key (8) - Linux Manuals
volume_key: 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 containted within:
- blkid -s TYPE VOLUME
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
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
- 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