demos/tunala/README

This is intended to be an example of a state-machine driven SSL application. It
acts as an SSL tunneler (functioning as either the server or client half,
depending on command-line arguments). *PLEASE* read the comments in tunala.h
before you treat this stuff as anything more than a curiosity - YOU HAVE BEEN
WARNED!! There, that's the draconian bit out of the way ...


Why "tunala"??
--------------

I thought I asked you to read tunala.h?? :-)


Show me
-------

If you want to simply see it running, skip to the end and see some example
command-line arguments to demonstrate with.


Where to look and what to do?
-----------------------------

The code is split up roughly coinciding with the detaching of an "abstract" SSL
state machine (which is the purpose of all this) and its surrounding application
specifics. This is primarily to make it possible for me to know when I could cut
corners and when I needed to be rigorous (or at least maintain the pretense as
such :-).

Network stuff:

Basically, the network part of all this is what is supposed to be abstracted out
of the way. The intention is to illustrate one way to stick OpenSSL's mechanisms
inside a little memory-driven sandbox and operate it like a pure state-machine.
So, the network code is inside both ip.c (general utility functions and gory
IPv4 details) and tunala.c itself, which takes care of application specifics
like the main select() loop. The connectivity between the specifics of this
application (TCP/IP tunneling and the associated network code) and the
underlying abstract SSL state machine stuff is through the use of the "buffer_t"
type, declared in tunala.h and implemented in buffer.c.

State machine:

Which leaves us, generally speaking, with the abstract "state machine" code left
over and this is sitting inside sm.c, with declarations inside tunala.h. As can
be seen by the definition of the state_machine_t structure and the associated
functions to manipulate it, there are the 3 OpenSSL "handles" plus 4 buffer_t
structures dealing with IO on both the encrypted and unencrypted sides ("dirty"
and "clean" respectively). The "SSL" handle is what facilitates the reading and
writing of the unencrypted (tunneled) data. The two "BIO" handles act as the
read and write channels for encrypted tunnel traffic - in other applications
these are often socket BIOs so that the OpenSSL framework operates with the
network layer directly. In this example, those two BIOs are memory BIOs
(BIO_s_mem()) so that the sending and receiving of the tunnel traffic stays
within the state-machine, and we can handle where this gets send to (or read
from) ourselves.


Why?
----

If you take a look at the "state_machine_t" section of tunala.h and the code in
sm.c, you will notice that nothing related to the concept of 'transport' is
involved. The binding to TCP/IP networking occurs in tunala.c, specifically
within the "tunala_item_t" structure that associates a state_machine_t object
with 4 file-descriptors. The way to best see where the bridge between the
outside world (TCP/IP reads, writes, select()s, file-descriptors, etc) and the
state machine is, is to examine the "tunala_item_io()" function in tunala.c.
This is currently around lines 641-732 but of course could be subject to change.


And...?
-------

Well, although that function is around 90 lines of code, it could easily have
been a lot less only I was trying to address an easily missed "gotcha" (item (2)
below). The main() code that drives the select/accept/IO loop initialises new
tunala_item_t structures when connections arrive, and works out which
file-descriptors go where depending on whether we're an SSL client or server
(client --> accepted connection is clean and proxied is dirty, server -->
accepted connection is dirty and proxied is clean). What that tunala_item_io()
function is attempting to do is 2 things;

  (1) Perform all reads and writes on the network directly into the
      state_machine_t's buffers (based on a previous select() result), and only
      then allow the abstact state_machine_t to "churn()" using those buffers.
      This will cause the SSL machine to consume as much input data from the two
      "IN" buffers as possible, and generate as much output data into the two
      "OUT" buffers as possible. Back up in the main() function, the next main
      loop loop will examine these output buffers and select() for writability
      on the corresponding sockets if the buffers are non-empty.

  (2) Handle the complicated tunneling-specific issue of cascading "close"s.
      This is the reason for most of the complexity in the logic - if one side
      of the tunnel is closed, you can't simply close the other side and throw
      away the whole thing - (a) there may still be outgoing data on the other
      side of the tunnel that hasn't been sent yet, (b) the close (or things
      happening during the close) may cause more data to be generated that needs
      sending on the other side. Of course, this logic is complicated yet futher
      by the fact that it's different depending on which side closes first :-)
      state_machine_close_clean() will indicate to the state machine that the
      unencrypted side of the tunnel has closed, so any existing outgoing data
      needs to be flushed, and the SSL stream needs to be closed down using the
      appropriate shutdown sequence. state_machine_close_dirty() is simpler
      because it indicates that the SSL stream has been disconnected, so all
      that remains before closing the other side is to flush out anything that
      remains and wait for it to all be sent.

Anyway, with those things in mind, the code should be a little easier to follow
in terms of "what is *this* bit supposed to achieve??!!".


How might this help?
--------------------

Well, the reason I wrote this is that there seemed to be rather a flood of
questions of late on the openssl-dev and openssl-users lists about getting this
whole IO logic thing sorted out, particularly by those who were trying to either
use non-blocking IO, or wanted SSL in an environment where "something else" was
handling the network already and they needed to operate in memory only. This
code is loosely based on some other stuff I've been working on, although that
stuff is far more complete, far more dependant on a whole slew of other
network/framework code I don't want to incorporate here, and far harder to look
at for 5 minutes and follow where everything is going. I will be trying over
time to suck in a few things from that into this demo in the hopes it might be
more useful, and maybe to even make this demo usable as a utility of its own.
Possible things include:

  * controlling multiple processes/threads - this can be used to combat
    latencies and get passed file-descriptor limits on some systems, and it uses
    a "controller" process/thread that maintains IPC links with the
    processes/threads doing the real work.

  * cert verification rules - having some say over which certs get in or out :-)

  * control over SSL protocols and cipher suites

  * A few other things you can already do in s_client and s_server :-)

  * Support (and control over) session resuming, particularly when functioning
    as an SSL client.

If you have a particular environment where this model might work to let you "do
SSL" without having OpenSSL be aware of the transport, then you should find you
could use the state_machine_t structure (or your own variant thereof) and hook
it up to your transport stuff in much the way tunala.c matches it up with those
4 file-descriptors. The state_machine_churn(), state_machine_close_clean(), and
state_machine_close_dirty() functions are the main things to understand - after
that's done, you just have to ensure you're feeding and bleeding the 4
state_machine buffers in a logical fashion. This state_machine loop handles not
only handshakes and normal streaming, but also renegotiates - there's no special
handling required beyond keeping an eye on those 4 buffers and keeping them in
sync with your outer "loop" logic. Ie. if one of the OUT buffers is not empty,
you need to find an opportunity to try and forward its data on. If one of the IN
buffers is not full, you should keep an eye out for data arriving that should be
placed there.

This approach could hopefully also allow you to run the SSL protocol in very
different environments. As an example, you could support encrypted event-driven
IPC where threads/processes pass messages to each other inside an SSL layer;
each IPC-message's payload would be in fact the "dirty" content, and the "clean"
payload coming out of the tunnel at each end would be the real intended message.
Likewise, this could *easily* be made to work across unix domain sockets, or
even entirely different network/comms protocols.

This is also a quick and easy way to do VPN if you (and the remote network's
gateway) support virtual network devices that are encapsulted in a single
network connection, perhaps PPP going through an SSL tunnel?


Suggestions
-----------

Please let me know if you find this useful, or if there's anything wrong or
simply too confusing about it. Patches are also welcome, but please attach a
description of what it changes and why, and "diff -urN" format is preferred.
Mail to geoff@openssl.org should do the trick.


Example
-------

Here is an example of how to use "tunala" ...

First, it's assumed that OpenSSL has already built, and that you are building
inside the ./demos/tunala/ directory. If not - please correct the paths and
flags inside the Makefile. Likewise, if you want to tweak the building, it's
best to try and do so in the makefile (eg. removing the debug flags and adding
optimisation flags).

Secondly, this code has mostly only been tested on Linux. However, some
autoconf/etc support has been added and the code has been compiled on openbsd
and solaris using that.

Thirdly, if you are Win32, you probably need to do some *major* rewriting of
ip.c to stand a hope in hell. Good luck, and please mail me the diff if you do
this, otherwise I will take a look at another time. It can certainly be done,
but it's very non-POSIXy.

See the INSTALL document for details on building.

Now, if you don't have an executable "tunala" compiled, go back to "First,...".
Rinse and repeat.

Inside one console, try typing;

(i)  ./tunala -listen localhost:8080 -proxy localhost:8081 -cacert CA.pem \
              -cert A-client.pem -out_totals -v_peer -v_strict

In another console, type;

(ii) ./tunala -listen localhost:8081 -proxy localhost:23 -cacert CA.pem \
              -cert A-server.pem -server 1 -out_totals -v_peer -v_strict

Now if you open another console and "telnet localhost 8080", you should be
tunneled through to the telnet service on your local machine (if it's running -
you could change it to port "22" and tunnel ssh instead if you so desired). When
you logout of the telnet session, the tunnel should cleanly shutdown and show
you some traffic stats in both consoles. Feel free to experiment. :-)

Notes:

 - the format for the "-listen" argument can skip the host part (eg. "-listen
   8080" is fine). If you do, the listening socket will listen on all interfaces
   so you can connect from other machines for example. Using the "localhost"
   form listens only on 127.0.0.1 so you can only connect locally (unless, of
   course, you've set up weird stuff with your networking in which case probably
   none of the above applies).

 - ./tunala -? gives you a list of other command-line options, but tunala.c is
   also a good place to look :-)