1.\" $NetBSD: cgdconfig.8,v 1.8 2002/10/13 01:30:29 elric 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd September 23, 2002 38.Dt CGDCONFIG 8 39.Os 40.Sh NAME 41.Nm cgdconfig 42.Nd configuration utility for the cryptographic disk driver 43.Sh SYNOPSIS 44.Nm "" 45.Op Fl nv 46.Ar cgd dev 47.Op Ar paramsfile 48.Nm "" 49.Fl C 50.Op Fl nv 51.Op Fl f Ar configfile 52.Nm "" 53.Fl U 54.Op Fl nv 55.Op Fl f Ar configfile 56.Nm "" 57.Fl g 58.Op Fl nrv 59.Op Fl i Ar ivmeth 60.Op Fl k Ar kgmeth 61.Op Fl o Ar outfile 62.Ar alg 63.Op Ar keylen 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.Ar cgd 76.Sh DESCRIPTION 77.Nm 78is used to configure and unconfigure cryptographic disk devices (cgds) 79and to maintain the configuration files that are associated with them. 80For more information about cgd see 81.Xr cgd 4 . 82.Pp 83The options are as follows: 84.Bl -tag -width configfilexxxx 85.It Fl C 86Configure all the devices listed in the cgd configuration file. 87.It Fl f Ar configfile 88Specify the configuration file explicitly, rather than defaulting to 89.Pa /etc/cgd/cgd.conf . 90.It Fl g 91Generate a paramsfile (to stdout). 92.It Fl i Ar ivmeth 93Specify the IV method (default: encblkno). 94.It Fl k Ar kgmeth 95Specify the key generation method (default: pkcs5_pbkdf2). 96.It Fl o Ar outfile 97When generating a 98.Ar paramsfile , 99store it in 100.Ar outfile . 101.It Fl s 102Read the key from stdin. 103.It Fl U 104Unconfigure all the devices listed in the cgd configuration file. 105.It Fl u 106Unconfigure a cgd. 107.It Fl V Ar vmeth 108Specify the verification method (default: none). 109.It Fl v 110Be verbose. 111May be specified multiple times. 112.El 113.Pp 114For more information about the cryptographic algorithms and IV methods 115supported, please refer to 116.Xr cgd 4 . 117.Ss Key Generation Methods 118The Key Generation Method refers to how the key should be generated. 119The methods and descriptions are as follows: 120.Bl -tag -width indentxxxxxx 121.It pkcs5_pbkdf2 122This method requires a passphrase which is entered at configuration 123time. 124It is a salted hmac-based scheme detailed in 125.Dq PKCS#5 v2.0: Password-Based Cryptography Standard , 126RSA Laboratories, March 25, 1999, pages 8-10. 127PKCS #5 was also republished as RFC 2898. 128.It randomkey 129The method simply reads 130.Pa /dev/random 131and uses the resulting bits as the key. 132It does not require a passphrase to be entered. 133This method is typically used to present disk devices that do not 134need to survive a reboot, such as the swap partition. 135It is also handy to facilitate overwriting the contents of 136a disk volume with meaningless data prior to use. 137.El 138.Ss Verification Method 139The verification method is how 140.Nm 141determines if the passphrase that has been entered is correct. 142If the newly configured disk fails to verify, then 143.Nm 144will ask for the passphrase again and re-configure the device. 145The following verification methods are supported: 146.Pp 147.Bl -tag -width indentxxx 148.It none 149perform no verification. 150.It disklabel 151scan for a valid disklabel. 152.El 153.Ss /etc/cgd/cgd.conf 154The file 155.Pa /etc/cgd/cgd.conf 156is used to configure 157.Nm 158if either of 159.Fl C 160or 161.Fl U 162are specified. 163Each line of the file is composed of either two or three 164tokens: cgd, target, and optional paramsfile. 165.Pp 166A 167.Sq \&# 168character is interpreted as a comment and indicated that the 169rest of the line should be ignored. 170A 171.Sq \e 172at the end of a line indicates that the next line is a continuation of 173the current line. 174.Pp 175See 176.Sx EXAMPLES 177for an example of 178.Pa /etc/cgd/cgd.conf . 179.Ss Parameters File 180The Parameters File contains the required information to generate the 181key and configure a device. 182These files are typically generated by with the 183.Fl g 184flag and not edited by hand. 185When a device is configured the default parameters file is constructed 186by taking the basename of the target disk and prepending 187.Pa /etc/cgd/ 188to it. 189E.g., if the target is 190.Pa /dev/sd0h , 191then the default parameters file will be 192.Pa /etc/cgd/sd0h . 193.Pp 194The parameters file contains a list of key-value pairs which are 195specified one per line. 196Comments and line continuation work in the same way as for 197.Pa /etc/cgd/cgd.conf . 198.Pp 199The keys are as follows: 200.Bl -tag -width indentxxxxxxx 201.It algorithm 202The cryptographic algorithm. 203.It iv-method 204The IV generation method. 205.It keylength 206The length of the key. 207.It keygen_method 208The method used to generate the key. 209.It keygen_salt 210If the keygen_method requires a salt, then this is the salt. 211It is base64 encoded. 212.It xor_key 213If this is present, then it will be XOR'ed with the generated key before 214the device is configured. 215This can be used if the parameters file is 216stored on separate removable media, e.g. USB mass storage, to ensure that 217the generated key is immune to passphrase-guessing attacks. 218It is not valuable unless the parameters file is stored on removable media. 219It is base64 encoded. 220.It verify_method 221The verification method. 222.El 223.Sh FILES 224.Bl -tag -width indentxxxxxxxxxxxxxxxxxx -compact 225.It Pa /etc/cgd/ 226configuration directory, used to store paramsfiles. 227.It Pa /etc/cgd/cgd.conf 228cgd configuration file. 229.El 230.Sh EXAMPLES 231To set up and configure a cgd that uses AES with a 192 bit key 232in CBC mode with the IV Method 233.Sq encblkno 234(encrypted block number): 235.Bd -literal 236 # cgdconfig -g -o /etc/cgd/wd0e aes-cbc 192 237 # cgdconfig cgd0 /dev/wd0e 238 /dev/wd0e's passphrase: 239.Ed 240.Pp 241To configure a cgd that uses Blowfish with a 200 bit key that it 242reads from stdin: 243.Bd -literal 244 # cgdconfig -s cgd0 /dev/sd0h blowfish-cbc 200 245.Ed 246.Pp 247An example 248.Pa /etc/cgd/cgd.conf : 249.Bd -literal 250 # 251 # /etc/cgd/cgd.conf 252 # Configuration file for cryptographic disk devices 253 # 254 255 # cgd target [paramsfile] 256 cgd0 /dev/wd0e 257 cgd1 /dev/sd0h /usr/local/etc/cgd/sd0h 258.Ed 259.Pp 260Note that this will store the parameters file as 261.Pa /etc/cgd/wd0e . 262And use the entered passphrase to generate the key. 263.Sh SEE ALSO 264.Xr cgd 4 265.Pp 266.Dq PKCS #5 v2.0: Password-Based Cryptography Standard , 267RSA Laboratories, March 25, 1999. 268.Sh HISTORY 269The 270.Nm 271utility appeared in 272.Nx 1.7 . 273.Sh BUGS 274Since 275.Nm 276uses 277.Xr getpass 3 278to read in the passphrase, it is limited to 128 characters. 279