diff options
Diffstat (limited to 'openssl/vendor/0.9.8d/demos/tunala/README')
-rw-r--r-- | openssl/vendor/0.9.8d/demos/tunala/README | 233 |
1 files changed, 0 insertions, 233 deletions
diff --git a/openssl/vendor/0.9.8d/demos/tunala/README b/openssl/vendor/0.9.8d/demos/tunala/README deleted file mode 100644 index 15690088..00000000 --- a/openssl/vendor/0.9.8d/demos/tunala/README +++ /dev/null @@ -1,233 +0,0 @@ -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 :-) - - |