chiark / gitweb /
doc: Fix distribution of generated manpages.
[tripe] / doc / tripe-keys.8
CommitLineData
060ca767 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 8 "14 September 2005" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
33.SH "NAME"
34tripe-keys \- simple centralized key management for tripe
35.SH "SYNOPSIS"
36.B tripe-keys
37.I operation
38.IP "Operations supported:"
c77687d5 39.BI "help \fR[" command \fR]
40.br
41.B "setup"
42.br
43.B "upload"
060ca767 44.br
45.BI "generate " tag
46.br
47.B "update"
48.br
c77687d5 49.B "newmaster"
060ca767 50.br
c77687d5 51.B "rebuild"
060ca767 52.br
c77687d5 53.B "clean"
060ca767 54.SH "DESCRIPTION"
55The
56.B tripe-keys
57script implements a very simple, centralized key management system for
58.BR tripe (8).
59It assumes that there is a central authority who knows all the public
60keys for a private network.
61.SS "Overview"
62The
63.B tripe-keys
64program maintains a
65.I repository
66of public keys. It provides a way for a master authority to publish the
67repository and for clients to obtain authentic copies of it.
68.PP
69The repository is very simple: it consists of a directory
70.B repos
71full of public-key files, each named
72.BI peer- tag .pub \fR.
73.PP
74The repository setup process creates a master signing key, stored in the
75.B master
76keyring, and a key describing the parameters to be used for generating
77key-exchange keys, stored in
78.BR repos/param .
79.PP
80The master authority has a configuration file
81.BR tripe-keys.master ,
82usually created by copying the template provided and editing it.
83.PP
84The published repository consists of a tarball of the
85.B repos
86directory, containing the key-generation parameters and all the peers'
87public keys, and a client configuration file
88.BR tripe-keys.conf .
89The tarball is signed by the master authority's signing key.
90.PP
91The client configuration file is essentially a copy of
92.B tripe-keys.master
93with some extra bits filled in: in particular, it contains the
94fingerprint of the master signing key, so that the client can be sure
95it's checking the right key.
96.PP
97A peer starts by downloading a copy of
98.B tripe-keys.conf
99and then making sure it's authentic. (This is one of the tricky bits.
100The other is getting public keys back to the master authority.) This is
101enough for the peer to fetch a copy of the repository, verify the
102signature, and assemble a public keyring for the other peers in the
103network.
104.PP
105In fact, it's not
106.I quite
107that simple. The system allows new signing keys to replace old ones, so
108in fact the publication process signs the repository archive using a
109collection of keys. Each signing key is given a sequence number. The
110client configuration file contains the sequence number of the master
111signing key whose fingerprint it knows. During an update, the right
112signature is fetched and checked; if there's a new master key, then the
113.B tripe-keys.conf
114in the new repository archive will have its sequence number and
115fingerprint: the update process will replace its configuration file with
116the new version, and the peer will use the new key from then on.
117.SS "Options"
118The
119.B tripe-keys
120program accepts some standard command-line options:
121.TP
122.B "\-h, \-\-help"
123Print general help about
124.B tripe-keys
125to standard output and exit successfully.
126.TP
127.B "\-v, \-\-version"
128Print the version number of
129.B tripe-keys
130to standard output and exit successfully.
131.TP
132.B "\-u, \-\-usage"
133Print brief usage about
134.B tripe-keys
135to standard output and exit successfully.
136.SS "Subcommands"
137.TP
c77687d5 138.BI "help \fR[" command \fR]
060ca767 139With no arguments, shows help, as for the
140.B \-\-help
141option. With an argument, shows help about that
142.IR command .
143.TP
144.B "setup"
145Constructs a new repository and makes a signing key (as for
146.BR newmaster )
147and key-exchange parameters. Fails if
148.B repos
149already exists.
150.TP
151.B "upload"
152Build a repository archive, sign it with the active signing keys, and
153make a
154.B tripe-keys.conf
155file. Copy the results to the places named by
156.IR repos-file ,
157.IR sig-file ,
158and
159.I conf-file
160respectively. (This command is currently misnamed. It only copies
161stuff about the local filesystem. Some day it'll really upload stuff.)
162.TP
163.BI "generate " tag
164Generate a peer key for the peer named
165.IR tag .
166The private key ends up in
167.BR keyring ;
168the public key is written to
169.BI peer- tag .pub
170in the
171.I current
172directory.
173.TP
174.B update
175Fetches a new copy of the repository archive and its signature. It
176unpacks the archive in a temporary directory, and checks the enclosed
177master public key against the fingerprint in the configuration file. It
178then verifies the signature on the archive using this public key. If
179all is well, it replaces the current
180.B repos
181directory with the version in the new archive, and if necessary it
182replaces the current configuration file with the new one in the
183archive. It then does a
184.B rebuild
185to construct a new
186.B keyring.pub
187file.
188.TP
189.B newmaster
190Generates a new master signing key. The old master key is not deleted.
191.TP
192.B rebuild
193Rebuilds the public keyring
194.B keyring.pub
195from the public keys in the
196.B repos
197directory.
198.TP
199.B clean
200Deletes everything which
201.B tripe-keys
202might have written to a directory. In particular, it deletes
203.BR repos ,
204.BR tmp ,
205.BR master ,
206.BR keyring ,
207.BR keying.pub ,
208and their associated
209.B .old
210files.
211.SH "SEE ALSO"
212.BR key (1),
213.BR tripe\-keys.conf (5),
214.BR tripe (8).
215.SH "AUTHOR"
216Mark Wooding, <mdw@distorted.org.uk>