--- /dev/null
+.\" -*-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, <mdw@nsict.org>
.el \{\
. ds o o
. ds ss ^
-. ds se _
+. ds se
.\}
.TH tripe 8 "10 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.SH "NAME"
.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 ,
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 .
~mdw / tripe / commitdiff