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