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