2 .\" Copyright (c) 2002 Poul-Henning Kamp
3 .\" Copyright (c) 2002 Networks Associates Technology, Inc.
4 .\" All rights reserved.
6 .\" This software was developed for the FreeBSD Project by Poul-Henning Kamp
7 .\" and NAI Labs, the Security Research Division of Network Associates, Inc.
8 .\" under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the
9 .\" DARPA CHATS research program.
11 .\" Redistribution and use in source and binary forms, with or without
12 .\" modification, are permitted provided that the following conditions
14 .\" 1. Redistributions of source code must retain the above copyright
15 .\" notice, this list of conditions and the following disclaimer.
16 .\" 2. Redistributions in binary form must reproduce the above copyright
17 .\" notice, this list of conditions and the following disclaimer in the
18 .\" documentation and/or other materials provided with the distribution.
20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
39 .Nd operation and management utility for Geom Based Disk Encryption
46 .Op Fl p Ar pass-phrase
55 .Op Fl K Ar new-keyfile
56 .Op Fl L Ar new-lockfile
57 .Op Fl P Ar new-pass-phrase
64 .Op Fl p Ar pass-phrase
65 .Op Fl K Ar new-keyfile
66 .Op Fl L Ar new-lockfile
67 .Op Fl P Ar new-pass-phrase
74 .Op Fl p Ar pass-phrase
80 .Op Fl p Ar pass-phrase
84 Please be aware that this code has not yet received much review
85 and analysis by qualified cryptographers and therefore should be considered
86 a slightly suspect experimental facility.
88 We cannot at this point guarantee that the on-disk format will not change
89 in response to reviews or bug-fixes, so potential users are advised to
93 based migrations may be called for in the future.
98 utility is the only official operation and management interface for the
101 based disk encryption kernel facility.
102 The interaction between the
104 utility and the kernel part is not a published interface.
106 The operational aspect consists of two subcommands:
107 one to open and attach
108 a device to the in-kernel cryptographic
112 and one to close and detach a device
115 The management part allows initialization of the master key and lock sectors
118 initialization and replacement of pass-phrases
128 argument is used to supply the lock selector data.
131 option is specified, the first sector is used for this purpose.
134 .Fl L Ar new-lockfile
136 specifies the lock selector file for the key
146 argument can be used to specify to which of the four keys
147 the operation applies.
148 A value of 1 to 4 selects the specified key, a value of 0 (the default)
151 (i.e., the key used to gain access to the device)
152 and a value of \-1 means
157 specifies an optional parameter file for use under initialization.
161 option toggles an interactive mode where a template file with descriptions
162 of the parameters can be interactively edited.
167 specifies the pass-phrase used for opening the device.
168 If not specified, the controlling terminal will be used to prompt the user
170 Be aware that using this option may expose the pass-phrase to other
171 users who happen to run
173 or similar while the command is running.
176 .Fl P Ar new-pass-phrase
178 can be used to specify the new pass-phrase to the
183 If not specified, the user is prompted for the new pass-phrase on the
184 controlling terminal.
185 Be aware that using this option may expose the pass-phrase to other
186 users who happen to run
188 or similar while the command is running.
192 argument specifies a key file to be used in combination with the
193 pass-phrase (whether the pass-phrase is specified on the command line
194 or entered from the terminal) for opening the device.
195 The device will only be opened if the contents of the key file and the
196 pass-phrase are both correct.
200 argument can be used to specify a new key file to the
205 If not specified, no key file will be used (even if one was previously
208 To initialize a device, using default parameters:
210 .Dl "gbde init /dev/ada0s1f -L /etc/ada0s1f.lock"
212 To attach an encrypted device:
214 .Dl "gbde attach ada0s1f -l /etc/ada0s1f.lock"
216 The encrypted device has the suffix
219 command to create and mount a file system would be:
221 .Dl "newfs /dev/ada0s1f.bde"
222 .Dl "mount /dev/ada0s1f.bde /secret"
224 To detach an encrypted device:
226 .Dl "gbde detach ada0s1f"
228 Please notice that detaching an encrypted device corresponds to
229 physically removing it, do not forget to unmount the file system first.
231 To initialize the second key using a detached lockfile and a trivial
234 .Dl "gbde setkey ada0s1f -n 2 -P foo -L key2.lockfile"
236 To destroy all copies of the masterkey:
238 .Dl "gbde destroy ada0s1f -n -1"
243 This software was developed for the
246 .An "Poul-Henning Kamp"
247 and NAI Labs, the Security Research Division of Network Associates, Inc.\&
248 under DARPA/SPAWAR contract N66001-01-C-8035
251 DARPA CHATS research program.
253 .An "Poul-Henning Kamp" Aq phk@FreeBSD.org
255 The cryptographic algorithms and the overall design have not been
256 attacked mercilessly for over 10 years by a gang of cryptoanalysts.