Pre-Requisite
J2SSH Maverick API
Target Host running SSH Server
Email client, the example uses Microsoft Outlook 2003
Resources
OpenSSH Free open source SSH server http://www.openssh.com/
What It Does
This tutorial demonstrates local port forwarding between a client machine and a host target machine. The client acts as the listener taking requests and passes them onto the SSH server process which in turns passes it to the intended recipient. For this example a connection is established between a remote email client, Outlook, and the POP3 and SMTP email servers. The practical implication is that a client, remote to the office network, can access his/her email remotely and securely. Once the secure tunnel has been established all that is required is the configuration of the email client to utilise the respective tunnels. The principle demonstrated can be applied to many insecure applications.
How It Works
Establishing A Session
The first action that is carried out is establishing a SSH session with the host.
con = SshConnector.getInstance();
ssh = connectionSetup(con);
All necessary SSH communication protocols such as key verification and authentication are maintained within this method for clarity. For details regarding how the connectionSetup method works please refer to the Connections set of articles within the Developer Knowledge Base.
Requesting a Pseudo Terminal
After a session has been established between our SSH client and server our next task is to configure a pseudo terminal. A pseudo terminal is a device that imitates a terminal. Rather than being connected to an actual terminal, a pseudo-terminal or pty) is connected to a process. This will allow us to gain visual representation of the remotely opened shell.
if(ssh.isAuthenticated()) {
final ForwardingClient fwd = new ForwardingClient(ssh);
final SshSession session = ssh.openSessionChannel();
session.requestPseudoTerminal("vt100", 80, 24, 0, 0);
As you can see the above block of code and the remaining is all maintained within a secure 'if' block, only successfully Authenticated connections are allowed to continue. A psuedoTerminal can only be retrieved through an SshClient session object and as above we open a new session instance through our successful connection 'SshClient' object, calling the 'openSessionChannel' method.
Opening a Shell
We now must start up a shell to interact with the remote shell on the SSH Server.
session.startShell();
Displaying Status Information
Maverick allows us to query various details regarding sessions, tunnels, clients, connections here we simply demonstrate this by requesting status information on firstly the SshClient, whether it is connected to the server still. Secondly whether the authentication on the client succeeded or not and finally if the connection to the SSH server is still alive.
System.out.println("SshClient connected["+ssh.isConnected()+"]");
System.out.println("SshClient authenticated["+ssh.isAuthenticated()+"]");
System.out.println("SshSession closed["+session.isClosed()+"]");
Establish Local Forwards
A local forward (tunnel) is instantiated to the incoming POP3 email server,
fwd.startLocalForwarding("localhost", 1110, "email.server.co.uk", 110);
The first pair of parameters represents the listener, in our case the SSH client machine, the loopback interface is bound to a random port 1110, ("localhost", 1110. The second pair of parameters identifies the target host we are trying to reach. Of course this is the POP3 email server which listens on the standard POP3 port 110, "email.server.co.uk", 110).
As mentioned earlier we need to establish a second connection from our SSH client machine but this time to the SMTP email server which handles all outgoing emails.
fwd.startLocalForwarding("localhost", 225, "email.server.co.uk", 25);
Once again a local forward is requested from the ForwardingClient object, the first pair of parameters, ("localhost", 225,identifies the listener, our SSH client and a random port number and the second parameter, "email.server.co.uk", 25), the location of out SMTP server listening on the standard 25 SMTP port number.
Handling Output Session Data
Our session and tunnels have all been configured now and are ready but before we run things we need to establish a few minor things mainly IO interaction with our shell. Firstly we establish a means of retrieving the shells response to our requests,
final InputStream in = session.getInputStream();
Terminal terminal = new Terminal(in);
terminal.start();
We retrieve the sessions InputStream and pass that to the Terminal class, If you take a look at the Terminal class you can see this is a simple thread that iterates through the InputStream we supplied, simply printing out the characters received from the remote shell.
Handling Input Session Data
Now that we can see what the shell is returning we need someway of replying to and writing commands to it. This is achieved through the current sessions OutputStream,
while((read = System.in.read()) > -1) {
session.getOutputStream().write(read);
}
We simply loop around writing the content of the System read buffer and writing it out to the sessions output stream.
Execute The Code
Once this code is executed the session will be established and the tunnels ready to be used. Now all that is required is an associated client that can utilise the communication across these channels and interpret them appropriately.
Configuring The Email Client
The email client is our intended recipient of any traffic over this secure channel, a new POP3 account needs to be created.
The server details for the POP3 and SMTP will be to the local machine, localhost port 1110, and localhost 225 respectively, as defined by the two local forwards we established earlier,
fwd.startLocalForwarding("localhost", 1110, "email.server.co.uk", 110);
fwd.startLocalForwarding("localhost", 225, "email.server.co.uk", 25);
When the email client tries to set up the incoming POP3 account the traffic will be locally forwarded to port 1110. This traffic will be forwarded now securely over the network to the SSH server on port 22. This will in turn forward this information to the intended target of the POP3 email server listening on port 110. This process is also performed for the outgoing SMTP account through port 225.
Communication
The communication is now secured across the tunnel not only this but previously inaccessible services outside of the network become accessible through the SSH server as this usually is left open on the network. Now we can access our once insecure email through a single point of contact in a secure manner.
Copyright 2002 O'Reilly & Associates.This principle can be applied to any inaccessible resource on a companys internal network, by leaving just the secure SSH port 22 open we suddenly gain secure, encrypted access to all our once unavailable and insecure resources.
How To Run This Code
This attached zip file contains several source files. Unzip these into a new Java project and build.
2005 3SP Ltd, All Rights Reserved
Developers
Tutorials
Attachments
Print
Add Comment