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