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