
	    For psyv, march 20, 1979 - November 29, 2001,
		My memories of you will always stay.


+Aesop:  Advanced Encrypted Stackable Open Proxy

+Table of Contents:

 - Overview
 - Key features
 - License
 - Design
    - Single proxy
    - Chain of proxies
 - How to build?
 - How to use?
 - The syntax for the routes file
 - Libaesop
 - Information
 - Thanks
 - Bugs
 - Todo
 - Suggestions

+Overview:

Aesop is a TCP-proxy which supports many advanced and powerful features.
It's designed to be secure, fast and reliable. Aesop makes use of strong
cryptography for all it's data-transmission up to the end-link. Another 
powerful feature of Aesop is that Aesop proxies can be transparently 
stacked into a secure chain. Aesop is implemented using multiplexing and
is therefore fast and lightweight. Aesop ships with libaesop, which is a
LD_PRELOAD wrapper around connect(), it enables almost any application to
be run over a defined chain of aesop proxies.

+Key features:

	- Fast and reliable TCP-proxy.
	- Strong cryptography: Arcfour (RC4) with a 512bit key exchanged
	  by the Signed Diffie Hellman protocol (With RSA/MD5 for the 
	  signature).
	- Encryption and key-exchange is all transparent to the user.
	- Multiple proxies can be stacked in a chain to create a secure
	  anonymous route, there is no limit on how many proxies can be
	  stacked. Stacking is done all transparent to the user.
	- Libaesop enables almost any application to be run over a defined
	  chain of aesop proxies.
	- Proper forwarding and handling of Out-of-Band (OOB) data.
	- Optimal performance by a single-thread design. Aesop is fully
	  multiplexed.
	- Advisory/Mandatory endpoint sourceport specification.
	- Lightweight.

+License:

Aesop is released under the GNU Public License version 2. See the included
LICENSE file for more information.

+Design:

Aesop can be used in 2 ways. Either as stand-alone link or as a chain of
proxies. We will discuss both of them now:

++Single proxy:

The basic idea is as follows:

   user <encrypted> proxy <plain data> destination

An implementation of this situation will work as follows:

   application <plain> aesoptunnel <Signed DH, RC4> aesopd <plain> destination

The user selects a proxy to use, tells aesoptunnel to use that proxy, gives it
the destination host/port and a local port to bind to. Then the application tcp
will be told to connect to the localhost on the said tunnel and the connection will
transparently use encrypted communications through the Aesop proxy. Between the aesoptunnel and
the aesopd a Signed DH key exchange is done in order to exchange a 512bit key, which is
used to initialise an RC4 cipher where further encryption is done with.

++Chain of proxies:

The basic idea is as follows:

   user <encrypted> proxy0 <encrypted> proxy1 ... proxyN <plain> destination

An implementation of this situation will work as follows:

app <plain> aesoptunnel <DH, RC4> aesopd1 <DH, RC4> aesopd2 ... aesopdN <plain> dest.
			<-----------Signed DH, RC4------------>

The user sets up the aesoptunnel in the same way, the only difference is that a
chain of multiple proxies is specified. Aesoptunnel does a DH key exchange
with the first proxy and sets up a RC4-encrypted link, then it passes all it's control
headers (automatically generated by aesoptunnel according to the route specified by
the user). Those headers specify that the proxy should run (for that connection) in
chain mode and it connects to the next proxy in the route. Another DH key exchange is
done between these hosts and another rc4-encrypted link is setup. This continues upto
the last proxy. This proxy is called the endpoint. Once the endpoint has completed DH with
the previous proxy and setup a rc4-encrypted link with it, it does over that encrypted
link back with the user a Signed DH key exchange to initialise another RC4 cipher which
goes over the baselink of the chain-proxies. Since a Signed DH key exchange is done. No
Man-In-The-Middle attack can be successfully performed without being noticed by the
user. Also since every proxy in the chain initialises a new cipher with the next proxy
in the chain, incoming data will be completely different from outgoing data for every
proxy.


+How to build:

The BUILDING file explains how aesop can be built. It contains some very important 
information, so read it carefully!

Once successfully built you should see three new files in the current directory:
   aesopd:		The Aesop proxy server daemon
   aesoptunnel:		The Aesop client tunnel
   keygen:		A program to create a 1024bit RSA public/private key-pair.

And if you have configured aesop with --enable-aesop, you ll also find:
   libaesop.so.0:	The LD_PRELOAD wrapper around connect(). (See Libaesop section)

+How to use:

To use the Aesop proxy you need to create a RSA key-pair first. This can be done with the
keygen program:
	keygen <publickeyfile> <privatekeyfile>

You have to specify the output public and private key-files. The default names for these 
files which aesopd and aesoptunnel expect are "Server.pub" and "Server.prv". This can be
changed with the -k switch for both aesopd and aesoptunnel.

Now the Aesop proxy (aesopd) can be started. The syntax for aesopd is:
	aesopd [options] [[listenhost[/v4|/v6]:]port]

A listenhost and a port can be specified optionally. If the listenhost is given, aesopd
will attempt to bind to that host, else it will take INADDR_ANY, if the port is not specified
the default port of 6789 will be used. The options to aesopd are as follows:

   -h		Show a listing of the syntax and options.
   -d           Run the daemon in debug mode. Aesop will not fork into the background
		and will print out all debug messages to stdout.
   -c dir       Aesop will chroot to that directory and then changedir to it's new root.
		An effective uid of root is required for this operation.
   -u uid       Run daemon under uid. An effective uid of root is required to change the
		user id.
   -g gid       Run daemon under gid. An effective uid of root is required to change the
		user id.
   -e           Disable support for udp probing. Aesop binds by default also a listening
		UDP socket on the same port it bound it's listening TCP socket on. It
		waits for special datagrams to arrive on this port which are sent out by
		some aesoptunnel to detect if the proxy is running. 
   -l num       Maximum simultaneous connections.
   -s size      Set internal buffersize. Here you can change the default read buffer size
		for every internal Connection structure. The default buffer is as big
		as the host's TCP send-buffer size.
   -k file      Specify which private keyfile to use. If not specified the default of
		"Server.prv" is assumed. This private key is used to sign the servers part
		of the DH protocol.
   -t timeout   Change the default connection timeout. The default timeout is 10 seconds.
   -b base      Set sourceport specification base. If a connection request comes in with
		sourceport specification and the port specified is lower than base, then
		the specification will be ignored. If all sourceport specifications need
		to be ignored, set base to be greater than 65535.
   -r file	Specify random seed file. You can override the default random seed file	
		with this option. It is VERY IMPORTANT that Aesop always gets good random
		seed. If this option is omitted, and the default RANDOM_SEED_FILE has not
		been changed, then /dev/urandom will be used. Read the BUILDING file on
		how to change the default file permanently.
   -v           Show version information.


Once a user wants to tunnel a TCP connection over an Aesop proxy it starts up an 
aesoptunnel session. The user specifies a file which contains the proxy or the proxies
to use and eventually specifies the label of the route he wants to take. Aesoptunnel has
two modes of operation. The syntax for the first mode of operation for aesoptunnel is as 
follows:

	aesoptunnel [options] [destinationhost[/v4|/v6]:]port [listenhost[/v4|/v6]:]port

If destination host is omitted, localhost is assumed. If listenhost is omitted INADDR_ANY
is assumed. The first port specifies the port to connect on, on the destination host. The
second port specifies the local port where aesoptunnel should be listening for incoming
connections.

The syntax for the second mode of operation for aesoptunnel is as follows:

	aesoptunnel [options] [listenhost[/v4|/v6]#]port

The destinationhost and port are omitted, and aesoptunnel will read a destination header
in on any connection which specifies the destinationhost and port. This mode is for
example used in conjunction with libaesop. If listenhost is omitted INADDR_ANY is assumed.

The options to aesoptunnel are as follows:

   -h		Show a listing of the syntax and options.
   -d		Run the daemon in debug mode. Aesop will not fork into the background
		and will print out all debug messages to stdout.
   -f file	Specify file to read the proxy information from. File must have a special
		syntax which is explained later.
   -l label	Specify the label of the proxy information. The default label is the
		first label
   -k file	Specify which public keyfile to use. If not specified the default of
		"Server.pub" is assumed. The public key must be the public key of the
		endpoint. It's important that this is the correct key else the Signed DH
		protocol will fail.
   -i		Ignore signature from endpoint. If this option is specified aesoptunnel
		will not verify the signature from the endpoint. By ignoring this signature
		a MITM attack will remain unnoticed and therefore the use of this option
		is not recommended. (It can for example be used if the public key of the 
		endpoint is lost).
   -u		Do a UDP probe on all the proxies in the route. If a proxy does not respond
		to the probe and -s is not specified. aesoptunnel will stop with an error.
   -s		Skip proxies which didn't respond to udp probe. aesoptunnel will give a
		warning for every proxy which didnt respond to the probe when this option is
		specified.
   -a port      Advisory sourceport specification. The endpoint will be requested to use the
		specified port as sourceport for the connection to the destination. If the
		proxy has been configured to disallow that port, or if the port could not be
		bound the proxy is allowed to choose a random sourceport.
   -m port      Mandatory sourceport specification. Same as with the -a option. With one 
		important difference: If the sourceport can not be used for whatever reason
		then the connection will not be made.
   -r file      Specify random seed file. You can override the default random seed file
		with this option. It is VERY IMPORTANT that Aesop always gets good random
		seed. If this option is omitted, and the default RANDOM_SEED_FILE has not
		been changed, then /dev/urandom will be used. Read the BUILDING file on
		how to change the default file permanently.
   -v		Show version information.


+The syntax for the routes file:

Every line starting with a hash-symbol '#' is ignored as a comment-line, empty lines are ignored
too. A route starts with a new label and ends on eof of the file, or if a new label is 
specified. A label consists of alphanumeric digits ended by a dollarsign '$'. like this: 'label$'
Each line after the specification of a label specifies the hostname (and
eventually a port) of a host running Aesop to use. An entry exists of a hostname or
IP-address and then eventually a port-number separated from the hostname by whitespace. If the
port-number is omitted a default port of 6789 is assumed.

Libaesop:

Libaesop provides a LD_PRELOAD wrapper around connect(). Every application using connect() from
a library (ie, not statically compiled binaries) will be redirected to use a predefined chain of
aesop proxies when it makes a connection. This will only work on systems which have support for
LD_PRELOAD. Those systems include: Linux, FreeBSD, NetBSD, OpenBSD, Solaris. It makes no sense
to compile libaesop on any system which does not support LD_PRELOAD. If you want to built libaesop
you need to give the --enable-libaesop function to the configure script.

Libaesop requires one systemwide aesoptunnel to be running. It must be running without a destination
specified. (See the description for aesoptunnel). Libaesop will generate the destination header
according to the arguments connect() is called with and connect to the systemwide aesoptunnel. Only
one aesoptunnel has to be running on the whole system for all applications using libaesop to work.
You do not need to start a seperate aesoptunnel for every connection you make. Libaesop looks
on initialisation after 3 environmental variables:

AESOP_TUNNEL_ADDR	: Contains the IPv4 or IPv6 address where the systemwide aesoptunnel is running
			  on. A /v4 or /v6 prefix is NOT needed. If the variable is not set
			  "127.0.0.1" is assumed for IPv4 sockets and "::1" is assumed for IPv6 sockets. 
AESOP_TUNNEL_PORT	: Contains the port the systemwide aesoptunnel is running on. If this variable
			  is not set the string "3000" will be assumed. 
AESOP_ALLOW_IPV4TOIPV6  : If this variable is set then libaesop will turn an IPv4 socket into an IPv6
                          socket if the AESOP_TUNNEL_ADDR is set to an IPv6 address and the socket
                          passed to connect() is an IPv4 socket. Because there is a little chance that
                          some applications will not work correctly with this, you have to set this
                          yourself.


Libaesop will work with the majority of applications. Some examples of applications i've had success with
include: Mozilla, Netscape, Ftp, Telnet and my email client.

Sample usage:

$ export AESOP_TUNNEL_PORT="5000"
$ export LD_PRELOAD="./libaesop.so.0"
$ mozilla

You can also use the runaesop.sh script which does nothing more than setting the variables for you and
executing it's commandline arguments.

+Information:

More information can be found on the Aesop web-site:
	http://www.kryptology.org/aesop/

The author of Aesop is bighawk and he can be reached at bighawk@kryptology.org.


+Thanks:

I would like to thank the following people for invaluable help and input:

anakata		Many useful advise
scut		Idea for libaesop
sectorx		Initial idea

+Bugs:

There are currently no known bugs. However it's almost certain that Aesop contains bugs, if
you find any, or if you expect other behavior. Please mail them to bighawk@kryptology.org.
With a clear description of the bug. And a debug output if possible.

+Todo:

There are many more things to do, a few important things are:

	- Secure authentication.
	- Various other improvements..

+Suggestions:

If you have any suggestions, you are welcome to mail them to bighawk@kryptology.org.
