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