path: root/README

Rapid Tunneling
===============
Tzafrir Cohen <tzafrir.cohen@xorcom.com>

Rapid Tunnelling(tm) uses the capabilities of openssh to allow you to 
support your clients even behind firewalls.

The software includes a client-side component and a server-side component.
Both are mainly built around the features of the ssh protocol to provide 
tunneling.

The server should have a well-known address (hostname/IP and port) that
the client will use to establish a connection. The client initiates an
initial ssh connection to the server and provides the server reverse port
forwarding.

Furthermore, the client sets up an ability for the user on the server
to login to the client system using an ssh private key that is sent on
the connection. Thus the support personnel on the support server can login.


Setup
-----
Server
~~~~~~
The server has an extra service running (an extra instance of sshd with 
different configuration). Forthermore, it has a special user called 
'support'. This will be the user generating the connections and connecting
to remote users. 

* Install the package rapid-tunneling-server
* Edit the host (name/IP) and port in /etc/rapid-tunnelling/rtadm . This 
  is where the client should connect to.
* Provide a special way for the support user to login. It cannot login 
  through ssh. One possible way is from another user account through 
  sudo -i .


Client
~~~~~~
* Install the packages rapid-tunneling (base package) and 
  rapid-tunneling-gui (simple web interface).
* Package installs a user called rapid-tunneling for all the dirty work.
* The client only trusts servers for which it has the keys. Make sure it
  knows the keys with which you sign on the server.
* The -gui places a web interface on http://<hostname>/support . 
  While technically this interface should only allow usage through 
  a signed tarball, you may still wish to limit access to it.


Usage
-----
Connecting
~~~~~~~~~~
Clint the client opens a support ticket. Someone logs into the support 
user on the server and runs:

  rtadm create 4567 clint
  rtadm enable clint

4567::
  The port clint will open on the server (using ssh -R). 
  Thus make sure it is unique for the time of the support.

clint::
  A string used to identify this connection.

This has created 'remote-access-clint.tar.gz' which has the details of
the connection. The next step is to deliver that tarball to the client.
The file is created under the subdirectory ''tar/'' .

The client now connects to the web interface, places the tarball and clicks
on "Connect". A connection should be established.

Which means that the support user can now connect with ssh to 'ra-clint'
and be logged on to the special rapid-tunneling account on Client's 
machine.

When the client has had enough, the client selects "disconnect" from
the web interface.


Command-Line Usage
------------------
Generating the tarball is as above. On the client side:

  rapid-tunneling path/to/remote-access-clint.tar.gz

This will fork a background demon process to keep the connection alive. As
this is done in the background you will not get any potential errors. Thus
you should run:

  rapid-tunneling-status

To disconnect: run

  rapid-tunneling-status -s


Server Operation
----------------
rtadm
~~~~~
The utility that controls things on the server side. 

TODO: document it. For starters, its help message:

  Usage: /usr/share/rapid-tunneling/bin/rtadm <command> [options]
  Commands:
  create [-e] <tunnel-port> <connection-name>
    # create invitation tar.gz, if -e specified, enable it
  show
    # show current connections
  enable <connection-name>
  disable <connection-name>
    # enable/disable future connections
  disconnect <connection-name>
    # disconnect connection
  upload <connection-name>
    # upload a copy of the key
  delete <connection-name>
    # disconnect, disable and delete any trace of the connection

"Enabled" connection is a connection that can start a new tunnel. 
Disabling it does not Disconnect an existing connection. It essentially
rems-out the respective line in .ssh/authorized_keys .

"Upload" pipes the tarball over SSH to a remote system. Using the example
script rt_handle_uploaded_key on that remote system you can use it to
provide a download version of your keys.


Server Troubleshooting
~~~~~~~~~~~~~~~~~~~~~~
The client connects with (essentially)

  ssh -i key support@server <ra-params.tar.gz

It uses the ssh key that the server generated in the support request and
sent over in the tarball. It connects and sends a tarball as its
standard input.

This is answered by the dedicated sshd. As per the command directive in
the authorized_keys file, /usr/share/rapid-tunneling/bin/rt-from-remote
will be run to handle this. Output from this goes to the file 'log' in
the support home directory. Errors go to 'err'. Malformed tarballs go to 
the 'bad/' subdirectory. Tarballs used by active connections are in 'ra/'
and ones belonging to deleted connections: in 'ra/old/'.



Client Operation
----------------
Here should be described the actual command-line interface.

For starters:

A connection is maintianed by a daemonized ssh process.


rapid-tunneling
~~~~~~~~~~~~~~~
Used to start the connection:

  rapid-tunneling remote-access-<name>.tar.gz


rapid-tunneling-status
~~~~~~~~~~~~~~~~~~~~~~
Prints out a textual status and also returns:

* 0: Connected
* 1: Connecting
* 2: Disconnected

Can also be used to disconnect a running connection by killing the ssh
process that maintains it.


Development
-----------
* https://sourceforge.net/projects/rapid-tunneling/[Project page at SourceForge]
* https://sourceforge.net/scm/?type=git&group_id=255282[Git Repository]

Feel free to send Tzafrir any questions or patches.


Security
--------
Ideally this system should be simple to set up (assuming you have an SSH
server with a public IP address) and thus would be a handy and more secure
replacement to sending a password in the clear, or installing some Big
Binary Blob.

The Server
~~~~~~~~~~
The remote access tarball is sent potentially over an untrusted channel
(read: the Internet). It contains potentially sensitive information: a 
private ssh key. An imposter could try to impersionate as the client.
But I can see no specific benifit here. We did not want to assume that
the server has any prior knowledge of the client, anyway.

However that private key only allows a remote user very limited ability:
The authorized_keys line is:

no-X11-forwarding,no-agent-forwarding,no-pty,permitopen="127.0.0.1:65534",command="/usr/share/rapid-tunneling/bin/rt-from-remote 4567" ssh-rsa <snip lengthy key> ra-4567-clint-20090105180013

A key can also be used to flood the server's disk, which means that the
support user's quota should be limited.


The Client
~~~~~~~~~~
The client then sends the connection information over the already
established connection.

Alternatively, if an attacker manages to send her own key (pointing to
her own RapidTunneling server) to the user, while pretending that this
key comes from a trusted support contact, the attacker will gain access
to the user's system. Thus the user should be careful about the key he gets.

I believe that there's no inherent issue with adding an extra key to the
user's authorized_keys file: If the user has explicitly asked for remote
support from a trusted party, the user might as well have sent the
password. If the connection was not disconnected explicitly by the user
(`rapid-tunneling-status -s`), those entries will remain and the client
should delete them manually (`rapid-tunneling-status -r`).