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