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