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