
Copyright (c) 2009-2010 Jess Mahan <ctunnel-`date + %s`>@nardcore.org

----------------
ctunnel    0.4
----------------

  What it is:
    ctunnel is a software for proxying and forwarding TCP or UDP
    connections via a cryptographic tunnel.

    ctunnel can be used to secure any existing TCP or UDP based 
    protocol, such as HTTP, Telnet, FTP, RSH, MySQL, etc. 
    You can even tunnel SSH! (if you are really paranoid!).

    You can also chain/bounce connections to any number of intermediary
    hosts.

  What it is not:
    ctunnel is not a replacement for any TCP or UDP server like 
    SSH or HTTP, nor is it a good idea to keep using insecure protocols 
    such as telnet or ftp even if you are using ctunnel! Antiquated 
    protocols are just that, antiquated, and should be fased out.


----------------
How it works
----------------

  ctunnel works by listening on the client machine, encrypting the
  TCP or UDP traffic, and then forwarding the encrypted traffic to the server,
  where another instance of ctunnel will decrypt that traffic in turn
  and forward the decrypted traffic to the destination port.


----------------
Examples
----------------

  How about an example?

  ** Note, the examples below are for OpenSSL            **
  ** Substitute '-C aes-256-cfb' with '-C aes256 -M cfb' **
  ** when compiled with libgcrypt                        **

  For instance, your local machine has an IP of 10.0.0.2. Now let's say you've 
  got a VNC server running on 10.0.0.4, listening on 5901 (the default port for
  vnc) and you want to secure it.

  On the client machine (10.0.0.2) we'll run ctunnel.

    ./ctunnel -H 10.0.0.4 -c -l 2221 -f 2222 -C aes-256-cfb

  On the server machine (10.0.0.4 running the vnc server) we'll also run ctunnel.

    ./ctunnel -H 127.0.0.1 -s -l 2222 -f 2221 -C aes-256-cfb

  On the client machine (10.0.0.2) we run vncviewr throught the tunnel.

    ./vncviewer 127.0.0.1::2221
    

  Ta DA! You've got an encrypted tunnel right to your VNC Server.

  An even more secure example would be to make sure that VNC Server on
  10.0.0.4 was only listening on it's local loopback interface of 127.0.0.1,
  this way the only way to access it would be via ctunnel.

  MySQL:

  Client/10.0.0.2

    ./ctunnel -c -H 10.0.0.4 -l 2221 -f 3306 -C aes-256-cfb

  Server/10.0.0.4

    ./ctunnel -s -H 127.0.0.1 -l 3306 -f 2221 -C aes-256-cfb

  Client

    mysql -u root -p -h 127.0.0.1 


  You can also bounce connections off an intermediary proxy, like this:

  Client/10.0.0.2

    ./ctunnel -c -H 10.0.0.3 -l 2221 -f 2222 -C aes-256-cfb

  Proxy/10.0.0.3

    ./ctunnel -s -H 127.0.0.1 -l 2222 -f 2223 -C aes-256-cfb &
    ./ctunnel -c -H 10.0.0.4 -l 2223 -f 2224 -C aes-256-cfb

  Server/10.0.0.4

    ./ctunnel -s -H 127.0.0.1 -l 2224 -f 3306 -C aes-256-cfb


  DNS:

  Server/10.0.0.3

    ./ctunnel -U -n -s -l 5001 -f 53 -H localhost -C aes-256-cfb

  Client/10.0.0.2
    ./ctunnel -U -n -c -l 53 -f 5001 -H 10.0.0.3 -C aes-256-cfb
    dig @localhost nardcore.org


----------------
Ciphers
----------------

  ctunnel current allows you to specifcy any OpenSSL/libgcrypt cipher via
  the -C switch (-C and -M for libgcrypt). ctunnel does not check wether 
  you are using a stream or block cipher, but you MUST use a stream cipher
  for it to work.

  ******** YOU MUST USE A STREAM CIPHER ********

  In the example above we use aes-256-cfb, which is the Cipher Feeback mode
  for aes-256. You can use Ouput Feedback (ofb) mode. See the OpenSSL or
  libgcrypt manual for a complete list of Cipher Types.


----------------
Keys
----------------

  So, how do we securely make a tunnel with a stream cipher? I'll
  bet you're thinking Keys, and you're correct, partly! Thinking passwords?
  You're correct there also.

  Let's explain:
  CTunnel does not rely on traditional PEM format keys, or a CA authority.
  It uses what you might call a "Key" as a "Password". CTunnel will store
  your "Passkey" in ~/.passkey. It stores a 16 character Key and IV in this
  file. SO PROTECT IT! 

  On your first run of CTunnel you will be prompted to enter your Key and
  IV in, after which CTunnel won't prompt you again until you remove
  your passkey file located in ~/.passkey

----------------
Requirments
----------------

  OpenSSL    http://www.openssl.org
  or
  libgcrypt  http://www.gnupg.org

  Typically you can just apt-get install libssl-dev or grab the openssl
  or libgcrypt development libraries and headers for your distro.


----------------
Building
----------------

  Yup, you guessed it...
  If you have met all the *requirements* then just do:
  make; make install


----------------
Getting Help
----------------

  If you need help, please make sure before asking a question
  that you do indeed have the ssl development libraries installed,
  and that you have read and understand the section "Examples" and
  the section "Ciphers".

  More often than not you are either getting your -c/-s switches 
  mixed up, or you are not using a stream cipher as specified in
  the "Ciphers" section.

  NOTE: If you do not specify the -U switch (to operate in UDP mode), 
  CTunnel will operate in TCP mode.

  If you are still having trouble, feel free to contact me. I can
  be reached via ctunnel-<unixtimestamp>@nardcore.org

