chiark / gitweb /
configure.ac: Abolish use of `libtool'.
[tripe] / keys / tripe-keys.8.in
CommitLineData
060ca767 1.\" -*-nroff-*-
2.\".
fc916a09
MW
3.\" Manual for the key-management tool
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.\"--------------------------------------------------------------------------
0647ba7c 30.TH tripe-keys 8tripe "14 September 2005" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
fc916a09
MW
31.
32.\"--------------------------------------------------------------------------
060ca767 33.SH "NAME"
fc916a09 34.
060ca767 35tripe-keys \- simple centralized key management for tripe
fc916a09
MW
36.
37.\"--------------------------------------------------------------------------
060ca767 38.SH "SYNOPSIS"
fc916a09 39.
060ca767 40.B tripe-keys
41.I operation
42.IP "Operations supported:"
c77687d5 43.BI "help \fR[" command \fR]
44.br
45.B "setup"
46.br
47.B "upload"
060ca767 48.br
49.BI "generate " tag
50.br
51.B "update"
52.br
c77687d5 53.B "newmaster"
060ca767 54.br
c77687d5 55.B "rebuild"
060ca767 56.br
c77687d5 57.B "clean"
65faf8df 58.br
c2f28e4b
MW
59.B "check"
60.br
65faf8df 61.BR "mtu " [ \fIpath-mtu ]
fc916a09
MW
62.
63.\"--------------------------------------------------------------------------
060ca767 64.SH "DESCRIPTION"
fc916a09 65.
060ca767 66The
67.B tripe-keys
68script implements a very simple, centralized key management system for
69.BR tripe (8).
70It assumes that there is a central authority who knows all the public
71keys for a private network.
72.SS "Overview"
73The
74.B tripe-keys
75program maintains a
76.I repository
77of public keys. It provides a way for a master authority to publish the
78repository and for clients to obtain authentic copies of it.
79.PP
80The repository is very simple: it consists of a directory
81.B repos
82full of public-key files, each named
83.BI peer- tag .pub \fR.
84.PP
85The repository setup process creates a master signing key, stored in the
86.B master
87keyring, and a key describing the parameters to be used for generating
88key-exchange keys, stored in
89.BR repos/param .
90.PP
91The master authority has a configuration file
92.BR tripe-keys.master ,
e04c2d50 93usually created by copying the template provided and editing it.
060ca767 94.PP
95The published repository consists of a tarball of the
96.B repos
97directory, containing the key-generation parameters and all the peers'
98public keys, and a client configuration file
99.BR tripe-keys.conf .
100The tarball is signed by the master authority's signing key.
101.PP
102The client configuration file is essentially a copy of
103.B tripe-keys.master
104with some extra bits filled in: in particular, it contains the
105fingerprint of the master signing key, so that the client can be sure
106it's checking the right key.
107.PP
108A peer starts by downloading a copy of
109.B tripe-keys.conf
110and then making sure it's authentic. (This is one of the tricky bits.
e04c2d50 111The other is getting public keys back to the master authority.) This is
060ca767 112enough for the peer to fetch a copy of the repository, verify the
113signature, and assemble a public keyring for the other peers in the
114network.
115.PP
116In fact, it's not
117.I quite
118that simple. The system allows new signing keys to replace old ones, so
119in fact the publication process signs the repository archive using a
120collection of keys. Each signing key is given a sequence number. The
121client configuration file contains the sequence number of the master
122signing key whose fingerprint it knows. During an update, the right
123signature is fetched and checked; if there's a new master key, then the
124.B tripe-keys.conf
125in the new repository archive will have its sequence number and
126fingerprint: the update process will replace its configuration file with
127the new version, and the peer will use the new key from then on.
128.SS "Options"
129The
130.B tripe-keys
131program accepts some standard command-line options:
132.TP
133.B "\-h, \-\-help"
134Print general help about
135.B tripe-keys
136to standard output and exit successfully.
137.TP
138.B "\-v, \-\-version"
139Print the version number of
140.B tripe-keys
141to standard output and exit successfully.
142.TP
143.B "\-u, \-\-usage"
144Print brief usage about
145.B tripe-keys
146to standard output and exit successfully.
147.SS "Subcommands"
148.TP
c77687d5 149.BI "help \fR[" command \fR]
060ca767 150With no arguments, shows help, as for the
151.B \-\-help
152option. With an argument, shows help about that
153.IR command .
154.TP
155.B "setup"
e04c2d50 156Constructs a new repository and makes a signing key (as for
060ca767 157.BR newmaster )
158and key-exchange parameters. Fails if
159.B repos
160already exists.
161.TP
162.B "upload"
163Build a repository archive, sign it with the active signing keys, and
164make a
165.B tripe-keys.conf
166file. Copy the results to the places named by
167.IR repos-file ,
168.IR sig-file ,
169and
170.I conf-file
838e5ce7
MW
171respectively. Remove unexpected files from the
172.IR base-dir ,
173since these tend to be signatures made by old master keys which don't
174work any more. Run the
f8fb566e
MW
175.I upload-hook
176to copy things into the right places.
060ca767 177.TP
178.BI "generate " tag
179Generate a peer key for the peer named
180.IR tag .
181The private key ends up in
182.BR keyring ;
183the public key is written to
184.BI peer- tag .pub
185in the
186.I current
187directory.
188.TP
189.B update
190Fetches a new copy of the repository archive and its signature. It
191unpacks the archive in a temporary directory, and checks the enclosed
192master public key against the fingerprint in the configuration file. It
193then verifies the signature on the archive using this public key. If
194all is well, it replaces the current
195.B repos
196directory with the version in the new archive, and if necessary it
197replaces the current configuration file with the new one in the
e04c2d50 198archive. It then does a
060ca767 199.B rebuild
200to construct a new
201.B keyring.pub
202file.
203.TP
204.B newmaster
205Generates a new master signing key. The old master key is not deleted.
206.TP
207.B rebuild
208Rebuilds the public keyring
209.B keyring.pub
210from the public keys in the
211.B repos
212directory.
213.TP
214.B clean
215Deletes everything which
216.B tripe-keys
217might have written to a directory. In particular, it deletes
218.BR repos ,
219.BR tmp ,
220.BR master ,
221.BR keyring ,
222.BR keying.pub ,
223and their associated
224.B .old
225files.
65faf8df 226.TP
c2f28e4b
MW
227.B check
228Checks the various keyrings. Currently, it checks the
229.B master
230and
231.B keyring.pub
232files, and prints a report warning of keys which will expire soon. It
233is expected that this command be run against the master repository by
234.BR cron (8).
235Additional checking may added in the future.
236.TP
65faf8df
MW
237.BR "mtu " [ \fIpath-mtu ]
238Write, as a decimal number on standard output, the recommended MTU for a
239TrIPE tunnel interface, given that the
240.I path-mtu
241between two peers is as specified. The default is 1500, which is very
242commonly correct, but you should check using a tool such as
e7c18650 243.BR pathmtu (1).
65faf8df
MW
244Getting the MTU too big will lead to unnecessary fragmentation of
245TrIPE's UDP datagrams; getting it too small will fail to utilize the
246underlying network effectively. If in doubt, it's therefore better to
247underestimate.
fc916a09
MW
248.
249.\"--------------------------------------------------------------------------
060ca767 250.SH "SEE ALSO"
fc916a09 251.
060ca767 252.BR key (1),
253.BR tripe\-keys.conf (5),
254.BR tripe (8).
fc916a09
MW
255.
256.\"--------------------------------------------------------------------------
060ca767 257.SH "AUTHOR"
fc916a09 258.
060ca767 259Mark Wooding, <mdw@distorted.org.uk>
fc916a09
MW
260.
261.\"----- That's all, folks --------------------------------------------------