summaryrefslogtreecommitdiffstats
path: root/sbin/gbde/gbde.8
blob: 57208b56a1aacda616b6abec0e58625fa3071009 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
.\"
.\" Copyright (c) 2002 Poul-Henning Kamp
.\" Copyright (c) 2002 Networks Associates Technology, Inc.
.\" All rights reserved.
.\"
.\" This software was developed for the FreeBSD Project by Poul-Henning Kamp
.\" and NAI Labs, the Security Research Division of Network Associates, Inc.
.\" under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the
.\" DARPA CHATS research program.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd October 19, 2002
.Dt GBDE 8
.Os
.Sh NAME
.Nm gbde
.Nd operation and management utility for Geom Based Disk Encryption
.Sh SYNOPSIS
.Nm
.Cm attach
.Ar destination
.Op Fl l Ar lockfile
.Op Fl p Ar pass-phrase
.Nm
.Cm detach
.Ar destination
.Nm
.Cm init
.Ar destination
.Op Fl i
.Op Fl f Ar filename
.Op Fl L Ar lockfile
.Op Fl P Ar pass-phrase
.Nm
.Cm setkey
.Ar destination
.Op Fl n Ar key
.Op Fl l Ar lockfile
.Op Fl p Ar pass-phrase
.Op Fl L Ar new-lockfile
.Op Fl P Ar new-pass-phrase
.Nm
.Cm destroy
.Ar destination
.Op Fl n Ar key
.Op Fl l Ar lockfile
.Op Fl p Ar pass-phrase
.Op Fl L Ar lockfile
.Sh DESCRIPTION
.Bf -symbolic
NOTICE:
Please be aware that this code has not yet received much review
and analysis by qualified cryptographers and therefore should be considered
a slightly suspect experimental facility.
.Pp
We cannot at this point guarantee that the on-disk format will not change
in response to reviews or bug-fixes, so potential users are advised to
be prepared that
.Xr dump 8 Ns / Ns
.Xr restore 8
based migrations may be called for in the future.
.Ef
.Pp
The
.Nm
utility is the only official operation and management interface for the
.Xr gbde 4
.Tn GEOM
based disk encryption kernel facility.
The interaction between the
.Nm
utility and the kernel part is not a published interface.
.Pp
The operational aspect consists of two subcommands:
one to open and attach
a device to the in-kernel cryptographic
.Nm
module,
and one to close and detach a device.
.Pp
The management part allows initialization of the master key and lock sectors
on a device, initialization and replacement of pass-phrases and
key invalidation and blackening functions.
.Pp
The
.Fl l Ar lockfile
argument is used to supply the lock selector data.
If no
.Fl l
option is specified, the first sector is used for this purpose.
.Pp
The
.Fl L Ar new-lockfile
argument
specifies the lock selector file for the key modified with the
.Cm setkey
subcommand.
.Pp
The
.Fl n Ar key
argument can be used to specify to which of the four keys
the operation applies.
A value of 1 to 4 selects the specified key, a value of 0 (the default)
means
.Dq "this key"
(i.e., the key used to gain access to the device)
and a value of \-1 means
.Dq "all keys" .
.Pp
The
.Fl f Ar filename
specifies an optional parameter file for use under initialization.
.Pp
Alternatively, the
.Fl i
option toggles an interactive mode where a template file with descriptions
of the parameters can be interactively edited.
.Pp
The
.Fl p Ar pass-phrase
argument
specifies the pass-phrase used for opening the device.
If not specified, the controlling terminal will be used to prompt the user
for the pass-phrase.
Be aware that using this option may expose the pass-phrase to other
users who happen to run
.Xr ps 1
or similar while the command is running.
.Pp
The
.Fl P Ar new-pass-phrase
argument
can be used to specify the new pass-phrase to the
.Cm init
and
.Cm setkey
subcommands.
If not specified, the user is prompted for the new pass-phrase on the
controlling terminal.
Be aware that using this option may expose the pass-phrase to other
users who happen to run
.Xr ps 1
or similar while the command is running.
.Sh EXAMPLES
To initialize a device, using default parameters:
.Pp
.Dl "gbde init /dev/ad0s1f -L /etc/ad0s1f.lock"
.Pp
To attach an encrypted device:
.Pp
.Dl "gbde attach ad0s1f -l /etc/ad0s1f.lock"
.Pp
The encrypted device has the suffix
.Pa .bde
so a typical
command to create and mount a file system would be:
.Pp
.Dl "newfs /dev/ad0s1f.bde"
.Dl "mount /dev/ad0s1f.bde /secret"
.Pp
To detach an encrypted device:
.Pp
.Dl "gbde detach ad0s1f"
.Pp
Please notice that detaching an encrypted device corresponds to
physically removing it, do not forget to unmount the file system first.
.Pp
To initialize the second key using a detached lockfile and a trivial
pass-phrase:
.Pp
.Dl "gbde setkey ad0s1f -n 2 -P foo -L key2.lockfile"
.Pp
To destroy all copies of the masterkey:
.Pp
.Dl "gbde destroy ad0s1f -n -1"
.Sh SEE ALSO
.Xr gbde 4 ,
.Xr geom 4
.Sh HISTORY
This software was developed for the
.Fx
Project by
.An "Poul-Henning Kamp"
and NAI Labs, the Security Research Division of Network Associates, Inc.\&
under DARPA/SPAWAR contract N66001-01-C-8035
.Pq Dq CBOSS ,
as part of the
DARPA CHATS research program.
.Sh AUTHORS
.An "Poul-Henning Kamp" Aq phk@FreeBSD.org
.Sh BUGS
The cryptographic algorithms and the overall design have not been
attacked mercilessly for over 10 years by a gang of cryptoanalysts.
OpenPOWER on IntegriCloud