Upgrade licence to GPLv3+.

[tripe] / proxy / tripe-mitm.8.in

.\" -*-nroff-*-
.\".
.\" Manual for the malicious proxy
.\"
.\" (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 3 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, see <https://www.gnu.org/licenses/>.
.
.\"--------------------------------------------------------------------------
.so ../common/defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH tripe-mitm 8tripe "14 October 2003" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.
.\"--------------------------------------------------------------------------
.SH "NAME"
.
tripe-mitm \- malicious proxy for TrIPE
.
.\"--------------------------------------------------------------------------
.SH "SYNOPSIS"
.
.B tripe-mitm
.RB [ \-k
.IR keyring ]
.IR directive ...
.
.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
.
The
.B tripe-mitm
program is a
.I malicious
proxy for
.BR tripe (8).
Its purpose is to test the robustness of the TrIPE implementation, by
deliberately introducing communication problems such as dropped,
repeated or corrupted packets.
.PP
The command line contains a sequence of directives, each of which has
the form
.IB command : arg \c
.BR : ...
A list of directives can be stored in a file, one per line, and included
using the
.B include
command.
.SS "Command line options"
The following options are recognized.
.TP
.B "\-h, \-\-help"
Write a very brief help message to standard output, and exit
successfully.
.TP
.B "\-v, \-\-version"
Write the program's version number to standard output, and exit
successfully.
.TP
.B "\-u, \-\-usage"
Write a usage message to standard output, and exit successfully.
.TP
.BI "\-k, \-\-keyring=" file
Read keys from
.IR file .
The default keyring file is
.B keyring.pub
in the current directory.
.SS "Directives"
A directive is ignored if it is empty, or if its first character is a
.RB ` # '.
The following directives are recognized.
.TP
.BI peer: name : local-port : remote-addr : remote-port
Register a peer.  We listen for packets on
.I local-port
and send them on to
.I remote-port
on
.IR remote-addr .
The
.I name
identifies the public key which that peer uses to authenticate itself.
Both
.I local-port
and
.I remote-port
must be numbers;
.I remote-addr
may be a hostname or an IP address in dotted-quad format.  Exactly two
.B peer
directives must be present.  The one first registered is the
.I left
peer; the second is the
.I right
peer.  The two peers must use
.I different
local ports.
.TP
.BI include: file
Read more directives from
.IR file .
Directives should appear one per line.  Empty lines and comments are
permitted.  An included file may include other files.  It may even
include itself, though this is just a good way to tie the program in
knots until it runs out of file handles.
.TP
.BI filt: filter : args : \fR...
Apply a given filter to packets received from either peer.  See the
description of filters below for more details.
.TP
.BI lfilt: filter : args : \fR...
Apply a given filter to packets received from the left peer.
.TP
.BI lfilt: filter : args :\fR...
Apply a given filter to packets received from the right peer.
.TP
.BI next: tag :\fR...
Begin the next branch of the first fork filter node named
.I tag
in each filter chain.  See below for more about filter chains.
.TP
.BI flood\fR[\fP: type : millis : size\fR]
Flood both peers with random packets.  If
.I type
is given, it is interpreted as a TrIPE message type code in hexadecimal,
and the messages sent will have this type; otherwise the messages have
random type.  Messages are sent approximately once every
.I millis
milliseconds; the default interval is 10 milliseconds.  The messages
will be
.I size
bytes long each; the default size is 128 bytes.
.TP
.BI lflood\fR[\fP: type : millis : size\fR]
As for
.B flood
above, but only flood the left peer.
.TP
.BI rflood\fR[\fP: type : millis : size\fR]
As for
.B flood
above, but only flood the right peer.
.SS "Filters"
Each peer has a filter chain associated with it.  Messages received from
that peer get processed by the filter chain.  Only if the filter chain
decides to send the message is it actually sent.  (See the
.B send
filter, described below.)
Messages generated by a
.B flood
directive (above) are also processed by a filter chain, just like normal
messages.  The filters in a chain are processed in the order they were
added.
.PP
The filters currently supported are as follows.
.TP
.B send
Send the message to the destination peer.  This is the
.I only
way messages are sent.  If your filter chains don't end in a
.B send
filter then nothing will get through!
.TP
.BI fork: tag
Introduce a fork in a filter chain.  A fork may have multiple branches
leading off it.  The end of a branch is indicated by a
.B next
directive which names the fork
.IR tag :
further filters added to the chain form a new parallel branch of that
fork.  (If there are two forks with the same tag on a peer's chain, then
only the earliest is matched.  This isn't helpful behaviour.)
.TP
.BI delay: qlen \fR[\fP: millis : p-replay\fR]
Delay, replay and reorder messages.  A queue of
.I qlen
messages is maintained.  If the queue fills up, or every
.I millis
milliseconds (default 100), a message from the queue is chosen at random
and transmitted (i.e., processed by the rest of the filter chain).  If
the message was transmitted due to a timer (rather than lack of space in
the queue) then it has a 1 in
.I p-replay
probability (default 1 in 20) of being left in the queue.
.TP
.BI drop\fR[\fP: p-drop\fR]
Randomly drop messages.  Each message has a 1 in
.I p-drop
probability (default 1 in 5) of being discarded.
.TP
.BI corrupt\fR[\fP: p-corrupt\fR]
Randomly corrupt messages.  Each message has a 1 in
.I p-corrupt
probability (default 1 in 5) of being corrupted by having a
randomly chosen byte mangled.  The message might be further corrupted,
again with a 1 in
.I p-corrupt
probability.
.
.\"--------------------------------------------------------------------------
.SH "BUGS"
.
The parser is currently very primitive, and error handling is rather
poor.  There are lots of pointless restrictions which wouldn't take very
long to fix.  The program generally lacks polish.  The program doesn't
understand the TrIPE protocol to a sufficient extent to really attack it
properly.
.
.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
.
.BR tripe (8).
.
.\"--------------------------------------------------------------------------
.SH "AUTHOR"
.
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------