Copyright (c) 2002 #c RusNet channel
All rights reserved

See license.txt for licensing details.

$Id$

This document describes the architecture of the `TCP over SMTP' (ToS) package.


1. Overview.
	The ToS package can be used to achieve TCP over SMTP tunnelling feature.
	This may be needed for certain type of networks, where all outbound
	traffic except the mail traffic, is rejected.

	In order to provide this functionality, the package contains of
	two parts: first part runs on remote UNIX host, and second part
	runs on local windows box.

2. Windows client
	the following data is needed to configure windows client:
		o mail server
		o mail user
		o mail password
		o remote email
		o remote server
		o remote port
	
	windows client opens a listening port (7777), and all the data
	received on this port it packs to a mail message and sends to a
	'remote email'. the 'remote server' and 'remote port' means the 
	server/port user wants to tunnel to, and these are packed into the
	mail message 'subject' header. the data in base64-encoded and packed
	into the mail message body. this is should be done by a separate
	thread of execution.
	
	another thread connects to a 'mail server', using 'mail user' and
	'mail password', and checks for the email replies from the
	'remote email'. If a reply comes in, this thread extracts the data
	from the email message, and writes into listening port.

3. UNIX bouncer
	unix part runs on a remote host, and checks specific file
	(/var/spool/mail/<user> or similar) for the incoming mail.
	When receiving the mail message, bouncer extracts the following
	information from the mail message:
		o remote host/port to connect to
		o data to send
	remote host/port is sent into the message header, and the data is
	in the message body, base64 encoded.

	if the connection to the remote host/port is not established yet,
	the bouncer connects to the host/port, otherwise it uses the
	established connection to send a data.

	if the remote server replies, the bouncer packs the data into a mail
	message, and sends a reply back.

4. Email message format
        Email message, either incoming and outgoing, must have the
        fololowing format:

        o smtp headers play no role
        o data is base64 - encoded
        o mail body has the following format: (note MAGIC must start from
	 the first byte on the line)

MAGIC SEQUENCE/ID/EMAIL/SERVER/PORTNUMBER : DATA

	this format describes message as of two parts: header and data,
	delimited by the `:' character.

	MAGIC is the magic string, used to identify the tunnel message

	SEQUENCE is a message number.the message number must increment
        with every message, and message numbers for incoming and
        outgoing mails are independent. this is decimal integer.
	every connection thread (ID) has its own sequence numbers

	ID is the identifier of receiver. since windows client may serve
	several connections, this is the unique connection identifier.
	UNIX bouncer must leave it unchanged while replying.
	this is hexadecimal integer

	EMAIL is the local email, and is used to tell the unix side,
	where to send the replies

	SERVER is a string, identifying 'remote server'.
	
	PORT is a decimal integer, identifies port on remote server

	DATA is a base64-encoded data. if no data is present, but the
	header is valid, that means disconnection request.


5. Data flow diagram.

	
        the 'WINDOWS BOX'  wants to connect to the 'REMOTE HOST'
        

         _______________________
        |                       |
        |  'remote host'        |
        |                       |
        |       'remote port'   |
        |_____o_________________|
              |
              | 
         _____|______________________________________
        |     |     UNIX machine with a remote shell |
        |   __|___________                           |
        |  |              |                          |
        |  | unix bouncer |--                        |
        |  |______________|    \     'remote email'  |
        |                        \                   |
	|                          mail daemon       |
        |__________________________|_________________|
                                   |
                                   |
                                   |    
        internet                   | MAIL hole
     ----------------------------- o --------------------  Firewall
        internal network.            \
                                       \
                                         \       _______________________
                                           \    |                       |
                                             \  | 'mail server'         |
                                               \|                       |
                                                | (can be external)     |
                                                |_______________________|
                       ----------------------->                      | 
                      |                                              |
                      |  from: 'local email'                         |
                      |  to: 'remote email'                          |
                      |                                              |
                      |                                              |
                      |                                              |
         _____________|____________                                  |
        |          ___|__________  |    ('mail user'/'mail password')|
        |         |  mproxy      | |<--------------------------------
        |         |              | |    from: 'remote email'
        |         |     port 7777| |    to: 'local email'
        |         |___o__________| |
        |           /   \          |
        |         /      |         |
        |  ______|___    |         |
        | |irc client|   |         |
        | |__________|   |         |
        |                |         |
        |       _________|___      |
        |      | web browser |     |
        |      |_____________|     |
        |                          |
        |                          |
        |                          |
        |  windows box             |
        |__________________________|

