From d6623498a744000582f21ca046f1c79766e0bafc Mon Sep 17 00:00:00 2001 Message-Id: From: Mark Wooding Date: Mon, 19 Feb 2001 19:11:43 +0000 Subject: [PATCH] More documentation. Organization: Straylight/Edgeware From: mdw --- doc/tripe-admin.5 | 214 ++++++++++++++++++++++++++++++++++++++++++++++ doc/tripe.8 | 207 +++++++++++++++++++++++++++++++++++++------- doc/tripectl.1 | 32 +++++++ 3 files changed, 420 insertions(+), 33 deletions(-) create mode 100644 doc/tripe-admin.5 create mode 100644 doc/tripectl.1 diff --git a/doc/tripe-admin.5 b/doc/tripe-admin.5 new file mode 100644 index 00000000..9a07b941 --- /dev/null +++ b/doc/tripe-admin.5 @@ -0,0 +1,214 @@ +.\" -*-nroff-*- +.TH tripe-admin 5 "18 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" +.SH NAME +tripe-admin \- administrator commands for TrIPE +.SH DESCRIPTION +This manual page describes the administration interface provided by the +.BR tripe (8) +daemon. +.PP +The +.BR tripectl (8) +program can be used either interactively or in scripts to communicate +with the server using this interface. Alternatively, simple custom +clients can be written in scripting languages such as Perl, Python or +Tcl, or more advanced clients such as GUI monitors can be written in C +with little difficulty. +.PP +By default, the server listens for admin connections on the Unix-domain +socket +.BR /var/lib/tripe/tripesock . +Administration commands use a simple textual protocol. Each client +command or server response consists of a line of ASCII text terminated +by a single linefeed character. +.SS "General structure" +Each command or response line consists of a sequence of +whitespace-separated words. The number and nature of whitespace +characters separating two words in a client command is not significant; +the server always uses a single space character. The first word in a +line is a +.I keyword +identifying the type of command or response contained. Keywords in +client commands are not case-sensitive; the server always uses uppercase +for its keywords. +.SS "Server responses" +For client command, the server responds with zero or more +.B INFO +lines, followed by either an +.B OK +line or a +.B FAIL +line. Each +.B INFO +provides information requested in the command. An +.B OK +response contains no further data. A +.B FAIL +code is followed by a human-readable explanation of why the command +failed. +.PP +In addition, there are two types of asynchronous `responses', which +aren't associated with any particular command. The +.B WARN +response contains a human-readable message warning of an error +encountered while processing a command, unexpected or unusual behaviour +by a peer, or a possible attack by an adversary. Under normal +conditions, the server shouldn't emit any warnings. The +.B TRACE +response contains a human-readable tracing message containing diagnostic +information. Trace messages are controlled using the +.B \-T +command-line option to the server, or the +.B TRACE +administration command (see below). Support for tracing can be disabled +when the package is being configured, and may not be available in your +version. +.SS "Command reference" +The commands provided are: +.TP +.B "HELP" +Causes the server to emit an +.B INFO +line for each command it supports. Each line lists the command name, +followed by the names of the arguments. This may be helpful as a memory +aid for interactive use, or for program clients probing for features. +.TP +.BR "TRACE " [\fIoptions\fP] +A trace argument consists of a string of letters (listed below) +selecting trace outputs, optionally interspersed with +.RB ` + ' +to enable, or +.RB ` \- ' +to disable, the subsequently listed outputs; the initial behaviour is to +enable listed outputs. For example, the string +.B ra\-st+x +enables tracing of peer management, admin-connection handling and +key-exchange processing, and disables tracing of symmetric keyset +management and the system-specific tunnel driver. If no argument is +given, a table is returned showing the available tracing option letters +and their meanings. Programs should not attempt to parse this table: +its format is not guaranteed to remain the same. +.RS +Currently, the following tracing options are supported: +.TP +.B t +Tunnel events: reception of packets to be encrypted, and injection of +successfully-decrypted packets. +.TP +.B r +Peer management events: creation and destruction of peer attachments, +and arrival of messages. +.TP +.B a +Administration interface: acceptance of new connections, and handling of +the backgroud name-resolution required by the +.B ADD +command. +.TP +.B p +Display contents of packets sent and received by the tunnel and/or peer +modules. +.TP +.B c +Display inputs, outputs and intermediate results of cryptographic +operations. This includes plaintext and key material. Use with +caution. +.TP +.B s +Handling of symmetric keysets: creation and expiry of keysets, and +encryption and decryption of messages. +.TP +.B x +Key exchange: reception, parsing and emission of key exchange messages. +.TP +.B m +Key management: loading keys and checking for file modifications. +.PP +Note that the +.B p +(packet contents) +and +.B c +(crypto details) +outputs provide extra detail for other outputs. Specifying +.B p +without +.B r +or +.B t +isn't useful; neither is specifying +.B c +without one of +.BR s , +.B x +or +.BR m . +.RE +.TP +.B "PORT" +Emits an +.B INFO +line containing just the number of the UDP port used by the +.B tripe +server. If you've allowed your server to allocate a port dynamically, +this is how to find out which one it chose. +.TP +.B "DAEMON" +Causes the server to disassociate itself from its terminal and become a +background task. This only works once. A warning is issued. +.TP +.B "LIST" +For each currently-known peer, an +.B INFO +line is written containing the peer's name, as given to +.BR ADD . +.TP +.BI "IFNAME " peer +Emits an +.B INFO +line containing the name of the network interface used to collect IP +packets which are to be encrypted and sent to +.IR peer . +Used by configuration scripts so that they can set up routing tables +appropriately after adding new peers. +.TP +.BI "ADDR " peer +Emits an +.B INFO +line reporting the IP address and port number stored for +.IR peer . +.TP +.BI "STATS " peer +Emits a number of +.B INFO +lines, each containing one or more statistics in the form +.IB name = value \fR. +The statistics-gathering is experimental and subject to change. +.TP +.BI "KILL " peer +Causes the server to forget all about +.IR peer . +All keys are destroyed, and no more packets are sent. No notification +is sent to the peer: if it's important that the peer be notified, you +must think of a way to do that yourself. +.TP +.BI "ADD " "peer addr port" +Adds a new peer. The peer is given the name +.IR peer ; +the peer's public key is assumed to be in the file +.B keyring.pub +(or whatever alternative file was specified in the +.B \-K +option on the command line). The peer's +.B tripe +implementation may be contacted at the given UDP port and IP address. +.TP +.B "QUIT" +Instructs the server to exit immediately. A warning is sent. +.SH "SEE ALSO" +.BR tripectl (1), +.BR tripe (8). +.PP +.IR "The Trivial IP Encryption Protocol" , +.SH "AUTHOR" +Mark Wooding, diff --git a/doc/tripe.8 b/doc/tripe.8 index 4c031500..fd73144d 100644 --- a/doc/tripe.8 +++ b/doc/tripe.8 @@ -27,7 +27,7 @@ .el \{\ . ds o o . ds ss ^ -. ds se _ +. ds se .\} .TH tripe 8 "10 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" .SH "NAME" @@ -186,46 +186,192 @@ rather than the default .BI "\-T, \-\-trace=" trace-opts Allows the enabling or disabling of various internal diagnostics. See below for the list of options. -.SS "Key management" -The TrIPE protocol requires all cooperating hosts to be using keys -with the same group parameters. A suitable group may be created with the -command: +.SS "Setting up a VPN with tripe" +The +.B tripe +server identifies peers by name. While it's +.I possible +for each host to maintain its own naming system for its peers, this is +likely to lead to confusion, and it's more sensible to organize a naming +system that works everywhere. How you manage this naming is up to you. +The only restriction on the format of names is that they must be valid +Catacomb key tags, since this is how +.B tripe +identifies which public key to use for a particular peer: they may not +contain whitespace characters, or a colon +.RB ` : ' +or dot +.RB ` . ', +.PP +Allocating IP addresses for VPNs can get quite complicated. I'll +attempt to illustrate with a relatively simple example. Our objective +will be to set up a virtual private network between two sites of +.BR example.com . +The two sites are using distinct IP address ranges from the private +address space described in RFC1918: site A is using addresses from +10.0.1.0/24 and site B is using 10.0.2.0/24. Each site has a gateway +host set up with both an address on the site's private network, and an +externally-routable address from the public IP address space. Site A's +gateway machine, +.BR alice , +has the addresses 10.0.1.1 and 200.0.1.1; site B's gateway is +.B bob +and has addresses 10.0.2.1 and 200.0.2.1. +.PP +This isn't quite complicated enough. Each of +.B alice +and +.B bob +needs an extra IP address which we'll use when setting up the +point-to-point link. These addresses need to be routable, at least +within the virtual private network: unfortunately, you can't just use +the same pair everywhere. We'll assign +.B alice +the point-to-point address 192.168.0.1, and +.B bob +the address 192.168.0.2. +.hP 1. +Install +.B tripe +on both of the gateway hosts. Create the directory +.BR /var/lib/tripe . +.hP 2. +On +.BR alice , +make +.B /var/lib/tripe +the current directory and generate a Diffie-Hellman group: +.RS .VS key add \-adh\-param \-LS \-b2048 \-B256 \e \-eforever \-tparam tripe\-dh\-param .VE -This creates a `parameters' key labelled -.B param -in your keyring file: it doesn't contain any secrets. You may vary the -security parameters -.B \-b -and -.B \-B -to taste: the ones given provide good security, at the expense of -performance. Even so, from a cryptographic point of view, these keys -will be the weak point in the security of the system. Generation of the -group parameters can take a few minutes. -.PP -You should extract the parameters from your keyring and distribute them -(securely) to the other administrators. The parameters may be extracted -from your keyring with the command: +(See +.BR key (1) +from the Catacomb distribution for details about the +.B key +command.) Also generate a private key for +.BR alice : +.VS +key add \-adh \-pparam \-talice \e + \-e"now + 1 year" tripe\-dh +.VE +Extract the group parameters and +.BR alice 's +public key to +.I separate +files, and put the public key in +.BR keyring.pub : .VS key extract param param +key extract \-f\-secret alice alice.pub +key \-kkeyring.pub merge alice.pub .VE -This may be merged into a keyring with: +Send the files +.B param +and +.B alice.pub +to +.B bob +in some secure way (e.g., in PGP-signed email, or by using SSH), so that +you can be sure they've not been altered in transit. +.RE +.hP 3. +On +.B bob +now, make +.B /var/lib/tripe +the current directory, and import the key material from +.BR alice : +.RS .VS key merge param +key \-kkeyring.pub merge alice.pub .VE -Once your keyring contains the parameters, a suitable key can be created -with the command: +Generate a private key for +.B bob +and extract the public half, as before: .VS -key add \-adh \-pparam \-e"now + 1 year" tripe\-dh +key add \-adh \-pparam \-tbob \e + \-e"now + 1 year" tripe\-dh +key extract \-f\-secret bob bob.pub +key \-kkeyring.pub merge bob.pub .VE -This creates a Diffie-Hellman key using the parameters from key -.B param -which expires in one year. The new key has type -.BR tripe\-dh . +and send +.B bob.pub +back to +.B alice +using some secure method. +.RE +.hP 4 +On +.BR alice , +merge +.B bob 's +key into the public keyring. Now, on each host, run +.RS +.VS +key \-kkeyring.pub fingerprint +.VE +and check that the hashes match. If the two sites have separate +administrators, they should read the hashes to each other over the +telephone (assuming that they can recognize each other's voices). +.RE +.hP 5. +Start the +.B tripe +servers up. Run +.RS +.VS +tripectl \-slD \-S\-P23169 +.VE +on each of +.B alice +and +.BR bob . +(The +.RB ` \-P23169 ' +forces the server to use UDP port 23169: use some other number if 23169 +is inappropriate for your requirements. I chose it by reducing the +RIPEMD160 hash of +.RB ` tripe\-port\-number\e0 ' +modulo 2\*(ss16\*(se.) +.RE +.hP 6. +To get +.B alice +talking to +.BR bob , +run this shell script (or one like it): +.RS +.VS +#! /bin/sh +tripectl add bob 200.0.2.1 23169 +ifname=`tripectl ifname bob` +ifconfig $ifname \e + 192.168.0.1 \e + pointopoint 192.168.0.2 +route add -net \e + 10.0.2.0 netmask 255.255.255.0 \e + gw 192.168.0.2 +.VE +Read +.BR ifconfig (8) +and +.BR route (8) +to find out about your system's variants of these commands. The +versions shown above assume a Linux system. +Run a similar script on +.BR bob , +to tell its +.B tripe +server to talk to +.BR alice . +.RE +.hP 7. +Congratulations. The two servers will exchange keys and begin sending +packets almost immediately. You've set up a virtual private network. .SS "About the name" The program's name is .BR tripe , @@ -233,11 +379,6 @@ all in lower-case. The name of the protocol it uses is `TrIPE', with four capital letters and one lower-case. The name stands for `Trivial IP Encryption'. .SH "BUGS" -It's too easy to deny service during key exchange. If both ends are -honest, they'll notice any interference and resend their packets, but -it's possible to delay successful negotation for as long as desired by -sending bogus key exchange messages. -.PP The code hasn't been audited. It may contain security bugs. If you find one, please inform the author .IR immediately . diff --git a/doc/tripectl.1 b/doc/tripectl.1 new file mode 100644 index 00000000..877a467a --- /dev/null +++ b/doc/tripectl.1 @@ -0,0 +1,32 @@ +.\" -*-nroff-*- +.TH tripectl 1 "19 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption" +.SH NAME +tripectl \- simple client for TrIPE +.SH SYNOPSIS +.B tripectl +.RB [ \-w ] +.RB [ \-\fIoptions ] +.RI [ command +.RI [ args ]...] +.br +.B tripectl +.RB [ \-Dl ] +.RB [ \-f +.IR file ] +.RB [ \-\fIoptions ] +.PP +Options: +.br + \& +.RB [ \-s ] +.RB [ \-d +.IR directory ] +.RB [ \-a +.IR socket ] +.br + \& +.RB [ \-p +.IR program ] +.RB [ \-S +.IB arg , arg ,\fR...] +.SH DESCRIPTION -- [mdw]