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