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