chiark / gitweb /
src/tripe-ifup.in: Hack IPv6 up on VPN interfaces.
[tripe] / keys / tripe-keys.conf.5.in
1 .\" -*-nroff-*-
2 .\".
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 .\"--------------------------------------------------------------------------
27 .so ../common/defs.man \" @@@PRE@@@
28 .
29 .\"--------------------------------------------------------------------------
30 .TH tripe-keys.conf 5 "14 September 2005" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
31 .
32 .\"--------------------------------------------------------------------------
33 .SH "NAME"
34 .
35 tripe-keys.conf \- configuration file format for tripe-keys
36 .
37 .\"--------------------------------------------------------------------------
38 .SH "DESCRIPTION"
39 .
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 .
62 Many
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
108 .I base-url
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
116 .I master-keygen-flags
117 Additional options for generating master keys.  Default is
118 .RB ` -l '.
119 .TP
120 .I hk-master
121 The fingerprint of the current master signing key.  No default.  Usually
122 set up automatically.
123 .TP
124 .I upload-hook
125 A shell command to run by
126 .B tripe-keys upload
127 after it has successfully written the
128 .I repos-file
129 and
130 .IR sig-file s.
131 Default is
132 .B ": run upload hook"
133 which does nothing.
134 .SS "Crypto parameters"
135 .TP
136 .I kx
137 Key-exchange algorithm to use.  Either
138 .B dh
139 (integer Diffie-Hellman)
140 or
141 .B ec
142 (elliptic curves).  The default is
143 .BR dh .
144 .TP
145 .I kx-param
146 Options to pass to
147 .B "key add"
148 when generating the parameters key.  Default depends on
149 .I kx
150 as follows.
151 .TS
152 center;
153 | ci | ci |
154 | lb | lb |.
155 _
156 kx      kx-param
157 _
158 dh      \-LS \-b3072 \-B256
159 ec      \-Cnist-p256
160 _
161 .TE
162 .TP
163 .I kx-expire
164 Expiry time for generated keys.  Default is
165 .BR "now + 1 year" .
166 .TP
167 .I hash
168 Hashing algorithm to use.  Default is
169 .BR sha256 .
170 .TP
171 .I mac
172 Message authentication algorithm to use.  Default is
173 .IB hash -hmac/ halfhashlen \fR,
174 where
175 .I halfhashlen
176 is half of
177 .IR hash 's
178 output length.
179 .TP
180 .I mgf
181 Mask-generation algorithm to use.  Default is
182 .IB hash -mgf \fR.
183 This is probably a good choice.
184 .TP
185 .I cipher
186 Symmetric encryption scheme to use.  Default is
187 .BR blowfish-cbc .
188 .TP
189 .I sig
190 Signature scheme to use.  Must be one of those recognized by
191 .BR catsign (1).
192 Default is
193 .B dsa
194 if
195 .I kx
196 is
197 .BR dh ,
198 or
199 .B ecdsa
200 if
201 .I kx
202 is
203 .BR ec .
204 .TP
205 .I sig-genalg
206 Key-generation algorithm for signing key.  Default depends on
207 .I sig
208 as follows.
209 .TS
210 center;
211 | ci | ci |
212 | lb | lb |.
213 _
214 sig     sig-genalg
215 _
216 kcdsa   dh
217 dsa     dsa
218 rsapcs1 rsa
219 rsapss  rsa
220 ecdsa   ec
221 eckcdsa ec
222 _
223 .TE
224 .TP
225 .I sig-param
226 Signature-key generation parameters.  Default depends on
227 .I sig-genalg
228 as follows.
229 .TS
230 center;
231 | ci | ci |
232 | lb | lb |.
233 _
234 sig-genalg      sig-param
235 _
236 dh      \-LS \-b3072 \-B256
237 dsa     \-b3072 \-B256
238 rsa     \-b3072
239 ec      \-Cnist-p256
240 _
241 .TE
242 .TP
243 .I sig-hash
244 Hash function to use for making signatures.  Default is
245 .IR hash .
246 .TP
247 .I sig-fresh
248 Oldest time we should consider a signed archive to be fresh.  Default is
249 .BR always ,
250 meaning that all signatures are fresh.
251 .TP
252 .I sig-expire
253 Expiry time for master signing key.  Default is
254 .BR forever .
255 .TP
256 .I fingerprint-hash
257 Hash function to use for key fingerprinting.  Default is
258 .IR hash .
259 .SS "Master maintenance parameters"
260 .TP
261 .I base-dir
262 Local base directory for the repository files.  This probably ought to
263 end in a
264 .RB ` / '
265 character.  No default.
266 .TP
267 .I repos-file
268 Filename for local repository tarball.  Default is the concatenation of
269 .I base-dir
270 and
271 .IB repos-base .
272 .TP
273 .I sig-file
274 Template for repository signatures.  Default is the concatenation of
275 .I base-dir
276 and
277 .IR sig-base .
278 .TP
279 .I conf-file
280 Filename for local repository configuration file.  Default is
281 .IB basedir /tripe-keys.conf \fR.
282 .TP
283 .I kx-warn-days
284 The
285 .B "tripe-keys check"
286 command will warn about keys which will in less than
287 .I kx-warn-days
288 days.  Default is 28.
289 .
290 .\"--------------------------------------------------------------------------
291 .SH "SEE ALSO"
292 .
293 .BR tripe (8),
294 .BR tripe\-keys (8).
295 .
296 .\"--------------------------------------------------------------------------
297 .SH "AUTHOR"
298 .
299 Mark Wooding, <mdw@distorted.org.uk>
300 .
301 .\"----- That's all, folks --------------------------------------------------