Commit | Line | Data |
---|---|---|
060ca767 | 1 | .\" -*-nroff-*- |
2 | .\". | |
fc916a09 MW |
3 | .\" Manual for the key-management configuration files |
4 | .\" | |
5 | .\" (c) 2008 Straylight/Edgeware | |
6 | .\" | |
7 | . | |
8 | .\"----- Licensing notice --------------------------------------------------- | |
9 | .\" | |
10 | .\" This file is part of Trivial IP Encryption (TrIPE). | |
11 | .\" | |
11ad66c2 MW |
12 | .\" TrIPE is free software: you can redistribute it and/or modify it under |
13 | .\" the terms of the GNU General Public License as published by the Free | |
14 | .\" Software Foundation; either version 3 of the License, or (at your | |
15 | .\" option) any later version. | |
fc916a09 | 16 | .\" |
11ad66c2 MW |
17 | .\" TrIPE is distributed in the hope that it will be useful, but WITHOUT |
18 | .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
19 | .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
20 | .\" for more details. | |
fc916a09 MW |
21 | .\" |
22 | .\" You should have received a copy of the GNU General Public License | |
11ad66c2 | 23 | .\" along with TrIPE. If not, see <https://www.gnu.org/licenses/>. |
fc916a09 MW |
24 | . |
25 | .\"-------------------------------------------------------------------------- | |
e99aedcf | 26 | .so ../common/defs.man \" @@@PRE@@@ |
fc916a09 MW |
27 | . |
28 | .\"-------------------------------------------------------------------------- | |
0647ba7c | 29 | .TH tripe-keys.conf 5tripe "14 September 2005" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" |
fc916a09 MW |
30 | . |
31 | .\"-------------------------------------------------------------------------- | |
060ca767 | 32 | .SH "NAME" |
fc916a09 | 33 | . |
060ca767 | 34 | tripe-keys.conf \- configuration file format for tripe-keys |
fc916a09 MW |
35 | . |
36 | .\"-------------------------------------------------------------------------- | |
060ca767 | 37 | .SH "DESCRIPTION" |
fc916a09 | 38 | . |
060ca767 | 39 | The |
40 | .B tripe-keys.master | |
41 | or | |
42 | .B tripe-keys.conf | |
43 | file is a simple line-based configuration file read by | |
44 | .BR tripe-keys (1). | |
45 | Lines may be empty (consist only of whitespace), be comments (first | |
46 | non-whitespace character is | |
47 | .RB ` # ') | |
48 | or have the form | |
49 | .IP | |
50 | .I name | |
51 | .RB [ = ] | |
52 | .I value | |
53 | .PP | |
54 | A | |
55 | .I name | |
56 | consists of alphanumeric characters and hyphens. Values may contain | |
57 | substitutions, of the form | |
58 | .BI ${ name } \fR, | |
59 | which are replaced by the value assigned to | |
60 | .IR name . | |
e04c2d50 | 61 | Many |
060ca767 | 62 | .IR name s |
63 | have significance to the | |
64 | .B tripe-keys | |
65 | program: these are described below. Many have sensible defaults. | |
66 | .SS "The tripe-keys.master file" | |
67 | The client configuration file is built by applying substitutions to the | |
68 | .B tripe-keys.master | |
69 | file. The following tokens are substituted: | |
70 | .TP | |
71 | .B @MASTER-SEQUENCE@ | |
72 | The sequence number of the most recently-added signing key. | |
73 | .TP | |
74 | .B @HK-MASTER@ | |
75 | The fingerprint of the signing key identified by | |
76 | .BR @MASTER-SEQUENCE@ . | |
77 | .SS "Master repository parameters" | |
78 | .TP | |
79 | .I base-url | |
80 | The base URL of the key repository (usually with a trailing | |
81 | .RB ` / '). | |
82 | Typically, this will be something like | |
83 | .RB http://www.distorted.org.uk/vpn/ . | |
84 | No default. | |
85 | .TP | |
86 | .I repos-base | |
87 | The basename for the repository archive. Default is | |
88 | .BR tripe-keys.tar.gz . | |
89 | .TP | |
90 | .I sig-base | |
91 | The basename template for repository signatures. Default is | |
92 | .BR tripe-keys.sig-<SEQ> . | |
93 | The | |
94 | .RB ` <SEQ> ' | |
95 | portion, if any, is replaced by the sequence number of the key which | |
96 | made the signature. | |
97 | .TP | |
98 | .I repos-url | |
99 | The URL for the key repository tarball. Default is the concatenation of | |
100 | .I base-url | |
101 | and | |
102 | .IR repos-base . | |
103 | .TP | |
104 | .I sig-url | |
105 | The URL template for key repository signatures. Default is the | |
106 | concatenation of | |
bdbd9326 | 107 | .I base-url |
060ca767 | 108 | and |
109 | .IR sig-base . | |
110 | .TP | |
111 | .I master-sequence | |
112 | The sequence number of the master authority's current signing key. No | |
113 | default. Usually set up automatically. | |
114 | .TP | |
7858dfa0 MW |
115 | .I master-keygen-flags |
116 | Additional options for generating master keys. Default is | |
117 | .RB ` -l '. | |
118 | .TP | |
67bb121f MW |
119 | .I master-attrs |
120 | Additional attributes to set on the master key, | |
121 | as | |
122 | .IB key = value | |
123 | pairs separated by spaces. | |
124 | Default is empty. | |
125 | .TP | |
060ca767 | 126 | .I hk-master |
127 | The fingerprint of the current master signing key. No default. Usually | |
128 | set up automatically. | |
b14ccd2f MW |
129 | .TP |
130 | .I upload-hook | |
131 | A shell command to run by | |
132 | .B tripe-keys upload | |
133 | after it has successfully written the | |
134 | .I repos-file | |
135 | and | |
136 | .IR sig-file s. | |
137 | Default is | |
138 | .B ": run upload hook" | |
139 | which does nothing. | |
060ca767 | 140 | .SS "Crypto parameters" |
141 | .TP | |
142 | .I kx | |
143 | Key-exchange algorithm to use. Either | |
e04c2d50 | 144 | .B dh |
060ca767 | 145 | (integer Diffie-Hellman) |
146 | or | |
147 | .B ec | |
148 | (elliptic curves). The default is | |
149 | .BR dh . | |
26936c83 | 150 | .ne 9 |
060ca767 | 151 | .TP |
256bc8d0 MW |
152 | .I kx-genalg |
153 | Key generation algorithm name to pass to | |
154 | .B "key add" | |
155 | when generating keys. | |
156 | Default depends on | |
157 | .I kx | |
158 | as follows. | |
159 | .TS | |
160 | center; | |
161 | | ci | ci | | |
162 | | lb | lb |. | |
163 | _ | |
164 | kx kx-genalg | |
165 | _ | |
166 | dh dh | |
167 | ec ec | |
26936c83 MW |
168 | x25519 x25519 |
169 | x448 x448 | |
256bc8d0 MW |
170 | _ |
171 | .TE | |
26936c83 | 172 | .ne 9 |
256bc8d0 MW |
173 | .TP |
174 | .I kx-param-genalg | |
175 | Key generation algorithm name to pass to | |
176 | .B "key add" | |
177 | when generating the parameters key. | |
178 | Default depends on | |
179 | .I kx | |
180 | as follows. | |
181 | .TS | |
182 | center; | |
183 | | ci | ci | | |
184 | | lb | lb |. | |
185 | _ | |
186 | kx kx-param-genalg | |
187 | _ | |
188 | dh dh-param | |
189 | ec ec-param | |
26936c83 MW |
190 | x25519 empty |
191 | x448 empty | |
256bc8d0 MW |
192 | _ |
193 | .TE | |
26936c83 | 194 | .ne 9 |
256bc8d0 | 195 | .TP |
060ca767 | 196 | .I kx-param |
197 | Options to pass to | |
198 | .B "key add" | |
199 | when generating the parameters key. Default depends on | |
200 | .I kx | |
201 | as follows. | |
202 | .TS | |
203 | center; | |
204 | | ci | ci | | |
205 | | lb | lb |. | |
206 | _ | |
207 | kx kx-param | |
208 | _ | |
ca3aaaeb | 209 | dh \-LS \-b3072 \-B256 |
060ca767 | 210 | ec \-Cnist-p256 |
26936c83 MW |
211 | x25519 \fInone |
212 | x448 \fInone | |
060ca767 | 213 | _ |
214 | .TE | |
26936c83 | 215 | .ne 9 |
060ca767 | 216 | .TP |
67bb121f MW |
217 | .I kx-attrs |
218 | Additional attributes to set on the parameters | |
219 | (and therefore copied to peer keys), | |
220 | as | |
221 | .IB key = value | |
222 | pairs separated by spaces. | |
26936c83 MW |
223 | Default depends on |
224 | .I kx | |
225 | as follows. | |
226 | .TS | |
227 | center; | |
228 | | ci | ci | | |
229 | | lb | lb |. | |
230 | _ | |
231 | kx kx-attrs | |
232 | _ | |
233 | dh serialization=constlen | |
234 | ec serialization=constlen | |
235 | x25519 \fIempty | |
236 | x448 \fIempty | |
237 | _ | |
238 | .TE | |
67bb121f | 239 | .TP |
060ca767 | 240 | .I kx-expire |
241 | Expiry time for generated keys. Default is | |
ca3aaaeb | 242 | .BR "now + 1 year" . |
060ca767 | 243 | .TP |
244 | .I hash | |
245 | Hashing algorithm to use. Default is | |
246 | .BR sha256 . | |
247 | .TP | |
39bcd193 MW |
248 | .I bulk |
249 | The bulk crypto transform to use. | |
250 | Default is | |
251 | .BR iiv . | |
de8edc7f MW |
252 | .ne 8 |
253 | .TP | |
060ca767 | 254 | .I mac |
de8edc7f MW |
255 | Message authentication algorithm to use. |
256 | Default depends on | |
257 | .I bulk | |
258 | as follows. | |
259 | .TS | |
260 | center; | |
261 | | ci | ci | | |
262 | | lb | lb |. | |
263 | _ | |
264 | bulk mac | |
265 | _ | |
266 | v0 \fIhash\fB-hmac/\fIhalfhashlen | |
267 | iiv \fIhash\fB-hmac/\fIhalfhashlenrijndael-cbc | |
268 | naclbox poly1305/128 | |
269 | _ | |
270 | .TE | |
271 | .IP | |
272 | (In the above, | |
060ca767 | 273 | .I halfhashlen |
274 | is half of | |
275 | .IR hash 's | |
de8edc7f | 276 | output length.) |
060ca767 | 277 | .TP |
278 | .I mgf | |
279 | Mask-generation algorithm to use. Default is | |
280 | .IB hash -mgf \fR. | |
281 | This is probably a good choice. | |
de8edc7f | 282 | .ne 7 |
060ca767 | 283 | .TP |
284 | .I cipher | |
de8edc7f MW |
285 | Symmetric encryption scheme to use. |
286 | Default depends on | |
287 | .I bulk | |
288 | as follows. | |
289 | .TS | |
290 | center; | |
291 | | ci | ci | | |
292 | | lb | lb |. | |
293 | _ | |
294 | bulk cipher | |
295 | _ | |
296 | v0 rijndael-cbc | |
297 | iiv rijndael-cbc | |
298 | naclbox chacha20 | |
299 | _ | |
300 | .TE | |
26936c83 | 301 | .ne 8 |
060ca767 | 302 | .TP |
303 | .I sig | |
304 | Signature scheme to use. Must be one of those recognized by | |
305 | .BR catsign (1). | |
b86e6f3f | 306 | Default depends on |
060ca767 | 307 | .I kx |
b86e6f3f MW |
308 | as follows. |
309 | .TS | |
310 | center; | |
311 | | ci | ci | | |
312 | | lb | lb |. | |
313 | _ | |
314 | kx sig | |
315 | _ | |
316 | dh dsa | |
317 | ec ecdsa | |
26936c83 MW |
318 | x25519 ed25519 |
319 | x448 ed448 | |
b86e6f3f MW |
320 | _ |
321 | .TE | |
06a174df | 322 | .ne 12 |
060ca767 | 323 | .TP |
324 | .I sig-genalg | |
e04c2d50 | 325 | Key-generation algorithm for signing key. Default depends on |
060ca767 | 326 | .I sig |
327 | as follows. | |
328 | .TS | |
329 | center; | |
330 | | ci | ci | | |
331 | | lb | lb |. | |
332 | _ | |
333 | sig sig-genalg | |
334 | _ | |
335 | kcdsa dh | |
336 | dsa dsa | |
f3664e7c | 337 | rsapkcs1 rsa |
060ca767 | 338 | rsapss rsa |
339 | ecdsa ec | |
340 | eckcdsa ec | |
06a174df MW |
341 | ed25519 ed25519 |
342 | ed448 ed448 | |
060ca767 | 343 | _ |
344 | .TE | |
06a174df | 345 | .ne 10 |
060ca767 | 346 | .TP |
347 | .I sig-param | |
348 | Signature-key generation parameters. Default depends on | |
349 | .I sig-genalg | |
350 | as follows. | |
351 | .TS | |
352 | center; | |
353 | | ci | ci | | |
354 | | lb | lb |. | |
355 | _ | |
356 | sig-genalg sig-param | |
357 | _ | |
ca3aaaeb MW |
358 | dh \-LS \-b3072 \-B256 |
359 | dsa \-b3072 \-B256 | |
360 | rsa \-b3072 | |
060ca767 | 361 | ec \-Cnist-p256 |
06a174df MW |
362 | ed25519 \fInone |
363 | ed448 \fInone | |
060ca767 | 364 | _ |
365 | .TE | |
366 | .TP | |
367 | .I sig-hash | |
368 | Hash function to use for making signatures. Default is | |
369 | .IR hash . | |
370 | .TP | |
371 | .I sig-fresh | |
372 | Oldest time we should consider a signed archive to be fresh. Default is | |
373 | .BR always , | |
374 | meaning that all signatures are fresh. | |
375 | .TP | |
376 | .I sig-expire | |
377 | Expiry time for master signing key. Default is | |
378 | .BR forever . | |
379 | .TP | |
380 | .I fingerprint-hash | |
381 | Hash function to use for key fingerprinting. Default is | |
382 | .IR hash . | |
383 | .SS "Master maintenance parameters" | |
384 | .TP | |
385 | .I base-dir | |
386 | Local base directory for the repository files. This probably ought to | |
387 | end in a | |
388 | .RB ` / ' | |
838e5ce7 MW |
389 | character. Unexpected files in this directory will be removed by the |
390 | .B tripe-keys upload | |
391 | command. No default. | |
060ca767 | 392 | .TP |
393 | .I repos-file | |
394 | Filename for local repository tarball. Default is the concatenation of | |
395 | .I base-dir | |
396 | and | |
397 | .IB repos-base . | |
398 | .TP | |
399 | .I sig-file | |
ca3aaaeb | 400 | Template for repository signatures. Default is the concatenation of |
060ca767 | 401 | .I base-dir |
402 | and | |
403 | .IR sig-base . | |
404 | .TP | |
405 | .I conf-file | |
406 | Filename for local repository configuration file. Default is | |
407 | .IB basedir /tripe-keys.conf \fR. | |
c2f28e4b MW |
408 | .TP |
409 | .I kx-warn-days | |
410 | The | |
411 | .B "tripe-keys check" | |
412 | command will warn about keys which will in less than | |
413 | .I kx-warn-days | |
414 | days. Default is 28. | |
fc916a09 MW |
415 | . |
416 | .\"-------------------------------------------------------------------------- | |
060ca767 | 417 | .SH "SEE ALSO" |
fc916a09 | 418 | . |
060ca767 | 419 | .BR tripe (8), |
420 | .BR tripe\-keys (8). | |
fc916a09 MW |
421 | . |
422 | .\"-------------------------------------------------------------------------- | |
060ca767 | 423 | .SH "AUTHOR" |
fc916a09 | 424 | . |
060ca767 | 425 | Mark Wooding, <mdw@distorted.org.uk> |
fc916a09 MW |
426 | . |
427 | .\"----- That's all, folks -------------------------------------------------- |