--- /dev/null
+.\" -*-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>
~mdw / tripe / blobdiff