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