Initial versions of documentation.

[tripe] / doc / tripe.8

.\" -*-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 8 "10 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.SH "NAME"
tripe \- a simple VPN daemon
.SH "SYNOPSIS"
.B tripe
.RB [ \-D ]
.RB [ \-p
.IR port ]
.RB [ \-T
.IR trace-opts ]
.RB [ \-d
.IR dir ]
.RB [ \-a
.IR socket ]
.br
	
.RB [ \-k
.IR priv-keyring ]
.RB [ \-K
.IR pub-keyring ]
.RB [ \-t
.IR key-tag ]
.SH "DESCRIPTION"
The
.B tripe
program is a server which can provide strong IP-level encryption and
authentication between two co-operating hosts.  The program and its
protocol are deliberately very simple, to make analysing them easy and
to help build trust rapidly in the system.
.SS "Overview"
The
.B tripe
server manages a number of secure connections to other `peer' hosts.
Each daemon is given a private key of its own, and a file of public keys
for the peers with which it is meant to communicate.  It is responsible
for negotiating sets of symmetric keys with its peers, and for
encrypting, encapsulating and sending IP packets to its peers, and
decrypting, checking and de-encapsulating packets it receives from
them.
.PP
When the server starts, it creates a Unix-domain socket on which it
listens for administration commands.  It also logs warnings and
diagnostic information to the programs connected to its admin socket.
Clients connected to the socket can add new peers, and remove or find
out about existing peers.  The textual protocol used to give the
.B tripe
server admin commands is described in
.BR tripe\-admin (5).
A client program
.BR tripectl (1)
is provided to allow commands to be sent to the server either
interactively or by simple scripts.
.SS "Command-line arguments"
If not given any command-line arguments,
.B tripe
will initialize by following these steps:
.hP \*o
It changes directory to
.BR /var/lib/tripe .
.hP \*o
It acquires a UDP socket with an arbitrary kernel-selected port number.
It will use this socket to send and receive all communications with its
peer servers.  The port chosen may be discovered by means of the
.B PORT
admin command (see
.BR tripe\-admin (5)).
.hP \*o
It loads the private key with the tag or type name
.B tripe\-dh
from the Catacomb-format file
.BR keyring ,
and loads the file
.B keyring.pub
ready for extracting the public keys of peers as they're introduced.
(The format of these files is described in
.BR keyring (5).
They are maintained using the program
.BR key (1)
provided with the Catacomb distribution.)
.hP \*o
It creates and listens to the Unix-domain socket
.BR tripesock .
.PP
Following this, the server enters its main loop, accepting admin
connections and obeying any administrative commands, and communicating
with peers.  It also treats its standard input and standard output
streams as an admin connection, reading commands from standard input and
writing responses and diagnostics messages to standard output.
.PP
Much of this behaviour may be altered by giving
.B tripe
suitable command-line options:
.TP
.B "\-h, \-\-help"
Writes a brief description of the command-line options available to
standard output and exits with status 0.
.TP
.B "\-v, \-\-version"
Writes
.BR tripe 's
version number to standard output and exits with status 0.
.TP
.B "\-u, \-\-usage"
Writes a brief usage summary to standard output and exits with status 0.
.TP
.B "\-D, \-\-daemon"
Dissociates from its terminal and starts running in the background after
completing the initialization procedure described above.  If running as
a daemon,
.B tripe
will not read commands from standard input or write diagnostics to
standard output.  A better way to start
.B tripe
in the background is with
.BR tripectl (1).
.TP
.BI "\-d, \-\-directory=" dir
Makes
.I dir
the current directory, instead of
.BR /var/lib/tripe .
Give a current directory of
.B .
if you don't want it to change directory at all.
.TP
.BI "\-p, \-\-port=" port
Use the specified UDP port for all communications with peers, rather
than an arbitarary kernel-assigned port.
.TP
.BI "\-k, \-\-priv\-keyring=" file
Reads the private key from
.I file
rather than the default
.BR keyring .
.TP
.BI "\-K, \-\-pub\-keyring=" file
Reads public keys from
.I file
rather than the default
.BR keyring.pub .
This can be the same as the private keyring, but that's not recommended.
.TP
.BI "\-t, \-\-tag=" tag
Uses the private key whose tag or type is
.I tag
rather than the default
.BR tripe\-dh .
.TP
.BI "\-a, \-\-admin\-socket=" socket
Accept admin connections to a Unix-domain socket named
.I socket
rather than the default
.BR tripesock .
.TP
.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:
.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:
.VS
key extract param param
.VE
This may be merged into a keyring with:
.VS
key merge param
.VE
Once your keyring contains the parameters, a suitable key can be created
with the command:
.VS
key add \-adh \-pparam \-e"now + 1 year" tripe\-dh
.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 .

.SS "About the name"
The program's name is
.BR tripe ,
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 .
.SH "SEE ALSO"
.BR key (1),
.BR tripectl (1),
.BR tripe\-admin (5).
.PP
.IR "The Trivial IP Encryption Protocol" ,
.IR "The Wrestlers Protocol" .
.SH "AUTHOR"
Mark Wooding, <mdw@nsict.org>