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 September 12, 2008 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 79is used to configure and unconfigure cryptographic disk devices (cgds) 80and to maintain the configuration files that are associated with them. 81For more information about cryptographic disk devices see 82.Xr cgd 4 . 83.Pp 84The options are as follows: 85.Bl -tag -width configfilexxxx 86.It Fl C 87Configure all the devices listed in the cgd configuration file. 88.It Fl f Ar configfile 89Specify the configuration file explicitly, rather than using the default 90configuration file 91.Pa /etc/cgd/cgd.conf . 92.It Fl G 93Generate a new paramsfile (to stdout) using the values from 94.Ar paramsfile 95which will generate the same key. 96This may need to prompt for multiple passphrases. 97.It Fl g 98Generate a paramsfile (to stdout). 99.It Fl i Ar ivmeth 100Specify the IV method (default: encblkno1). 101.It Fl k Ar kgmeth 102Specify the key generation method (default: pkcs5_pbkdf2/sha1). 103.It Fl o Ar outfile 104When generating a 105.Ar paramsfile , 106store it in 107.Ar outfile . 108.It Fl p 109Read all passphrases from stdin rather than 110.Pa /dev/tty . 111Passphrases are separated by newlines. 112Users of this flag must be able to predict the order in which passphrases 113are prompted. 114If this flag is specified then verification errors will cause the device 115in question to be unconfigured rather than prompting for the passphrase 116again. 117.It Fl s 118Read the key from stdin. 119.It Fl U 120Unconfigure all the devices listed in the cgd configuration file. 121.It Fl u 122Unconfigure a cgd. 123.It Fl V Ar vmeth 124Specify the verification method (default: none). 125.It Fl v 126Be verbose. 127May be specified multiple times. 128.El 129.Pp 130For more information about the cryptographic algorithms and IV methods 131supported, please refer to 132.Xr cgd 4 . 133.Ss Key Generation Methods 134To generate the key which it will use, 135.Nm 136evaluates all of the key generation methods in the parameters file 137and uses the exclusive-or of the outputs of all the methods. 138The methods and descriptions are as follows: 139.Bl -tag -width indentxxxxxxxxxxx 140.It pkcs5_pbkdf2/sha1 141This method requires a passphrase which is entered at configuration 142time. 143It is a salted hmac-based scheme detailed in 144.Dq PKCS#5 v2.0: Password-Based Cryptography Standard , 145RSA Laboratories, March 25, 1999, pages 8-10. 146PKCS #5 was also republished as RFC 2898. 147.It pkcs5_pbkdf2 148This is an earlier, slightly incorrect and deprecated implementation 149of the above algorithm. 150It is retained for backwards compatibility with existing parameters 151files, and will be removed. 152Existing parameters files should be 153converted to use the correct method using the 154.Fl G 155option, and a new passphrase. 156.It storedkey 157This method stores its key in the parameters file. 158.It randomkey 159The method simply reads 160.Pa /dev/random 161and uses the resulting bits as the key. 162It does not require a passphrase to be entered. 163This method is typically used to present disk devices that do not 164need to survive a reboot, such as the swap partition. 165It is also handy to facilitate overwriting the contents of 166a disk volume with meaningless data prior to use. 167.It urandomkey 168The method simply reads 169.Pa /dev/urandom 170and uses the resulting bits as the key. This is similar to the 171.Pa randomkey 172method, but it guarantees that cgdconfig will not stall waiting for 173hard-random bits (useful when configuring a cgd for swap at boot time). 174Note, however, that some or all of the bits used to generate the 175key may be obtained from a pseudo-random number generator, 176which may not be as secure as the entropy based hard-random 177number generator. 178.It shell_cmd 179This method executes a shell command via 180.Xr popen 3 181and reads the key from stdout. 182.El 183.Ss Verification Method 184The verification method is how 185.Nm 186determines if the generated key is correct. 187If the newly configured disk fails to verify, then 188.Nm 189will regenerate the key and re-configure the device. 190It only makes sense to specify a verification method if at least of the 191key generation methods is error prone, e.g., uses a user-entered passphrase. 192The following verification methods are supported: 193.Pp 194.Bl -tag -width indentxxx -compact 195.It none 196perform no verification. 197.It disklabel 198scan for a valid disklabel. 199.It ffs 200scan for a valid FFS file system. 201.It re-enter 202prompt for passphrase twice, and ensure entered passphrases are 203identical. 204This method only works with the pkcs5_pbkdf2/sha1 and pkcs5_pbkdf2 key 205generators. 206.El 207.Ss /etc/cgd/cgd.conf 208The file 209.Pa /etc/cgd/cgd.conf 210is used to configure 211.Nm 212if either of 213.Fl C 214or 215.Fl U 216are specified. 217Each line of the file is composed of either two or three 218tokens: cgd, target, and optional paramsfile. 219.Pp 220A 221.Sq \&# 222character is interpreted as a comment and indicates that the 223rest of the line should be ignored. 224A 225.Sq \e 226at the end of a line indicates that the next line is a continuation of 227the current line. 228.Pp 229See 230.Sx EXAMPLES 231for an example of 232.Pa /etc/cgd/cgd.conf . 233.Ss Parameters File 234The Parameters File contains the required information to generate the 235key and configure a device. 236These files are typically generated by the 237.Fl g 238flag and not edited by hand. 239When a device is configured the default parameters file is constructed 240by taking the basename of the target disk and prepending 241.Pa /etc/cgd/ 242to it. 243E.g., if the target is 244.Pa /dev/sd0h , 245then the default parameters file will be 246.Pa /etc/cgd/sd0h . 247.Pp 248It is possible to have more than one parameters file for a given 249disk which use different key generation methods but will generate 250the same key. 251To create a parameters file that is equivalent to an existing parameters 252file, use 253.Nm 254with the 255.Fl G 256flag. 257See 258.Sx EXAMPLES 259for an example of this usage. 260.Pp 261The parameters file contains a list of statements each terminated 262with a semi-colon. 263Some statements can contain statement-blocks which are either a 264single unadorned statement, or a brace-enclosed list of semicolon 265terminated statements. 266Three types of data are understood: 267.Pp 268.Bl -tag -compact -width integerxx 269.It integer 270a 32 bit signed integer. 271.It string 272a string. 273.It base64 274a length-encoded base64 string. 275.El 276.Pp 277The following statements are defined: 278.Bl -tag -width indentxx 279.It algorithm Ar string 280Defines the cryptographic algorithm. 281.It iv-method Ar string 282Defines the IV generation method. 283.It keylength Ar integer 284Defines the length of the key. 285.It verify_method Ar string 286Defines the verification method. 287.It keygen Ar string Ar statement_block 288Defines a key generation method. 289The 290.Ar statement_block 291contains statements that are specific to the key generation method. 292.El 293.Pp 294The keygen statement's statement block may contain the following statements: 295.Bl -tag -width indentxx 296.It key Ar string 297The key. 298Only used for the storedkey key generation method. 299.It cmd Ar string 300The command to execute. 301Only used for the shell_cmd key generation method. 302.It iterations Ar integer 303The number of iterations. 304Only used for pkcs5_pbkdf2/sha1 and pkcs5_pbkdf2. 305.It salt Ar base64 306The salt. 307Only used for pkcs5_pbkdf2/sha1 and pkcs5_pbkdf2. 308.El 309.Sh FILES 310.Bl -tag -width indentxxxxxxxxxxxxxxxxxx -compact 311.It Pa /etc/cgd/ 312configuration directory, used to store paramsfiles. 313.It Pa /etc/cgd/cgd.conf 314cgd configuration file. 315.El 316.Sh EXAMPLES 317To set up and configure a cgd that uses AES with a 192 bit key 318in CBC mode with the IV Method 319.Sq encblkno1 320(encrypted block number): 321.Bd -literal 322 # cgdconfig -g -o /etc/cgd/wd0e aes-cbc 192 323 # cgdconfig cgd0 /dev/wd0e 324 /dev/wd0e's passphrase: 325.Ed 326.Pp 327When using verification methods, the first time that we configure the 328disk the verification method will fail. 329We overcome this by supplying 330.Fl V Ar re-enter 331when we configure the first time to set up the disk. 332Here is the 333sequence of commands that is recommended: 334.Bd -literal 335 # cgdconfig -g -o /etc/cgd/wd0e -V disklabel aes-cbc 336 # cgdconfig -V re-enter cgd0 /dev/wd0e 337 /dev/wd0e's passphrase: 338 re-enter device's passphrase: 339 # disklabel -e -I cgd0 340 # cgdconfig -u cgd0 341 # cgdconfig cgd0 /dev/wd0e 342 /dev/wd0e's passphrase: 343.Ed 344.Pp 345To create a new parameters file that will generate the same key as an old 346parameters file: 347.Bd -literal 348 # cgdconfig -G -o newparamsfile oldparamsfile 349 old file's passphrase: 350 new file's passphrase: 351.Ed 352.Pp 353To configure a cgd that uses Blowfish with a 200 bit key that it 354reads from stdin: 355.Bd -literal 356 # cgdconfig -s cgd0 /dev/sd0h blowfish-cbc 200 357.Ed 358.Pp 359An example parameters file which uses PKCS#5 PBKDF2: 360.Bd -literal 361 algorithm aes-cbc; 362 iv-method encblkno1; 363 keylength 128; 364 verify_method none; 365 keygen pkcs5_pbkdf2/sha1 { 366 iterations 39361; 367 salt AAAAgMoHiYonye6Kog \\ 368 dYJAobCHE=; 369 }; 370.Ed 371.Pp 372An example parameters file which stores its key locally: 373.Bd -literal 374 algorithm aes-cbc; 375 iv-method encblkno1; 376 keylength 256; 377 verify_method none; 378 keygen storedkey key AAABAK3QO6d7xzLfrXTdsgg4 \\ 379 ly2TdxkFqOkYYcbyUKu/f60L; 380.Ed 381.Pp 382An example 383.Pa /etc/cgd/cgd.conf : 384.Bd -literal 385 # 386 # /etc/cgd/cgd.conf 387 # Configuration file for cryptographic disk devices 388 # 389 390 # cgd target [paramsfile] 391 cgd0 /dev/wd0e 392 cgd1 /dev/sd0h /usr/local/etc/cgd/sd0h 393.Ed 394.Pp 395Note that this will store the parameters file as 396.Pa /etc/cgd/wd0e . 397And use the entered passphrase to generate the key. 398.Sh DIAGNOSTICS 399.Bl -diag 400.It "cgdconfig: could not calibrate pkcs5_pbkdf2" 401An error greater than 5% in calibration occured. 402This could be the result of dynamic processor frequency scaling technology. 403Ensure that the processor clock frequency remains static throughout the 404program's execution. 405.El 406.Sh SEE ALSO 407.Xr cgd 4 408.Pp 409.Dq PKCS #5 v2.0: Password-Based Cryptography Standard , 410RSA Laboratories, March 25, 1999. 411.Sh HISTORY 412The 413.Nm 414utility appeared in 415.Nx 2.0 . 416.Sh BUGS 417Since 418.Nm 419uses 420.Xr getpass 3 421to read in the passphrase, it is limited to 128 characters. 422