1volume_key(8)               System Manager's Manual              volume_key(8)
2
3
4

NAME

6       volume_key - work with volume encryption secrets and escrow packets
7
8

SYNOPIS

10       volume_key [OPTION]... OPERAND...
11
12

DESCRIPTION

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
20       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
24

OPTIONS

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
31       The following options determine the mode of operation and expected  op‐
32       erands of volume_key:
33
34
35       --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
40
41       --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
46
47       --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
52              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
55              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
59
60       --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
65
66       --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
70
71       --secrets
72              Expects  operand  PACKET.   Open PACKET, decrypting it if neces‐
73              sary, and output secrets contained in PACKET.
74
75
76       --help Show usage information.
77
78
79       --version
80              Show version of volume_key.
81
82
83       The following options alter the behavior of the specified operation:
84
85
86       -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
91
92       -d, --nss-dir DIR
93              Use private keys in NSS database in DIR to decrypt  public  key-
94              encrypted packets.
95
96
97       -o, --output PACKET
98              Write the default secret to PACKET.
99
100              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
104
105       --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
109
110       --output-passphrase PACKET
111              Write a passphrase that can be used  to  access  the  volume  to
112              PACKET.
113
114
115       --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
120
121
122       -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
128              Note that CERT is a certificate file name, not a NSS certificate
129              nickname.
130
131
132       --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
139
140       --with-secrets
141              Include secrets in the output of --dump
142
143

EXIT STATUS

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

NOTES

149       The only currently supported volume format is LUKS.
150
151

EXAMPLE

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
160       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
169       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.)
174
175
176
177
178volume_key                         Sep 2010                      volume_key(8)
Impressum