234 lines
11 KiB
Plaintext
234 lines
11 KiB
Plaintext
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 :-)
|
|
|
|
|