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