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