| blob | ba596e280458f6f16fe014ddfb9e98edca16dd73 |
1 .\" $NetBSD: cgdconfig.8,v 1.28 2008/09/12 16:51:55 christos Exp $
2 .\"
3 .\" Copyright (c) 2002, The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Roland C. Dowdeswell.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd October 19, 2009
31 .Dt CGDCONFIG 8
32 .Os
33 .Sh NAME
34 .Nm cgdconfig
35 .Nd configuration utility for the cryptographic disk driver
36 .Sh SYNOPSIS
37 .Nm
38 .Op Fl npv
39 .Op Fl V Ar vmeth
40 .Ar cgd dev
41 .Op Ar paramsfile
42 .Nm
43 .Fl C
44 .Op Fl nv
45 .Op Fl f Ar configfile
46 .Nm
47 .Fl U
48 .Op Fl nv
49 .Op Fl f Ar configfile
50 .Nm
51 .Fl G
52 .Op Fl nv
53 .Op Fl i Ar ivmeth
54 .Op Fl k Ar kgmeth
55 .Op Fl o Ar outfile
56 .Ar paramsfile
57 .Nm
58 .Fl g
59 .Op Fl nv
60 .Op Fl i Ar ivmeth
61 .Op Fl k Ar kgmeth
62 .Op Fl o Ar outfile
63 .Ar alg
64 .Op Ar keylen
65 .Nm
66 .Fl s
67 .Op Fl nv
68 .Op Fl i Ar ivmeth
69 .Ar cgd
70 .Ar dev
71 .Ar alg
72 .Op Ar keylen
73 .Nm
74 .Fl u
75 .Op Fl nv
76 .Ar cgd
77 .Sh DESCRIPTION
78 .Nm
79 is used to configure and unconfigure cryptographic disk devices (cgds)
80 and to maintain the configuration files that are associated with them.
81 For more information about cryptographic disk devices see
82 .Xr cgd 4 .
83 .Pp
84 The options are as follows:
85 .Bl -tag -width configfilexxxx
86 .It Fl C
87 Configure all the devices listed in the cgd configuration file.
88 .It Fl f Ar configfile
89 Specify the configuration file explicitly, rather than using the default
90 configuration file
91 .Pa /etc/cgd/cgd.conf .
92 .It Fl G
93 Generate a new paramsfile (to stdout) using the values from
94 .Ar paramsfile
95 which will generate the same key.
96 This may need to prompt for multiple passphrases.
97 .It Fl g
98 Generate a paramsfile (to stdout).
99 .It Fl i Ar ivmeth
100 Specify the IV method (default: encblkno1).
101 .It Fl k Ar kgmeth
102 Specify the key generation method (default: pkcs5_pbkdf2/sha1).
103 .It Fl n
104 Do not actually configure or unconfigure a cryptographic disk
105 device, but instead report the steps that would be taken.
106 .It Fl o Ar outfile
107 When generating a
108 .Ar paramsfile ,
109 store it in
110 .Ar outfile .
111 .It Fl p
112 Read all passphrases from stdin rather than
113 .Pa /dev/tty .
114 Passphrases are separated by newlines.
115 Users of this flag must be able to predict the order in which passphrases
116 are prompted.
117 If this flag is specified then verification errors will cause the device
118 in question to be unconfigured rather than prompting for the passphrase
119 again.
120 .It Fl s
121 Read the key from stdin.
122 .It Fl U
123 Unconfigure all the devices listed in the cgd configuration file.
124 .It Fl u
125 Unconfigure a cgd.
126 .It Fl V Ar vmeth
127 Specify the verification method (default: none).
128 .It Fl v
129 Be verbose.
130 May be specified multiple times.
131 .El
132 .Pp
133 For more information about the cryptographic algorithms and IV methods
134 supported, please refer to
135 .Xr cgd 4 .
136 .Ss Key Generation Methods
137 To generate the key which it will use,
138 .Nm
139 evaluates all of the key generation methods in the parameters file
140 and uses the exclusive-or of the outputs of all the methods.
141 The methods and descriptions are as follows:
142 .Bl -tag -width indentxxxxxxxxxxx
143 .It pkcs5_pbkdf2/sha1
144 This method requires a passphrase which is entered at configuration
145 time.
146 It is a salted hmac-based scheme detailed in
147 .Dq PKCS#5 v2.0: Password-Based Cryptography Standard ,
148 RSA Laboratories, March 25, 1999, pages 8-10.
149 PKCS #5 was also republished as RFC 2898.
150 .It pkcs5_pbkdf2
151 This is an earlier, slightly incorrect and deprecated implementation
152 of the above algorithm.
153 It is retained for backwards compatibility with existing parameters
154 files, and will be removed.
155 Existing parameters files should be
156 converted to use the correct method using the
157 .Fl G
158 option, and a new passphrase.
159 .It storedkey
160 This method stores its key in the parameters file.
161 .It randomkey
162 The method simply reads
163 .Pa /dev/random
164 and uses the resulting bits as the key.
165 It does not require a passphrase to be entered.
166 This method is typically used to present disk devices that do not
167 need to survive a reboot, such as the swap partition.
168 It is also handy to facilitate overwriting the contents of
169 a disk volume with meaningless data prior to use.
170 .It urandomkey
171 The method simply reads
172 .Pa /dev/urandom
173 and uses the resulting bits as the key. This is similar to the
174 .Pa randomkey
175 method, but it guarantees that cgdconfig will not stall waiting for
176 hard-random bits (useful when configuring a cgd for swap at boot time).
177 Note, however, that some or all of the bits used to generate the
178 key may be obtained from a pseudo-random number generator,
179 which may not be as secure as the entropy based hard-random
180 number generator.
181 .It shell_cmd
182 This method executes a shell command via
183 .Xr popen 3
184 and reads the key from stdout.
185 .El
186 .Ss Verification Method
187 The verification method is how
188 .Nm
189 determines if the generated key is correct.
190 If the newly configured disk fails to verify, then
191 .Nm
192 will regenerate the key and re-configure the device.
193 It only makes sense to specify a verification method if at least of the
194 key generation methods is error prone, e.g., uses a user-entered passphrase.
195 The following verification methods are supported:
196 .Pp
197 .Bl -tag -width indentxxx -compact
198 .It none
199 perform no verification.
200 .It disklabel
201 scan for a valid disklabel.
202 .It ffs
203 scan for a valid FFS file system.
204 .It re-enter
205 prompt for passphrase twice, and ensure entered passphrases are
206 identical.
207 This method only works with the pkcs5_pbkdf2/sha1 and pkcs5_pbkdf2 key
208 generators.
209 .El
210 .Ss /etc/cgd/cgd.conf
211 The file
212 .Pa /etc/cgd/cgd.conf
213 is used to configure
214 .Nm
215 if either of
216 .Fl C
217 or
218 .Fl U
219 are specified.
220 Each line of the file is composed of either two or three
221 tokens: cgd, target, and optional paramsfile.
222 .Pp
223 A
224 .Sq \&#
225 character is interpreted as a comment and indicates that the
226 rest of the line should be ignored.
227 A
228 .Sq \e
229 at the end of a line indicates that the next line is a continuation of
230 the current line.
231 .Pp
232 See
233 .Sx EXAMPLES
234 for an example of
235 .Pa /etc/cgd/cgd.conf .
236 .Ss Parameters File
237 The Parameters File contains the required information to generate the
238 key and configure a device.
239 These files are typically generated by the
240 .Fl g
241 flag and not edited by hand.
242 When a device is configured the default parameters file is constructed
243 by taking the basename of the target disk and prepending
244 .Pa /etc/cgd/
245 to it.
246 E.g., if the target is
247 .Pa /dev/sd0h ,
248 then the default parameters file will be
249 .Pa /etc/cgd/sd0h .
250 .Pp
251 It is possible to have more than one parameters file for a given
252 disk which use different key generation methods but will generate
253 the same key.
254 To create a parameters file that is equivalent to an existing parameters
255 file, use
256 .Nm
257 with the
258 .Fl G
259 flag.
260 See
261 .Sx EXAMPLES
262 for an example of this usage.
263 .Pp
264 The parameters file contains a list of statements each terminated
265 with a semi-colon.
266 Some statements can contain statement-blocks which are either a
267 single unadorned statement, or a brace-enclosed list of semicolon
268 terminated statements.
269 Three types of data are understood:
270 .Pp
271 .Bl -tag -compact -width integerxx
272 .It integer
273 a 32 bit signed integer.
274 .It string
275 a string.
276 .It base64
277 a length-encoded base64 string.
278 .El
279 .Pp
280 The following statements are defined:
281 .Bl -tag -width indentxx
282 .It algorithm Ar string
283 Defines the cryptographic algorithm.
284 .It iv-method Ar string
285 Defines the IV generation method.
286 .It keylength Ar integer
287 Defines the length of the key.
288 .It verify_method Ar string
289 Defines the verification method.
290 .It keygen Ar string Ar statement_block
291 Defines a key generation method.
292 The
293 .Ar statement_block
294 contains statements that are specific to the key generation method.
295 .El
296 .Pp
297 The keygen statement's statement block may contain the following statements:
298 .Bl -tag -width indentxx
299 .It key Ar string
300 The key.
301 Only used for the storedkey key generation method.
302 .It cmd Ar string
303 The command to execute.
304 Only used for the shell_cmd key generation method.
305 .It iterations Ar integer
306 The number of iterations.
307 Only used for pkcs5_pbkdf2/sha1 and pkcs5_pbkdf2.
308 .It salt Ar base64
309 The salt.
310 Only used for pkcs5_pbkdf2/sha1 and pkcs5_pbkdf2.
311 .El
312 .Sh FILES
313 .Bl -tag -width indentxxxxxxxxxxxxxxxxxx -compact
314 .It Pa /etc/cgd/
315 configuration directory, used to store paramsfiles.
316 .It Pa /etc/cgd/cgd.conf
317 cgd configuration file.
318 .El
319 .Sh EXAMPLES
320 To set up and configure a cgd that uses AES with a 192 bit key
321 in CBC mode with the IV Method
322 .Sq encblkno1
323 (encrypted block number):
324 .Bd -literal
325 # cgdconfig -g -o /etc/cgd/wd0e aes-cbc 192
326 # cgdconfig cgd0 /dev/wd0e
327 /dev/wd0e's passphrase:
328 .Ed
329 .Pp
330 When using verification methods, the first time that we configure the
331 disk the verification method will fail.
332 We overcome this by supplying
333 .Fl V Ar re-enter
334 when we configure the first time to set up the disk.
335 Here is the
336 sequence of commands that is recommended:
337 .Bd -literal
338 # cgdconfig -g -o /etc/cgd/wd0e -V disklabel aes-cbc
339 # cgdconfig -V re-enter cgd0 /dev/wd0e
340 /dev/wd0e's passphrase:
341 re-enter device's passphrase:
342 # disklabel -e -I cgd0
343 # cgdconfig -u cgd0
344 # cgdconfig cgd0 /dev/wd0e
345 /dev/wd0e's passphrase:
346 .Ed
347 .Pp
348 To create a new parameters file that will generate the same key as an old
349 parameters file:
350 .Bd -literal
351 # cgdconfig -G -o newparamsfile oldparamsfile
352 old file's passphrase:
353 new file's passphrase:
354 .Ed
355 .Pp
356 To configure a cgd that uses Blowfish with a 200 bit key that it
357 reads from stdin:
358 .Bd -literal
359 # cgdconfig -s cgd0 /dev/sd0h blowfish-cbc 200
360 .Ed
361 .Pp
362 An example parameters file which uses PKCS#5 PBKDF2:
363 .Bd -literal
364 algorithm aes-cbc;
365 iv-method encblkno1;
366 keylength 128;
367 verify_method none;
368 keygen pkcs5_pbkdf2/sha1 {
369 iterations 39361;
370 salt AAAAgMoHiYonye6Kog \\
371 dYJAobCHE=;
372 };
373 .Ed
374 .Pp
375 An example parameters file which stores its key locally:
376 .Bd -literal
377 algorithm aes-cbc;
378 iv-method encblkno1;
379 keylength 256;
380 verify_method none;
381 keygen storedkey key AAABAK3QO6d7xzLfrXTdsgg4 \\
382 ly2TdxkFqOkYYcbyUKu/f60L;
383 .Ed
384 .Pp
385 An example
386 .Pa /etc/cgd/cgd.conf :
387 .Bd -literal
388 #
389 # /etc/cgd/cgd.conf
390 # Configuration file for cryptographic disk devices
391 #
393 # cgd target [paramsfile]
394 cgd0 /dev/wd0e
395 cgd1 /dev/sd0h /usr/local/etc/cgd/sd0h
396 .Ed
397 .Pp
398 Note that this will store the parameters file as
399 .Pa /etc/cgd/wd0e .
400 And use the entered passphrase to generate the key.
401 .Sh DIAGNOSTICS
402 .Bl -diag
403 .It "cgdconfig: could not calibrate pkcs5_pbkdf2"
404 An error greater than 5% in calibration occured.
405 This could be the result of dynamic processor frequency scaling technology.
406 Ensure that the processor clock frequency remains static throughout the
407 program's execution.
408 .El
409 .Sh SEE ALSO
410 .Xr cgd 4
411 .Pp
412 .Dq PKCS #5 v2.0: Password-Based Cryptography Standard ,
413 RSA Laboratories, March 25, 1999.
414 .Sh HISTORY
415 The
416 .Nm
417 utility appeared in
418 .Nx 2.0 .
419 .Sh BUGS
420 Since
421 .Nm
422 uses
423 .Xr getpass 3
424 to read in the passphrase, it is limited to 128 characters.