chiark / gitweb /
tripe-keys.conf.5: Description of sig-url shouldn't be circular!
[tripe] / keys / tripe-keys.conf.5
1 .\" -*-nroff-*-
2 .\".
3 .de hP
4 .IP
5 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
6 ..
7 .de VS
8 .sp 1
9 .RS
10 .nf
11 .ft B
12 ..
13 .de VE
14 .ft R
15 .fi
16 .RE
17 .sp 1
18 ..
19 .ie t \{\
20 .  ds o \(bu
21 .  ds ss \s8\u
22 .  ds se \d\s0
23 .  if \n(.g \{\
24 .    fam P
25 .  \}
26 .\}
27 .el \{\
28 .  ds o o
29 .  ds ss ^
30 .  ds se
31 .\}
32 .TH tripe-keys.conf 5 "14 September 2005" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
33 .SH "NAME"
34 tripe-keys.conf \- configuration file format for tripe-keys
35 .SH "DESCRIPTION"
36 The
37 .B tripe-keys.master
38 or
39 .B tripe-keys.conf
40 file is a simple line-based configuration file read by
41 .BR tripe-keys (1).
42 Lines may be empty (consist only of whitespace), be comments (first
43 non-whitespace character is
44 .RB ` # ')
45 or have the form
46 .IP
47 .I name
48 .RB [ = ]
49 .I value
50 .PP
51 A
52 .I name
53 consists of alphanumeric characters and hyphens.  Values may contain
54 substitutions, of the form
55 .BI ${ name } \fR,
56 which are replaced by the value assigned to
57 .IR name .
58 Many
59 .IR name s
60 have significance to the
61 .B tripe-keys
62 program: these are described below.  Many have sensible defaults.
63 .SS "The tripe-keys.master file"
64 The client configuration file is built by applying substitutions to the
65 .B tripe-keys.master
66 file.  The following tokens are substituted:
67 .TP
68 .B @MASTER-SEQUENCE@
69 The sequence number of the most recently-added signing key.
70 .TP
71 .B @HK-MASTER@
72 The fingerprint of the signing key identified by
73 .BR @MASTER-SEQUENCE@ .
74 .SS "Master repository parameters"
75 .TP
76 .I base-url
77 The base URL of the key repository (usually with a trailing
78 .RB ` / ').
79 Typically, this will be something like
80 .RB http://www.distorted.org.uk/vpn/ .
81 No default.
82 .TP
83 .I repos-base
84 The basename for the repository archive.  Default is
85 .BR tripe-keys.tar.gz .
86 .TP
87 .I sig-base
88 The basename template for repository signatures.  Default is
89 .BR tripe-keys.sig-<SEQ> .
90 The
91 .RB ` <SEQ> '
92 portion, if any, is replaced by the sequence number of the key which
93 made the signature.
94 .TP
95 .I repos-url
96 The URL for the key repository tarball.  Default is the concatenation of
97 .I base-url
98 and
99 .IR repos-base .
100 .TP
101 .I sig-url
102 The URL template for key repository signatures.  Default is the
103 concatenation of
104 .I base-url
105 and
106 .IR sig-base .
107 .TP
108 .I master-sequence
109 The sequence number of the master authority's current signing key.  No
110 default.  Usually set up automatically.
111 .TP
112 .I master-keygen-flags
113 Additional options for generating master keys.  Default is
114 .RB ` -l '.
115 .TP
116 .I hk-master
117 The fingerprint of the current master signing key.  No default.  Usually
118 set up automatically.
119 .TP
120 .I upload-hook
121 A shell command to run by
122 .B tripe-keys upload
123 after it has successfully written the
124 .I repos-file
125 and
126 .IR sig-file s.
127 Default is
128 .B ": run upload hook"
129 which does nothing.
130 .SS "Crypto parameters"
131 .TP
132 .I kx
133 Key-exchange algorithm to use.  Either
134 .B dh
135 (integer Diffie-Hellman)
136 or
137 .B ec
138 (elliptic curves).  The default is
139 .BR dh .
140 .TP
141 .I kx-param
142 Options to pass to
143 .B "key add"
144 when generating the parameters key.  Default depends on
145 .I kx
146 as follows.
147 .TS
148 center;
149 | ci | ci |
150 | lb | lb |.
151 _
152 kx      kx-param
153 _
154 dh      \-LS \-b2048 \-B256
155 ec      \-Cnist-p256
156 _
157 .TE
158 .TP
159 .I kx-expire
160 Expiry time for generated keys.  Default is
161 .BR "now + 1 day" .
162 .TP
163 .I hash
164 Hashing algorithm to use.  Default is
165 .BR sha256 .
166 .TP
167 .I mac
168 Message authentication algorithm to use.  Default is
169 .IB hash -hmac/ halfhashlen \fR,
170 where
171 .I halfhashlen
172 is half of
173 .IR hash 's
174 output length.
175 .TP
176 .I mgf
177 Mask-generation algorithm to use.  Default is
178 .IB hash -mgf \fR.
179 This is probably a good choice.
180 .TP
181 .I cipher
182 Symmetric encryption scheme to use.  Default is
183 .BR blowfish-cbc .
184 .TP
185 .I sig
186 Signature scheme to use.  Must be one of those recognized by
187 .BR catsign (1).
188 Default is
189 .B dsa
190 if
191 .I kx
192 is
193 .BR dh ,
194 or
195 .B ecdsa
196 if
197 .I kx
198 is
199 .BR ec .
200 .TP
201 .I sig-genalg
202 Key-generation algorithm for signing key.  Default depends on
203 .I sig
204 as follows.
205 .TS
206 center;
207 | ci | ci |
208 | lb | lb |.
209 _
210 sig     sig-genalg
211 _
212 kcdsa   dh
213 dsa     dsa
214 rsapcs1 rsa
215 rsapss  rsa
216 ecdsa   ec
217 eckcdsa ec
218 _
219 .TE
220 .TP
221 .I sig-param
222 Signature-key generation parameters.  Default depends on
223 .I sig-genalg
224 as follows.
225 .TS
226 center;
227 | ci | ci |
228 | lb | lb |.
229 _
230 sig-genalg      sig-param
231 _
232 dh      \-LS \-b2048 \-B256
233 dsa     \-b2048 \-B256
234 rsa     \-b2048
235 ec      \-Cnist-p256
236 _
237 .TE
238 .TP
239 .I sig-hash
240 Hash function to use for making signatures.  Default is
241 .IR hash .
242 .TP
243 .I sig-fresh
244 Oldest time we should consider a signed archive to be fresh.  Default is
245 .BR always ,
246 meaning that all signatures are fresh.
247 .TP
248 .I sig-expire
249 Expiry time for master signing key.  Default is
250 .BR forever .
251 .TP
252 .I fingerprint-hash
253 Hash function to use for key fingerprinting.  Default is
254 .IR hash .
255 .SS "Master maintenance parameters"
256 .TP
257 .I base-dir
258 Local base directory for the repository files.  This probably ought to
259 end in a
260 .RB ` / '
261 character.  No default.
262 .TP
263 .I repos-file
264 Filename for local repository tarball.  Default is the concatenation of
265 .I base-dir
266 and
267 .IB repos-base .
268 .TP
269 .I sig-file
270 Tempalte for repository signatures.  Default is the concatenation of
271 .I base-dir
272 and
273 .IR sig-base .
274 .TP
275 .I conf-file
276 Filename for local repository configuration file.  Default is
277 .IB basedir /tripe-keys.conf \fR.
278 .SH "SEE ALSO"
279 .BR tripe (8),
280 .BR tripe\-keys (8).
281 .SH "AUTHOR"
282 Mark Wooding, <mdw@distorted.org.uk>