.\" -*-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 8tripe "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. Remove unexpected files from the .IR base-dir , since these tend to be signatures made by old master keys which don't work any more. Run the .I upload-hook to copy things into the right places. .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, . .\"----- That's all, folks --------------------------------------------------