MsnShell-1.1
============

================================================================================

GRAY-WORLD.NET / MsnShell
=========================

  The MsnShell program is part of the Gray-World.net projects.

  Our Gray-World Team presents on the http://gray-world.net website the projects
  and publications we are working on which  are  related  to  the  NACS (Network
  Access Control System)  bypassing  research  field  and  to  the  computer and
  network security topics.

================================================================================

INTRODUCTION
------------

  MsnShell is a kind of covert channel tunneling tool. With it, You can remotely
  control a Linux computer behind a firewall. It can encapsulate  shell  command
  in MSN protocol. It only consists of an executable file as the Msnshell server
  daemon. Not only can MsnShell work with firewall, but can also pierce an HTTP
  proxy.

  Computers often are located behind  firewalls  which  deny  many  connections.
  Therefore these computers are expected to be  relatively  safe  from  external
  network. But Msn Messenger connection from internal network is usually allowed
  and is made through a gateway or a http proxy which allows internal computers
  to access internet via HTTP.

THE KEY FEATURES
----------------

  1. Give a SSH/FTP from any box located in the internal network to an external
     boxes;
  2. Encapsulate SSH/FTP command or result in MSN protocol;
  3. Can also work with a HTTP proxy;
  4. Multiple access at a same time.

HOW IT WORKS
------------

                  Internal Network                 External Network
                                         |
   |-------|  |-----|     |---------|    f    |--------------------|   |------|
   |C2 sshd|--|C1   |-TCP-| GateWay |----i    |Microsoft Msn server|   |      |
   |-------|  |     |     |---------|    r    |   |------------|   |   |      |
              | MSN |                    e    |   |Notificatoin|   |   |      |
   |-------|  |     |                    |    |   |------------|   |   |  MSN |
   |C3 sshd|--|     |-------HTTP 80------|----|         |          |---|      |
   |-------|  |SHELL|                    w    |   |------------|   |   |CLIENT|
              |     |     |---------|    a    |   |Switch Board|   |   |      |
   |-------|  |     |-WEB-|HttpProxy|----l    |   |------------|   |   |      |
   |C4 ftpd|--|     |     |---------|    l    |--------------------|   |------|
   |-------|  |-----|                    |

   (1) MsnShell connects with Msn Notification server by way of a httpproxy or a
       gateway  within   internal  network.  The  user  logon   process involves
       identifying  the  user to  the  MSN  client and  setting  and  retrieving
       fundamental information.  The client subsequently notifies the MSN server
       in  order for the user to be  shown as 'online'.  After a series of these
       logon process, The MSN client gets the information from server about who
       is online or offline.
   (2) Once MsnShell logged on, It continuously receives both the messages which
       indicates the status of online users and the messages which points out a
       new dialog request from a certain online user. For every online users in
       the msn-messenger, MsnShell creates a struct called online_user_info that
       is a reserved share memory.
   (3) When a new dialog request arrives at the port  connected with MSN server,
       MsnShell  tries to fork a child  process and  sends the  share  memory ID
       relevant to sessions' the other participant to it,The child process opens
       a tunnel to the switchboard  server whose ip is specified by the field of 
       message <IP address>:<PORT>.Generally,You are required to notify at least
       three parameters, <account> <password> and <protocol>. If the parameters 
       <Proxy address> and <Proxy port> are missing, A direct connection is made
       and fills out the fields "authentication" and "session id". If the proxy 
       field are present. It tries to open a connection to the HTTP proxy. 
       MsnShell has to encapsulate MSN protocol message in http protocol package
       . Because It can directly connect to MSN server both Port 1863 and Port 
       80. By means of wrappering MSN in HTTP, It is able to deceive firewall 
       into believing this connection a normal web connection. 
   (4) The initialization  procedure of the  child process  is to make a  socket
       connect with the  switchboard,  After the connection is established,  The
       child process sends authentication field and session id field back to the
       switchboard. Afterwards, It  seperately  generates three threads, namely 
       "read-socket function","execute function" and "write-socket function".The
       read-socket function constantly picks up the command-line information 
       from "MSG" message until A 'BYE' message arrives at this socket. And then
       the "execute thread" executes the corresponding protocl client, according 
       as the first command. And delivers the feedback of the command to STDOUT 
       and STDERR which have been redirected to WRITE FD of a pipefd declared in
       advance.
   (5) The write-socket function parses the info stream obtained from the other 
       side of the pipefd.Afterwards pack in "MSG" message and sends them to the
       client by way of the switchboard.As far as the HTTP protocol is concerned,
       The aspects of it is quite different from normal TCP/IP procedure. In 
       order to  deceiving the HTTP proxy into believing  the connections which 
       are all under it's control is an usual HTTP connection,Both "read-socket"
       function and "write-socket" function are all in the same thread and run 
       alternatively. Therefore, This thread seems to be a ordinary web-client's
       thread sending POST request and GET response through a HTTP proxy.

USAGE
-----

  msnshell 1.11
  Usage: msnshell --account ******@hotmail.com --password ****** --protocol [tcp
         |http] [--proxyhost *.*.*.* --proxyport num]
  Options:
    -a --account ACCOUNT     Msn Account
    -p --password PASSWORD   Msn Password
    -c --protocol [tcp|http] Protocol
    -x --proxyhost *.*.*.*   Proxy server
    -o --proxyport NUMBER    Proxy port
    -v --version             Print version information and exit.
    -h --help                Print usage information and exit.


Troubleshooting
---------------

See that you have following packages installed in your system before you install
MsnShell ...

    a) expect (programmed  dialogue with interactive programs)
    b) expect-devel


Bugs
----

Hopefully none, but if you find any please let me know.


LICENSE
-------

  MsnShell is distributed under the terms of the GNU General Public License v2.0
  and is copyright (c) 2003 Wei Zheng <v_zheng [at] yahoo.com>.
  See the file COPYING for details.

AUTHOR
------

  Wei Zheng <v_zheng [at] yahoo.com>

  Latest MsnShell version is available on :
  http://gray-world.net/
  or
  http://wei-zheng.3322.org/

  MsnShell discussion board at :
  http://gray-world.net/board/

THANKS
------
================================================================================

  Alex Dyatlov <alex [at] gray-world.net>
  
     I would like to thank Alex Dyatlov of Russia for his  generous  support of
     MsnShell development to date.

  Simon Castro <scastro [at] entreelibre.com>

     French README.


