1volume_key(8) System Manager's Manual volume_key(8)
2
6 volume_key - work with volume encryption secrets and escrow packets
7
10 volume_key [OPTION]... OPERAND...
11
14 volume_key extracts "secrets" used for volume encryption (for example
15 keys or passphrases) and stores them into separate encrypted "escrow
16 packets", uses a previously created escrow packet to restore access to
17 a volume (e.g. if the user forgets a passphrase), or manipulates the
18 information in escrow packets.
19 The mode of operation and operands of volume_key are determined by
21 specifying one of the --save, --restore, --setup-volume, --reencrypt,
22 --dump or --secrets options. See the OPTIONS sections for details.
23
26 In all options described below, VOLUME is a LUKS device, not the plain‐
27 text device contained within:
28 blkid -s TYPE VOLUME
29 should report TYPE="crypto_LUKS".
30 The following options determine the mode of operation and expected op‐
32 erands of volume_key:
33 --save Expects operands VOLUME [PACKET]. Open VOLUME. If PACKET is
36 provided, load the secrets from it. Otherwise, extract secrets
37 from VOLUME, prompting the user if necessary. In any case,
38 store secrets in one or more output packets.
39 --restore
42 Expects operands VOLUME PACKET. Open VOLUME and use the secrets
43 in PACKET to make VOLUME accessible again, prompting the user if
44 necessary (e.g. by letting the user enter a new passphrase).
45 --setup-volume
48 Expects operands VOLUME PACKET NAME. Open VOLUME and use the
49 secrets in PACKET to set up VOLUME for use of the decrypted data
50 as NAME.
51 Currently NAME is a name of a dm-crypt volume, and this opera‐
53 tion makes the decrypted volume available as /dev/mapper/NAME.
54 This operation should not permanently alter VOLUME (e.g. by
56 adding a new passphrase); the user can of course access and mod‐
57 ify the decrypted volume, modifying VOLUME in the process.
58 --reencrypt
61 Expects operand PACKET. Open PACKET, decrypting it if neces‐
62 sary, and store the information in one or more new output pack‐
63 ets.
64 --dump Expects operand PACKET. Open PACKET, decrypting it if neces‐
67 sary, and output the contents of PACKET. The secrets are not
68 output by default.
69 --secrets
72 Expects operand PACKET. Open PACKET, decrypting it if neces‐
73 sary, and output secrets contained in PACKET.
74 --help Show usage information.
77 --version
80 Show version of volume_key.
81 The following options alter the behavior of the specified operation:
84 -b, --batch
87 Run in batch mode. Read passwords and passphrases from standard
88 input, each terminated by a NUL character. If a packet does not
89 match a volume exactly, fail instead of prompting the user.
90 -d, --nss-dir DIR
93 Use private keys in NSS database in DIR to decrypt public key-
94 encrypted packets.
95 -o, --output PACKET
98 Write the default secret to PACKET.
99 Which secret is the default depends on volume format: it should
101 not be likely to expire, and it should allow restoring access to
102 the volume using --restore.
103 --output-data-encryption-key PACKET
106 Write the data encryption key (the key directly used to encrypt
107 the actual volume data) to PACKET.
108 --output-passphrase PACKET
111 Write a passphrase that can be used to access the volume to
112 PACKET.
113 --create-random-passphrase PACKET
116 Generate a random alphanumeric passphrase, add it to VOLUME
117 (without affecting other passphrases) and store the random
118 passphrase into PACKET.
119 -c, --certificate CERT
123 Load a certificate from the file specified by CERT and encrypt
124 all output packets using the public key contained in the cer‐
125 tificate. If this option is not specified, all output packets
126 are encrypted using a passphrase.
127 Note that CERT is a certificate file name, not a NSS certificate
129 nickname.
130 --output-format FORMAT
133 Use FORMAT for all output packets. FORMAT can currently be one
134 of asymmetric (use CMS to encrypt the whole packet, requires a
135 certificate), asymmetric_wrap_secret_only (wrap only the secret,
136 requires a certificate), passphrase (use GPG to encrypt the
137 whole packet, requires a passphrase).
138 --unencrypted
141 Only dump the unencrypted parts of the packet, if any, with
142 --dump. Do not require any passphrase or private key access.
143 --with-secrets
146 Include secrets in the output of --dump
147
150 volume_key returns with exit status 0 on success, 1 on error.
151
154 The only currently supported volume format is LUKS.
155
158 Typical usage of volume_key proceeds as follows. During system instal‐
159 lation or soon after, back up the default secret of a volume, and add a
160 system-specific random passphrase. Encrypt both using a certificate:
161 volume_key --save VOLUME -c CERT -o PACKET_DEFAULT --create-ran‐
162 dom-passphrase PACKET_PASSPHRASE
163 Store PACKET_DEFAULT and PACKET_PASSPHRASE outside of the computer.
164 If the user forgets a passphrase, and you can access the computer,
166 decrypt PACKET_DEFAULT using the certificate private key (which should
167 never leave a secure machine):
168 volume_key --reencrypt -d NSS_DB PACKET_DEFAULT -o
169 PACKET_DEFAULT_PW
170 Then boot the computer (e.g. using a "rescue mode"), copy
171 PACKET_DEFAULT_PW to it, and restore access to the volume:
172 volume_key --restore VOLUME PACKET_DEFAULT_PW
173 If the user forgets the passphrase, and you cannot access the computer,
175 decrypt the backup passphrase:
176 volume_key --secrets PACKET_PASSPHRASE
177 and tell the backup passphrase to the user. (You can later generate a
178 new backup passphrase.)
179volume_key Jun 2011 volume_key(8)