volume_key - work with volume encryption secrets and escrow packets

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.

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--saveVOLUME-cCERT-oPACKET_DEFAULT--create-random-passphrasePACKET_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-dNSS_DBPACKET_DEFAULT-oPACKET_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--restoreVOLUMEPACKET_DEFAULT_PW

       If the user forgets the passphrase, and you cannot access the computer, decrypt the backup passphrase:
              volume_key--secretsPACKET_PASSPHRASE
       and tell the backup passphrase to the user.  (You can later generate a new backup passphrase.)

volume_key                                          Jun 2011                                       volume_key(8)

Exit Status

volume_key returns with exit status 0 on success, 1 on error.

Name

       volume_key - work with volume encryption secrets and escrow packets

Notes

       The only currently supported volume format is LUKS.

Options

In all options described below, VOLUME is a LUKS device, not the plaintext device contained within:
blkid-sTYPEVOLUME
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 VOLUMEPACKET. 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 VOLUMEPACKETNAME. 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-dirDIR
Use private keys in NSS database in DIR to decrypt public key-encrypted packets.

-o, --outputPACKET
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-keyPACKET
Write the data encryption key (the key directly used to encrypt the actual volume data) to PACKET.

--output-passphrasePACKET
Write a passphrase that can be used to access the volume to PACKET.

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

-c, --certificateCERT
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-formatFORMAT
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