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 containted 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 --with-secrets
141 Include secrets in the output of --dump
142
145 volume_key returns with exit status 0 on success, 1 on error.
146
149 The only currently supported volume format is LUKS.
150
153 Typical usage of volume_key proceeds as follows. During system instal‐
154 lation or soon after, back up the default secret of a volume, and add a
155 system-specific random passphrase. Encrypt both using a certificate:
156 volume_key --save VOLUME -c CERT -o PACKET_DEFAULT --create-ran‐
157 dom-passphrase PACKET_PASSPHRASE
158 Store PACKET_DEFAULT and PACKET_PASSPHRASE outside of the computer.
159 If the user forgets a passphrase, and the you can access the computer,
161 decrypt PACKET_DEFAULT using the certificate private key (which should
162 never leave a secure machine):
163 volume_key --reencrypt -d NSS_DB PACKET_DEFAULT -o
164 PACKET_DEFAULT_PW
165 Then boot the computer (e.g. using a "rescue mode"), copy
166 PACKET_DEFAULT_PW to it, and restore access to the volume:
167 volume_key --restore VOLUME PACKET_DEFAULT_PW
168 If the user forgets the passphrase, and you cannot access the computer,
170 decrypt the backup passphrase:
171 volume_key --secrets PACKET_PASSPHRASE
172 and tell the backup passphrase to the user. (You can later generate a
173 new backup passphrase.)
174volume_key Sep 2010 volume_key(8)