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 contained 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       --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
144
145       --with-secrets
146              Include secrets in the output of --dump
147
148

EXIT STATUS

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

NOTES

154       The only currently supported volume format is LUKS.
155
156

EXAMPLE

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
165       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
174       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.)
179
180
181
182
183volume_key                         Jun 2011                      volume_key(8)
Impressum