X-Git-Url: https://git.distorted.org.uk/~mdw/tripe/blobdiff_plain/85b1ebd6e0a50314cd28a602a69c6cde0efcecb1..6b6ad6702f305891ced3b9a7cf3061c75eabda86:/keys/tripe-keys.8?ds=sidebyside diff --git a/keys/tripe-keys.8 b/keys/tripe-keys.8 new file mode 100644 index 00000000..bebe3312 --- /dev/null +++ b/keys/tripe-keys.8 @@ -0,0 +1,216 @@ +.\" -*-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,