--- /dev/null
+.\" -*-nroff-*-
+.\".
+.de hP
+.IP
+\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
+..
+.de VS
+.sp 1
+.RS
+.nf
+.ft B
+..
+.de VE
+.ft R
+.fi
+.RE
+.sp 1
+..
+.ie t \{\
+. ds o \(bu
+. ds ss \s8\u
+. ds se \d\s0
+. if \n(.g \{\
+. fam P
+. \}
+.\}
+.el \{\
+. ds o o
+. ds ss ^
+. ds se
+.\}
+.TH tripe-keys 8 "14 September 2005" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
+.SH "NAME"
+tripe-keys \- simple centralized key management for tripe
+.SH "SYNOPSIS"
+.B tripe-keys
+.I operation
+.IP "Operations supported:"
+.BI "help \fR[" command \fR]
+.br
+.B "setup"
+.br
+.B "upload"
+.br
+.BI "generate " tag
+.br
+.B "update"
+.br
+.B "newmaster"
+.br
+.B "rebuild"
+.br
+.B "clean"
+.SH "DESCRIPTION"
+The
+.B tripe-keys
+script implements a very simple, centralized key management system for
+.BR tripe (8).
+It assumes that there is a central authority who knows all the public
+keys for a private network.
+.SS "Overview"
+The
+.B tripe-keys
+program maintains a
+.I repository
+of public keys. It provides a way for a master authority to publish the
+repository and for clients to obtain authentic copies of it.
+.PP
+The repository is very simple: it consists of a directory
+.B repos
+full of public-key files, each named
+.BI peer- tag .pub \fR.
+.PP
+The repository setup process creates a master signing key, stored in the
+.B master
+keyring, and a key describing the parameters to be used for generating
+key-exchange keys, stored in
+.BR repos/param .
+.PP
+The master authority has a configuration file
+.BR tripe-keys.master ,
+usually created by copying the template provided and editing it.
+.PP
+The published repository consists of a tarball of the
+.B repos
+directory, containing the key-generation parameters and all the peers'
+public keys, and a client configuration file
+.BR tripe-keys.conf .
+The tarball is signed by the master authority's signing key.
+.PP
+The client configuration file is essentially a copy of
+.B tripe-keys.master
+with some extra bits filled in: in particular, it contains the
+fingerprint of the master signing key, so that the client can be sure
+it's checking the right key.
+.PP
+A peer starts by downloading a copy of
+.B tripe-keys.conf
+and then making sure it's authentic. (This is one of the tricky bits.
+The other is getting public keys back to the master authority.) This is
+enough for the peer to fetch a copy of the repository, verify the
+signature, and assemble a public keyring for the other peers in the
+network.
+.PP
+In fact, it's not
+.I quite
+that simple. The system allows new signing keys to replace old ones, so
+in fact the publication process signs the repository archive using a
+collection of keys. Each signing key is given a sequence number. The
+client configuration file contains the sequence number of the master
+signing key whose fingerprint it knows. During an update, the right
+signature is fetched and checked; if there's a new master key, then the
+.B tripe-keys.conf
+in the new repository archive will have its sequence number and
+fingerprint: the update process will replace its configuration file with
+the new version, and the peer will use the new key from then on.
+.SS "Options"
+The
+.B tripe-keys
+program accepts some standard command-line options:
+.TP
+.B "\-h, \-\-help"
+Print general help about
+.B tripe-keys
+to standard output and exit successfully.
+.TP
+.B "\-v, \-\-version"
+Print the version number of
+.B tripe-keys
+to standard output and exit successfully.
+.TP
+.B "\-u, \-\-usage"
+Print brief usage about
+.B tripe-keys
+to standard output and exit successfully.
+.SS "Subcommands"
+.TP
+.BI "help \fR[" command \fR]
+With no arguments, shows help, as for the
+.B \-\-help
+option. With an argument, shows help about that
+.IR command .
+.TP
+.B "setup"
+Constructs a new repository and makes a signing key (as for
+.BR newmaster )
+and key-exchange parameters. Fails if
+.B repos
+already exists.
+.TP
+.B "upload"
+Build a repository archive, sign it with the active signing keys, and
+make a
+.B tripe-keys.conf
+file. Copy the results to the places named by
+.IR repos-file ,
+.IR sig-file ,
+and
+.I conf-file
+respectively. (This command is currently misnamed. It only copies
+stuff about the local filesystem. Some day it'll really upload stuff.)
+.TP
+.BI "generate " tag
+Generate a peer key for the peer named
+.IR tag .
+The private key ends up in
+.BR keyring ;
+the public key is written to
+.BI peer- tag .pub
+in the
+.I current
+directory.
+.TP
+.B update
+Fetches a new copy of the repository archive and its signature. It
+unpacks the archive in a temporary directory, and checks the enclosed
+master public key against the fingerprint in the configuration file. It
+then verifies the signature on the archive using this public key. If
+all is well, it replaces the current
+.B repos
+directory with the version in the new archive, and if necessary it
+replaces the current configuration file with the new one in the
+archive. It then does a
+.B rebuild
+to construct a new
+.B keyring.pub
+file.
+.TP
+.B newmaster
+Generates a new master signing key. The old master key is not deleted.
+.TP
+.B rebuild
+Rebuilds the public keyring
+.B keyring.pub
+from the public keys in the
+.B repos
+directory.
+.TP
+.B clean
+Deletes everything which
+.B tripe-keys
+might have written to a directory. In particular, it deletes
+.BR repos ,
+.BR tmp ,
+.BR master ,
+.BR keyring ,
+.BR keying.pub ,
+and their associated
+.B .old
+files.
+.SH "SEE ALSO"
+.BR key (1),
+.BR tripe\-keys.conf (5),
+.BR tripe (8).
+.SH "AUTHOR"
+Mark Wooding, <mdw@distorted.org.uk>
~mdw / tripe / blobdiff