chiark - git - mdw - tripe/blob - 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 8 "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.  (This command is currently misnamed.  It only copies
 172 stuff about the local filesystem.  Some day it'll really upload stuff.)
 173 .TP
 174 .BI "generate " tag
 175 Generate a peer key for the peer named
 176 .IR tag .
 177 The private key ends up in
 178 .BR keyring ;
 179 the public key is written to
 180 .BI peer- tag .pub
 181 in the
 182 .I current
 183 directory.
 184 .TP
 185 .B update
 186 Fetches a new copy of the repository archive and its signature.  It
 187 unpacks the archive in a temporary directory, and checks the enclosed
 188 master public key against the fingerprint in the configuration file.  It
 189 then verifies the signature on the archive using this public key.  If
 190 all is well, it replaces the current
 191 .B repos
 192 directory with the version in the new archive, and if necessary it
 193 replaces the current configuration file with the new one in the
 194 archive.  It then does a
 195 .B rebuild
 196 to construct a new
 197 .B keyring.pub
 198 file.
 199 .TP
 200 .B newmaster
 201 Generates a new master signing key.  The old master key is not deleted.
 202 .TP
 203 .B rebuild
 204 Rebuilds the public keyring
 205 .B keyring.pub
 206 from the public keys in the
 207 .B repos
 208 directory.
 209 .TP
 210 .B clean
 211 Deletes everything which
 212 .B tripe-keys
 213 might have written to a directory.  In particular, it deletes
 214 .BR repos ,
 215 .BR tmp ,
 216 .BR master ,
 217 .BR keyring ,
 218 .BR keying.pub ,
 219 and their associated
 220 .B .old
 221 files.
 222 .TP
 223 .B check
 224 Checks the various keyrings.  Currently, it checks the
 225 .B master
 226 and
 227 .B keyring.pub
 228 files, and prints a report warning of keys which will expire soon.  It
 229 is expected that this command be run against the master repository by
 230 .BR cron (8).
 231 Additional checking may added in the future.
 232 .TP
 233 .BR "mtu " [ \fIpath-mtu ]
 234 Write, as a decimal number on standard output, the recommended MTU for a
 235 TrIPE tunnel interface, given that the
 236 .I path-mtu
 237 between two peers is as specified.  The default is 1500, which is very
 238 commonly correct, but you should check using a tool such as
 239 .BR tracepath (8).
 240 Getting the MTU too big will lead to unnecessary fragmentation of
 241 TrIPE's UDP datagrams; getting it too small will fail to utilize the
 242 underlying network effectively.  If in doubt, it's therefore better to
 243 underestimate.
 244 .
 245 .\"--------------------------------------------------------------------------
 246 .SH "SEE ALSO"
 247 .
 248 .BR key (1),
 249 .BR tripe\-keys.conf (5),
 250 .BR tripe (8).
 251 .
 252 .\"--------------------------------------------------------------------------
 253 .SH "AUTHOR"
 254 .
 255 Mark Wooding, <mdw@distorted.org.uk>
 256 .
 257 .\"----- That's all, folks --------------------------------------------------