TunnelMate for Windows Read Me

TunnelMate™ for Windows
Version 2.2
Read Me

February 2003

Thank you for using TunnelMate Version 2.2, Powerlan Ltd's Secure Shell ("SSH") client for Windows-based computers. 

The following information is intended to help you install and use the software.

CONTENTS

1.  New in This Release
2.  Overview
3.  System Requirements
4.  Secure Shell Specifications
5.  Installation
6.  Usage
7.  Status and Configuration
8.  Contact Information
9.  Copyright Information and Disclaimer

1. NEW IN THIS RELEASE

NEW IN 2.2

  • Fixes in version 2.2
    • - Fixes to problems that resulted in high CPU usage after Tunnel closing
    • - Fix to problem where Tmate.exe was still in use after app exit (Win98)

ENHANCEMENTS IN VERSION 2.2

  • - Upgraded to OpenSSL 0.96h
  • - Upgraded to OpenSSH 3.5
  • - Added console support for SSH1 (in addition to SSH2)
  • - OpenSSH and OpenSSL version numbers now available via File Properties:
    • - OpenSSH Version see File Properties of TMate.exe
    • - OpenSSL Version see File Properties of ssleay32.dll and libeay32.dll
  • - Encrypted password no longer displayed in session logs

 

NEW IN 2.1

  • ---Important Security Fix---A potentially serious problem was discovered in March by the OpenSSH organization. The bug is described in the Pine Internet Security Advisory "PINE-CERT-20020301". This fix was introduced in release 2.0.1 and will be incorporated in future releases. To avoid the problem verify that you are not using any previous release of TunnelMate. For details about this security advisory, please refer to: http://www.pine.nl/advisories/pine-cert-20020301.html
     
  • ENHANCEMENTS IN VERSION 2.1:

    1) Support for Secure Windows File Sharing
    You can now open secure connections to Windows File servers using TunnelMate. TunnelMate includes a special pre-configured shortcut file that, when run, establishes a secure tunnel to a network on which Windows File Servers can be mounted as if they were directly connected to your local network.  Possible file servers include the following:

    • - Windows 95/98/ME
    • - Windows 2000/XP
    • - Linux/Unix (with Samba or equivalent)
    • - many other Windows-compatible file servers

    2) Support for Secure Email
    TunnelMate now can easily be configured to for securing POP3/SMTP email services.  TunnelMate includes a special pre-configured shortcut file that you can use in conjunction with your email client to assure privacy of your login information as well as the content of your mail messages. 

    3) Added support for Persistent Forwarding option
    In some cases you'll want tunneling to be a "one shot deal", such that the port forwarding only remains in place while the ensuing connection is in place.  In other cases - file sharing and email are good examples - you'll want the tunnel and port forwarding to stay in place even when there is no TCP connection active.  With the "persist" option specified, TunnelMate keeps the Tunnel and its associated forwarding(s) active even when no connection is in place.  So for an email that checks mail every few minutes, the tunnel and forwarding don't need to be re-established every time.  For obvious reasons, this is much more efficient than was previously possible.

    4) Added automatic Execute option
    This option is important because it allows TunnelMate to perform an action after establishing a tunnel and setting up forwarding.  The action is launched via the Windows "ShellExecute" command, allowing the launch of an application or a URL.

    5) Wildcarding of Forwarding Host
    When found in the Host subfield of a forwarding field, TunnelMate now interprets the asterisk ("*") character as specifying that the forwarding host is the same as the SSH server.  This increases the portability of shortcut files, so one shortcut file could be used for any number of hosts, and passed from one user to another.

    6) The "Host Port" fields of forwarding triplets are now displayed in TunnelMate's Status panel
    Using well-known port names, when appropriate, rather than just the port number.  For example "Telnet" instead of "23".

    7) Two additional Windows Shortcut files are installed into the Tunnelmate program folder
    Secure Share is a generic shortcut that is useful when you want to mount a Windows File Server volume residing on the same host as the SSH server.  Likewise Secure Mail is a generic shortcut that will set up tunneling and forwarding for an email server on the SSH host.

2.  OVERVIEW

TunnelMate seamlessly integrates Secure Shell (SSH) communications with products such as Powerlan's X Server product, WebTerm X™ and Powerlan's Terminal Emulator, WebTerm™. TunnelMate has fundamental differences from other SSH clients because of its seamlessness. The primary design goal of TunnelMate is to provide "full-service" Secure Shell communications without requiring users to run a separate shell application, as is necessary in other solutions. TunnelMate may also be run as a stand-alone product, providing a Secure Shell console.

When used in conjunction with WebTerm X Version 4.0, TunnelMate supplies all of the necessary Secure Shell services WebTerm X requires. TunnelMate is automatically started when WebTerm X launches an X application configured with the SSH option, and automatically stops running when WebTerm X quits. The underlying complexities of SSH and the tunneling of X client connections remain transparent to the WebTerm X user.

TunnelMate also provides secure terminal access to a variety of other environments. Virtually any host - whether or not it has built-in support for the SSH protocol - is reachable using a TunnelMate-secured terminal session. If your goal is simply to make a secure terminal connection to a Unix host, then TunnelMate will create a console session in a Windows Telnet window.

When TunnelMate is paired with WebTerm Version 2.0, many other hosts may also be accessible. WebTerm and TunnelMate together make SSH "tunneling" easy and seamless. Hosts on which direct SSH access isn't possible (including IBM Mainframes, Midranges, etc.), are reachable using a mechanism where a secure tunnel is established between your PC and a SSH-capable host, and the terminal session is essentially forwarded to any type of host that allows standard TN3270, TN5250 or VTxxx Telnet connections.

Thanks to its unique "open" URL-driven design, virtually any other product that uses TCP/IP can seamlessly integrate with TunnelMate to use SSH-based "tunnels" for high-grade security.

 

3.   SYSTEM REQUIREMENTS

  • The Windows 95/98/ME, Windows NT 4.0, Windows 2000 or Windows XP operating system

  • 3 MB free disk space

  • A TCP/IP connection to a host running the SSH Daemon software

 

4. SECURE SHELL SPECIFICATIONS

The TunnelMate software is based on OpenSSH Version 3.5. and OpenSSL Version 0.9.6h.

TunnelMate 2.2 is compatible with host SSH daemons (sshd) based on either SSH protocol version 1 or 2. Users are authenticated via password. All passwords and data are encrypted. When used with WebTerm X, TunnelMate automatically enables X11 forwarding for all connections.

5. INSTALLATION

The TunnelMate Installer may be downloaded from www.powerlan-usa.com/tunnelmate/downloadwin.

Double-click TunnelMateInstaller.exe and follow the on-screen instructions to install TunnelMate. All TunnelMate files are installed into the TMate folder, which is created in your Windows system folder.

If you have a registered copy of Webterm X 4.0 or WebTerm 2.0, you will not be asked for a serial number when TunnelMate is run for the first time. If you are asked for a TunnelMate serial number and you do not yet have it, click the Demo button to run in Demo mode.

 

Demo Limitations

If you are using the Demo mode, you can use TunnelMate for 15 minutes. After 15 minutes, any connections you have open will close.

You may obtain a 30 day evaluation serial number by contacting the Powerlan USA sales department.

 

6. USAGE 

Once installed, you will not need to deal directly with TunnelMate; it is "driven" by products such as WebTerm X and WebTerm, which send URLs (Uniform Resource Locators) containing connection information to TunnelMate. Please consult the WebTerm X 4.0 User Manual or WebTerm 2.0 User Manual for instructions for configuring these applications to use SSH.

TunnelMate is launched when it receives a URL containing user and host information and other optional information such as a command to launch an X client. It can also be launched effectively with the simple URLs ssh:// or sshx://. The ssh:// URL instructs TunnelMate to automatically launch the client machine's default telnet client and set it up as the SSH console for the secure session. The sshx:// URL instructs TunnelMate to automatically launch WebTerm X. In both cases, TunnelMate prompts for user/host/password and, in the case of sshx://, the command to launch an X client (xterm for example). Shortcuts for each of these URLs may be found in the TunnelMate program menu.

Here are some basic examples of TunnelMate URLs:
  • ssh://                                            --- A generic Secure Shell console session
  • ssh://myLogin@myHost                 --- A console for user 'myLogin' on host 'myHost'
  • sshx://                                          --- A generic SSH xterm (WebTerm X required)
  • sshx://myName@hostName/xterm  --- An secured Xterm for user 'myName' on host 'hostName' (WebTerm X required)
T unnelMate URLs can be executed from a web page (above), from the Windows Run command, or by other programs (WebTerm, WebTerm X, and others). For detailed information on integrating TunnelMate with your product(s) or to find what other products and technologies have been integrated with it, please see the TunnelMate Integration page. The combination of WebTerm and TunnelMate also supports 'forwarded' Telnet, which is crucial in using Secure Shell to connect to hosts that don't support Secure Shell (in particular IBM hosts). URLs for these connections are not listed above because they are typically constructed dynamically and passed programmatically. For more information, please refer to the WebTerm product page.

TunnelMate opens one or more secure tunnels to remote hosts. Each tunnel maintains one or more secure connections. The TunnelMate Secure Shell client transparently logs onto a remote host and executes commands on the host. Multiple applications can utilize TunnelMate simultaneously. The number of simultaneous tunnels is limited only by system resources.

KNOWN ISSUES:

  • Running under certain versions of Windows XP with Windows Telnet acting as the console, characters typed into the console appear twice. Consider using WebTerm™ instead of Windows Telnet if this problem affects you.

 

7.  STATUS AND CONFIGURATION

Right-click on the TunnelMate taskbar icon and select TunnelMate Status to display TunnelMate's status, logging and settings panels. 

The Status panel shows current status on existing tunnels and port forwardings. Individual tunnels can be closed from the Status panel as well. Logging messages for each tunnel may also be viewed .

The Session Log panel shows all SSH logging messages received since TunnelMate started.

The following settings may be customized on the Settings panel:

SSH Defaults:

Port -- the port used to connect to the SSH Daemon on the remote host. The default is port 22.
Verbose -- determines the amount of logging information.

 

General Settings:

Start Minimized -- causes TunnelMate to appear only as a Windows taskbar icon at startup.
Auto Close App -- TunnelMate automatically exits when there are no active tunnels.
Auto Close Tunnel -- TunnelMate tunnels automatically close when there are no active connections.

 

8.  CONTACT INFORMATION

GENERAL:

Powerlan USA, Inc.
39 Simon Street, Unit 12
Nashua, NH 03060 USA
Phone: 603-880-9118
Fax: 603-882-8884
http://www.powerlan-usa.com

Powerlan USA, Inc. is a wholly owned subsidiary of Powerlan, Ltd., a publicly traded company based in Sydney, Australia. For more information, see: http://www.powerlan.com.au

EMAIL CONTACTS:

General Information:
info@powerlan-usa.com 

Technical Support:
http://support.powerlan-usa.com 

Sales (Americas):
Direct: sales@powerlan-usa.com
Resellers: http://www.powerlan-usa.com/sales_partners_usa.html

Sales (outside Americas):
Direct: sales@powerlan-usa.com
Resellers: http://www.powerlan-usa.com/sales_partners_intl.html

 

 9.  COPYRIGHT INFORMATION AND DISCLAIMER

TunnelMate is a trademark of Powerlan Ltd.
WebTerm X and WebTerm are trademarks of Powerlan USA, Inc.

Detailed copyright information pertaining to OpenSSH and OpenSSL can be found in the files "OpenSSH.txt" and "OpenSSL.txt" in the TMate folder.

All other product names used in this document are trademarks or registered trademarks of their respective manufacturers, and are recognized as such. 

THIS SOFTWARE IS PROVIDED BY THE TRUSTEES AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE TRUSTEES OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Copyright © 2003 Powerlan Ltd.