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