Welcome to Tunnel Vision
========================

Tunnel Vision creates an encrypted network connection between computers on
the internet, and allows you to forward arbitrary TCP/IP packets between two
or more computers on the network.  This connection is sometimes called a VPN
(Virtual Private Network) because it serves as a drop-in replacement for the
very expensive "old-style" private networks that some companies run between
their offices.

This README file will give you quick information about how to install and
use TV.  For more detailed technical information, including an answer to the
question "Why aren't you using IPsec?" you should read the file TECHINFO,
which is included with the program.  The latest version is always available
from our web site:
                http://www.worldvisions.ca/tunnelv/

This free software is brought to you by Worldvisions Computer Technology in
Waterloo, Ontario, Canada.  To find out about the license terms (the GNU
*Library* General Public License, or LGPL) you should have a look at the
file COPYING.LIB, which was included with this archive.

We'll probably create a mailing list for TV pretty soon.  Until then, why
not just write to us directly?  We're really helpful people, really.  Send
e-mail to the following address:

                tunnelv@worldvisions.ca
                
                
Hey, export restrictions!
=========================

This program uses strong cryptography and it's illegal to export such simple
mathematics from the United States and some other countries.  It is,
however, legal to import it into the United States and other countries. 
We're in Canada here, and it's legal to export strong cryptographic code
from Canada.

Watch yourself though -- once imported into the U.S., it's still illegal to
export crypto code again.  Yes, it's weird, but you're better off giving
people pointers to our Canadian web site than placing TV on an American site. 
You can do it, but do it at your own risk.

Also, since RSA holds a patent on their encryption algorithm, if you're in
the U.S. you need to use the RSAREF library and not the international RSA
library when you build SSLeay.  That doesn't really affect how you use TV,
but it's something you should know.

Okay, enough legal stuff.


So what does it do?
===================

TV creates a "virtual" TCP/IP network (VPN) between two Tunnel
Vision-capable sites on the internet.  It uses the strongest encryption
that's actually useful (1024-bit RSA and 128-bit Blowfish) to protect your
data along the way.  This connection between two TV servers is called a
"tunnel."

Tunnel Vision is usually used on a router or gateway machine.  When someone
on your network wants to send data to someone on the other side of the
tunnel, it sends through the default gateway (the TV server) like it
normally would.  You configure the TV server to send data through the tunnel
instead of just forwarding it onto the internet.


What do I need?
===============

You need two computers at different places on the internet, so that you can
create a tunnel between them.  If you don't have these, you can still make a
tunnel on your own machine or your local network -- but it's pretty
pointless.

This free release of Tunnel Vision is completely compatible with the one
used in our Worldvisions Weaver gateway (http://www.worldvisions.ca), so if
you want, one or both ends of the TV connection can be a Weaver.  If both
ends are using a Weaver gateway, you don't need this distribution.  Read
your Weaver documentation instead.

To set up Tunnel Vision on a Linux machine, you need:

        - Linux 2.1.112 or higher with the "ethertap" and "netlink" devices
          configured.  Sorry, we know it's unstable, but we needed to use
          the new features.
          
          You need to load one ethertap kernel module for each tunnel you
          want to open at a time.  Many people will just use one tunnel, so
          you only need one ethertap.
          
        - The SSLeay library.  The only one we've tested is version 0.9.0a,
          so if you have problems, try switching to that version.  SSLeay
          does the actual low-level encryption for TV.  Look at
          ftp.replay.com to see if you can find SSLeay.

        - libc6, probably.  We haven't tested it with anything else.

That's about all.  If your SSLeay is installed in a nonstandard location,
you may need to edit tunnelv/Makefile to point at your SSLeay includes and
libraries.

Once all of these are installed, you should be able to just type:
        make
        
In the top-level tunnelv directory and it should compile and run.  Then run:
        
        make install
        
To put the tunnelv program in /usr/local/bin.  Edit the Makefile first if
you want it somewhere else.  Later, you can run:

        make uninstall
        
And it will go away again.


Making a Connection
===================

Okay, here's a basic idea of how it works.  If you want the low-down
nitty-gritty gory details, see the file TECHINFO in this directory.

Tunnel Vision doesn't actually use a password to identify itself to other TV
servers or do encryption.  It's been scientifically proven (by other people,
not by me) that passwords provide pretty lousy security for encryption
purposes, especially since people tend to pick really easy passwords.

Furthermore, sending any plaintext password across the internet is a rotten
idea, since sneaky people can view it while in transit.  We're trying to put
together a virtual _private_ network here.

So anyway, Tunnel Vision does its best to avoid sending passwords whenever
possible, and even when it does send a password, it makes sure it's
encrypted.  Here's how:

        - when you use TV for the first time, it generates a random 1024-bit
          RSA public/private key pair and stores it in /etc/tunnelv.conf.
          
        - TV connects to the other end of the tunnel (or waits for a
          connection to arrive).  When it makes a connection, each TV
          server sends the _public_ side of its RSA key to the other side.
          We switch to RSA-encrypted communications right away.
          
        - Now, RSA is pretty slow.  So one end of the TV connection
          generates a secret, random 128-bit "Blowfish" key and sends it
          over the RSA-encrypted connection.  Now we switch to the really
          fast and highly secure Blowfish encryption algorithm.  Anyone with
          the Blowfish key can read the traffic, but the only people with
          the Blowfish key should be the two TV servers -- after all, we
          sent the Blowfish key across the link in an encrypted form.
          
        - Now, we look at the RSA keys (I know, it seems backwards, but
          trust me on this).  If the TV servers recognize each other's RSA
          key, that's it -- they're authenticated.  There was no password
          ever sent, and all the keys we used were strongly random, so
          they're almost impossible for anyone to crack.  At least, we
          hope so.  No one has cracked them so far, anyway.

        - If the TV servers don't recognize each other, then they request
          an authentication password from the other end.  If you have a
          password listed in the config file, we send it across (encrypted
          using Blowfish, of course).  Ever after, or until removing the RSA
          keys from /etc/tunnelv.conf, these two servers don't need a
          password to talk to each other.  You can even take the password
          out of /etc/tunnelv.conf.  Actually, you should, because passwords
          make rotten security.  (Did we mention that using passwords is a
          bad way to do encryption?  Well, it is.  Bad, that is.)

Did you read all that?  I doubt it.  Okay, here's what you actually have to
do.  On both ends, create a file /etc/tunnelv.conf and enter the following
lines:

        [Tunnel Vision]
        Magic Password = funky-doo
        
And PLEASE, change the password to something other than funky-doo, okay? 
Remember, it only makes sense if you put the the SAME password on both
systems.

Now, on one end, running as root, do this:

        tunnelv 1234
        
And on the other end, this:

        tunnelv that-other-guy's-address 1234

Where "1234" is the port number you want to use (Worldvisions Weaver always
uses 1234, so you might want to do so as well) and that-other-guy's-address
is the address of the _first_ computer, the one where you just ran "tunnelv
1234".

Now, hopefully, they connected okay.  You know they did if they say
"starting to exchange packets" or something similar.  If it worked, get rid
of the password (on BOTH ends) to increase your security.  Remember, from
now on, the servers can authenticate each other using the much more secure
RSA algorithm.  Take the "Magic Password" line out of /etc/tunnelv.conf.


Routing Packets
===============

Now you have two computers connected together via a Tunnel Vision VPN.  But
does it work?  Well, if you're lucky, yes, because TV makes a few guesses
about your network setup.  But if you're more normal than lucky, you need to
fiddle with a few things first.  Check these details:

        - is the tap0 device up?  Check by typing "ifconfig".  If not, read
          the TV log messages to see if anything went wrong.
          
        - is IP forwarding enabled in your kernel?  No matter what you pick
          in the kernel configuration, it's off by default in 2.1.x kernels.
          You have to turn it on like this:
                echo 1 >/proc/sys/net/ipv4/ip_forward
                
        - is there a route (or more than one) through the tap0 interface?
          Check using the "route" command.  If there is, and it looks right,
          then you're done.  If not, you need to add one.  Try this:
          
                route add -net my-subnet-number netmask 255.255.255.0 tap0
                
          That will route all traffic for my-subnet-number across the
          tunnel.  If you don't know what my-subnet-number is, or which
          end needs this route command, or even what a route is, you should
          go read some books or HOWTOs now.  You'll probably never get
          this working otherwise.  Some excellent documentation is at the
          Linux documentation project:
                
                http://sunsite.unc.edu/linux/
                
Now, try to "ping" someone on the other side of the VPN.  You should get a
ping response back.  You should also see various messages coming out of
Tunnel Vision - read them.  If you don't see anything, you may have
configured something incorrectly.  Re-read the above instructions, and if it
still doesn't work, please contact us.


Bringing down the connection
============================

Just kill the tunnelv program on one or both ends.  It'll come down safely
and clean up after itself.


Contact us!
===========

This is an early release of Tunnel Vision for Linux.  It's well-tested in
our controlled Worldvisions Weaver environment, but lots of bugs can appear
when you run it in different Unix settings.  If you have problems, or even
if you have success, please let us know at the address at the top of this
file.

Have fun with it!

And remember:
        If it looks like a lemon, and smells like a lemon,
        Why are you eating it?  It's a lemon, for heaven's sake!