chiark - git - mdw - tripe/blob - doc/tripe-keys.8

   1 .\" -*-nroff-*-
   2 .\".
   3 .de hP
   4 .IP
   5 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
   6 ..
   7 .de VS
   8 .sp 1
   9 .RS
  10 .nf
  11 .ft B
  12 ..
  13 .de VE
  14 .ft R
  15 .fi
  16 .RE
  17 .sp 1
  18 ..
  19 .ie t \{\
  20 .  ds o \(bu
  21 .  ds ss \s8\u
  22 .  ds se \d\s0
  23 .  if \n(.g \{\
  24 .    fam P
  25 .  \}
  26 .\}
  27 .el \{\
  28 .  ds o o
  29 .  ds ss ^
  30 .  ds se
  31 .\}
  32 .TH tripe-keys 8 "14 September 2005" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
  33 .SH "NAME"
  34 tripe-keys \- simple centralized key management for tripe
  35 .SH "SYNOPSIS"
  36 .B tripe-keys
  37 .I operation
  38 .IP "Operations supported:"
  39 .BI "help \fR[" command \fR]
  40 .br
  41 .B "setup"
  42 .br
  43 .B "upload"
  44 .br
  45 .BI "generate " tag
  46 .br
  47 .B "update"
  48 .br
  49 .B "newmaster"
  50 .br
  51 .B "rebuild"
  52 .br
  53 .B "clean"
  54 .SH "DESCRIPTION"
  55 The
  56 .B tripe-keys
  57 script implements a very simple, centralized key management system for
  58 .BR tripe (8).
  59 It assumes that there is a central authority who knows all the public
  60 keys for a private network.
  61 .SS "Overview"
  62 The
  63 .B tripe-keys
  64 program maintains a
  65 .I repository
  66 of public keys.  It provides a way for a master authority to publish the
  67 repository and for clients to obtain authentic copies of it.
  68 .PP
  69 The repository is very simple: it consists of a directory
  70 .B repos
  71 full of public-key files, each named
  72 .BI peer- tag .pub \fR.
  73 .PP
  74 The repository setup process creates a master signing key, stored in the
  75 .B master
  76 keyring, and a key describing the parameters to be used for generating
  77 key-exchange keys, stored in
  78 .BR repos/param .
  79 .PP
  80 The master authority has a configuration file
  81 .BR tripe-keys.master ,
  82 usually created by copying the template provided and editing it.
  83 .PP
  84 The published repository consists of a tarball of the
  85 .B repos
  86 directory, containing the key-generation parameters and all the peers'
  87 public keys, and a client configuration file
  88 .BR tripe-keys.conf .
  89 The tarball is signed by the master authority's signing key.
  90 .PP
  91 The client configuration file is essentially a copy of
  92 .B tripe-keys.master
  93 with some extra bits filled in: in particular, it contains the
  94 fingerprint of the master signing key, so that the client can be sure
  95 it's checking the right key.
  96 .PP
  97 A peer starts by downloading a copy of
  98 .B tripe-keys.conf
  99 and then making sure it's authentic.  (This is one of the tricky bits.
 100 The other is getting public keys back to the master authority.)  This is
 101 enough for the peer to fetch a copy of the repository, verify the
 102 signature, and assemble a public keyring for the other peers in the
 103 network.
 104 .PP
 105 In fact, it's not
 106 .I quite
 107 that simple.  The system allows new signing keys to replace old ones, so
 108 in fact the publication process signs the repository archive using a
 109 collection of keys.  Each signing key is given a sequence number.  The
 110 client configuration file contains the sequence number of the master
 111 signing key whose fingerprint it knows.  During an update, the right
 112 signature is fetched and checked; if there's a new master key, then the
 113 .B tripe-keys.conf
 114 in the new repository archive will have its sequence number and
 115 fingerprint: the update process will replace its configuration file with
 116 the new version, and the peer will use the new key from then on.
 117 .SS "Options"
 118 The
 119 .B tripe-keys
 120 program accepts some standard command-line options:
 121 .TP
 122 .B "\-h, \-\-help"
 123 Print general help about
 124 .B tripe-keys
 125 to standard output and exit successfully.
 126 .TP
 127 .B "\-v, \-\-version"
 128 Print the version number of
 129 .B tripe-keys
 130 to standard output and exit successfully.
 131 .TP
 132 .B "\-u, \-\-usage"
 133 Print brief usage about
 134 .B tripe-keys
 135 to standard output and exit successfully.
 136 .SS "Subcommands"
 137 .TP
 138 .BI "help \fR[" command \fR]
 139 With no arguments, shows help, as for the
 140 .B \-\-help
 141 option.  With an argument, shows help about that
 142 .IR command .
 143 .TP
 144 .B "setup"
 145 Constructs a new repository and makes a signing key (as for
 146 .BR newmaster )
 147 and key-exchange parameters.  Fails if
 148 .B repos
 149 already exists.
 150 .TP
 151 .B "upload"
 152 Build a repository archive, sign it with the active signing keys, and
 153 make a
 154 .B tripe-keys.conf
 155 file.  Copy the results to the places named by
 156 .IR repos-file ,
 157 .IR sig-file ,
 158 and
 159 .I conf-file
 160 respectively.  (This command is currently misnamed.  It only copies
 161 stuff about the local filesystem.  Some day it'll really upload stuff.)
 162 .TP
 163 .BI "generate " tag
 164 Generate a peer key for the peer named
 165 .IR tag .
 166 The private key ends up in
 167 .BR keyring ;
 168 the public key is written to
 169 .BI peer- tag .pub
 170 in the
 171 .I current
 172 directory.
 173 .TP
 174 .B update
 175 Fetches a new copy of the repository archive and its signature.  It
 176 unpacks the archive in a temporary directory, and checks the enclosed
 177 master public key against the fingerprint in the configuration file.  It
 178 then verifies the signature on the archive using this public key.  If
 179 all is well, it replaces the current
 180 .B repos
 181 directory with the version in the new archive, and if necessary it
 182 replaces the current configuration file with the new one in the
 183 archive.  It then does a
 184 .B rebuild
 185 to construct a new
 186 .B keyring.pub
 187 file.
 188 .TP
 189 .B newmaster
 190 Generates a new master signing key.  The old master key is not deleted.
 191 .TP
 192 .B rebuild
 193 Rebuilds the public keyring
 194 .B keyring.pub
 195 from the public keys in the
 196 .B repos
 197 directory.
 198 .TP
 199 .B clean
 200 Deletes everything which
 201 .B tripe-keys
 202 might have written to a directory.  In particular, it deletes
 203 .BR repos ,
 204 .BR tmp ,
 205 .BR master ,
 206 .BR keyring ,
 207 .BR keying.pub ,
 208 and their associated
 209 .B .old
 210 files.
 211 .SH "SEE ALSO"
 212 .BR key (1),
 213 .BR tripe\-keys.conf (5),
 214 .BR tripe (8).
 215 .SH "AUTHOR"
 216 Mark Wooding, <mdw@distorted.org.uk>