Merge branch 'master' of git.distorted.org.uk:~mdw/publish/public-git/tripe

[tripe] / keys / tripe-keys.8.in

.\" -*-nroff-*-
.\".
.\" Manual for the key-management tool
.\"
.\" (c) 2008 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of Trivial IP Encryption (TrIPE).
.\"
.\" TrIPE is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" TrIPE is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with TrIPE; if not, write to the Free Software Foundation,
.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
.
.\"--------------------------------------------------------------------------
.so ../common/defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.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"
.br
.B "check"
.br
.BR "mtu " [ \fIpath-mtu ]
.
.\"--------------------------------------------------------------------------
.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.
.TP
.B check
Checks the various keyrings.  Currently, it checks the
.B master
and
.B keyring.pub
files, and prints a report warning of keys which will expire soon.  It
is expected that this command be run against the master repository by
.BR cron (8).
Additional checking may added in the future.
.TP
.BR "mtu " [ \fIpath-mtu ]
Write, as a decimal number on standard output, the recommended MTU for a
TrIPE tunnel interface, given that the
.I path-mtu
between two peers is as specified.  The default is 1500, which is very
commonly correct, but you should check using a tool such as
.BR tracepath (8).
Getting the MTU too big will lead to unnecessary fragmentation of
TrIPE's UDP datagrams; getting it too small will fail to utilize the
underlying network effectively.  If in doubt, it's therefore better to
underestimate.
.
.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
.
.BR key (1),
.BR tripe\-keys.conf (5),
.BR tripe (8).
.
.\"--------------------------------------------------------------------------
.SH "AUTHOR"
.
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------