SSH User Guide

SSH Tectia Client 5.1

User Manual

5 July 2006

SSH Tectia Client 5.1: User Manual

5 July 2006

Copyright © 1995–2006 SSH Communications Security Corp.

This software is protected by international copyright laws. All rights reserved. ssh® is a registered trademark of SSH Communications

Security Corp in the United States and in certain other jurisdictions. The SSH logo and Tectia are trademarks of SSH Communications

Security Corp and may be registered in certain jurisdictions. All other names and marks are property of their respective owners.

No part of this publication may be reproduced, published, stored in an electronic database, or transmitted, in any form or by any means,

electronic, mechanical, recording, or otherwise, for any purpose, without the prior written permission of SSH Communications Security

Corp.

THERE IS NO WARRANTY OF ANY KIND FOR THE ACCURACY OR USEFULNESS OF THIS INFORMATION EXCEPT AS

REQUIRED BY APPLICABLE LAW OR EXPRESSLY AGREED IN WRITING.

This Software contains portions of XFree86 software and the delivery of XFree86 software or portions of the said software is subject to

the acknowlegement of the following copyright notice and permission notice of The Open Group:

Copyright © 1988, 1998 The Open Group

Permission to use, copy, modify, distribute, and sell XFree86 software and its documentation for any purpose is hereby granted without

fee, provided that the above copyright notice appear in all copies and that both the copyright notice and this permission notice appear in

supporting documentation.

THE XFREE86 SOFTWARE IS PROVIDE "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING

BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND

NONINFRINGEMENT. IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LI-

ABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION

WITH THE XFREE86 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE XFREE86 SOFTWARE.

Except as contained in this notice, the name of The Open Group shall not be used in advertising or otherwise to promote the sale, use or

other dealings in this Software without prior written authorization from The Open Group.

SSH Communications Security Corp.

Valimotie 17, FIN-00380 Helsinki; Finland

Table of Contents

1. About This Document .......................................................................................................... 9

1.1. Component Terminology ................................................................................................. 9

1.2. Documentation Conventions ........................................................................................... 11

1.3. Customer Support ........................................................................................................ 12

2. Installing SSH Tectia Client ................................................................................................ 13

2.1. Planning the Installation ................................................................................................ 13

2.1.1. System Requirements ............................................................................................. 13

2.1.2. Packaging ............................................................................................................ 14

2.1.3. Licensing ............................................................................................................. 14

2.1.4. Upgrading from Version 4.x to 5.x ............................................................................ 15

2.1.5. Upgrading from 5.x Version ..................................................................................... 15

2.2. Installing the SSH Tectia Client Software .......................................................................... 16

2.2.1. Installing on AIX .................................................................................................. 16

2.2.2. Installing on HP-UX .............................................................................................. 17

2.2.3. Installing on Linux ................................................................................................ 18

2.2.4. Installing on Solaris .............................................................................................. 19

2.2.5. Installing on Windows ........................................................................................... 20

2.3. Removing the SSH Tectia Client Software ........................................................................ 23

2.3.1. Removing from AIX .............................................................................................. 23

2.3.2. Removing from HP-UX ......................................................................................... 24

2.3.3. Removing from Linux ........................................................................................... 24

2.3.4. Removing from Solaris .......................................................................................... 25

2.3.5. Removing from Windows ....................................................................................... 26

3. Getting Started ................................................................................................................. 27

3.1. Product Components ..................................................................................................... 27

3.2. Location of SSH Tectia Client Files ................................................................................. 27

3.2.1. File Locations on Unix ........................................................................................... 27

3.2.2. File Locations on Windows ...................................................................................... 28

3.3. Status Dialog Box (Windows) ......................................................................................... 30

3.3.1. Connections View .................................................................................................. 30

3.3.2. Keys View ............................................................................................................ 31

© 1995–2006 SSH Communications Security Corp.SSH Tectia Client 5.1 User Manual

3

3.3.3. Logs View ............................................................................................................ 31

3.4. Connecting to a Remote Host ......................................................................................... 32

3.4.1. Using the GUI Client (Windows) .............................................................................. 32

3.4.2. Using the Command-Line Client .............................................................................. 34

3.5. Defining Quick Connect Options (Windows) ..................................................................... 34

3.6. Using Public-Key Authentication .................................................................................... 35

3.7. Examples of Use .......................................................................................................... 35

4. Configuring Connection Broker .......................................................................................... 37

ssh-broker-config ............................................................................................................... 37

4.1. Configuration Tool (Windows) ....................................................................................... 57

4.1.1. Defining General Settings ....................................................................................... 58

4.1.2. Defining Default Settings ........................................................................................ 59

4.1.3. Defining Proxy Rules ............................................................................................. 63

4.1.4. Defining Logging Settings ....................................................................................... 65

4.1.5. Defining Connection Profiles ................................................................................... 67

4.1.6. Defining User Authentication ................................................................................... 83

4.1.7. Defining Server Authentication ................................................................................ 86

4.1.8. Defining SSH Tectia Connector Settings (SSH Tectia Connector) ................................... 91

4.1.9. Defining FTP-SFTP Conversion Rules (SSH Tectia Client with EFT Expansion Pack) ........ 95

4.1.10. Defining Static Tunnels ......................................................................................... 97

5. Configuring SSH Tectia Client GUI (Windows) ................................................................... 101

5.1. Defining Global Settings .............................................................................................. 101

5.1.1. Defining the Appearance ....................................................................................... 102

5.1.2. Selecting the Font ................................................................................................ 104

5.1.3. Selecting Colors .................................................................................................. 105

5.1.4. Defining Messages ............................................................................................... 107

5.1.5. Defining File Transfer Settings ............................................................................... 108

5.1.6. Defining Advanced File Transfer Options ................................................................. 112

5.1.7. Defining File Transfer Mode .................................................................................. 114

5.1.8. Defining Local Favorites ....................................................................................... 116

5.1.9. Defining Security Settings ..................................................................................... 117

5.1.10. Printing ............................................................................................................ 118

5.2. Using Command-Line Options ...................................................................................... 120

5.3. Customizing the User Interface ..................................................................................... 121

5.3.1. Saving Settings .................................................................................................... 121

5.3.2. Loading Settings .................................................................................................. 122

5.3.3. Customize Dialog ................................................................................................ 123

5.3.4. Customizing Toolbars ........................................................................................... 125

5.3.5. Customizing Menus .............................................................................................. 126

6. Authentication ................................................................................................................. 129

6.1. Server Authentication with Public Keys .......................................................................... 129

6.1.1. Using the System-Wide Host Key Storage ................................................................ 131

6.1.2. Using the OpenSSH known_hosts File .................................................................... 132

SSH Tectia Client 5.1 User Manual© 1995–2006 SSH Communications Security Corp.


6.2. Server Authentication with Certificates ........................................................................... 132

6.2.1. Using the Configuration File (Unix) ........................................................................ 133

6.2.2. Using the GUI (Windows) ..................................................................................... 134

6.3. User Authentication with Passwords ............................................................................... 134



6.4. User Authentication with Public Keys ............................................................................. 135

6.4.1. Creating Keys with ssh-keygen-g3 ........................................................................ 136

6.4.2. Uploading the Public Key Manually ........................................................................ 137

6.4.3. Creating Keys with the Key Generation Wizard (Windows) .......................................... 138

6.4.4. Uploading the Public Key Automatically (Windows) ................................................... 142

6.4.5. Using Keys Generated with OpenSSH ...................................................................... 144

6.5. User Authentication with Certificates ............................................................................. 144



6.6. Host-Based User Authentication (Unix) .......................................................................... 146

6.7. User Authentication with Keyboard-Interactive ................................................................ 146



6.8. User Authentication with GSSAPI ................................................................................. 147



7. Transferring Files ............................................................................................................ 149

7.1. File Transfer with the Command-Line Client ................................................................... 149

7.1.1. Using scpg3 ....................................................................................................... 149

7.1.2. Using sftpg3 ...................................................................................................... 150

7.2. File Transfer with the File Transfer GUI (Windows) .......................................................... 150

7.2.1. Defining File Transfer Settings ............................................................................... 150

7.2.2. Downloading Files with the File Transfer GUI ........................................................... 150

7.2.3. Uploading Files with the File Transfer GUI ............................................................... 152

7.2.4. Defining File Properties ........................................................................................ 153

7.2.5. Differences from Windows Explorer ........................................................................ 155

7.3. FTP-SFTP Conversion (EFT Expansion Pack) ................................................................. 156

7.3.1. Enabling FTP-SFTP Conversion (Windows) .............................................................. 156

7.3.2. Enabling FTP-SFTP Conversion (Unix) ................................................................... 156

7.4. Enhanced File Transfer (EFT Expansion Pack) ................................................................. 156

7.5. FTP Tunneling ........................................................................................................... 157

8. Tunneling ....................................................................................................................... 159

8.1. Local Tunnels ............................................................................................................ 159

8.1.1. Dynamic Tunneling .............................................................................................. 161

8.1.2. Transparent Tunneling with SSH Tectia Connector ..................................................... 162

8.2. Remote Tunnels ......................................................................................................... 162

8.3. FTP Tunneling ........................................................................................................... 164


5

8.4. X11 Forwarding ......................................................................................................... 165

8.5. Agent Forwarding ....................................................................................................... 166

A. Command-Line Tools ........................................................................................................ 167

ssh-broker-g3 .................................................................................................................. 167

sshg3 ............................................................................................................................. 172

scpg3 ............................................................................................................................. 178

sftpg3 ............................................................................................................................. 182

ssh-convert-ftp (EFT Expansion Pack on Unix) ...................................................................... 190

ssh-keygen-g3 ................................................................................................................. 191

ssh-cmpclient-g3 .............................................................................................................. 193

ssh-certview-g3 ................................................................................................................ 199

ssh-ekview-g3 ................................................................................................................. 203

B. Egrep Syntax ................................................................................................................... 205

B.1. Egrep Patterns ........................................................................................................... 205

B.2. Escaped Tokens for Regex Syntax Egrep ........................................................................ 206

B.3. Character Sets For Egrep ............................................................................................. 207

C. GUI Reference ................................................................................................................. 209

C.1. Terminal Window ....................................................................................................... 209

C.1.1. Terminal Window Title Bar ................................................................................... 209

C.1.2. Terminal Window Status Bar ................................................................................. 210

C.1.3. Terminal Window Shortcut Menu ........................................................................... 211

C.2. File Transfer Window ................................................................................................. 212

C.2.1. File Transfer Window Title Bar .............................................................................. 213

C.2.2. File Transfer Window Menu Bar ............................................................................. 213

C.2.3. File Transfer Window Toolbars .............................................................................. 213

C.2.4. File Transfer Window Status Bar ............................................................................ 214

C.2.5. Local View ......................................................................................................... 216

C.2.6. Local Folder View ............................................................................................... 216

C.2.7. Remote View ...................................................................................................... 216

C.2.8. Remote Folder View ............................................................................................ 217

C.2.9. Transfer View ..................................................................................................... 217

C.2.10. Navigating in the File Transfer Window ................................................................. 219

C.2.11. File Transfer Shortcut Menus ............................................................................... 219

C.3. Toolbar Reference ...................................................................................................... 223

C.3.1. Basic Toolbar ..................................................................................................... 224

C.3.2. File Transfer Window, Toolbar Buttons .................................................................... 230

C.3.3. Profiles Bar ........................................................................................................ 232

C.3.4. File Transfer Window, File Bar ............................................................................... 232

C.4. Menu Reference ........................................................................................................ 235

C.4.1. File Menu .......................................................................................................... 235

C.4.2. Edit Menu .......................................................................................................... 237

C.4.3. Terminal Window, View Menu ............................................................................... 239

C.4.4. File Transfer Window, View Menu .......................................................................... 240



C.4.5. File Transfer Window, Operation Menu ................................................................... 242

C.4.6. Window Menu .................................................................................................... 245

C.4.7. Help Menu ......................................................................................................... 246

D. Broker Configuration File Syntax ........................................................................................ 253

E. Man Pages and Help Files .................................................................................................. 259

F. Audit Messages ................................................................................................................ 261

Index ................................................................................................................................. 287


7



Chapter 1 About This Document

This document describes installing and using SSH Tectia Client. It is meant for SSH Tectia Client users.

This document contains the following information:

• Installing SSH Tectia Client

• Getting started

• Configuring SSH Tectia Client

• Transferring files

• Tunneling applications

• Appendices, including command-line tool, GUI, and audit message references

For more information, refer to SSH Tectia Client/Server Product Description.

Separate reference documentation for the file transfer APIs available with EFT Expansion Pack for SSH

Tectia Client is included in SSH Tectia Client (with EFT) installation CD.

If you are familiar with SSH Tectia Client 4.x or older, we recommend that you read SSH Tectia Client/Server

Migration Guide. It contains information on new and changed configuration options of SSH Tectia 5.1 and

instructions for migrating existing installations of SSH Tectia 4.x to 5.1.

1.1 Component Terminology

The following terms are used throughout the documentation.

client computer The computer, typically a workstation, from which the Secure Shell

connection is initiated.

host key A public-key pair used as the identification of the Secure Shell server.


9

remote host Refers to the other party of the connection, client computer or server

computer, depending on the viewpoint.

Secure Shell client A client-side application that uses the Secure Shell version 2 protocol,

for example sshg3, sftpg3 or scpg3 of SSH Tectia Client, or SSH Tectia

Connector.

Secure Shell server A server-side application that uses the Secure Shell version 2 protocol.

server computer The computer, typically a server, on which the Secure Shell service is

running and to which the Secure Shell client is connected.

SFTP server A server-side application that provides a secure file transfer service as a

subsystem of the Secure Shell server.

SSH Tectia Client A software component installed on a workstation. SSH Tectia Client

provides secure interactive file transfer and terminal client functionality

for remote users and system administrators to access and manage servers

running SSH Tectia Server or other applications using the Secure Shell

protocol. It also supports (non-transparent) static and dynamic tunneling

of TCP-based applications.

SSH Tectia Client with EFT

Expansion Pack

With the optional EFT Expansion Pack, SSH Tectia Client can be expan-

ded to perform enhanced file transfer (EFT) operations that require

higher encryption performance, APIs for application-level integration,

and additional reliability features such as checkpoint-restart. In addition,

SSH Tectia Client with EFT Expansion Pack incorporates an FTP-SFTP

Conversion Module to facilitate secure replacement of FTP without the

need to modify file transfer scripts or applications.

SSH Tectia client/server solu-

tion

The SSH Tectia client/server solution consists of three products, SSH

Tectia Server, SSH Tectia Client, and SSH Tectia Connector.

SSH Tectia Connector SSH Tectia Connector is a transparent end-user desktop client that

provides dynamic tunneling of client/server connections without the need

to re-configure the tunneled applications. It enables corporate end users

to connect to business applications securely and automatically when an

IP connection is established, while being fully transparent to the user.

SSH Tectia Connector connects to SSH Tectia Server with Tunneling

Expansion Pack and SSH Tectia Server with EFT Expansion Pack.

SSH Tectia Server SSH Tectia Server is a server-side component for SSH Tectia Connector

and Client. There are four separate versions of the product available: SSH

Tectia Server for secure system administration, SSH Tectia Server with

EFT Expansion Pack for secure file transfer, SSH Tectia Server with


About This Document10

Tunneling Expansion Pack for secure application connectivity, and SSH

Tectia Server for IBM z/OS for IBM mainframes.

The basic SSH Tectia Server is available for Linux, Unix, and Windows

platforms.

SSH Tectia Server with EFT

Expansion Pack

SSH Tectia Server with EFT Expansion Pack is available for Linux, Unix,

and Windows platforms. In addition to allowing normal Secure Shell

connections, it supports the enhanced file transfer (EFT) features provided

by SSH Tectia Client with EFT Expansion Pack.

SSH Tectia Server with Tunnel-

ing Expansion Pack

SSH Tectia Server with Tunneling Expansion Pack is available for Linux,

Unix, and Windows platforms. In addition to allowing normal Secure

Shell connections, it supports the enhanced file transfer (EFT) features

when used with SSH Tectia Client with EFT Expansion Pack and trans-

parent application tunneling when used with SSH Tectia Connector.

SSH Tectia Server for IBM

z/OS

SSH Tectia Server for IBM z/OS provides normal Secure Shell connec-

tions and supports the enhanced file transfer (EFT) features when used

with SSH Tectia Client with EFT Expansion Pack and transparent applic-

ation tunneling when used with SSH Tectia Connector.

tunneled application TCP application secured by a Secure Shell connection.

1.2 Documentation Conventions

The following special conventions are used in this document:

Table 1.1. Documentation conventions

ExampleUsageConvention

Click Apply or OK.Menus, GUI elements, strong emphasisBold

Select File → SaveSeries of menu selections→Refer to readme.txtFilenames, commands, directories, URLs etc.Monospace

See SSH Tectia Client User ManualReference to other documents or products, emphasisItalics

Note

Indicates neutral or positive information that emphasizes or supplements important points of the

main text. Supplies information that may apply only in special cases (for example, memory limitations,

equipment configurations, or specific versions of a program).


111.2 Documentation Conventions

Caution

Advises users that failure to take or avoid a specified action could result in loss of data.

1.3 Customer Support

If the product documentation does not answer all your questions, you can find the SSH Tectia FAQ and

Knowledge Base at http://support.ssh.com/.

If you have purchased a maintenance agreement, you are entitled to technical support from SSH Communic-

ations Security. Review your agreement for specific terms.

Please see the following page for more information on submitting support requests, feature requests, or bug

reports, and on accessing the available online resources: http://www.ssh.com/support/contact.


About This Document12

http://support.ssh.com/

http://www.ssh.com/support/contact

Chapter 2 Installing SSH Tectia Client

This chapter describes installing and removing SSH Tectia Client and the EFT Expansion Pack for Client.

2.1 Planning the Installation

This section describes system requirements and licensing, and upgrading the installation.

2.1.1 System Requirements

The following operating systems are supported as SSH Tectia Client platforms:

• IBM AIX 5L 5.1, 5.2, and 5.3 (POWER)

• HP-UX 11.00, 11.11 (11i v1), and 11.23 (11i v2) (PA-RISC)

• HP-UX 11.22 (11i v1.6) and 11.23 (11i v2) (IA64)

• Red Hat Enterprise Linux 3 and 4 (x86)

• SUSE LINUX Professional 9.1 and 9.2 (x86)

• SUSE LINUX Enterprise Server 9 (x86)

• Sun Solaris 2.6, 7, 8, 9, and 10 (SPARC)

• Microsoft Windows 2000 with SP4, XP with SP1-SP2, Server 2003 with SP1, and Server 2003 x64 Edition

(x86)

SSH Tectia Client does not have any special hardware requirements. Any computer capable of running a

current version of the listed operating systems, and equipped with a functional connection to a remote host

computer can be used.

The SSH Tectia Client installation requires about 50 megabytes of disk space. Note that the Client will save

each user's settings in that particular user's personal directory.


13

2.1.2 Packaging

On Unix and Linux platforms, SSH Tectia Client comes in two installation packages: ssh-tectia-common

and ssh-tectia-client. The first package contains the common components of SSH Tectia Client and

Server. The second contains the specific components of SSH Tectia Client.

On Windows, SSH Tectia Client comes in a single MSI installation package. The installed components can

be selected during the installation phase.

On Unix platforms (including Linux), SSH Tectia Client with EFT Expansion Pack comes in five installation

packages: ssh-tectia-common, ssh-tectia-client, ssh-tectia-client-ft-only, ssh-tectia-ftp-

conversion, and ssh-tectia-sdk. The first package contains the common components of SSH Tectia Client

and Server. The second contains the specific components of SSH Tectia Client. The third is similar with the

second, but it does not include the sshg3 program. The fourth package contains the FTP-SFTP conversion

components. The fifth package is a software development kit (SDK) that contains the file transfer APIs in C

and Java. The SDK is currently available on Linux x86 and Solaris platforms.

On Windows, SSH Tectia Client with EFT Expansion Pack comes in a single MSI installation package that

includes also the SDK, FTP-SFTP conversion, and the sshg3.exe program. The installed components can

be selected during the installation phase.

Table 2.1 summarizes the required and optional SSH Tectia Client packages on different platforms.

Table 2.1. The SSH Tectia Client and EFT Expansion Pack installation packages

SSH Tectia Client

(with EFT) on Win-

dows

SSH Tectia Client (with EFT) on

Unix and Linux

SSH Tectia Client

on Windows

SSH Tectia Client on

Unix and Linux

client-with-eft

common

client

common

client or client-ft-only

client ftp-conversion*

sdk**

* Optional on Linux x86, HP-UX, and Solaris.

** Optional on Linux x86 and Solaris.

2.1.3 Licensing

SSH Tectia Client requires a license file to function.

SSH Tectia Client and SSH Tectia Client with EFT Expansion Pack use license files of their own. Depending

on the Client type you have purchased, you have one of the following files:

• On Unix: tectia_client_51.lic or tectia_client_with_eft_51.lic.


Installing SSH Tectia Client14

• On Windows: stc51.dat or stcf51.dat.

In the CD-ROM, the license files can be found in the install/<platform> directory.

After installation, the license file should be located in /etc/ssh2/licenses on Unix and in "<IN-

STALLDIR>\SSH Tectia AUX\licenses" on Windows (the default installation directory is "C:\Program

Files\SSH Communications Security\SSH Tectia").

On Windows, when installing from the CD-ROM, the license file is automatically copied to the right directory.

In other cases, the license file has to be copied manually.

2.1.4 Upgrading from Version 4.x to 5.x

On Unix and Linux platforms, earlier versions of SSH Tectia Client should be removed before installing SSH

Tectia Client 5.x. (When installing via SSH Tectia Manager, this is handled automatically.)

On Windows, SSH Tectia Client 4.1 and later can be upgraded by installing a newer version of the software

on top of the older version. SSH Tectia Client 4.0 and earlier use a different type of installation package and

must be uninstalled before installing the new version.

The configuration file format and file locations have changed in SSH Tectia Client 5.0. The old configuration

files form 4.x will not be used with 5.x, but they must be converted manually to the new format.

A separate document, SSH Tectia Client/Server Migration Guide, gives detailed instructions on upgrading

from SSH Tectia client/server solution 4.x to SSH Tectia client/server solution 5.x, including information on

migrating the configuration files.

Note

Back up all your configuration files before starting the upgrade.

2.1.5 Upgrading from 5.x Version

SSH Tectia Client can be upgraded from a previous 5.x installation to a later 5.x simply by installing the

newer version of the software on top of the older version.

If installed on the same machine, SSH Tectia Client and SSH Tectia Server 5.x should be always upgraded

at the same time, because there are dependencies between the common components.

Note

The old 5.x configuration files are automatically backed up during the upgrade. The backups are

stored in the "%USERPROFILE%\Application Data\SSH\backup-<date>" directory for each user

(where <date> is the date of the upgrade).


152.1.4 Upgrading from Version 4.x to 5.x

2.2 Installing the SSH Tectia Client Software

This section gives instructions on installing SSH Tectia Client locally on the supported operating systems.

SSH Tectia Client can also be installed via SSH Tectia Manager. See SSH Tectia Manager Administrator

Manual for more information.

2.2.1 Installing on AIX

On the CD-ROM, the installation packages for AIX 5L platforms are located in the /install/aix/ directory.

Two packages are required: one for common components of SSH Tectia Client and Server, and another for

specific components of SSH Tectia Client. With SSH Tectia Client with EFT Expansion Pack you may choose

to install either the full client package or the client package without sshg3.

Note

You need GNU gzip in order to install SSH Tectia Client on AIX.

To install SSH Tectia Client on AIX, do the following:

1. Unpack the packages using the following commands:

$ gzip -d ssh-tectia-common-<ver>-aix5.x.bff.gz

$ gzip -d ssh-tectia-client-<ver>-aix5.x.bff.gz

In the commands, <ver> is the current package version of SSH Tectia Client (for example, 5.1.0.505).

(Optional with SSH Tectia Client with EFT Expansion Pack) If you do not want to install the sshg3

command, use the client-ft-only package instead of the client package:

$ gzip -d ssh-tectia-client-ft-only-<ver>-aix5.x.bff.gz

2. Install the packages by running the following commands with root privileges:

# installp -d ssh-tectia-common-<ver>-aix5.x.bff SSHTectia.Common

# installp -d ssh-tectia-client-<ver>-aix5.x.bff SSHTectia.Client

(Optional with SSH Tectia Client with EFT Expansion Pack) For the ft-only package, the command

is the following:

# installp -d ssh-tectia-client-ft-only-<ver>-aix5.x.bff SSHTectia.ClientF

3. (Not necessary in "third-digit" maintenance updates) Copy the license file to the /etc/ssh2/licenses

directory. See Section 2.1.3.



2.2.2 Installing on HP-UX

SSH Tectia Client is available for HP-UX 11.0, 11.11, and 11.23 on PA-RISC (11.00-pa-risc) and for HP-

UX 11.22 and 11.23 on Itanium (11.22-itanium).

SSH Tectia Client includes support for Entrust certificates on HP-UX 11.0. The necessary libraries are auto-

matically included in the installation.

On the CD-ROM, the installation packages for HP-UX platforms are located in the /install/hp-ux/ directory.




To install SSH Tectia Client on HP-UX, do the following:

1. Unpack the packages with gunzip. In order to be installable, the created packages must have the correct

long file name:

$ gunzip ssh-tectia-common-<ver>-sd-<arch>.depot.gz

$ gunzip ssh-tectia-client-<ver>-sd-<arch>.depot.gz

In the package name, <ver> is the current package version of SSH Tectia Client (for example, 5.1.0.505)

and <arch> is the version and architecture of the HP-UX operating system (11.00-pa-risc for HP-UX

on PA-RISC or 11.22-itanium for HP-UX on Itanium).



$ gunzip ssh-tectia-client-ft-only-<ver>-sd-<arch>.depot.gz

2. Install the packages by running the following command with root privileges:

# swinstall -s <path>/ssh-tectia-common-<ver>-sd-<arch>.depot SSHG3common

# swinstall -s <path>/ssh-tectia-client-<ver>-sd-<arch>.depot SSHG3client

In the command, <path> is the full path to the installation package (HP-UX requires this even when the

command is run in the same directory).


is the following:

# swinstall -s <path>/ssh-tectia-client-ft-only-<ver>-sd-<arch>.depot SSHG3clntf

3. (Optional with SSH Tectia Client with EFT Expansion Pack) Unpack the FTP-SFTP conversion package

with gunzip:

$ gunzip ssh-tectia-ftp-conversion-<ver>-sd-<arch>.depot.gz


172.2.2 Installing on HP-UX

4. (Optional with SSH Tectia Client with EFT Expansion Pack) Install the FTP-SFTP conversion package

with root privileges:

# swinstall -s <path>/ssh-tectia-ftp-conversion-<ver>-sd-<arch>.depot SSHG3ftpconv



2.2.3 Installing on Linux

SSH Tectia Client for Linux platforms is supplied in RPM (Red Hat Package Manager) binary packages. The

RPMs are available for Red Hat and SUSE Linux running on Intel x86 (i386) platforms. The package for the

x86 architecture is compatible also with the 64-bit versions of Red Hat and SUSE Linux running on x86-64

platforms.

On the installation CD-ROM, the installation packages for Linux are located in the /install/linux/ directory.




With SSH Tectia Client with EFT Expansion Pack, an additional SDK package is available on Intel x86

platforms. It contains the file transfer APIs in C and Java.

To install SSH Tectia Client on Linux, do the following:

1. Install the packages with root privileges:

# rpm -Uvh ssh-tectia-common-<ver>.<arch>.rpm

# rpm -Uvh ssh-tectia-client-<ver>.<arch>.rpm

In the commands, <ver> is the current package version of SSH Tectia Client (for example, 5.1.0.505)

and <arch> is the platform architecture (i386).



# rpm -Uvh ssh-tectia-client-ft-only-<ver>.<arch>.rpm



# rpm -Uvh ssh-tectia-ftp-conversion-<ver>.i386.rpm

3. (Optional with SSH Tectia Client with EFT Expansion Pack on x86.) Install the SDK package with root

privileges:

# rpm -Uvh ssh-tectia-sdk-<ver>.i386.rpm





2.2.4 Installing on Solaris

SSH Tectia Client is available for Sun Solaris on the SPARC architecture.

SSH Tectia Client includes support for Entrust certificates on Solaris 7 and 8. The necessary libraries are

automatically included in the installation.

On the CD-ROM, the installation packages for Solaris are located in the /install/solaris/ directory. Two

packages are required: one for common components of SSH Tectia Client and Server, and another for specific

components of SSH Tectia Client. With SSH Tectia Client with EFT Expansion Pack you may choose to install

either the full client package or the client package without sshg3.

With SSH Tectia Client with EFT Expansion Pack, an additional SDK package is available. It contains the

file transfer APIs in C and Java.

To install SSH Tectia Client on Solaris, do the following:

1. Unpack the installation packages to a suitable place. The standard place is /var/spool/pkg in a Solaris

environment.

$ uncompress ssh-tectia-common-<ver>-sparc-solaris2.6-10.pkg.Z

$ uncompress ssh-tectia-client-<ver>-sparc-solaris2.6-10.pkg.Z

In the command, <ver> is the current package version of SSH Tectia Client (for example, 5.1.0.505).



$ uncompress ssh-tectia-client-ft-only-<ver>-sparc-solaris2.6-10.pkg.Z

2. Then install the packages with the pkgadd tool with root privileges:

# pkgadd -d ssh-tectia-common-<ver>-sparc-solaris2.6-10.pkg all

# pkgadd -d ssh-tectia-client-<ver>-sparc-solaris2.6-10.pkg all


is the following:

# pkgadd -d ssh-tectia-client-ft-only-<ver>-sparc-solaris2.6-10.pkg all

3. (Optional with SSH Tectia Client with EFT Expansion Pack) Unpack the FTP-SFTP conversion install-

ation package:

$ uncompress ssh-tectia-ftp-conversion-<ver>-sparc-solaris2.6-10.pkg.Z


192.2.4 Installing on Solaris



# pkgadd -d ssh-tectia-ftp-conversion-<ver>-sparc-solaris2.6-10.pkg all

5. (Optional with SSH Tectia Client with EFT Expansion Pack) Unpack the SDK installation package:

$ uncompress ssh-tectia-sdk-<ver>-sparc-solaris2.6-10.pkg.Z

6. (Optional with SSH Tectia Client with EFT Expansion Pack) Install the SDK package with root privileges:

# pkgadd -d ssh-tectia-sdk-<ver>-sparc-solaris2.6-10.pkg all



2.2.5 Installing on Windows

The Windows installation packages are provided in the MSI (Microsoft Installer) format. The package is also

compatible with Microsoft Windows Server 2003 x64 Edition.

SSH Tectia Client includes support for Entrust certificates on Windows. The necessary libraries are automat-

ically included in the installation.

The installation is carried out by a standard installation wizard. The wizard prompts you for information,

copies the program files and sets up the client.

On the CD-ROM, the installation package for Windows is located in the /install/windows/ directory.

Depending on the software you have purchased, the package will be either for Client or Client with EFT Ex-

pansion.

If you are upgrading a previous installation of SSH Tectia Client, please see Section 2.1.4 or Section 2.1.5

first.

To install SSH Tectia Client, do the following:

1. Locate the installation file ssh-tectia-client-<version>.msi (where <version> corresponds to the

version and build number, for example 5.1.0.505). Double-click the installation file to start the install-

ation wizard.

If you are running the .msi installer directly from the online .zip package, you have to import the license

file (stc51.dat or stcf51.dat) after completing the installation. If you have extracted the contents of

the online .zip package before running the .msi installer or if you are installing from a CD-ROM, the

license file is imported automatically.

2. Follow the wizard through the installation steps and fill in information as requested.



3. (Optional with SSH Tectia Client) The Typical installation of SSH Tectia Client includes the sshg3.exe,

scpg3.exe, and sftpg3.exe command-line tools, and the graphical user interface for terminal and file

transfer.

If you want to select the components to install, select Custom when the wizard prompts for the setup

type. The next dialog box allows you to exclude some of the components from the installation. See Fig-

ure 2.1.

Figure 2.1. Installation options with SSH Tectia Client

4. (Optional with SSH Tectia Client with EFT Expansion Pack) The Typical installation of SSH Tectia

Client with EFT Expansion Pack includes the scpg3.exe and sftpg3.exe command-line tools and the

graphical user interface for terminal and file transfer. It does not include the sshg3.exe command-line

tool, the FTP-SFTP conversion component, or the file transfer SDKs.

To install all components, select Complete when the wizard prompts for the setup type.

To select the components to install, select Custom when the wizard prompts for the setup type. The next

dialog box allows you to select the optional components to install. See Figure 2.2.


21

Figure 2.2. Installation options with SSH Tectia Client with EFT Expansion Pack

5. When the installation has finished, click Finish to exit the wizard.

6. (SSH Tectia Client with EFT Expansion Pack) If you installed the FTP-SFTP conversion component,

you have to restart the computer. Click Yes to restart.

The default installation directory is "C:\Program Files\SSH Communications Security\SSH Tectia"

located on your system partition (typically the C drive).

The installation creates a new program group in the Start → Programs menu. The default name for this

program group is SSH Tectia Client.

Figure 2.3. The SSH Tectia Client program group

Silent Installation

SSH Tectia Client can also be installed silently on a workstation. Silent (non-interactive) installation means

that the installation procedure will not display any user interface and will not ask any questions from the user.

This option is especially useful for system administrators, as it allows remotely-operated automated installations.

The following command can be used to install SSH Tectia Client silently:



msiexec /q /i ssh-tectia-client-<version>.msi INSTALLDIR="<path>"

In the command, <version> is the current version of SSH Tectia Client (for example, 5.1.0.505), and <path>

is the path to the desired installation directory. If the INSTALLDIR variable is omitted, SSH Tectia Client is

installed to the default location ("C:\Program Files\SSH Communications Security\SSH Tectia").

Desktop Icons

During installation SSH Tectia Client icons are added to your desktop. There are separate program icons for

SSH Tectia Client terminal and file transfer windows. They both start the same application, ssh-client-

g3.exe. The former icon starts with the terminal window and the latter with the file transfer window

Figure 2.4. The SSH Tectia Client icon

Figure 2.5. The SSH Tectia Client - File Transfer icon

2.3 Removing the SSH Tectia Client Software

This section gives instructions on removing SSH Tectia Client from the supported operating systems.

2.3.1 Removing from AIX

To remove SSH Tectia Client from an AIX environment, do the following:

1. Remove the installation by issuing the following command with root privileges:

# installp -u SSHTectia.Client

(SSH Tectia Client with EFT Expansion Pack) If you had installed the ft-only package, use the following

command instead:

# installp -u SSHTectia.ClientF

2. If you want to remove also the components that are common with SSH Tectia Server, give the following

command:


232.3 Removing the SSH Tectia Client Software

# installp -u SSHTectia.Common

Note

The uninstallation procedure removes only the files that were created when installing the software.

Any configuration files have to be removed manually.

2.3.2 Removing from HP-UX

To remove SSH Tectia Client from an HP-UX environment, do the following:


# swremove SSHG3client


command instead:

# swremove SSHG3clntf

2. (SSH Tectia Client with EFT Expansion Pack) If you had the FTP-SFTP conversion installed, remove

it by giving the following command:

# swremove SSHG3ftpconv


command:

# swremove SSHG3common

Note



2.3.3 Removing from Linux

To remove SSH Tectia Client from a Linux environment, do the following:


# rpm -e ssh-tectia-client-<ver>

In the command, <ver> is the package version of SSH Tectia Client to be removed (for example,

5.1.0.505).




command instead:

# rpm -e ssh-tectia-client-ft-only-<ver>



# rpm -e ssh-tectia-ftp-conversion-<ver>

3. (SSH Tectia Client with EFT Expansion Pack) If you had the file transfer SDK installed, remove it by

giving the following command:

# rpm -e ssh-tectia-sdk-<ver>


command:

# rpm -e ssh-tectia-common-<ver>

Note



2.3.4 Removing from Solaris

To remove SSH Tectia Client from a Solaris environment, do the following:


# pkgrm SSHG3clnt


command instead:

# pkgrm SSHG3clnf



# pkgrm SSHG3ftp

3. (SSH Tectia Client with EFT Expansion Pack) If you had the file transfer SDK installed, remove it by

giving the following command:

# pkgrm SSHG3sdk


252.3.4 Removing from Solaris


command:

# pkgrm SSHG3cmmn

Note



2.3.5 Removing from Windows

To remove the SSH Tectia Client installation, do the following:

1. Open the Control Panel and double-click the Add or Remove Programs option.

2. Select SSH Tectia Client from the list of installed programs and click the Remove button.

3. Click Yes to confirm.

4. (SSH Tectia Client with EFT Expansion Pack) If you had the FTP-SFTP conversion component installed,

you have to restart the computer after uninstalling SSH Tectia Client. Click Yes to restart.

SSH Tectia Client can also be removed silently by giving the following command:

msiexec /q /x ssh-tectia-client-<version>.msi

In the command, <version> is the version of SSH Tectia Client to be removed (for example, 5.1.0.505).

Note





Chapter 3 Getting Started

This chapter provides information on how to get started with SSH Tectia Client software after it has been

successfully installed.

3.1 Product Components

SSH Tectia Client consists of the following components:

• Connection Broker: ssh-broker-g3

• Secure Shell command-line tools: sshg3, scpg3, sftpg3

• Auxiliary command-line tools: ssh-keygen-g3, ssh-cmpclient-g3, ssh-certview-g3, ssh-ekview-

g3

• SSH Tectia Client terminal (Windows)

• SSH Tectia Client file transfer GUI (Windows)

• Connection Broker and SSH Tectia Configuration GUI (Windows)

For more information on the command-line tools, see Appendix A.

3.2 Location of SSH Tectia Client Files

This section lists the locations of the installed executables, configuration files, the license file, and the user-

specific configuration files.

3.2.1 File Locations on Unix

On Unix platforms, the SSH Tectia Client files are located in the following directories:


27

• /etc/ssh2

• /etc/ssh2/ssh-broker-config.xml: the global Connection Broker configuration file (see ssh-

broker-config(5))

• /etc/ssh2/licenses: the license file directory (see Section 2.1.3)

• /etc/ssh2/hostkeys: the global directory for known remote host keys

• /etc/ssh2/ssh-tectia/auxdata/ssh-broker-ng: the Connection Broker configuration file DTD

directory

• /etc/ssh2/ssh-tectia/auxdata/ssh-broker-ng/ssh-broker-config-default.xml: the

configuration file with factory default settings (see ssh-broker-config(5))

• /opt/tectia/bin: user binaries such as sshg3 and ssh-broker-g3

• /opt/tectia/libexec: library binaries

• /opt/tectia/lib/sshsecsh: library binaries

The user-specific configurations are stored in the following directories:

• $HOME/.ssh2: the default directory for user keys

• $HOME/.ssh2/ssh-broker-config.xml: the user-specific Connection Broker configuration file

• $HOME/.ssh2/random_seed: the seed file for the random number generator

• $HOME/.ssh2/hostkeys: the user-specific directory for known remote host keys

• $HOME/.ssh2/identification: (optional) the identification file used with public-key authentication

3.2.2 File Locations on Windows

On Windows, the default installation directory for SSH Tectia products is "C:\Program Files\SSH Commu-

nications Security\SSH Tectia".

On Windows, the SSH Tectia Client files are located in the following directories:

• "<INSTALLDIR>\SSH Tectia Client": user binaries such as ssh-client-g3.exe

• "<INSTALLDIR>\SSH Tectia Broker": the Connection Broker binaries

• "<INSTALLDIR>\SSH Tectia Broker\ssh-broker-config.xml": the global Connection Broker

configuration file (see ssh-broker-config(5))

• "<INSTALLDIR>\SSH Tectia AUX": auxiliary binaries such as ssh-keygen-g3.exe


Getting Started28

• "<INSTALLDIR>\SSH Tectia AUX\ssh-broker-ng": the Connection Broker configuration file DTD

directory

• "<INSTALLDIR>\SSH Tectia AUX\ssh-broker-ng\ssh-broker-config-default.xml": the

configuration file with factory default settings (see ssh-broker-config(5))

• "<INSTALLDIR>\SSH Tectia AUX\licenses": the license file directory (see Section 2.1.3)

Figure 3.1 shows the SSH Tectia directory structure when also SSH Tectia Server and SSH Tectia Connector

have been installed on the same machine.

Figure 3.1. The SSH Tectia directory structure on Windows

The user-specific configurations are stored in the following directories (by default, %USERPROFILE% expands

to "C:\Documents and Settings\<username>"):

• "%USERPROFILE%\Application Data\SSH\ssh-broker-config.xml": the user-specific Connection

Broker configuration file

• "%USERPROFILE%\Application Data\SSH\global.dat": the SSH Tectia Client GUI configuration file

• "%USERPROFILE%\Application Data\SSH\*.ssh2": the SSH Tectia Client GUI profile configuration

files

• "%USERPROFILE%\Application Data\SSH\random_seed": the seed file for the random number generator

• "%USERPROFILE%\Application Data\SSH\HostKeys": the user-specific directory for known remote

host keys

• "%USERPROFILE%\Application Data\SSH\UserKeys": the default directory for user keys

• "%USERPROFILE%\Application Data\SSH\UserKeys\identification": (optional) the identification

file used with public-key authentication


29

Note

The user-specific Application Data directory is hidden by default. To view hidden directories,

change the setting in Windows Explorer. For example, on Windows XP, select Tools → Folder

Options on the menu, click the View tab, and select Show hidden files and folders.

3.3 Status Dialog Box (Windows)

When the Connection Broker is running, it shows a small SSH Tectia icon in the system tray. It provides in-

formation of its status in the SSH Tectia Status dialog box.

To open the SSH Tectia Status dialog box, double-click the SSH Tectia icon in the system tray or select the

Status option from the shortcut menu. The left-hand side of the Status dialog box contains links to the different

views of the dialog box: the Connections, Keys, and Logs views. Click on the page icons to see the relevant

view.

3.3.1 Connections View

The Connections view of the Status dialog box displays the currently active secured connections (terminal,

tunnel, or SFTP) to and from your computer.

Figure 3.2. The Connections view of the Status dialog box

The following information is displayed for each connection:


Getting Started30

• Connection: The destination of the connection in the user@host#port format.

• Program: The name of the program connecting via SSH Tectia Connector.

• Upload: Amount of data uploaded (in bytes).

• Download: Amount of data downloaded (in sbytes).

• Upload speed: Upload speed in kilobytes per second.

• Download speed: Download speed in kilobytes per second.

3.3.2 Keys View

The keys view displays the keys and certificates used.

Figure 3.3. The Keys view of the Status dialog box

3.3.3 Logs View

The Logs view of the Status dialog box displays logged information of the currently secured connections.


313.3.2 Keys View

Figure 3.4. The Logs view of the Status dialog box

3.4 Connecting to a Remote Host

The sshg3, scpg3, and sftpg3 command-line clients are available on both Unix and Windows. The terminal

and SFTP GUI clients are available on Windows only. This section gives basic instructions on using sshg3

and the Windows terminal GUI to connect to a remote server host.

3.4.1 Using the GUI Client (Windows)

With SSH Tectia Client on Windows it is easy to establish connections to new remote host computers, and

to manage the settings required for each host. The Quick Connect option allows you to create new connections

fast, minimizing the work associated with configuring each connection. It is easy to define profiles for new

hosts, and save the correct settings for each.

To connect to a remote host using the GUI client:

1. Click the Connect icon on the toolbar, or select File → Connect, or hit Enter or Space on the keyboard

when the (still disconnected) terminal window is active. This opens the Connect to Server dialog.


Getting Started32

Figure 3.5. Identify yourself to the remote host computer

2. In the Connect to Server dialog, specify the host name (or IP address) of the server, your user name on

the server, and the port number where the Secure Shell server is running on. The standard port for Secure

Shell connections is 22.

Unless this is your first connection, the values used in the previous connection are pre-filled.

Click Connect to open the connection.

3. When you connect to a remote server (using server public-key authentication), the server host will provide

your local computer with its host public key. The host key identifies the server host.

SSH Tectia Client checks if this key is already stored in your own host key directory. If not, the host key

directory common to all users on your computer is checked next.

If the host key is not found, you are asked to verify it. The host identification dialog opens. See Figure 3.6.

Figure 3.6. The Host Identification dialog


33

After verifying the key, select whether to cancel the connection, to proceed and to save the key, or to

proceed without saving the key. Click OK.

For more information on server authentication, see Section 6.1.

4. You will be prompted to authenticate yourself to the server. The required authentication method(s) depends

on the server settings.

After you have completed the authentication, you are logged in to the server.

3.4.2 Using the Command-Line Client

To connect to a remote host using the command-line client:

1. Run the sshg3 Secure Shell client. The basic command syntax is the following:

$ sshg3 user@host#port

In the command, user is your username on the server, host is the domain name or IP address of the

server host, and port is the port where the Secure Shell server is running on. The default port for Secure

Shell connections is 22.

For more information on the command-line commands and options, see Appendix A.

2. When you connect to a remote server (using server public-key authentication), the server host will provide

your local computer with its host public key. The host key identifies the server host.

SSH Tectia Client checks if this key is already stored in your own host key directory. If not, the host key

directory common to all users on your computer is checked next.

If the host key is not found, you are asked to verify it.

After verifying the key, you can select whether to cancel the connection, to proceed and to save the key,

or to proceed without saving the key.

For more information on server authentication, see Section 6.1.

3. You will be prompted to authenticate yourself to the server. The required authentication method(s) depends

on the server settings.

After you have completed the authentication, you are logged in to the server.

3.5 Defining Quick Connect Options (Windows)

To start a new connection with the Quick Connect option, do the following:


Getting Started34

1. Select the Quick Connect option (toolbar or File menu) to establish a completely new Secure Shell

connection that can be operated independently of any other clients and connections. You can connect to

an entirely new remote host computer and still keep the old connection to a different host open.

2. The Connect to Server dialog opens, containing the values defined in the default configuration file.

Click Connect.

Use the Settings dialog (see Section 5.3.1) to set the most commonly used options and save them in the con-

figuration file.

When you need to establish a new connection, click the Quick Connect button to connect to a new host with

the default settings. When connected, you can modify the settings to match your exact requirements for this

particular host and save the settings as a host profile. See Section C.4.1.4.

3.6 Using Public-Key Authentication

Public-key authentication is based on the use of digital signatures and provides the best authentication security.

To use public-key authentication, you must first create a key pair on the client, and upload the public key to

the server. For more information, see Section 6.4.

The Connection Broker operates automatically as an authentication agent. It offers an easy method for utilizing

digital certificates and smart cards. The authentication forwarding functionality allows the forwarding of

public-key authentication over several Secure Shell connections. The Connection Broker is started automat-

ically when you start SSH Tectia Client.

3.7 Examples of Use

For examples of using SSH Tectia Client, see http://www.ssh.com/products/material/compatibility/.


353.6 Using Public-Key Authentication

http://www.ssh.com/products/material/compatibility/


Getting Started36

Chapter 4 Configuring Connection Broker

The Connection Broker is a shared component included in SSH Tectia Client and SSH Tectia Connector. All

cryptographic operations and authentication-related tasks for SSH Tectia Client and Connector are handled

by the Connection Broker.

The Connection Broker uses an XML-based configuration file ssh-broker-config.xml. The configuration

file can be edited with an ASCII-text editor or an XML editor (see ssh-broker-config(5)). On Windows, you

can use the SSH Tectia Client GUI to configure the client (see Section 4.1).

ssh-broker-config

ssh-broker-config -- SSH Connection Broker configuration file format

The Connection Broker configuration file ssh-broker-config.xml is a valid XML file.

The Connection Broker reads three configuration files (if all are available):

1. The ssh-broker-config-default.xml file is read first. It holds the factory default settings. It is not

recommended to edit the file, but you can use it to check the default settings.

This file must be available and correctly formatted for the Connection Broker to start.

2. Next, the Connection Broker reads the global configuration file. The settings in the global configuration

file override the default settings.

If the global configuration file is missing or malformed, the Connection Broker will start normally. A

malformed global configuration file is ignored and no settings in it are used.

3. Last, the Connection Broker reads the user-specific configuration file if it is available. The settings in

the user-specific configuration file override the settings in the global configuration file, with the following

exceptions:

• The settings under the key-stores, profiles, and static-tunnels elements from the user-specific

configuration are combined with the settings of the global configuration file. If a connection profile


37

with the same name has been defined in both the global configuration file and user-specific config-

uration file, the latter is used.

• If the crypto-lib, strict-host-key-checking, host-key-always-ask, and accept-unknown-

host-keys elements have different values in the global and user-specific configuration, the more

secure of these values is used.

If the user-specific configuration file is missing, the Connection Broker will start using the previously

read configuration files. However, if the user-specific configuration is malformed, the Connection Broker

will not start.

On Unix, the default configuration file locations are /etc/ssh2/ssh-tectia/auxdata/ssh-broker-ng/ssh-

broker-config-default.xml for the default configuration, /etc/ssh2/ssh-broker-config.xml for the

global configuration, and $HOME/.ssh2/ssh-broker-config.xml for the user-specific configuration. The

XML DTD can be found in the /etc/ssh2/ssh-tectia/auxdata/ssh-broker-ng directory.

On Windows, the default configuration file locations are "C:\Program Files\SSH Communications Secur-

ity\SSH Tectia\SSH Tectia AUX\ssh-broker-ng\ssh-broker-config-default.xml" for the default

configuration, "C:\Program Files\SSH Communications Security\SSH Tectia\SSH Tectia Broker\ssh-

broker-config.xml " for the global configuration, and "%USERPROFILE%\Application Data\SSH\ssh-

broker-config.xml" for the user-specific configuration. The XML DTD can be found in the "C:\Program

Files\SSH Communications Security\SSH Tectia\SSH Tectia AUX\ssh-broker-ng" directory.

This section describes the options available in the Connection Broker configuration file. See Appendix D for

more information on the syntax of the configuration file.

Document Type Declaration and the Root Element

The broker configuration file is a valid XML file and starts with the Document Type Declaration.

The root element in the configuration file is secsh-broker. It can include general, default-settings,

profiles, static-tunnels, gui, filter-engine, and logging elements.

An example of an empty configuration file is shown below:

<!DOCTYPE secsh-broker SYSTEM "ssh-broker-ng-config-1.dtd">

<secsh-broker version="1.0">

<general />

<default-settings />

<profiles />

<static-tunnels />

<gui />

<filter-engine />

<logging />

</secsh-broker>


Configuring Connection Broker38

The gui element is used with SSH Tectia Connector only. The filter-engine element is used with SSH

Tectia Client with EFT Expansion Pack and SSH Tectia Connector.

The general Element

The general element contains settings such as the cryptographic library and the key stores to be used.

crypto-lib

This element selects the cryptographic library mode to be used. Either the standard version (standard)

or the FIPS 140-2 certified version (fips) of the crypto library can be used. The library name is given

as a value of the mode attribute. By default, standard crypto libraries are used.

FIPS mode will be used, if it is so specified either in global or in user configuration file (or both).

<crypto-lib mode="standard" />

In the FIPS mode, the cryptographic operations are performed according to the rules of the FIPS 140-2

standard. The FIPS library includes the 3des-cbc, aes128-cbc, aes192-cbc, and aes256-cbc ciphers

and the hmac-sha1 MAC.

Note

Setting the FIPS mode does not prevent using algorithms from crypto plugins. For example,

CryptiCore can be used even when the main crypto library is set in the FIPS mode. To enforce

that only FIPS-compliant algorithms are used, disable the non-FIPS algorithms from the config-

uration. See cipher and mac.

For a list of platforms on which the FIPS library has been validated or tested, see SSH Tectia Client/Server

Product Description.

cert-validation

This element defines public-key infrastructure (PKI) settings used for validating remote server authentic-

ation certificates. The element can have three attributes: end-point-identity-check, default-domain,

http-proxy-url, and socks-server-url.

The end-point-identity-check attribute specifies whether the client will verify the server's hostname

against the Subject Name or Subject Alternative Name (DNS Address) in the server's certificate. If set

to no, the fields in the server host certificate are not verified and the certificate is accepted based on

validity period and CRL check only. Note that this is a possible security risk, as anyone with a certificate

issued by the same trusted CA that issues the server host certificates can perform a man-in-the-middle

attack on the server if a client has the end-point identity check disabled. The default value is yes.


39The general Element

The default-domain attribute can be used when the end-point identity check is enabled. It specifies the

default domain part of the remote system name and it is used if only the base part of the system name is

available. The default-domain is appended to the system name if it does not contain a dot (.).

If the default domain is not specified, the end-point identity check fails, for example, when a user tries

to connect to a host "tower" giving only the short hostname and the certificate contains the full DNS

address "tower.example.com".

The http-proxy-url attribute defines a HTTP proxy and the socks-server-url attribute defines a

SOCKS proxy for making LDAP or OCSP queries for certificate validity.

The address of the proxy is given as the value of the attribute. The format of the address is

socks://username@socks_server:port/network/netmask,network/netmask ... (with a SOCKS

proxy) or http://username@proxy_server:port/network/netmask,network/netmask ... (with

an HTTP proxy).

For example, by setting socks-server-url to "socks://mylo-

[email protected]:1080/192.196.0.0/16,10.100.23.0/24", the host socks.ssh.com and port

1080 are used as your SOCKS server for connections outside of networks 192.196.0.0 (16-bit domain)

and 10.100.23.0 (8-bit domain). Those networks are connected directly.

The cert-validation element can contain multiple ldap-server and ocsp-responder elements, a

dod-pki element, and multiple ca-certificate elements.

ldap-server

This element specifies an LDAP server address and port used for fetching CRLs and/or subordinate

CA certificates based on the issuer name of the certificate being validated. Several LDAP servers

can be specified by using several ldap-server elements.

CRLs are automatically retrieved from the CRL distribution point defined in the certificate to be

verified if the point exists.

The default value for port is 389.

ocsp-responder

This element specifies an OCSP (Online Certificate Status Protocol) responder service address in

URL format (url). Several OCSP responders can be specified by using several ocsp-responder

elements.

If the certificate has a valid Authority Info Access extension with an OCSP Responder URL, it

will be used instead of this setting. Note that for the OCSP validation to succeed, both the end-entity

certificate and the OCSP Responder certificate must be issued by the same CA.



The validity-period (in seconds) can be optionally defined. During this time, new OCSP queries

for the same certificate are not made but the old result is used. The default validity period is 0 (a new

query is made every time).

dod-pki

This element defines whether the certificates are required to be compliant with the DoD PKI (US

Department of Defense Public-Key Infrastructure). In practise, this means that the Digital Signature

bit must be set in the Key Usage of the certificate. The enable attribute can have a value of yes or

no. The default is no.

ca-certificate

This element defines a CA used in server authentication. It can have four attributes: name, file,

disable-crls, and use-expired-crls.

The name attribute must contain the name of the CA.

The element must either contain the path to the X.509 CA certificate file as a value of the file at-

tribute, or include the certificate as a base64-encoded ASCII block.

CRL checking can be disabled by setting the disable-crls attribute to yes. The default is no.

Expired CRLs can be used by setting a numeric value (in seconds) for the use-expired-crls attribute.

The default is 0 (do not use expired CRLs).

An example of a certificate validation configuration is shown below:

<cert-validation end-point-identity-check="yes"

default-domain="example.com"

http-proxy-url="http://proxy.example.com:8080">

<ldap-server address="ldap://ldap.example.com:389" />

<ocsp-responder url="http://ocsp.example.com:8090" validity-period="0" />

<dod-pki enable="no" />

<ca-certificate name="ssh_ca1"

file="ssh_ca1.crt"

disable-crls="no"

use-expired-crls="100" />

</cert-validation>

key-stores

There can be one <key-stores> instance under the <general> element. It can have any amount of <key-

store> elements each of which configures one key store provider.


41

key-store

The key-store element has two attributes: type and init. The type attribute is the key store type.

Currently supported types are "software", "mscapi", "entrust", and "pkcs11". The init attribute

is the key-store-provider-specific initialization info.

See the section called “Key Store Configuration Examples” for key store configuration examples.

strict-host-key-checking

This element enables strict host key checking. If it is enabled, the Connection Broker never adds host

keys to the user's .ssh2/hostkeys directory upon connection, and refuses to connect to hosts whose key

has changed. This provides maximum protection against man-in-the-middle attacks. However, it can be

somewhat annoying if you frequently connect to new hosts.

The word yes or no is given as the value of the enable attribute. The default is no (the user is asked

whether to accept a new or changed host key).

Strict host key checking will be used, if it is so specified in either the global or the user configuration file

(or both).

<strict-host-key-checking enable="yes" />

host-key-always-ask

This element defines whether the Connection Broker should prompt the user to accept the proposed host

key even if it is already known.

The word yes or no is given as the value of the enable attribute. The default is no (known host keys are

accepted without prompting).

Host keys are always asked, if it is so specified in either the global or the user configuration file (or both).

<host-key-always-ask enable="yes" />

accept-unknown-host-keys

This element defines whether the Connection Broker will always accept the proposed host key without

saving the key. It is the equivalent of automatically answering "Once" to all accept-host-key prompts.

The word yes or no is given as the value of the enable attribute. The default is no (unknown host keys

are not automatically accepted).

If this element is set to no either in the global or the user configuration file, the changed or new host keys

are prompted normally. Additionally, setting this element to yes takes effect only when both strict-

host-key-checking and host-key-always-ask are set to no (or are not explicitly defined).

<accept-unknown-host-keys enable="no" />



Caution

Consider carefully before enabling this option. Disabling the host-key checks can make you

vulnerable to a man-in-the-middle attack.

known-hosts

This element specifies the location of an OpenSSH-style known-hosts file that contains the public key

data of known server hosts. The full path to the known_hosts file must be given as a value of the path

attribute.

<known-hosts path="/u/username/.ssh/known_hosts" />

The hostname(s) in the file must be in clear-text format. Hashed hostnames are not supported.

Key Store Configuration Examples

Software provider

The software provider handles key pairs stored on disk in standard Secure Shell v2 or legacy OpenSSH formats

and X.509 certificates stored in native X.509, PKCS#7, and PKCS#12 formats.

To add a single key file (for example, /u/exa/keys/enigma and /etc/my_key), specify both the private key

file and the public key file:

<key-stores>

<key-store type="software"

init="key_files(/u/exa/keys/enigma.pub,/u/exa/keys/enigma)" />


init="key_files(/etc/my_key.pub,/etc/my_key)" />

</key-stores>

To add all keys from a specific directory (for example all keys from /u/exa/keys and /etc/keys):

<key-stores>


init="directory(path(/u/exa/keys))" />


init="directory(path(/etc/keys))" />

</key-stores>

Entrust provider

The Entrust provider handles keys and certificates stored in the proprietary Entrust format.

You should provide the initialization file and the profile specific file for the Entrust provider. For example:

<key-stores>

<key-store type="entrust"

init="ini-file(/etc/entrust.ini),profile-file(/etc/profile.epf)" />

</key-stores>


43Key Store Configuration Examples

PKCS#11 provider

The PKCS#11 provider handles keys and certificates stored in PKCS#11 tokens (for example, smart cards or

USB tokens).

Specify the dynamic library path for the PKCS provider and all or a specific slot. For example, with all slots:

<key-stores>

<key-store type="pkcs11" init="dll(/usr/lib/pkcs.so),slots(all)" />

</key-stores>

For example, with one slot named sesam:

<key-stores>

<key-store type="pkcs11" init="dll(/usr/local/lib/pkcs.so),slots(sesam)" />

</key-stores>

The default-settings Element

The default-settings element defines the default connection-related settings. Profile-specific settings can

override these settings.

ciphers

This element defines the ciphers that the client will propose to the server. The ciphers element can

contain multiple cipher elements.

The ciphers are tried in the order they are specified.

cipher

This element selects a cipher name that the client requests for data encryption.

The supported ciphers are 3des-cbc, aes128-cbc, aes192-cbc, aes256-cbc, arcfour, blowfish-

cbc, twofish-cbc, twofish128-cbc, twofish192-cbc, twofish256-cbc, [email protected],

[email protected], and none (no encryption).

The default ciphers used by the Connection Broker are, in order: [email protected] (on

Windows and Linux x86), aes128-cbc, aes192-cbc, aes256-cbc, 3des, and [email protected].

The ciphers that can operate in the FIPS mode are aes128-cbc, aes192-cbc, aes256-cbc, and

3des-cbc.

<ciphers>

<cipher name="[email protected]" />

<cipher name="aes128-cbc" />

</ciphers>



macs

This element defines the MACs that the client will propose to the server. The macs element can contain

multiple mac elements.

The MACs are tried in the order they are specified.

mac

This element selects a MAC name that the client requests for data integrity verification.

The supported MAC algorithms are hmac-md5, hmac-md5-96, hmac-sha1, hmac-sha1-96,

[email protected], and none (no data integrity verification).

The default MACs used by the Connection Broker are, in order: [email protected] (on

Windows and Linux x86), hmac-md5, and hmac-sha1.

The hmac-sha1 algorithm can operate in the FIPS mode.

<macs>

<mac name="hmac-sha1" />

</macs>

transport-distribution

This setting defines the number of transport channels used by the Secure Shell connection. Using more

than one transport may increase the throughput over low bandwidth connections.

The number of transports is given as value of the num-transports attribute. Currently, a value of 1 to

8 transports is supported. On Unix, the default is 1 transport. On Windows, the default is 2 transports.

<transport-distribution num-transports="1" />

rekey

This element specifies the number of transferred bytes after which the key exchange is done again. The

value "0" turns rekey requests off. This does not prevent the server from requesting rekeys, however.

The default is 1000000000 (1 GB).

<rekey bytes="1000000000" />

authentication-methods

This element specifies the authentication methods that are requested by the client. The authentication-

methods element can contain multiple authentication-method elements.

The authentication methods are tried in the order of the authentication-method elements. This means

that the least interactive methods should be placed first.


45

authentication-method

This element specifies an authentication method name.

The allowed authentication method names are: gssapi-with-mic, publickey, keyboard-inter-

active, password, and hostbased.

SSH Tectia Client supports host-based authentication only on Unix platforms.

If you want to use non-interactive password authentication, you can also predefine a response (text

string) or a response-file (path to a file containing the response).

Caution

Use this option only with tunneling connections when the tunneled application takes care

of authentication. In any case, specifying a password or other authentication secret in the

configuration file will not provide full level of security. This option is not recommended

for scripting.

<authentication-methods>

<authentication-method name="hostbased" />

<authentication-method name="gssapi-with-mic" />

<authentication-method name="publickey" />

<authentication-method name="keyboard-interactive" />

<authentication-method name="password" response-file="C:\path\password.txt" />

</authentication-methods>

compression

This element specifies whether to use compression.

The name of the compression algorithm and the compression level can be given as attributes. Currently

only zlib is supported as the algorithm. The level can be an integer from 0 to 9. By default, compression

is not used.

<compression name="none" />

proxy

This element defines rules for HTTP or SOCKS proxy servers the client will use for connections. It has

a single attribute: ruleset.

The format of the attribute value is a sequence of rules delimited by semicolons (;). Each rule has a

format that resembles the URL format. In a rule, the connection type is given first. The type can be direct,

socks, socks4, socks5, or http-connect (socks is a synonym for socks4). This is followed by the

server address and port. If the port is not given, the default ports 1080 for SOCKS and 80 for HTTP are

used.



After the address, zero or more conditions delimited by commas (,) are given. The conditions can specify

IP addresses or DNS names.

direct:///[cond[,cond]...]

socks://server/[cond[,cond]...]

socks4://server/[cond[,cond]...]

socks5://server/[cond[,cond]...]

http-connect://server/[cond[,cond]...]

The IP address/port conditions have an address pattern and an optional port range:

ip_pattern[:port_range]

The ip_pattern may have one of the following forms:

• a single IP address x.x.x.x

• an IP address range of the form x.x.x.x-y.y.y.y

• an IP sub-network mask of the form x.x.x.x/y

The DNS name conditions consist of a hostname which may be a regular expression containing the

characters "*" and "?" and a port range:

name_pattern[:port_range]

An example proxy element is shown below. It causes the server to access the callback address and the

ssh.com domain directly, access *.example with HTTP CONNECT, and all other destinations with

SOCKS4.

<proxy ruleset="direct:///127.0.0.0/8,*.ssh.com;

http-connect://http-proxy.ssh.com:8080/*.example;

socks://fw.ssh.com:1080/" />

idle-timeout

This element specifies how long idle time (after all connection channels are closed) is allowed for a

connection before automatically closing the connection. The time is given in seconds.

The default setting is 5 seconds. Setting a longer time allows the connection to the server to remain open

even after a session (for example, sshg3) is closed. During this time, a new session to the server can be

initiated without re-authentication. Setting the time to 0 (zero) terminates the connection immediately

when the last channel to the server is closed.

<idle-timeout time="5" />

server-banners

This element defines whether the server banner message file (if it exists) is visible to the user before login.

The word yes or no is given as the value of the visible attribute. The default is yes.


47

<server-banners visible="no" />

forwards

This element contains forward elements that define whether X11 or agent forwarding (tunneling) are

allowed at the client side.

forward

This element defines X11 or agent forwarding settings.

The type attribute defines the forwarding type (either x11 or agent). The state attribute sets the

forwarding on, off, or denied. If the forwarding is set as denied, the user cannot enable it on the

command-line.

An example forward configuration, which allows X11 forwarding and denies agent forwarding globally,

is shown below:

<forwards>

<forward type="x11" state="on" />

<forward type="agent" state="denied" />

</forwards>

For more information on using X11 and agent forwarding, see Section 8.4 and Section 8.5.

The profiles Element

The profiles element defines the connection profiles for connecting to different servers. It can contain

multiple profile elements. Each profile defines connection rules to one server.

profile

The profile element defines a connection profile. It has seven attributes: id, name, host, port, connect-

on-startup, user, and gateway-profile.

The profile id must be a unique identifier that does not change during the lifetime of the profile.

An additional name can be given to the profile. This is a free-form text string.

The host address and port must also be given. The address can be either an IP address or a domain

name. The default port is 22.

If you want to make the connection specified by the profile automatically at reboot, set the value of the

connect-on-startup attribute to yes. In this case, give also the user attribute (the username the con-

nection is made with). You also need to set up some form of non-interactive authentication for the con-

nection.



In the user attribute, the value '%USERNAME%' can be used to set the username to the current user. In the

host and user attributes, the value '*' can be used to prompt the user for the hostname or the username.

The gateway-profile attribute can be used to create nested tunnels. The profile name through which

the connection is made is given as the value of the attribute. The first tunnel is created using the gateway

host profile and from there the second tunnel is created to the host defined in this profile.

hostkey

This element gives the path to the remote server host public key file as a value of the file attribute.

Alternatively, the public key can be included as a base64-encoded ASCII block.

ciphers

This element defines the ciphers used with this profile. See the section called “The default-settings

Element”.

macs

This element defines the MACs used with this profile. See the section called “The default-settings

Element”.

transport-distribution

This element defines the transport distribution for this profile. See the section called “The default-

settings Element”.

rekey

This element defines the rekeying settings used with this profile. See the section called “The default-


authentication-methods

This element defines the authentication methods used with this profile. See the section called “The

default-settings Element”.

compression

This element defines the compression settings used with this profile. See the section called “The


proxy

This element defines the proxy settings used with this profile. See the section called “The default-



49

If a gateway profile (gateway-profile) has been defined for this profile, the proxy setting is ignored

and the default proxy setting or the proxy setting of the gateway profile is used.

idle-timeout

This element defines the idle timeout settings used with this profile. See the section called “The de-

fault-settings Element”.

server-banners

This element defines the server banner setting used with this profile. See the section called “The


forwards

This element defines the forwards allowed with this profile. See the section called “The default-


tunnels

The tunnels element defines the tunnels that are opened when a connection with this profile is made.

The element can contain multiple local-tunnel and remote-tunnel elements.

local-tunnel

This element defines a local tunnel (port forwarding) that is opened automatically when a con-

nection is made with the connection profile. It has five attributes: type, listen-port, dst-

host, dst-port, and allow-relay.

This allocates a listener port (listen-port) on the local client. Whenever a connection is made

to this listener, the connection is tunneled over Secure Shell to the remote server and another

connection is made from the server to a specified destination host and port (dst-host, dst-

port). The connection from the server onwards will not be secure, it is a normal TCP connection.

The type attribute defines the type of the tunnel. This can be tcp (default, no special processing),

ftp (temporary forwarding is created for FTP data channels, effectively securing the whole FTP

session), or socks (SSH Tectia Client will act as a SOCKS server for other applications, creating

forwards as requested by the SOCKS transaction).

The listen-port attribute defines the local port to be listened. The dst-host and dst-port

attributes define the destination host address and port. The value of dst-host can be either an

IP address or a domain name. The default is 127.0.0.1 (localhost = server host).

The allow-relay attribute defines whether connections to the listened port are allowed from

outside the client host. The default is no.

For more information on using local tunnels, see Section 8.1.



remote-tunnel

This element defines a remote tunnel (port forwarding) that is opened automatically when a

connection is made with the connection profile. It has four attributes: type, listen-port, dst-

host, dst-port, and allow-relay.

This allocates a listener port (listen-port) on the remote server. Whenever a connection is

made to this listener, the connection is tunneled over Secure Shell to the local client and another

connection is made from the client to a specified destination host and port (dst-host, dst-

port). The connection from the client onwards will not be secure, it is a normal TCP connection.

The type attribute defines the type of the tunnel. This can be either tcp (default, no special

processing) or ftp (temporary forwarding is created for FTP data channels, effectively securing

the whole FTP session).

The listen-port attribute defines the remote port to be listened. The dst-host and dst-port

attributes define the destination host address and port. The value of dst-host can be either an

IP address or a domain name. The default is 127.0.0.1 (localhost = client host).

The allow-relay attribute defines whether connections to the listened port are allowed from

outside the server host. The default is no.

For more information on using remote tunnels, see Section 8.2.

An example connection profile is shown below:

<profile name="tower"

id="id1"

host="tower.example.com"

port="22"

connect-on-startup="no"

user="doct">

<hostkey file="key_22_tower.pub">

</hostkey>



<authentication-method name="password" />


<server-banners visible="yes" />

<forwards>

<forward type="agent" state="on" />

<forward type="x11" state="on" />

</forwards>

<tunnels>


51

<local-tunnel type="tcp"

listen-port="143"

dst-host="imap.example.com"

dst-port="143"

allow-relay="no" />

</tunnels>

</profile>

The static-tunnels Element

With the static-tunnels setting, you can create listeners for local tunnels automatically when the Connection

Broker starts up. The actual tunnel is formed the first time a connection is made to the listener port. If the

connection to the server is not open at that time, it will be opened automatically as well.

The static-tunnels element can contain any number of tunnel elements.

tunnel

The tunnel element specifies a static tunnel. It has six attributes: type, listen-port, dst-host, dst-

port, allow-relay, and profile.

The type attribute defines the type of the tunnel. This can be either tcp or ftp.

The listen-port attribute defines the local port to be listened. The dst-host and dst-port attributes

define the destination host address and port. The value of dst-host can be either an IP address or a domain

name. The default is 127.0.0.1 (localhost = client host).

The allow-relay attribute defines whether connections to the listened port are allowed from outside the

client host. The default is no.

The profile attribute specifies the connection profile id that is used for the tunnel.

<static-tunnels>

<tunnel type="tcp"

listen-port="9000"

dst-host="st.example.com"

dst-port="9000"

allow-relay="no"

profile="id1" />

</static-tunnels>

The gui Element

The gui element contains only one element (gui), which is used to adjust the Connection Broker GUI settings.

The gui element has five attributes: hide-tray-icon, show-exit-button, show-admin, enable-connector,

and show-security-notification. All of these must have yes or no as the value. The last two settings have

effect only if SSH Tectia Connector has been installed on the system.



The hide-tray-icon attribute controls whether the SSH Tectia tray icon is displayed in the system tray. The

default is no (the tray icon is displayed).

The show-exit-button attribute controls whether the Exit command is displayed in the tray icon shortcut

menu. The default is yes.

The show-admin attribute defines whether the Configuration command is displayed in the tray icon shortcut

menu. The default is yes. If the button is not displayed, the SSH Tectia Configuration tool can be started by

running ssh-tectia-configuration.exe, located by default in the "C:\Program Files\SSH Communica-

tions Security\SSH Tectia\SSH Tectia Broker" directory.

The enable-connector attribute defines whether SSH Tectia Connector (if present) is active and capturing

connections. The default is yes.

The show-security-notification attribute defines whether the SSH Tectia Connector security notification

is shown upon establishing a secure application tunnel. The default is yes.

<gui hide-tray-icon="no"

show-exit-button="yes"

show-admin="yes"

enable-connector="yes"

show-security-notification="yes" />

The filter-engine Element (EFT Expansion Pack, SSH Tectia Connector)

The filter-engine element defines the SSH Tectia Connector filter rules and SSH Tectia Client (with EFT)

FTP-SFTP conversion rules. These settings have no effect if only the basic SSH Tectia Client has been installed

on the system.

The top level element is filter-engine. It has one attribute: ip-generate-start. This attribute defines

the start address of the pseudo IP address space. Pseudo IPs are generated by the Connection Broker when

applications do the DNS query through the SSH Capture DLL.

Under the filter-engine element there can be any amount of elements of the type network, dns, or filter.

The order of the elements is important, because the filter engine uses the elements in the order they were

specified in the configuration file.

network

The network element specifies a "location" where SSH Tectia Connector is running. Using the network

elements you can implement location-awareness for SSH Tectia Connector. It has four attributes: id,

address, domain, and ip-generate-start.

The id attribute specifies a unique identifier for the network element. The address attribute specifies

the address of the network. It can be missing or empty, in which case it is not used. The domain attribute

contains the domain name of the computer. It can also be missing or empty, in which case it is not used.


53The filter-engine Element (EFT Expansion Pack, SSH Tectia Con-

nector)

The ip-generate-start attribute defines the start address of the pseudo IP space. If it is defined here,

it overrides the ip-generate-start attribute of the filter-engine element.

dns

The dns element creates a DNS rule for the filter engine. It has six attributes: id, network-id, applica-

tion, host, ip-address, and pseudo-ip.

The id attribute specifies a unique identifier for the dns element. The network-id attribute contains a

reference to a network element. This can be left empty if the dns entry does not bind to a specific network.

The application attribute specifies the application for which this DNS entry is used. This can be a

regular expression.

The host attribute specifies a target host name. It can be a regular expression. The ip-address attribute

specifies the target host IP address. It can be a regular expression. When both the hostname and the IP

address are defined, the host attribute takes precedence and the ip-address attribute is ignored. When

the ip-address is left empty and the host matches one of the following things happen:

• When the pseudo-ip attribute is set to yes, the Connection Broker assigns a pseudo IP address for

the target host and SSH Tectia Server resolves the real IP address.

Pseudo IP addresses should be used when accessing an internal network from the outside, because

name resolution for the machines in the internal network is not available from the outside.

• When the pseudo-ip attribute is set to to no, a normal DNS query is made for the target hostname.

filter

The filter element specifies an action for a connection. It has five attributes: dns-id, ports, action,

profile-id, and fallback-to-plain.

The dns-id attribute is a reference to a dns element. The ports attribute can be a single port or a range.

A range is specified with a dash between two integers (like "21-25").

The action attribute specifies the action to be done when a filter is used. Its value can be DIRECT, BLOCK,

TUNNEL (with SSH Tectia Connector), or FTP-PROXY (with SSH Tectia Client with EFT Expansion Pack).

• If the action is DIRECT, the connection is made directly as plaintext without tunneling or FTP-SFTP

conversion.

• If the action is BLOCK, the connection is blocked.

• If the action is TUNNEL, a reference to a profile ID must be given in the profile-id attribute. This

means that a connection is tunneled through a Secure Shell server specified in the profile.

• If the action is FTP-PROXY, a reference to a profile ID can be given in the profile-id attribute. This

means that the FTP-SFTP connection is made to the Secure Shell server specified in the profile. If

the profile-id attribute is left empty or the referred profile has * (an asterisk) as the value of the

host attribute, the connection is made to the server specified by the FTP client application.



When applying the filter rule, if creating the tunnel fails (or the connection to the Secure Shell server

fails) the Connection Broker will normally return a "host not reachable" error. However, if the fallback-

to-plain attribute is set to yes, a direct (unsecured) connection is used instead.

The fallback-to-plain and pseudo-ip options should not be enabled at the same time. If they are,

and the secure connection fails, the application will try a direct connection with the pseudo IP, which

will not work.

An example filter engine configuration with SSH Tectia Connector is shown below.

<filter-engine ip-generate-start="188.1.1.1">

<network id="office"

address="10.1.48.0"

domain=".*\.ssh\.com"

ip-generate-start="" />

<dns id="telnet-app-dns"

network-id="office"

application="telnet.exe"

host=".*"

ip-address=".*"

pseudo-ip="yes" />

<dns id="all-dns"

network-id="office"

application=""

host=".*"

ip-address=".*"

pseudo-ip="yes" />

<dns id="www-proxy-dns"

network-id="office"

application=""

host="www-cache.*"

ip-address=""

pseudo-ip="no" />

<filter dns-id="telnet-app-dns"

ports="23"

action="TUNNEL"

profile-id="tower"

fallback-to-plain="no" />

<filter dns-id="all-dns"

ports="21"

action="BLOCK"


<filter dns-id="www-proxy-dns"

ports="8080"


55

action="DIRECT"


<filter dns-id="all-dns"

ports="1-65535"

action="TUNNEL"

profile-id="firewall"


</filter-engine>

This configuration specifies the following:

• All connections from a Telnet application are tunneled through a profile named tower.

• All connections to a FTP port are blocked.

• Connections to a WWW proxy host are passed through directly.

• All other connections are tunneled through a profile named firewall.

All of the rules are only used in the "office" network which is specified by network address 10.1.48.0.

Pseudo IPs are generated starting from 188.1.1.1.

An example filter engine configuration with SSH Tectia Client with EFT Expansion Pack on Unix is shown

below.

<filter-engine>

<dns id="ftp-proxy"

application="ftp"

host=".*"

ip-address=".*"

pseudo-ip="no" />

<filter dns-id="ftp-proxy"

ports="21"

action="FTP-PROXY"

profile-id=""


</filter-engine>

This configuration specifies that all connections from a FTP application are converted to SFTP and the con-

nection is made to the server specified by the FTP application.

Note

On Unix platforms, specifying the application with a long application name (with the path) will not

work in all cases. Use short application names.



The logging Element

The logging element changes the logging settings that define the log event severities and logging facilities.

The element contains one or more log-events elements.

log-events

This element sets the severity and facility of different logging events. The events have reasonable default

values, which are used if no explicit logging settings are made. This setting allows customizing the default

values.

For the events, facility and severity can be set as attributes. The events itself should be listed inside

the log-events element.

The facility can be normal, daemon, user, auth, local0, local1, local2, local3, local4, local5,

local6, local7, or discard. Setting the facility to discard causes the server to ignore the specifed log

events.

On Windows, only the normal and discard facilities are used.

The severity can be informational, notice, warning, error, critical, security-success, or secur-

ity-failure.

Any events that are not specifically defined in the configuration file will use the default values. The defaults

can be overridden for all remaining events by giving an empty log-events element after all other

definitions and setting a severity value for it.

For a complete list of log events, see Appendix F.

4.1 Configuration Tool (Windows)

The Connection Broker is a common component for SSH Tectia Client and SSH Tectia Connector. On Win-

dows, it is configured in the SSH Tectia Configuration tool. Most of the settings are shared by both SSH

Tectia Client and SSH Tectia Connector.

SSH Tectia Client and SSH Tectia Connector authentication and connection profile settings are defined in

the SSH Tectia Configuration tool. Also all SSH Tectia Connector settings are defined in the SSH Tectia

Connector pages (Section 4.1.8).

The configuration tool can be accessed from the SSH Tectia tray icon shortcut menu. Select Configuration

to open the configuration tool.

If the command has been disabled from the shortcut menu, you can start the SSH Tectia Configuration tool

by running ssh-tectia-configuration.exe, located by default in the "C:\Program Files\SSH Communic-

ations Security\SSH Tectia\SSH Tectia Broker" directory.


57The logging Element

4.1.1 Defining General Settings

On the General page, you can select the cryptographic library to be used and define the SSH Tectia tray icon

settings.

Figure 4.1. General settings

Configuration File

Shows the location of the user-specific Broker configuration file. The default location is "%USERPRO-

FILE%\Application Data\SSH\ssh-broker-config.xml".

Each time the configuration file is saved, a backup of the old configuration is stored in "%USERPROFILE%\Ap-

plication Data\SSH\ssh-broker-config-backup.xml".

Cryptographic Library

SSH Tectia Client can be operated in FIPS mode, using a version of the cryptographic library that has

been validated according to the Federal Information Processing Standard (FIPS) 140-2. In this mode, the

cryptographic operations are performed according to the rules of the FIPS 140-2 standard.

Select whether to use the Standard or the FIPS 140-2 certified version of the cryptographic library.



Note

Setting the FIPS mode does not prevent using algorithms from crypto plugins. For example,

CryptiCore can be used even when the main crypto library is set in the FIPS mode. To enforce

that only FIPS-compliant algorithms are used, disable the non-FIPS algorithms from the config-

uration. See Section 4.1.2.2, Section 4.1.2.3, Section 4.1.5.3, and Section 4.1.5.4.

Connection Broker

Select whether to hide the SSH Tectia tray icon, and whether to show the Exit and Configuration options

in the shortcut menu.

4.1.2 Defining Default Settings

The Default Connection page allows you to edit default settings for authentication (Section 4.1.2.1), ciphers

(Section 4.1.2.2), MACs (Section 4.1.2.3), and server connection (Section 4.1.2.4).

Newly created connection profiles will inherit the default settings defined here. The values can be customized

on the profile-specific tabbed pages and they override the default settings. See Section 4.1.5.2, Section 4.1.5.3,

Section 4.1.5.4, and Section 4.1.5.5.

Defining Authentication

On the Authentication tab, you can define the default user authentication methods.


594.1.2 Defining Default Settings

Figure 4.2. Authentication methods for Client and Connector

To add a new authentication method to the list, click Add and select the method from the drop-down menu.

To remove an authentication method, select a method from the list and click Delete.

Use the arrow buttons to organize the preferred order of the authentication methods. The first method that is

allowed by the Secure Shell server is used. Note that in some cases, the server may require several authentic-

ation methods to be passed before allowing login.

Possible methods for user authentication are the following:

• Password: Use a password for authentication.

• Public-key: Use public-key authentication. See also Section 4.1.6.

• Keyboard-interactive: Keyboard-interactive is designed to allow the Secure Shell client to support sev-

eral different types of authentication methods, including RSA SecurID, and PAM. For more information

on keyboard-interactive, see Section 6.7.

• GSSAPI: GSSAPI (Generic Security Service Application Programming Interface) is a common security

service interface that allows different security mechanisms to be used via one interface. For more inform-

ation on GSSAPI, see Section 6.8.



Defining Ciphers

On the Ciphers tab, you can define the encryption algorithms used.

Figure 4.3. Defining a cipher list

Select the Use factory defaults check box to use the factory default algorithms, or define a cipher list using

the arrow buttons. The ciphers are tried in the order they are specified.

The factory default ciphers are, in order:

• CryptiCore

• AES-128

• AES-192

• AES-256

• 3DES

• SEED

The ciphers that can operate in the FIPS mode are 3DES, AES-128, AES-192, and AES-256.


61

Defining MACs

On the MACs tab, you can configure the message integrity algorithms used.

Figure 4.4. Defining a MAC list

Select the Use factory defaults check box to use the factory default algorithms, or define a MAC list using

the arrow buttons. The MACs are tried in the order they are specified.

The factory default MACs are, in order:

• CryptiCore

• HMAC-MD5

• HMAC-SHA1

The HMAC-SHA1 algorithm can operate in the FIPS mode.

Defining Advanced Connection Settings

On the Server tab, you can define advanced server connection settings.



Figure 4.5. Defining server connection settings

Use factory defaults

Select the check box to use default values for the server connection settings.

Transport distribution

This settings define the number of transport channels used by the Secure Shell connection. Using more

than one transport may increase the throughput over low bandwidth connections. Currently, a value of 1

to 8 transports is supported. The default is 2 transports.

Connection timeout

This setting specifies how long idle time (after all connection channels are closed) is allowed for a con-

nection before automatically closing the connection. The default is 5 seconds. Setting a longer time allows

the connection to the server to remain open even after a session (for example, GUI client) is closed.

During this time, a new session to the server can be initiated without re-authentication. Setting the time

to 0 (zero) terminates the connection immediately when the last channel to the server is closed.

Show server banner

Select the check box if you want to have the server banner message file (if it exists) visible to users before

login.

4.1.3 Defining Proxy Rules

On the Proxy Rules page, you can define proxy rules to be used for connections.


634.1.3 Defining Proxy Rules

Figure 4.6. Defining proxy rules

To add a new proxy rule:

1. Click Add. The Proxy Rule dialog box opens.

2. Select the Type of the rule. The type can be Direct (no proxy), Socks4, Socks5, or Http.

Figure 4.7. Defining proxy settings

For other types than direct, enter the proxy Server address and Port.



Select also whether the proxy rules applies to Any connection or only to connections to the specified

Network. In the Network field, you can enter one or more conditions delimited by commas (,). The

conditions can specify IP addresses or DNS names.

The IP address/port conditions have an address pattern and an optional port range (ip_pat-

tern[:port_range]).

The ip_pattern may have one of the following forms:

• a single IP address x.x.x.x

• an IP address range of the form x.x.x.x-y.y.y.y

• an IP sub-network mask of the form x.x.x.x/y

The DNS name conditions consist of a hostname which may be a regular expression containing the

characters "*" and "?" and a port range (name_pattern[:port_range]).

Click OK.

To edit a proxy rule, select a rule from the list and click Edit.

To delete a proxy rule, select a rule from the list and click Delete.

The rules are read from top down. Use the arrow button to change the order of the rules.

To use these general proxy rules with a connection profile, you must select to do so in the profile settings.

See Section 4.1.5.6.

4.1.4 Defining Logging Settings

On the Logging page, you can customize the information that is logged in the event log.


654.1.4 Defining Logging Settings

Figure 4.8. Logging settings

Each event has an associated Action and Type. They have reasonable default values, which are used if no

explicit logging settings are made.

The action can be either log or discard.

The event type can be one of the following:

• Informational

• Warning

• Error

• Security success

• Security failure

For a description of the log events, see Appendix F.

To change whether the event is logged or not, select an event from the list and click Log/Discard. You can

select multiple events by holding down the SHIFT or CTRL key while clicking.



To customize the event action and type, select an event from the list and click Edit. You can select multiple

events by holding down the SHIFT or CTRL key while clicking. The Edit Audit dialog box opens. Select

the Action and Type for the event and click OK.

4.1.5 Defining Connection Profiles

Under Connection Profiles you can configure separate connection settings for each Secure Shell server you

connect to. You can also configure several profiles for the same server, for example, with different user ac-

counts.

To add a connection profile, click Add profile in the Connection Profiles page. Type a name for the profile

and click OK. By default, the profile name is also used as the hostname of the server.

Newly created connection profiles will inherit the default values for authentication, ciphers, MACs, and ad-

vanced server settings defined under the General → Defaults page (Section 4.1.2). The values can be custom-

ized on the profile-specific tabbed pages.

Define the profile settings in the tabbed view as described in Section 4.1.5.1, Section 4.1.5.2, Section 4.1.5.3,

Section 4.1.5.4, Section 4.1.5.5, Section 4.1.5.6, Section 4.1.5.7, Section 4.1.5.8, Section 4.1.5.9, Sec-

tion 4.1.5.10, and Section 4.1.5.11.

If you have a lot of different servers you are connecting to, you can organize the connection profiles in folders.

To add a folder for connection profiles, click Add folder in the Connection Profiles page. Type a name for

the folder and click OK. You can now add connection profiles to the folder by selecting the folder and

clicking Add profile. The profile will be created in the folder.

To move a profile to a different profile folder, select the profile from the list and click Move. Select the folder

where you want to move the profile from the drop-down list and click OK.

To rename a connection profile or a profile folder, select a profile or a folder and click Rename. Type a new

name and click OK.

To remove a connection profile or a profile folder, select a profile or a folder and click Delete. You will be

asked for confirmation. Click OK to proceed with the deletion.

Note that removing a profile folder removes also all profiles in it.

Defining Connection Settings

On the Connection tab, you can define the protocol settings used in the connection. Any changed connection

settings will take effect the next time you log in.


674.1.5 Defining Connection Profiles

Figure 4.9. Configuring connection profiles

Hostname

Type the name of the remote host computer you want to connect to using this profile. If you specify *

(an asterisk) as the hostname, you will be prompted to type in the hostname when connecting.

Username

Type the username you want to use when connecting to the remote host computer. If you specify * (an

asterisk) as the username, you will be prompted to type in the username when connecting. If you specify

%USERNAME% (note the percent signs) as the username, it will be replaced with the name of the current

Windows user account upon connecting.

Port number

Type the port number you want to use for the Secure Shell connection. The default port is 22.

Note

A Secure Shell server program must be listening to the specified port on the remote host computer

or the connection attempt will not succeed. If you are unsure which port the remote host computer

is listening to, contact the system administrator of the remote host.

Compression

Select the desired compression setting from the drop-down menu. Valid choices are zlib and none.

Compression is disabled by default.



Tunnel using profile

Use this drop-down list to select a profile for creating a nested tunnel.

Terminal answerback

Use this drop-down list to select the desired terminal answerback.

Defining Authentication

On the Authentication tab, you can define the user authentication methods for the profile.

Figure 4.10. Configuring authentication methods for the profile

To add a new authentication method to the list, click Add and select the method from the drop-down menu.

To remove an authentication method, select a method from the list and click Delete.

Use the arrow buttons to organize the preferred order of the authentication methods. The first method that is

allowed by the Secure Shell server is used. Note that in some cases, the server may require several authentic-

ation methods to be passed before allowing login.

Possible methods for user authentication are the following:

• Password: Use a password for authentication.

• Public-key: Use public-key authentication. See also Section 4.1.6.


69

• Keyboard-interactive: Keyboard-interactive is designed to allow the Secure Shell client to support sev-

eral different types of authentication methods, including RSA SecurID, and PAM. For more information

on keyboard-interactive, see Section 6.7.

• GSSAPI: GSSAPI (Generic Security Service Application Programming Interface) is a common security

service interface that allows different security mechanisms to be used via one interface. For more inform-

ation on GSSAPI, see Section 6.8.

Defining Ciphers

On the Ciphers tab, you can define the encryption algorithms used for the profile.

Figure 4.11. Defining a cipher list for the profile

Select the Use Defaults check box to use the algorithms defined on the Defaults page (Section 4.1.2.2), or

define a cipher list using the arrow buttons. The ciphers are tried in the order they are specified.

Defining MACs

On the MACs tab, you can configure the message integrity algorithms used for the profile.



Figure 4.12. Defining a MAC list for the profile

Select the Use Defaults check box to use the algorithms defined on the Defaults page (Section 4.1.2.3), or

define a MAC list using the arrow buttons. The MACs are tried in the order they are specified.

Defining Advanced Connection Settings

On the Server tab, you can define advanced server connection settings for the profile.


71

Figure 4.13. Defining server connection settings for the profile

Use Defaults

Select the check box to use the values defined on the Defaults page (Section 4.1.2.4) for the server con-

nection settings.

Transport distribution

This settings define the number of transport channels used by the Secure Shell connection. Using more

than one transport may increase the throughput over low bandwidth connections. Currently, a value of 1

to 8 transports is supported. The default is 2 transports.

Connection timeout

This setting specifies how long idle time (after all connection channels are closed) is allowed for a con-

nection before automatically closing the connection. The default is 5 seconds. Setting a longer time allows

the connection to the server to remain open even after a session (for example, GUI client) is closed.

During this time, a new session to the server can be initiated without re-authentication. Setting the time

to 0 (zero) terminates the connection immediately when the last channel to the server is closed.

Show server banner

Select the check box if you want to have the server banner message file (if it exists) visible to users before

login.



Defining Proxy Settings

On the Proxy tab, you can select proxy settings for the profile.

Figure 4.14. Defining proxy settings for the profile

No proxy

Select this option if you do not want to use a proxy.

Use proxy rules

Select this option to use the proxy rules defined in the General settings Proxy page (Section 4.1.3).

Specify proxy for this profile only

Click Add... to add a new proxy definition for this profile.

Figure 4.15. Defining alternate proxy for the profile


73

Select the Type of the rule. The type can be Direct, Socks4, Socks5, or Http.

For other types than direct, enter the proxy server Address and Port.

Defining Tunneling (SSH Tectia Client)

Tunneling, or port forwarding, is a way of forwarding otherwise unsecured TCP traffic through an encrypted

Secure Shell tunnel. You can secure for example POP3, SMTP, and HTTP connections that would otherwise

be unsecured.

Note

The client-server applications using the tunnel will carry out their own authentication procedures

(if any) the same way they would without the encrypted tunnel.

Tunneling settings are configured using the Tunneling tab. Any changed tunneling settings will take effect

the next time you log in.

Figure 4.16. Defining SSH Tectia Client tunneling

The local (outgoing) and remote (incoming) tunnel settings are configured using the Local tunnels and Remote

tunnels tabs of the Tunneling tab.



Local Tunnels

Local tunnels protect TCP connections that your local computer forwards from a specified local port to the

specified port on the remote host computer you are connected to.

It is also possible to forward the connection beyond the remote host computer. However, the connection is

encrypted only between the client (local computer) and the Secure Shell server.

Click the Local tunnels tab to edit outgoing tunnel definitions.

To add a new local tunnel, click Add. The Local Tunnel dialog box opens.

Figure 4.17. Defining a local tunnel

The following fields are used to define a local tunnel:

• Type: Select the type of the tunnel from the drop-down list. Valid choices are TCP and FTP. If you are

tunneling an FTP connection, set the tunnel type as FTP. For other protocols, set the tunnel type as TCP.

Note

If the Secure Shell server and the FTP server are located on different computers, FTP tunneling

works only if FTP is set to run in passive mode. If the Secure Shell server and the FTP server

are located on the same computer, tunneling works regardless of whether FTP is running in

passive or active mode. For more information on tunneling FTP, see Section 8.3.

• Listen port: This is the number of the local port that the tunnel listens to, or captures.

Note

The protocol or application that you wish to create the tunnel for may have a fixed port number

(for example 143 for IMAP) that it needs to use to connect successfully. Other protocols or ap-

plications may require an offset (for example 5900 for VNC) that you will have to take into an

account.


75

• Allow local connections only: Select this option if you want to allow only local connections to be made.

This means that other computers will not be able to use the tunnel created by you. By default, only local

connections are allowed. This is the right choice for most situations. You should carefully consider the

security implications if you decide to also allow outside connections.

• Destination host: This field defines the destination host for the tunneling. The default value is localhost.

Note

The destination host is resolved by the Secure Shell server after the Secure Shell connection has

been established, so here localhost refers to the Secure Shell server host you are connecting

to.

• Destination port: The destination port defines the port that is used for the forwarded connection on the

destination host.

To edit a tunnel definition, select a tunnel from the list and click Edit. The Local Tunnel dialog opens.

To delete a tunnel definition, select a tunnel from the list and click Delete to remove a tunnel. Note that the

selected tunnel will be removed immediately, with no confirmation dialog.

For more information on local tunnels, see Section 8.1.

Remote Tunnels

Remote tunnels protect TCP connections that the remote host forwards from a specified remote port to the

specified port on your local computer.

Click the Remote tunnels tab to edit incoming tunnel definitions. Click Add... to open the Remote Tunnel

dialog box.

Figure 4.18. Defining a remote tunnel

The following fields are used to define a remote tunnel:



• Type: Select the type of the tunnel from the drop-down list. Valid choices are TCP and FTP. For more

information on FTP tunneling, see Section 8.3.

• Listen port: The port that the tunnel listens to, or captures from the remote host computer.

Note

Privileged ports (below 1024) can be forwarded only when logging in with root privileges on

the remote host computer.

• Destination host: This field defines the destination host for the port forwarding. The default value is

localhost.

Note

Here localhost refers to your local computer. Also note that if the connection from the remote

host computer is forwarded beyond your local computer, that connection is unsecured.


destination host.

To edit a tunnel definition, select a tunnel from the list and click Edit. The Remote Tunnel dialog opens.

To delete a tunnel definition, select a tunnel from the list and click Delete to remove a tunnel. Note that the

selected tunnel will be removed immediately, with no confirmation dialog.

For more information on remote tunnels, see Section 8.2.

X11 Tunneling

SSH Tectia Client can securely tunnel (forward) X11 graphic connections from the remote host computer to

an X Windows server running on the local computer.

Note

You must also be running an X emulator such as eXceed or Reflection X in passive mode on the

Windows computer for X11 tunneling to work.

To tunnel (forward) X11 traffic, do the following:

1. Install an X server (X emulation) program on Windows (eXceed, Reflection X, or the like).

2. Start SSH Tectia Client.

3. Select the Tunneling tab of the Connection Profiles page and make sure that the Tunnel X11 connections

check box is selected.


77

4. Save your settings for SSH Tectia Client.

5. Quit the client, start it again and log into the remote host.

6. Start the X server (X emulation) program.

7. To test the tunneling, run xterm or xclock from SSH Tectia Client.

For more information, see Section 8.4.

Defining Color Settings (SSH Tectia Client)

The colors used in the SSH Tectia Client terminal window can be selected using the Colors page.

The color settings can be defined either globally or per profile. When colors are defined in SSH Tectia Client

Global Settings, the Use Global Colors option is not available, but the color settings will affect all connection

profiles. See Section 5.1.3.

Figure 4.19. Defining SSH Tectia Client terminal colors

• Use Global Colors: Select the Use Global Colors check box if you want to use the same color settings

for each connection. If the check box is selected, you cannot specify different color settings for each

connection profile (the other color settings are grayed out).



Text Colors

The text colors affect the terminal window background color and the color of text in both a connected window

and a disconnected window.

• Foreground: Select the desired foreground color from the drop-down menu. Foreground color is used

for text in a window that has a connection to a remote host computer. You can select from sixteen colors.

Black is the default foreground color.

• Background: Select the desired background color from the drop-down menu. You can select from sixteen

colors. White is the default background color.

• Selection: Use the drop-down menu to select the color that is used as the background color when selecting

text with the mouse. You can select from sixteen colors. Aqua is the default selection color.

• Disconnected: Use the drop-down menu to select the color that is used as the foreground color in a ter-

minal window that has no connection to a remote host computer. You can select from sixteen colors. Gray

is the default foreground color for a disconnected terminal window.

Cursor Color

Select the desired cursor color from the drop-down menu. You can select from sixteen colors. Navy is the

default cursor color.

ANSI Colors

With ANSI control codes it is possible to change the color of text in a terminal window. With the ANSI Colors

setting you can select to use this feature. Even if you disable ANSI colors, you can still select your favorite

text and background colors to be used in the terminal window.

• Enable ANSI Colors: Select this check box to allow ANSI colors to be used in the terminal window. By

default, ANSI colors are selected.

Reverse Colors

By reversing the display colors you can quickly change the display from positive (dark on light) to negative

(light on dark) to improve visibility.

• Reverse Video: Select this check box to change the foreground color into background color and vice

versa. This setting affects the whole terminal window when you click OK.

Defining Keyboard Settings (SSH Tectia Client)

The keyboard settings used for the SSH Tectia Client terminal are configured using the Keyboard tab. Keyboard

mappings take effect when you start a new connection or reset the terminal.


79

Figure 4.20. Defining SSH Tectia Client keyboard settings

• User Defined Keymap File: With this option you can create additional keyboard shortcuts or modify the

existing ones. The additional key mappings are saved into a separate file with the .sshmap file extension.

The current keymap file is displayed in the text field.

You can modify the current key mappings by clicking Edit to open the Keymap Editor dialog.

If you have defined an alternative keymap settings file, you can load it by typing the path and file name

in the text field, or by clicking on the button on the right-hand side of the text field. Clicking the button

will open an Open dialog that allows you to locate an alternative keymap file.

• Backspace sends Delete: Select the Backspace sends Delete check box if you want to map the Backspace

key to the Delete operation.

• Delete Sends Backspace: Select the Delete Sends Backspace check box if you want to map the Delete

key to the Backspace operation.

• Enter sends CR + LF: Select the Enter sends CR + LF check box if you want to map the Enter key to

send the carriage return (CR) and line feed (LF) characters. Otherwise only the line feed character will

be sent.

• Lock Function Keys: Select the Lock Function Keys check box if you want to lock the function keys.



• Line Wrap: Select the Line Wrap check box if you want the text lines to wrap at the terminal window

edge. By default, line wrapping is on.

• Use Alt as meta key (send Escape): Select the Use Alt as meta key (send Escape) check box if you want

the Alt key to function as the meta key in the same way as the Escape key. If this option is selected, you

can for example press the Alt+X key combination to simulate the Escape followed by X.

• Keypad Mode: Select how you want the numeric keypad on the right-hand side of the regular keyboard

to function.

Numeric Keypad: The keypad is used to type numbers.

Application Keypad: The keypad is used for application control (with the keypad keys functioning as

cursor keys, Home, End, Page Up, Page Down, Insert and Delete).

Defining File Transfer Settings (SSH Tectia Client)

The File Transfer tab affects which files are transferred using ASCII mode.

Figure 4.21. Defining SSH Tectia Client file transfer settings

ASCII transfer with old servers

Detect Windows server from the version string: Secure Shell client and server exchange version strings

when setting up the connection. Select this check box to automatically detect Windows servers and use the


81

correct setting for them. For this feature to work correctly, the Windows server has to specify "windows" in

its version string.

• Unix: Select the Unix check box to use Unix compatible line breaks (LF).

• Windows: Select the Windows check box to use Windows compatible line breaks (CRLF).

• Ask before ASCII transfer: If you select this check box, the client will ask you to specify the server type

before each ASCII file transfer.

Defining Favorite Folders (SSH Tectia Client)

In the Favorites Folders tab, you can create a list of commonly used remote directories. These favorites can

then be easily selected from a drop-down menu in the file transfer window.

Figure 4.22. Defining favorite remote folders for file transfer

Favorite Folders

This list contains the favorite folders you have defined for the current connection profile. You can add, remove,

and sort the favorites by using Add..., Delete, and the arrow buttons below the list.

If you are defining a remote favorite that is located on a Windows Secure Shell server, the folder on the

Windows server must be specified as follows: /drive/folder/subfolder.



A valid favorite folder definition would be, for example:

/C/Documents and Settings/All Users/Desktop

Home Folder

In the Home Folder field you can type the directory where any new SFTP connections associated with this

profile will start. If you leave the field empty, new connections will use the remote home folder that has been

specified for your user account on the remote host computer.

4.1.6 Defining User Authentication

Under User Authentication, you can configure settings related to public-key and certificate authentication.

See Section 4.1.6.1 and Section 4.1.6.2.

To enable or disable public-key authentication, see Section 4.1.2 and Section 4.1.5.2.

Managing Keys and Certificates

On the Keys and Certificates page, you can add key and certificate files used in user authentication, generate

a new key, upload a key to a server, or change the passphrase for a key.

Figure 4.23. Defining keys and certificates


834.1.6 Defining User Authentication

Default keys

The default location of user keys.

Default certificates

The default location of user certificates.

Directories

Use the Add... button to add a directory of keys, Delete to remove.

Files

Select a key from the list and click Change passphrase... to change the passphrase.

Click Upload... to upload the key to a server. See Section 6.4.4.

Click New key... to start the key generation wizard. See Section 6.4.3.1.

Use the Add... button to add single keys and certificates, Delete to remove.

Note

The user-specific Application Data directory is hidden by default. To view hidden directories,

change the setting in Windows Explorer. For example, on Windows XP, select Tools → Folder

Options on the menu, click the View tab, and select Show hidden files and folders.

Managing Key Providers

On the Key Providers page you can define the settings of external key providers used in user authentication.

Available key providers are MSCAPI, Entrust, and PKCS#11.



Figure 4.24. Defining key providers

Microsoft Crypto API

SSH Tectia Client and Connector can access keys via Microsoft Crypto API (MSCAPI). MSCAPI is a

standard cryptographic interface used in Microsoft Windows systems.

Microsoft Crypto API (MSCAPI) providers can be enabled by selecting the Enable Microsoft Crypto

API check box. If you enable the MSCAPI providers, you can use software keys and certificates created

by Microsoft applications.

You can also select the polling interval (in milliseconds) for MSCAPI. If 0 (zero) is selected, the Connec-

tion Broker will not poll MSCAPI, but will wait for system notifications instead.

Entrust

Select the Enable Entrust check box to enable using Entrust.

Enter the Initialization file (*.ini) and Profile file (*.epf).

By using the Entrust provider, SSH Tectia Client and Connector can utilize keys and certificates stored

in an Entrust profile file (.epf). The initialization file includes the basic Entrust PKI configuration (for

example the CA address).


85

When the provider is enabled for the first time, Entrust Entelligence will prompt for your Entrust password.

As long as the Entrust provider is enabled, the password is asked each time SSH Tectia Client/Connector

is started.

PKCS#11

By using the PKCS#11 provider, SSH Tectia Client and Connector can use keys and certificates stored in

PKCS#11 tokens (for example, smart cards or USB tokens).

Click Add... to define a PKCS#11 provider.

Figure 4.25. Defining a PKCS#11 provider, Aladdin eToken DLL path shown as an example

Dynamic library

Define a dynamic library containing the PKCS#11 driver.

Slots

Define slots. A slot is a logical reader that potentially contains a token. Slots are manufacturer-specific.

They are defined with an integer. Examples: "0,1", "0-3, !2", "2".

4.1.7 Defining Server Authentication

Under Server Authentication, you can define server authentication settings as described in Section 4.1.7.1,

Section 4.1.7.2, and Section 4.1.7.3.

Managing Keys

On the Keys page, you can manage the known server host keys.



Figure 4.26. Defining server host keys settings

Click Add... to add keys from a directory, Delete to remove.

For more information on server host keys, see Section 6.1.

Managing CA Certificates

On the Certificates page, you can manage trusted CA certficates.

For more information on server certificate authentication, see Section 6.2.


87

Figure 4.27. Defining CA certificates

The following fields are displayed on the CA certificate list:

• Issued to: The certification authority to whom the certificate has been issued.

• Issued by: The entity who has issued the CA certificate.

• Expiration date: The date that the CA certificate will expire.

• Filename: The file containing the CA certificate.

CRL Checking

Select the Disable check box to prevent the use of a certificate revocation list (CRL). A CRL is used to check

if any of the used server certificates have been revoked.

Note

Disabling CRL checking is a security risk and should be done for testing purposes only.

OCSP responder URL

The OCSP Responder Service provides client applications a point of control for retrieving real-time information

on the validity status of certificates using the Online Certificate Status Protocol (OCSP).



For the OCSP validation to succeed, both the end-entity (=Secure Shell server) certificate and the OCSP re-

sponder certificate must be issued by the same CA. If the certificate has an Authority Info Access extension

with an OCSP Responder URL, it is only used if there are no configured OCSP responders. It is not used if

any OCSP responders have been configured.

If an OCSP responder is defined in the configuration file or in the certificate, it is tried first; only if it fails,

traditional CRL checking is tried, and if that fails, the certificate validation returns a failure.

Enable endpoint identity check

Specifies whether the client will verify the server's hostname against the Subject Name or Subject Alternative

Name (DNS Address) in the server's certificate.

If this check box is not selected, the fields in the server host certificate are not verified and the certificate is

accepted based on validity period and CRL check only. Note that this is a possible security risk, as anyone

with a certificate issued by the same trusted CA that issues the server host certificates can perform a man-in-

the-middle attack on the server if a client has the endpoint identity check disabled.

Enable DOD PKI compliancy

This element defines whether the certificates are required to be compliant with the DoD PKI (US Department

of Defense Public-Key Infrastructure).

Endpoint domain

Specify the default domain used in the end-point identity check. This is the default domain part of the remote

system name and it is used if only the base part of the system name is available.

If the default domain is not specified, the end-point identity check fails, for example, when a user tries to

connect to a host "tower" giving only the short hostname and the certificate contains the full DNS address

"tower.example.com".

HTTP proxy URL

Specify the HTTP proxy used when making LDAP or OCSP queries for certificate validity.

The format of the address is "http://username@proxy_server:port/network/netmask,network/net-

mask... ". The network/netmask part is optional and defines the network(s) that are connected directly

(without the proxy).

SOCKS server URL

Specify the SOCKS server used when making LDAP or OCSP queries for certificate validity.

The format of the address is "socks://username@socks_server:port/network/netmask,network/net-

mask... ". The network/netmask part is optional and defines the network(s) that are connected directly

(without the SOCKS server).


89

Managing LDAP Settings

On the LDAP Servers page, you can define LDAP servers used for fetching CRLs and/or subordinate CA

certificates based on the issuer name of the certificate being validated.

CRLs are automatically retrieved from the CRL distribution point defined in the certificate to be verified if

the point exists.

Figure 4.28. Defining LDAP servers

To add an LDAP server, click the Add... button. Define the hostname and port for the server.

Figure 4.29. Adding an LDAP server

To edit an LDAP server, select the server from the list and click Edit.

To delete an LDAP server, select the server from the list and click Delete.



4.1.8 Defining SSH Tectia Connector Settings (SSH Tectia Connector)

SSH Tectia Connector settings are defined entirely in the SSH Tectia Configuration tool. See Section 4.1.8.1

and Section 4.1.8.2.

Defining General Settings for Connector

On the General page, you can define general settings for SSH Tectia Connector.

Figure 4.30. Defining general settings for SSH Tectia Connector

Defining Applications for Pass-Through

Applications that are passed through are defined in the General Settings view.

• Select the Pass-through when engine down check box to have connections passed through when the

SSH Tectia Connector engine is not operational. This option can be activated if it is necessary to tempor-

arily deactivate SSH Tectia Connector so that it does not block network communications. If users should

only access the network using secure communications, leave this option disabled.

• Use the Pass-through apps text box to enter the process names of the applications that are allowed to

pass through. Comparing the application name to the applications listed in this field is case-insensitive.

The process names should include the file extension (the correct name format can be checked from Windows


914.1.8 Defining SSH Tectia Connector Settings (SSH Tectia Connect-

or)

Task Manager). Use commas to separate entries, for example: ssh-client-g3.exe,nslook-

up.exe,ping.exe

The pass-through settings are not stored in the ssh-broker-config.xml file but directly in the Windows

Registry, under HKEY_LOCAL_MACHINE\SOFTWARE\SSH Communications Security\SSH Tectia Con-

nector

Defining Pseudo IPs

Pseudo IP numbers are used when accessing an internal network from the outside because name resolution

for the machines in the internal network is not available from the outside. If specified in the filter rule, pseudo

IP numbers are used when an IP address cannot be resolved by the Connection Broker. In this case, SSH

Tectia Server resolves the real IP address.

Specify an IP address (using the dotted decimal notation) in the Pseudo IP start text box. This address is

used as the base for the pseudo IP addresses that will be generated for connections.

Settings

When the Show security notification check box is selected, a notification is briefly displayed when a new

application is secured. A list of currently tunneled applications is shown in the Connector icon tray menu.

Figure 4.31. Security notification

Select the Enable Connector check box to use Connector. The text Connector enabled is shown in the tray

menu. When SSH Tectia Connector is enabled, it can be temporarily disabled from the tray menu by clicking

the Connector enabled menu command. To disable Connector also in the future sessions, clear the Enable

Connector check box.

Defining Filter Rules

On the Filters page, you can define the SSH Tectia Connector filter rules.



Figure 4.32. Filter rules

Type an application name in the Application to tunnel field or click Browse... to locate an application.

Click the Add... button to define a new filter rule in the Filter Rule dialog box. Click Edit... to modify and

Delete to remove.

Figure 4.33. Defining a filter rule


93

• Any host or IP address: The rule is used for all addresses.

• Hostname: The rule is used for connections to the defined DNS address(es). The engine will resolve the

IP address using a DNS query. This value can be a regular expression. See Appendix B.

• IP address: The rule is used for connections to the defined IP address(es). This value can be a regular

expression. See Appendix B.

• Ports: Select a single port or a port range and define port numbers for the captured connections. If this is

undefined, the rule will be used for all ports.

• Action: Select one of the following:

DIRECT

The connection is made directly to the host without tunneling, using the host's IP address if it can be

resolved. If it cannot be resolved, the connection fails.

BLOCK

The connection is blocked. Applications usually inform the user that the connection is refused.

TUNNEL

The connection is tunneled through the selected profile. If the connection is made using a DNS name,

the tunnel is created with the DNS name. This means that the actual DNS name resolution is done at

the remote end, which enables tunneling connections to hosts that are not visible to the local machine.

If the port does not match a port or port range, the connection is direct.

• Select a server profile to tunnel through from the second drop-down list.

• Fall back to DIRECT if secure connection cannot be established: If creating the tunnel fails (or the

connection to the Secure Shell server fails) the Connection Broker will normally return a "host not

reachable" error. However, when this check box is selected a direct (unsecured) connection is used instead.

• Use pseudo IP: When this check box is selected and a captured application attempts connection using a

hostname, SSH Tectia Connector assigns a pseudo IP address for the host instead of doing a DNS query.

When the check box is not selected, a normal DNS query is made.

The fallback and pseudo IP options cannot be enabled at the same time. If they are, and the secure connec-

tion fails, the application will try a direct connection with the pseudo IP, which will not work.

When an application connects to a host, filters are used to determine the correct action to apply to the connec-

tion. The filter list is scanned through to find a filter that matches the connection. The first matching filter is

used. Filters are evaluated from top down. Use the arrow buttons to organize the list.



4.1.9 Defining FTP-SFTP Conversion Rules (SSH Tectia Client with EFT

Expansion Pack)

On the FTP-SFTP Conversion page, you can define the filter rules used for FTP-SFTP conversion.

Figure 4.34. Defining an FTP-SFTP conversion rule

Type the name of your FTP application in the Application to capture field or click Browse... to locate an

application.

Click the Add... button to define a new filter rule in the Filter Rule dialog box. Click Edit... to modify and

Delete to remove.


954.1.9 Defining FTP-SFTP Conversion Rules (SSH Tectia Client with

EFT Expansion Pack)

Figure 4.35. Defining a filter rule

• Any host or IP address: The rule is used for all addresses.

• Hostname: The rule is used for connections to the defined DNS address(es). The engine will resolve the

IP address using a DNS query. This value can be a regular expression. See Appendix B.

• IP address: The rule is used for connections to the defined IP address(es). This value can be a regular

expression. See Appendix B.

• Ports: Select a single port or a port range and define port numbers for the captured connections. If this is

undefined, the rule will be used for all ports.

• Action: Select one of the following:

DIRECT

The connection is made directly to the host without tunneling, using the host's IP address if it can be

resolved. If it cannot be resolved, the connection fails.

BLOCK

The connection is blocked. Applications usually inform the user that the connection is refused.

FTP-PROXY

The FTP-SFTP connection is made to the Secure Shell server specified in the profile.

• Select a server profile for the FTP-SFTP connection from the second drop-down list.

To allow the FTP client application to specify the SFTP server to be connected, you can create a profile

with * (an asterisk) as the hostname and select that profile here. See Section 4.1.5.1.



• Fall back to DIRECT if secure connection cannot be established: If creating the SFTP connection

fails, the Connection Broker will normally return a "host not reachable" error. However, when this check

box is selected a direct (unsecured) FTP connection is used instead.

• Use pseudo IP: When this check box is selected and the FTP application attempts connection using a

hostname, the Connection Broker assigns a pseudo IP address for the host instead of doing a DNS query.

When the check box is not selected, a normal DNS query is made.

Pseudo IPs cannot be used if the connection profile does not specify the SFTP server (it has * as the

hostname).

The fallback and pseudo IP options cannot be enabled at the same time. If they are, and the secure connec-

tion fails, the application will try a direct connection with the pseudo IP, which will not work.

When an application connects to a host, filters are used to determine the correct action to apply to the connec-

tion. The filter list is scanned through to find a filter that matches the connection. The first matching filter is

used. Filters are evaluated from top down. Use the arrow buttons to organize the list.

4.1.10 Defining Static Tunnels

On the Static Tunnels page, you can create listeners for local tunnels automatically when the Connection

Broker starts up. The actual tunnel is formed the first time a connection is made to the listener port. If the

connection to the server is not open at that time, it will be opened automatically as well.


974.1.10 Defining Static Tunnels

Figure 4.36. Static tunnels

Select Static Tunnels in the tree menu and click Add... to open the Static Tunnel dialog box.

Figure 4.37. Defining a static tunnel

• Type: Select the type of the tunnel from the drop-down list. Valid choices are TCP and FTP.

• Listen port: This is the number of the local port that the tunnel listens to, or captures. Do not use a reserved

port number.



Note

The protocol or application that you wish to create the tunnel for may have a fixed port number

(for example 143 for IMAP) that it needs to use to connect successfully. Other protocols or ap-

plications may require an offset (for example 5900 for VNC) that you will have to take into an

account.

• Allow local connections only: Leave a check mark in this box if you want to allow only local connections

to be made. This means that other computers will not be able to use the tunnel created by you. By default,

only local connections are allowed. This is the right choice for most situations. You should carefully

consider the security implications if you decide to also allow outside connections.

• Destination host: This field defines the destination host for the port forwarding. The default value is

localhost.

Note

The value of localhost is resolved after the Secure Shell connection has been established, so here

localhost refers to the remote host computer you have connected to.


destination host.

• Tunnel using profile: Select the server to use for the tunnel.

To edit a static tunnel, select a tunnel from the list and click Edit.

To delete a static tunnel, select a tunnel from the list and click Delete.

For more information on tunneling, see Section 8.1.


99



Chapter 5 Configuring SSH Tectia Client GUI

(Windows)

Before establishing a connection to a remote host computer, you should first check your connection settings.

The connection settings can be changed by using SSH Tectia Configuration tool.

SSH Tectia Configuration tool can be used to configure the profile settings that are associated with a single

remote host computer. With the Settings dialog you can control also the global settings that affect all connec-

tions.

To open the Settings dialog, click the Settings button on the toolbar, or select the Edit → Settings option.

The different settings categories are visible on the left-hand side of the Settings dialog as a tree structure.

Click on a branch to display the settings associated with it. You can change the settings by changing the se-

lections displayed on the right-hand side of the Settings window. Note that some of the settings do not take

effect until you save the settings and then open a new terminal or file transfer window, or start a new connection.

5.1 Defining Global Settings

Global configuration settings are configured using the Global Settings page of the Settings dialog. Global

settings are common for all connections to remote host computers.

Global settings are saved at the same time as profile settings. Global settings are always saved in the user

profile directory with the filename global.dat.


101

Figure 5.1. The Global Settings page of the Settings dialog

5.1.1 Defining the Appearance

The appearance of the application and the terminal window is configured using the Appearance page of the

Settings dialog.


Configuring SSH Tectia Client GUI (Windows)102

Figure 5.2. The Appearance page of the Settings dialog

Office XP Look

Select the Office XP Look check box to change the way the menu bar and toolbar are displayed to match

the visual style of Microsoft Office XP.

Terminal Settings

With the Terminal settings options you can define how the terminal window works.

Paste on Right Mouse Click

Select the Paste Selection on Right Mouse Click check box to enable fast copying of text on the terminal

display. When you have this option selected, you can copy text simply by highlighting it and then paste

it by clicking the right mouse button.


103

Scroll to Bottom on Output

Select the Scroll Bottom on Output check box to have the terminal window scroll to the bottom

whenever new text is output. If this option is not selected, you can view the terminal window without the

windows scrolling to the bottom every time a new line of text is displayed. By default, this option is on.

Scrollback Buffer Size

Type in the Terminal Scrollback Size field the number of lines that you want to collect into the scrollback

buffer. The larger the value, the more you can scroll back the terminal display to view previous terminal

output. The default value is 500 lines.

Open URLs on click

When this check box is selected, links in the terminal window can be opened by clicking them. This option

is selected by default.

Window Caption

The Window caption settings affect what is displayed in the title bar of the terminal window and the file

transfer window.

Display profile or host name

Select this check box to have the profile name of the currently connected remote host computer displayed

on the title bar if a profile is used. If a profile is not used, the hostname is displayed.

Window Layout

If you have created a connection profile with several windows open at the same time and saved the layout,

all of the windows associated with the profile are normally opened when you select the profile. With the

Window layout option you can override this behavior.

Open all windows of the profile

Select the Open all windows in the profile check box to open all the windows associated with a profile

when the profile is selected. If this option is not selected, the other windows open in their configured

positions when you open new windows. By default, this option is on.

5.1.2 Selecting the Font

The font used in the terminal window can be selected using the Font page of the Settings dialog. The new

font setting affects the terminal window immediately when you click OK To discard the changes, click

Cancel.



Figure 5.3. The Font page of the Settings dialog

Font Name

Select the desired font from the Font Name list. The list displays the non-proportional (fixed-width)

fonts installed in your local computer. Note that proportional fonts are not suitable for the terminal window

and therefore are not available for selection.

Font Size

Select the desired font size from the Font Size list. Note that the font size affects the size of the terminal

window: the smaller the selected font, the smaller the terminal window. However, after changing the font

size, the size of the terminal window can be modified.

5.1.3 Selecting Colors

The colors used in the terminal window can be selected using the Colors page of the Settings dialog. The

new color settings are active immediately when you click OK.


1055.1.3 Selecting Colors

The color settings defined in Global Settings affect all connection profiles.

Note that changing the terminal colors does not affect what is already visible in the terminal window, but

from this point onwards the text output will use the selected color scheme.

Figure 5.4. The Colors page of the Settings dialog

Text Colors

The text colors affect the terminal window background color and the color of text in both a connected window

and a disconnected window.

Foreground

Select the desired foreground color from the drop-down menu. Foreground color is used for text in a

window that has a connection to a remote host computer. You can select from sixteen colors. Black is

the default foreground color.



Background

Select the desired background color from the drop-down menu. You can select from sixteen colors. White

is the default background color.

Selection

Use the drop-down menu to select the color that is used as the background color when selecting text with

the mouse. You can select from sixteen colors. Aqua is the default selection color.

Disconnected

Use the drop-down menu to select the color that is used as the foreground color in a terminal window

that has no connection to a remote host computer. You can select from sixteen colors. Gray is the default

foreground color for a disconnected terminal window.

Cursor Color

Select the desired cursor color from the drop-down menu. You can select from sixteen colors. Navy is the

default cursor color.

ANSI Colors

With ANSI control codes it is possible to change the color of text in a terminal window. With the ANSI Colors

setting you can select to use this feature. Even if you disable ANSI colors, you can still select your favorite

text and background colors to be used in the terminal window.

Enable ANSI Colors

Select this check box to allow ANSI colors to be used in the terminal window. By default, ANSI colors

are selected.

Reverse Colors

By reversing the display colors you can quickly change the display from positive (dark on light) to negative

(light on dark) to improve visibility.

Reverse Video

Select this check box to change the foreground color into background color and vice versa. This setting

affects the whole terminal window when you click OK.

5.1.4 Defining Messages

On the Messages page of the Settings dialog you can configure default replies to standard messages that

normally ask for user confirmation. The messages are listed under several categories.


1075.1.4 Defining Messages

Figure 5.5. Specifying which confirmation dialogs are displayed

Each confirmation can be set to automatically accept (Yes) or reject (No) the action, or to ask the user for

confirmation (Ask). By default all messages ask the user to confirm the action.

5.1.5 Defining File Transfer Settings

The default file transfer settings can be configured using the File Transfer page of the Settings dialog. The

new settings will affect subsequently started file transfer windows.



Figure 5.6. The global File Transfer page of the Settings dialog

Options

Show Root Directory

Select the Show Root Directory check box to show the root directory in the file transfer window by default.

Show Hidden Files

Select the Show Hidden Files check box to show hidden files in the file transfer window by default.

Check and Confirm Overwrite

Select the Check and Confirm Overwrite check box if you want the file transfer utility to ask for con-

firmation when you try to transfer a file that already exists in the target system.


109

Display Items by Using

With the Display Items by Using setting you can select the default view for the file transfer window by

choosing one of the four possible views.

Large Icons

Select this option to display the file transfer file view as a Large Icons view. Each file and folder has a

large icon associated with it, making for a clear and uncluttered display.

Small Icons

Select this option to display the file transfer file view as a Small Icons view. Each file and folder has a

small icon associated with it. This makes it possible to display several times more items than the Large

Icons view.

List

Select this option to display the file transfer file view as a List view. Each file and folder has a small icon

associated with it, and the files and folders are displayed in one column.

Details

Select this option to display the file transfer folder view as a Details view. The files and folders are dis-

played with a small icon, their file name, file size, file type, their last modification date and attributes

visible.

By clicking on the Name, Size, Type, Modified and Attributes sort bars located at the top of the File

view, you can sort the files and folders based on their file name, file size, file type and the time they were

last modified. Clicking the same sort option again reverses the sorting order.

Note that the sort function is not case-sensitive: uppercase text is sorted together with lowercase text.

The file type associations are derived from your local computer. If you have defined a new file type de-

scription for files with a certain file name extension, also the files in the remote computer are shown to

be of that file type. This makes it easy to recognize particular file types also on the host computer.

If a file association is missing, use this application to open the file

SSH Tectia Client uses file type associations in the same way as Windows Explorer does. When you double-

click a file in the filet transfer window, it is opened using the application with which its file type has been

associated.

All file types are not associated with any application. With this field you can define the application to use to

open a file that has no file type association. The default application is Notepad, which is a reasonable choice

for files containing text.

To change the default association for unknown file types, click the button next to the text field. A Select Ap-

plication dialog is displayed, allowing you to select the desired application.



Formatting string for file time

In the formatting string field you can type a string that defines how the time and date stamps of the files are

displayed in the file transfer window. The default value is %c, which means that the date and time will be

shown in the format defined in the Windows country settings (locale).

To change the format of the time and date stamps, replace the default value with a string consisting of some

of the following character combinations.

%a

Abbreviated weekday name

%A

Full weekday name

%b

Abbreviated month name

%B

Full month name

%c

Date and time representation appropriate for locale

%d

Day of month as decimal number (01 - 31)

%H

Hour in 24-hour format (00 - 23)

%I

Hour in 12-hour format (01 - 12)

%j

Day of year as decimal number (001 - 366)

%m

Month as decimal number (01 - 12)

%M

Minute as decimal number (00 - 59)

%p

Current locale's A.M. / P.M. indicator for 12-hour clock

%S

Second as decimal number (00 - 59)


111

%U

Week of year as decimal number, with Sunday as the first day of week (00 - 53)

%w

Weekday as decimal number (0 - 6; Sunday is 0)

%W

Week of year as decimal number, with Monday as the first day of week (00 - 53)

%x

Date representation for current locale

%X

Time representation for current locale

%y

Year without century, as decimal number (00 - 99)

%Y

Year with century, as decimal number

%z, %Z

Time-zone name or abbreviation; no characters if time zone is unknown

%%

Percent sign

View Layout

You can select how the file transfer window positions the local and remote view panes. The following options

are available:

• Remote view on top, local view on bottom

• Remote view on right, local view on left

• Remote view on left, local view on right

• Wide folder view in file bar

Select this check box to show fewer buttons in the file bar, leaving more room for the favorite folders lists.

5.1.6 Defining Advanced File Transfer Options

On the Advanced page of the Settings dialog you can configure additional file transfer options. The new

settings will affect subsequently started file transfer windows.



Figure 5.7. The advanced file transfer options

Force Lowercase

Selecting this option forces lower case file names in file transfers.

Preserve Original File Time

Select the Preserve Original File Time check box if you want the transferred files to retain their original

time and date stamp values. If this option is not selected, the transferred files will be stamped with the

time of the transfer.

Upload

The following settings affect the upload process:


113

Do not change destination permissions

Select this check box to preserve the file permissions on the server. If the transferred file overwrites an

existing file, it will use the same file permissions as the original file. If the file is new, it will use the default

permission mask of the server target directory.

Clear this check box to force new file permissions on uploaded files. Define the permissions in New file

permissions and New directory permissions below.

New file permissions

Type the octal Unix file permission mask (as with the Unix chmod command) that is to be used as the

value for uploaded files. For more information on file permissions, see Section C.2.4.1.

New directory permissions

Type the octal Unix directory permission mask (as with the Unix chmod command) that is to be used as

the value for uploaded directories.

File Transfer Send Window

The following settings affect the file transfer process:

Number of Buffers

Type the number of buffers used in file transfer. The default value is 10.

Buffer size

Type the default buffer size (measured in kilobytes). The default value is 32 kilobytes.

Upload Locally Modified Remote Files

This selection affects how SSH Tectia Client reacts if you locally edit a file stored in the remote host computer.

Yes

If you select this option, the locally modified file is uploaded to the remote host computer.

No

If you select this option, the locally modified file is not uploaded to the remote host computer.

Ask

If you select this option, SSH Tectia Client asks you to decide if you want to upload a locally modified

file.

5.1.7 Defining File Transfer Mode

The Mode page of the Settings dialog affects which files are transferred using ASCII mode.



Figure 5.8. Selecting the file transfer mode

File Transfer Mode

Select the default file transfer mode from the following options:

ASCII

By default all files will be transferred in ASCII mode.

Binary

By default all files will be transferred in binary mode.

Auto Select

The files using a file extension specified on the ASCII Extensions list will be transferred in ASCII mode.

All other files will be transferred in binary mode.


115

ASCII Extensions

Files using a file extension specified in the ASCII Extensions list will be transferred using ASCII mode.

New

Click the New button (at the top right-hand side of the ASCII Extensions list) to add a new file extension

to the list. The keyboard shortcut for the New button is the Ins key.

Note that you can use wild cards to specify the file extensions. The ? character matches any 1 character,

and the * character matches any 0 or more characters. For example htm* would match both htm and html.

Delete

Select a file extension entry from the list and click the Delete button (at the top right-hand side of the

ASCII Extensions list) to remove the extension. The keyboard shortcut for the Delete button is the Delete

key.

5.1.8 Defining Local Favorites

On the Local Favorites page of the Settings dialog you can create a list of commonly used directories on

your local computer. These favorites can then be easily selected from a drop-down menu in the File Transfer

window.



Figure 5.9. Creating a list of most commonly used directories

Favorite Folders

This list contains the favorite folders you have defined for your local computer. Initially the list contains your

locally available drives. You can add, remove and sort the favorites by using the New, Delete, Up, and Down

icons displayed above the list.

Home Folder

In the Home Folder field you can type the directory that is initially displayed in the local view pane of the

file transfer window.

5.1.9 Defining Security Settings

The security settings can be configured using the Security page of the Settings dialog.


1175.1.9 Defining Security Settings

Figure 5.10. The Security page of the Settings dialog

Terminal Connections

Empty Clipboard on Exit

Select the Empty Clipboard on Exit check box to remove anything that was recently copied using the

cut and paste operations from the clipboard.

Empty Scrollback Buffer on Session Close

Select the Empty Scrollback Buffer on Session Close check box to empty any remains of the terminal

output from the scrollback buffer.

5.1.10 Printing

The print settings can be configured using the Printing page of the Settings dialog.



Figure 5.11. The Printing page of the Settings dialog

Printer Font

Select the Font Name and Font Size to be used in the printed output. Any non-proportional font installed

on your system can be selected.

Margins (mm)

Select the width of the blank border around the page in printed output. The margins for the top, bottom,

left and right side of the page can all be specified individually. The default value for all margins is 10

millimeters (or 1 centimeter).

Header & Footer

Select additional information to appear on the printed pages.

Title appears at the top left of the page and displays the title of the terminal window (for example remote-

host - SSH Tectia Client).


119

Date appears at the top right of the page and displays the date and time when the page was printed (for

example 15 September 2003, 11:10). The date and time format is the same as used in Windows.

Page Number appears at the bottom right of the page (for example Page 1 of 2).

Pass-Through Printing

Pass-through printing allows the server to print on a client printer using terminal emulation codes.

In raw mode, SSH Tectia Client sends the data to be printed as plaintext to the printer. In this mode,

printing for example line graphics does not work.

If not in raw mode, SSH Tectia Client sends the data to be printed to the printer as graphics. This is the

default setting and should be used if there are no problems in printing. However, some older printers

might not support printing graphics.

Use Raw Mode

Select this check box to pass the data to be printed to the printer in raw mode. If you experience printing

problems, select or clear this selection as applicable.

5.2 Using Command-Line Options

For some purposes it may be useful to operate the SSH Tectia Client GUI from the command line (command

prompt).

The command-line syntax for the SSH Tectia Client GUI (ssh-client-g3.exe) is the following:

ssh-client-g3 [-r] [-p port] [-u user] [-h host] [profile]

The meaning of the command-line parameters is the following:

-r

The -r option will reset all customizations made to the user interface (toolbars and menus). A confirmation

dialog is displayed.

-p [port_number]

The -p option specifies the port number used for the connection. If this option is not specified, the port

number defined in the default profile is used.

-u [user_name]

The -u option specifies the user name for the connection. If this option is not specified, the user name

defined in the default profile is used.

-h [host_name]

The -h option specifies the host name for the connection. If this option is not specified, the host name

defined in the default profile is used.



[profile]

If a profile is specified, it must be the last option on the command line. Any command-line parameters

override the profile settings. If no profile is specified, the default profile is used.

-f

The -f (or /f) option starts the default SFTP file transfer profile.

For example, the following command would immediately start a connection to a host called remotehost and

connect as guest. The port number is not specified, so the connection would use the port specified in the default

profile.

ssh-client-g3 -h remotehost -u guest

The following command would immediately start a connection to remotehost using the settings defined in

the profile file custom.ssh2.

ssh-client-g3 -h remotehost custom.ssh2

If the host is not specified (using the -h option) and no profile is specified, the login dialog opens, automatically

filled with the values specified on the command line.

For example, the following command would display the login dialog with the port number already defined

as 222 and guest as the user name.

ssh-client-g3 -u guest -p 222

Note

A pure command-line version of SSH Tectia Client is shipped with the Windows client. The com-

mand-line client sshg3.exe is a port of the Unix version of SSH Tectia Client, and may be useful

also in the Windows command-line environment, especially for creating scripts. For a more detailed

description of the sshg3.exe syntax, see sshg3(1).

Also several other command-line utilities are shipped with the Windows and command-line clients. For more

information, see Appendix A.

5.3 Customizing the User Interface

This section describes the options for modifying the graphical user interface.

5.3.1 Saving Settings

When you have made changes to the settings, an asterisk (*) is displayed on the SSH Tectia Client title bar,

after the name of the current settings file (for example: default*). This indicates that the changed settings

are not yet permanent - they have not been saved yet.


1215.3 Customizing the User Interface

If you want to make the changes permanent, you can save them for later use. Click the Save button on the

toolbar, or select the File → Save Settings to save any changes you have made to your current settings.

The default settings file is loaded automatically when you start the client. Therefore all the settings that you

save in the default settings file take effect immediately when you launch the client. These settings are also

used for connections started with the Quick Connect option (see Section 3.5).

The positions of the currently open terminal and file transfer windows can be saved separately with the File

→ Save Layout option. If you arrange your window positions and save the layout settings in the default settings

file, the windows will be automatically positioned the way you prefer them when you next start the client.

Note that by default all of the windows will be opened at once. This can be changed on the Appearance page

of the Settings dialog so that the defined windows are opened only when necessary when you open new ter-

minal and file transfer windows. See Section 5.1.1.

If you spend a lot of effort specifying the settings, it is a good idea to create backup copies of the modified

settings files (ssh-broker-config.xml, global.dat, and *.ssh2) and store them in a safe location. This

way you will not have to create your personal settings again if your settings files are lost (for example because

of a hardware failure).

Multiple Settings Files

You can save separate settings files for each remote host computer. This can be done by using the Profiles

option. For more information on using profiles, see Section 4.1.5.

5.3.2 Loading Settings

It is easy to take a previously saved profile into use. Select the Profiles option on the Profiles toolbar, or from

File → Profiles, and you will see a menu of previously saved profiles. Click on a profile name, and a connection

using the profile settings is started immediately.

Note that this also works when you are already connected to a remote host computer. Clicking the profile

name will start a new, separate connection.

Another way to load the settings for a particular connection is to double-click the settings file name for example

in Windows Explorer. When SSH Tectia Client is installed, files with the extension .ssh2 are associated with

SSH Tectia Client. This means that you can start SSH Tectia Client with any settings file loaded by double-

clicking the settings file.

If you regularly connect to several remote host computers, you can create shortcuts to the corresponding settings

files for example on the Windows desktop. This way you can quickly open the desired connection with the

relevant settings already defined, just by clicking on an icon on the desktop.



5.3.3 Customize Dialog

Select View → Customize to modify the menu options, toolbars layout, keyboard mapping, menu settings,

and general preferences. Note that you can have only one terminal window open when using the Customize

option.

Figure 5.12. Use the Customize dialog to modify the user interface settings

Click on the tabs at the top of the dialog to switch between different pages:

Commands tab

Select the Commands tab to move individual menu options. Select the menu category from the list on

the left, and then use the mouse to drag menu options into the menus or toolbars displayed in the SSH

Tectia Client window.

Toolbars tab

Select the Toolbars tab to define which toolbars are displayed in the SSH Tectia Client window.

• Reset: Select the toolbar that you want to restore to its initial settings and click the Reset button to

discard the changes you have made.

• Reset All: Click the Reset All button to discard the changes you have made to all of the toolbars.

• Show Text Labels: Select either the Profiles or the Toolbar option and then select the Show text

labels check box to display text labels on these toolbars. Text labels clarify the toolbar icons, but also

take up space.


1235.3.3 Customize Dialog

Keyboard tab

Select the Keyboard tab to define shortcut keys for the menu commands.

Use the Category menu to select the category of the accelerator key you want to modify. The categories

are based on the menu hierarchy.

Use the Commands menu to select a specific command from the selected category.

The Description box displays a brief description of the currently selected command.

Use the Set Accelerator for menu to select the profile that you want to associate with the current keyboard

configuration.

The Current Keys field shows the currently assigned accelerator keys.

Click on the Press New Shortcut Key field to activate it. Then press the combination of keys on the

keyboard that you want to associate with the currently selected command.

• Assign: Click Assign the add the definition from the Press New Shortcut Key field to the Current

Keys field.

• Remove: Select a key assignment from Current Keys field and click Remove to delete it.

• Reset All: Click Reset All to undo all your changes and reset the keyboard assignments. A confirm-

ation dialog will be displayed.

Menu tab

Select the Menu tab to define the menu settings.

• Application Frame Menus: Select the menu setup you want to change from the Show Menus For

drop-down menu. By default, only Default Menu is available for editing.

Click Reset to reset the menus to their original configuration.

• Use the Menu Animations drop-down menu to select the type of menu animations. The available

options are None, Unfold, Slide, and Fade.

• Select the Menu Shadows check box to display shadows under open menus.

• Context Menus: Use the Select Context Menu drop-down menu to display any of the shortcut (or

popup) menus:

• File Local Menu 1 is displayed in the local view of the file transfer window when you do not have

a file selected.

• File Local Menu 2 is displayed in the local view of the file transfer window when you have a file

selected.



• File Remote Menu 1 is displayed in the remote view of the file transfer window when you do not

have a file selected.

• File Remote Menu 2 displayed in the remove view of the file transfer window when you have a

file selected.

• Terminal Popup menu is displayed when you right-click in the terminal window.

You can click the Commands tab and drag menu options into the shortcut menus (and remove items

from the shortcut menus by dragging them from the menu).

• Reset: Click Reset to reset the menus to their original configuration.

Options tab

Select the Options tab to change general user- interface options.

Select the Show ScreenTips on Toolbars check box to display a short help text when you place the

mouse pointer over a toolbar button.

Select the Show Shortcut Keys in ScreenTips check box to see the possible keyboard shortcut displayed

in addition to the short help text.

Select the Large Icons check box to display large toolbar icons.

Select the Look 2000 check box to enable Windows-2000-style features in the user interface. This option

affects mainly the style of the toolbar handles.

Help

Click Help to display the online help.

Close

Click Close to stop customizing.

5.3.4 Customizing Toolbars

SSH Tectia Client has a dynamic user interface that is very easy to modify. You can select the position of the

toolbars, and even move individual buttons from one place to another.

Note

The File bar displayed in the file transfer window is dynamically created, and therefore it cannot be

customized.


1255.3.4 Customizing Toolbars

Moving Toolbars

You can use the mouse to grab the toolbars by their handles (located on the left-hand end of each toolbar)

and move them around the SSH Tectia Client window. You can have the toolbars floating freely in the window,

or anchor them to the top, bottom or even either side of the window.

Moving Toolbar Buttons

You can also move individual toolbar buttons around and arrange them so that they best serve your needs.

To move a toolbar button, keep the Alt key on the keyboard pressed down and grab a button with your mouse.

You will see a new mouse pointer appear. Click the button with your left mouse button, keep the mouse button

pressed down and move the button around. When you release the mouse button, the toolbar button will be

move to a new position.

Note

If you move a button somewhere else than a toolbar (for example, in the terminal window text area),

it is removed from the window. Changes become permanent even if you do not save the settings,

but you can undo the changes by selecting View → Reset Toolbars.

Permanent Toolbar Changes

If you have made changes to the toolbars, but change your mind and want to return the toolbars to their ori-

ginal positions, select View → Reset Toolbars to undo the changes. A confirmation dialog opens, asking if

you really want to discard the changes. If you select Yes, the toolbars will return to their original configuration.

If you have modified the menus, this option resets them as well.

5.3.5 Customizing Menus

The SSH Tectia Client menus can be configured as easily as the toolbars. You can select the position of the

menus, and even move them into toolbars.

Moving Menus

You can move the SSH Tectia Client menus into new positions and arrange them so that they best serve your

needs.

To move a menu, keep the Alt key on the keyboard pressed down and click a menu with your mouse. You

will see a new mouse pointer appear. Keep the mouse button pressed down and move the menu around. When

you release the mouse button, the menu will be move to a new position. This way you can arrange the order

of the menus, or move menus into toolbars.

It also possible to move the individual menu options. This can be done using the Commands page of the

Customize dialog (see Section 5.3.3).



Note

If you move a menu somewhere else than the menu bar or a toolbar (for example, in the terminal

window text area), it is removed from the window. Changes become permanent even if you do not

save the settings, but you can undo the changes by selecting View → Reset Toolbars.

Permanent Menu Changes

If you have made changes to the toolbars, but change your mind and want to return the menus to their original

positions, select View → Reset Toolbars to unod the changes. A confirmation dialog opens, asking if you

really want to discard the changes. If you select Yes, the menus will return to their original configuration. If

you have modified the toolbars, this option resets them as well.


127



Chapter 6 Authentication

The Secure Shell protocol used by the SSH Tectia client/server solution provides mutual authentication – the

client authenticates the server and the server authenticates the client. Both parties are assured of the identity

of the other party.

The remote SSH Tectia Server host can authenticate itself using either traditional public-key authentication

or certificate authentication.

Different methods can be used to authenticate SSH Tectia Client users. These authentication methods can be

combined or used separately, depending on the level of functionality and security you want.

User authentication methods used by the client by default are, in the following order: public-key, password,

keyboard-interactive, and GSSAPI authentication. Public-key and certificate authentication are combined

into the public-key authentication method.

host-basedpassword

Keyboard-Interactive

SecurIDPAMRADIUS

otherpassword

plain public key certificate

public key GSSAPI

Kerberos

Figure 6.1. User authentication methods

6.1 Server Authentication with Public Keys

The server is authenticated with a digital signature based on a DSA or RSA public-key algorithm. At the be-

ginning of the connection, the server sends its public key to the client for validation.


129

Server authentication is done during Diffie-Hellman key exchange through a single public-key operation.

When public-key authentication is used to authenticate the server, the first connection is very important.

During the first connection the client will display a message similar to the one in Figure 6.2.

Figure 6.2. SSH Tectia Client on Windows – first connection to a remote host

To help you to verify the identity of the server host, the message displays a fingerprint of the host's public

key. The fingerprint is represented using the SSH Babble format, and it consists of a pronounceable series of

five lowercase letters separated by dashes.

At this point, you should verify the validity of the fingerprint, for example by contacting the administrator of

the remote host computer (preferably by telephone) and asking the administrator to verify that the key fingerprint

is correct. If the fingerprint is not verified, it is possible that the server you are connecting to is not the intended

one (this is known as a man-in-the-middle attack).

After verifying the fingerprint, it is safe to continue connecting. A copy of the server public key will then be

stored on the client machine. On SSH Tectia Client on Unix it is stored in the $HOME/.ssh2/hostkeys directory.

On SSH Tectia Client and SSH Tectia Connector on Windows it is stored in the "%USERPROFILE%\Application

Data\SSH\HostKeys" directory.

When the host key is received during the first connection to a remote host (or when the host key has changed)

and you choose to save the key, its filename is stored in hashed format. The hashed host key format is a security

feature to make address harvesting on the hosts difficult.

If you are adding the keys manually, the keys should be named with the key_<port>_<host>.pub pattern,

where <port> is the port the Secure Shell server is running on and <host> is the hostname you use when

connecting to the server (for example, key_22_alpha.example.com.pub).

If both the hashed and clear-text format keys exist, the hashed format takes precedence.


Authentication130

Note that the identification is different based on the host and port the client is connecting to. For example,

the short hostname alpha is considered different from the fully qualified domain name alpha.example.com.

Also a connection with an IP, for example 10.1.54.1, is considered a different host, as is a connection to the

same host but different port, for example alpha.example.com#222.

After the first connection, the local copy of the server public key will be used in server authentication.

6.1.1 Using the System-Wide Host Key Storage

If a host key is not found in the user-specific host key directory, it is next searched on Unix from the

/etc/ssh2/hostkeys directory and on Windows from the "%ALLUSERSPROFILE%\Application

Data\SSH\HostKeys" directory. Host key files are not automatically put in these directories but they have to

be updated manually by the system administrator (root) or by using SSH Tectia Manager.

If SSH Tectia Manager is not used for distributing the host keys, you can follow the instructions below for

doing it manually. The instructions reflect the Unix file paths but are applicable also to Windows. Simply

replace the Unix paths with the corresponding Windows paths.

To obtain and store hashed remote host keys in the system-wide storage:

1. Select a client-side user whose $HOME/.ssh2/hostkeys will be the basis for the system-wide

/etc/ssh2/hostkeys. The user should have administrative privileges, as placing the keys to the system-

wide location requires them.

This user must also be used to maintain the system-wide /etc/ssh2/hostkeys later on if the host key

on some server changes. The process is to maintain the user's host keys in the $HOME/.ssh2/hostkeys

directory and then replicate the changes to the system-wide /etc/ssh2/hostkeys directory.

2. Make sure that the $HOME/.ssh2/hostkeys directory is empty when obtaining the keys for the first

time, or that the saved host keys are intentional.

If you need to obtain new keys later, the same $HOME/.ssh2/hostkeys/salt file has to be used.

3. Connect with SSH Tectia Client to the remote server, verify the fingerprint, and save the key.

Repeat this step as many times as there are remote servers. Note that you do not have to complete the

user authentication, only key exchange part of the Secure Shell connection.

4. Once all host keys you wish to maintain in the system-wide location have been obtained, place the keys

to the system-wide location, for example by running the following commands:

# mkdir /etc/ssh2/hostkeys

# cp -p $HOME/.ssh2/hostkeys/* /etc/ssh2/hostkeys

Note that also the $HOME/.ssh2/hostkeys/salt file has to be copied so that SSH Tectia Client is able

to identify the hashed host keys. Also if multiple users contribute to the system-wide

/etc/ssh2/hostkeys, they have to share the same salt file.


1316.1.1 Using the System-Wide Host Key Storage

To obtain and store traditional remote host keys in the system-wide storage:

1. As a server-side user, copy the /etc/ssh2/hostkey.pub file from the server as key_<port>_<host-

name>.pub to the /etc/ssh2/hostkeys/ directory on the client.

You can do this as a non-privileged user on the server but you must be privileged user, for example root,

on the client.

2. Use secure means to transfer the file or verify the fingerprint matches after the transfer with the ssh-

keygen-g3 option -F, for example on the server:

$ ssh-keygen-g3 -F /etc/ssh2/hostkey.pub

On the client:

# ssh-keygen-g3 -F /etc/ssh2/hostkeys/key_<port>_<hostname>.pub

Note that the identification is different based on the host and port the client is connecting to. Also con-

nection with IP is considered a different host as well as connection to same host but different port. You

can copy the same traditional key_<port>_<hostname>.pub to all these different names.

6.1.2 Using the OpenSSH known_hosts File

SSH Tectia Client 5.1 (and later) supports also the OpenSSH-style known-hosts file that contains the public

key data of known server hosts. The location of the file must be defined in the ssh-broker-config.xml file

by using the known-hosts element. For example:

<general>

...

<known-hosts path="/u/username/.ssh/known_hosts" />

</general>

The file is never automatically updated by SSH Tectia Client. New host keys are always stored in the SSH

Tectia $HOME/.ssh2/hostkeys directory.


6.2 Server Authentication with Certificates

Server authentication with certificates happens similarly to server authentication with public keys, except that

the possibility of a man-in-the-middle attack during the first connection to a particular server is eliminated.

The signature of a certification authority in the server certificate guarantees the authenticity of the server

certificate even in the first connection.

A short outline of the server authentication process with certificates is detailed below:


Authentication132

1. The server sends its certificate (which contains a public key) to the client. The packet also contains random

data unique to the session, signed by the server's private key.

2. As the server certificate is signed with the private key of a certification authority (CA), the client can

verify the validity of the server certificate by using the CA certificate.

3. The client checks that the certificate matches the name of the server. This check can be disabled by setting

the end-point-identity-check attribute of the cert-validation element in the client configuration

file to no.

4. The client verifies that the server has a valid private key by checking the signature in the initial packet.

During authentication the system checks that the certificate has not been revoked. This can be done either by

using the Online Certificate Status Protocol (OCSP) or a certificate revocation list (CRL), which can be pub-

lished either in an LDAP or HTTP repository.

OCSP is automatically used if the certificate contains a valid Authority Info Access extension, or an OCSP

responder has been separately configured. If no OCSP responder is defined or the OCSP connection fails,

CRLs are used. If LDAP is used as the CRL publishing method, the LDAP repository location can also be

defined in the ssh-broker-config.xml file.

6.2.1 Using the Configuration File (Unix)

When configuring the client, it must be set up to trust the CA certificate and to access the certificate revocation

list (CRL).

To configure the client to trust the server's certificate, perform the following tasks:

1. Copy the CA certificate(s) to the client machine. You can either copy the X.509 certificate(s) as such,

or you can copy a PKCS #7 package including the CA certificate(s).

Certificates can be extracted from a PKCS #7 package by specifying the -7 flag with ssh-keygen-g3.

2. Define the CA certificate(s) to be used in host authentication in the ssh-broker-config.xml file under

the general element:

<cert-validation end-point-identity-check="yes"

http-proxy-url="http://proxy.example.com:800">

<ldap-server address="ldap://ldap.example.com:389" />

<ocsp-responder url="http://ocsp.example.com:8090" validity-period="0" />

<dod-pki enable="no" />

<ca-certificate name="ssh_ca1"

file="ssh_ca1.crt"

disable-crls="no"

use-expired-crls="100" />

</cert-validation>

The client will only accept certificates issued by the defined CA(s).



You can disable the use of CRLs by setting the disable-crls attribute of the ca-certificate element

to "yes".

Note

CRL usage should only be disabled for testing purposes. Otherwise it is highly recommended

to always use CRLs.

Also define the LDAP server(s) or OCSP responder(s) used for CRL checks. Defining the LDAP server

is not necessary if the CA certificate contains a CRL distribution point extension.

3. If the CA services (OCSP, CRL) are located behind a firewall, define also the SOCKS server in the ssh-

broker- config.xml file. The SOCKS server is defined inside cert-validation with the socks-

server-url element.

6.2.2 Using the GUI (Windows)

Using the SSH Tectia Configuration tool to manage CA certificates is described in Section 4.1.7.2.

6.3 User Authentication with Passwords

The password authentication method is the easiest to implement, as it is set up by default. Since all commu-

nication is encrypted, passwords are not available for eavesdroppers.

On a Unix system, password authentication uses the /etc/passwd or /etc/shadow file, depending on how

the passwords are set up.

On Windows, password authentication uses the Windows password to authenticate the user at login time.


To enable password authentication on the client, the authentication-methods element of the ssh-broker-

config.xml file must contain an authentication-method element with the name attribute value password:


...

<authentication-method name="password" />


Other authentication methods can be listed in the configuration file as well. Place the least interactive method

first (password is usually the last one).


Authentication134


Using the SSH Tectia Configuration tool to manage authentication methods is described in Section 4.1.5.2.

6.4 User Authentication with Public Keys

Public-key authentication is based on the use of digital signatures. Each user creates a pair of key files. One

of these key files is the user's public key, and the other is the user's private key. The server knows the user's

public key, and only the user has the private key.

When the user tries to authenticate, the server checks for matching public keys and sends a challenge to the

user. The users are authenticated by signing the challenge using their private keys.

Remember that your private key file is used to authenticate you. If anyone else can access your private key

file, they can attempt to log in to the remote host computer as you. Keep your private key file in a secure place

and make sure that no one else has access to it.

Caution

Do not use public-key authentication on a computer that is shared with other users. Generate keys

only on your personal computer that no one else can access!

Also note that if you are using the Windows roaming profiles functionality, your personal settings will be

replicated with the roaming profile server. If you store your private keys in the default location (under the

profile folder of your Windows user account) your private keys may be susceptible to a malicious user

listening to the network traffic. Therefore the User Settings folder should not be a directory that is used in

profile roaming.

To use public-key authentication, do the following:

1. Generate a key pair. You can generate your own key files with the help of a built-in Key Generation

wizard on Windows (see Section 6.4.3), or with ssh-keygen-g3 on Unix or Windows command line

(see Section 6.4.1).

On Windows, you can also import existing keys on the Keys and Certificates page of the SSH Tectia

Configuration tool. See Section 4.1.6.1.

2. Upload you public key to the remote host computer. On Windows, you can do this automatically (see

Section 6.4.4). On Unix and Windows, you can also copy the public key manually (see Section 6.4.2).

In the following instructions, Server is the SSH Tectia Server to which you are trying to connect. ServerUser

is the username on the server that you are logging into. Client is the machine running an SSH Tectia Client.

ClientUser is the username on the client machine that should be allowed to log in to Server as ServerUser.

See Figure 6.3.



SSH Tectia Client

private key public key

ClientUser

Client

ServerUser

Server

Secure Shell v2 server

Figure 6.3. User public-key authentication

The instructions assume that ClientUser is allowed to log in to Server as ServerUser using some other

authentication method (usually password).

6.4.1 Creating Keys with ssh-keygen-g3

To create a public key pair, run ssh-keygen-g3 on Client:

Client$ ssh-keygen-g3

Generating 2048-bit dsa key pair

9 oOo.oOo.oOo

Key generated.

2048-bit dsa, user@Client, Thu Jun 22 2006 12:09:46 +0200

Passphrase :

Again :

Private key saved to /home/user/.ssh2/id_dsa_2048_a

Public key saved to /home/user/.ssh2/id_dsa_2048_a.pub

ssh-keygen-g3 will now ask for a passphrase for the new key. Enter a sufficiently long (20 characters or so)

sequence of any characters (spaces are OK). On Unix, ssh-keygen-g3 creates a .ssh2 directory in your

home directory (if it is not already present), and stores your new authentication key pair in two separate files.

On Windows, the key pair is by default created in the "%USERPROFILE%\Application Data\SSH\UserKeys"

directory.

One of the keys is your private key which must never be made available to anyone but yourself. The private

key can only be used together with the passphrase.

In the example above, the private key file is id_dsa_2048_a. The other file id_dsa_2048_a.pub is your

public key, which can be distributed to other computers.

By default, ssh-keygen-g3 creates a DSA key pair. RSA keys can be generated by specifying the -t option

with ssh- keygen-g3. Key length can be specified with the -b option. For automated jobs, the key can be

generated without a passphrase with the -P option.:

Client$ ssh-keygen-g3 -t rsa -b 1536 -P

For more information on the ssh-keygen-g3 options, see ssh-keygen-g3(1).


Authentication136

6.4.2 Uploading the Public Key Manually

To enable public-key authentication with your key pair:

1. (Optional) Create a file called identification, on Unix in your $HOME/.ssh2 directory, or on Windows

in your "%USERPROFILE%\Application Data\SSH\UserKeys" directory.

Edit it with your favorite text editor to include the following line (replace id_dsa_2048_a with the file-

name of the private key):

IdKey id_dsa_2048_a

With SSH Tectia Client 5.x, using the identification file is not necessary if all your keys are stored

in the default directory and you allow all of them to be used for public-key and/or certificate authentication.

If the identification file does not exist, the Connection Broker attempts to use each key found in the

$HOME/.ssh2 directory on Unix or in the "%USERPROFILE%\Application Data\SSH\UserKeys" directory

on Windows.

On Windows, you can also add other directory locations on the Keys and Certificates page of the SSH

Tectia Configuration tool. See Section 4.1.6.1. On Unix, you can use the key-store element in the ssh-

broker-config.xml file. See the section called “Key Store Configuration Examples”.

2. Connect to Server using some other authentication method.

3. Depending on the server version, do the following:

• On SSH Tectia Server 5.x, use SFTP to upload your public key (for example, id_dsa_2048_a.pub)

to the server, to your authorized_keys directory (by default $HOME/.ssh2/authorized_keys on

Unix servers, or %USERPROFILE%\.ssh2\authorized_keys on Windows servers).

• SSH Tectia Server 4.x (or older) requires an authorization file stored in the .ssh2 directory. The

authorization file specifies the public keys that are authorized for login. The authorization file may

be optionally used with SSH Tectia Server 5.x as well.

Use SFTP to upload your public key to the server (by default to the $HOME/.ssh2 directory on Unix

servers, or to the %USERPROFILE%\.ssh2 directory on Windows servers) and edit the authorization

file.

An example file is shown below (by default $HOME/.ssh2/authorization on Unix servers, or

%USERPROFILE%\.ssh2\authorization on Windows servers):

Key id_dsa_2048_a.pub

This directs SSH Tectia Server to use id_dsa_2048_a.pub as a valid public key when authorizing

your login.

• On OpenSSH server, you must convert the key to the OpenSSH public-key file format.


1376.4.2 Uploading the Public Key Manually

Use STFP to upload the public to the OpenSSH server, to your $HOME/.ssh directory.

Convert the public key to the OpenSSH public key file format on the server and append it to your

~/.ssh/authorized_keys file. This can be done with the following command:

$ ssh-keygen -i -f id_dsa_2048_a.pub >> authorized_keys

4. Make sure that public-key authentication is allowed in the ssh-broker-config.xml file (it is allowed

by default). The configuration file should contain an authentication-method element line like the

following:



...


Other authentication methods can be listed in the configuration file as well. Place the least interactive

method first.

Assuming Server is configured to allow public-key authentication to your account, you should now be able

to log in from Client to Server using public-key authentication.

Try to log in:

Client$ sshg3 Server

You should be prompted for the passphrase of the private key. After you have entered the passphrase, a Secure

Shell connection will be established.

6.4.3 Creating Keys with the Key Generation Wizard (Windows)

On Windows, you can use the SSH Tectia Key Generation wizard to generate a key pair.

Key Generation Wizard

New keys are generated in the SSH Tectia Configuration tool. Select the User authentication section Keys

and Certificates page and click New Key... to start the Key Generation wizard.

The wizard will generate two key files, your private key and your public key. The private key file has no file

extension, and the public key has the same base file name as the private key, but with .pub as the file extension.

The key files will be stored on your local computer, in the user profile directory.

Key Generation - Start

The Key Generation - Start page contains important information about safety measures. Read the text and

click Next.


Authentication138

Figure 6.4. The Start page of the Key Generation wizard

Key Generation - Key Properties

On the Key Properties page, select the type of the key to be generated. You can select to generate either an

RSA or a DSA key, and select the key length.

Figure 6.5. Selecting the key type


139

Key Type

Select the type of the key to be generated. Available options are DSA or RSA.

Key Length

Select the length (complexity) of the key to be generated. Available options are 768, 1024, 2048 or 3072

bits. Larger keys are more secure, but also slower to use. The recommended key length for most occasions

is 2048 bits.

Key Generation - Generation

On the Key Generation - Generation page the computer will generate your key files. This can take several

minutes, depending on the chosen key length and the processor speed of the computer.

During the key generation phase, an animation of random bits is displayed. When the process is ready, the

Next button becomes active and you can proceed to the next phase by clicking Next.

Key Generation - Enter Passphrase

On the Key Generation - Enter Passphrase page you can provide information describing the generated key

pair, and protect the files with a passphrase.

Figure 6.6. Entering a passphrase for a newly generated key pair

File Name

Type a name for the key file in the File Name field.


Authentication140

Comment

In this field you can write a short comment that describes the key pair. You can for example describe the

connection the files are used for. This field is not obligatory, but can be quite useful.

Passphrase

Type a phrase that you have to enter when handling the key. This passphrase works in a similar way to

a password and gives some protection for your private key.

Make the passphrase difficult to guess. Use at least 8 characters, both letters and numbers. Any punctuation

characters can be used as well.

Memorize the passphrase carefully, and do not write it down.

Passphrase

Type the passphrase again. This ensures that you have not made a typing error.

When you have typed the file name and typed the passphrase twice, you can click Next to proceed to the next

phase.

Key Generation - Finish

The Key Generation - Finish page displays important information on the use of the key files.

The new private and public key have been generated. They are stored on your local computer in the "%USER-

PROFILE%\Application Data\SSH\UserKeys" directory.

Click Finish to exit the Key Generation wizard.


141

Figure 6.7. Keys have now been generated

To use the key pair for public-key authentication, you have to upload the public key to the remote host computer.

If the remote host has an SFTP server running, you can automatically upload a copy of your new public key

to the server. To upload the key automatically, see Section 6.4.4. To upload the key manually, see Section 6.4.2.

6.4.4 Uploading the Public Key Automatically (Windows)

Public keys can be uploaded automatically to servers that have the SFTP subsystem enabled. The automatic

upload can be done on the Keys and Certificates page of SSH Tectia Configuration GUI. As a pre-requisite,

you should have a connection profile created for the server you wish to upload the key to. See Section 4.1.5.

To enable public-key authentication with your key pair:

1. Open the SSH Tectia Configuration GUI by right-clicking the SSH Tectia tray icon and selecting

Configuration from the shortcut menu.

2. Click User Authentication → Keys and Certificates on the tree view.

3. Select a key pair from the list and click Upload. The Upload Public Key dialog box opens. See Figure 6.8.


Authentication142

Figure 6.8. Uploading a key

4. Enter the following information:

• Either select Quick connect and enter the host and user name of the remote host you want to upload

the key to, or select a Connection profile that specifies the host and user name.

• Enter the public key filename. The public key filename you selected on the Keys and Certificates

page is pre-filled and normally you do not need to change it.

• Enter the destination folder on the server, relative to the user home directory (%USERPROFILE% on

Windows, $HOME on Unix). The default is .ssh2.

• Enter the name of the authorization file. The default is authorization in the defined destination

folder directory.

• The key name is automatically added to the authorization file on the server. If you want to view and

edit the file, select the View authorization file check box.

Click Upload to start the upload.

5. If you are already connected to the host, the key upload starts immediately. If you are not connected,

you will be prompted to authenticate on the server (by default with password).

6. Make sure that public-key authentication is allowed in the Connection Broker configuration, in the default

settings and in the relevant connection profile (it is allowed by default). See Section 4.1.2.1 and Sec-

tion 4.1.5.2.


143

Note

The automatic key uploading process uses SFTP. The administrator of the remote host computer

may have restricted user access so that users are not able to configure public-key authentication for

themselves even if public-key authentication is allowed in the server configuration. If you do not

have the proper file permissions to the key directory, the automatic upload will fail.

Even if the automatic upload succeeds, it is possible that the server administrator has configured the system

to store keys elsewhere than under the user home directory. In this case the keys and the authorization file

additions have to be moved manually to the proper directory.

If you do not use the automatic upload facility, see Section 6.4.2.

6.4.5 Using Keys Generated with OpenSSH

SSH Tectia Client supports also user key pairs generated with OpenSSH. The OpenSSH keys can be specified

in the ssh-broker-config.xml file by using the key-stores element. An example configuration is shown

below:

<programlisting><![CDATA[<key-stores>


init="key_files(/u/exa/keys/id_dsa.pub,/u/exa/keys/id_dsa)" />


init="directory(path(/u/exa/.ssh))" />

</key-stores>

This example adds a key called id_dsa and all keys from the user's default OpenSSH key directory (.ssh

under the user's home directory).

On Windows, you can add OpenSSH keys and directories on the Keys and Certificates page of the SSH

Tectia Configuration tool. See Section 4.1.6.1.

The public key can be uploaded to the server the same way as with standard SSH2 keys. See Section 6.4.2

and Section 6.4.4.

6.5 User Authentication with Certificates

Certificate authentication is technically a part of the public-key authentication method. The signature created

with the private key and the verification of the signature using the public key (contained in the X.509 certificate

when doing certificate authentication) are done identically with conventional public keys and certificates.

The major difference is in determining whether a specific user is allowed to log in with a specific public key

or certificate. With conventional public keys, every server must have every user's public key, whereas with

certificates the users' public keys do not have to be distributed to the servers - distributing the public key of

the CA (self-signed certificate) is enough.


Authentication144

In brief, certificate authentication works in the following way:

1. The client sends the user certificate (which includes the user's public key) to the server. The packet also

contains random data unique to the session and signed by the user's private key.

2. The server uses the CA certificate (and external resources as required) to check that the user's certificate

is valid.

3. The server verifies that the user has a valid private key by checking the signature in the initial packet.

4. The server matches the user certificate against the rules in the server configuration file to decide whether

login is allowed or not.

Compared to traditional public-key authentication, this method is more secure because the system checks that

the user certificate was issued by a trusted CA. In addition, certificate authentication is more convenient because

no local database of user public keys is required on the server.

It is also easy to deny a user's access to the system by revoking his or her certificate, although this does not

take effect until the next CRL update and requires that every other authentication method has been disabled.

The status of a certificate can be checked either by using the Online Certificate Status Protocol (OCSP) or a

certificate revocation list (CRL), which can be published either in an LDAP or HTTP repository.


To configure the client to authenticate itself with an X.509 certificate, perform the following tasks:

1. Enroll a certificate for yourself.

Example: Enrollment using ssh-cmpclient

$ ssh-cmpclient INITIALIZE \

-P generate://ssh2:passphrase@rsa:512/user_rsa \

-o /home/user/.ssh2/user_rsa \

-p 62154:ssh \

-s 'C=FI,O=SSH,CN=user;[email protected]' \

http://pki.ssh.com:8080/pkix/ \

'C=FI, O=SSH Communications Security Corp, CN=Secure Shell Test CA'

Remember to define also the SOCKS server (-S) before the CA URL, if required.

For more information on the ssh-cmpclient syntax, see ssh-cmpclient-g3(1).

2. Make sure that public-key authentication is enabled in the ssh-broker-config.xml file.



...




3. (Optional) Specify the private key of your software certificate in the $HOME/.ssh2/identification

file.

CertKey private-key-path

The certificate itself will be read from private-key-path.crt.

With SSH Tectia Client 5.x, using the identification file is not necessary if all your keys are stored



$HOME/.ssh2 directory.


You can import existing PKCS #12, PKCS #7 and X.509 certificates on the Keys and Certificates page under

User Authentication in the SSH Tectia Configuration tool. See Section 4.1.6.1.

6.6 Host-Based User Authentication (Unix)

Host-based authentication uses the public host key of the client machine to authenticate a user to the remote

server. Host-based authentication can be used with SSH Tectia Client on Unix. The SSH Tectia Server can

be either an Unix or Windows server.

Setting up host-based authentication usually requires administrator (root) privileges on the server. The setup

is explained in the SSH Tectia Server documentation.

6.7 User Authentication with Keyboard-Interactive

Keyboard-interactive is a generic authentication method that can be used to implement different types of au-

thentication mechanisms. Any currently supported authentication method that requires only the user's input

can be performed with keyboard-interactive.

Currently, the following methods are supported:

• password

• PAM (Unix only, see note below)

• RSA SecurID

• RADIUS


Authentication146

With the current version of SSH Tectia Server on Windows, password, RADIUS, and RSA SecurID authen-

tication can be performed over keyboard-interactive. In the future, it may be possible to use keyboard-inter-

active also with other authentication methods.

Methods that require passing some binary information, such as public-key authentication, cannot be used as

submethods of keyboard-interactive. But public-key authentication, for example, can be used as an additional

method alongside keyboard-interactive authentication.

Note

PAM has support for binary messages and client-side agents, and those cannot be supported with

keyboard-interactive. However, currently there are no implementations that take advantage of the

binary messages in PAM, and the specification may not be cast in stone yet.


To enable keyboard-interactive authentication on the client, make sure that you have the following line in the

ssh-broker-config.xml file:


...

<authentication-method name="keyboard-interactive" />

...


Note

The client cannot request any specific keyboard-interactive submethod if the server allows several

optional submethods. The order in which the submethods are offered depends on the server config-

uration. However, if the server allows, for example, the two optional submethods SecurID and

password, the user can skip SecurID by pressing enter when SecurID is offered by the server. The

user will then be prompted for a password.


Using keyboard-interactive authentication is a Connection Broker setting. Using the SSH Tectia Configuration

tool to manage authentication methods is described in Section 4.1.5.2.

6.8 User Authentication with GSSAPI

GSSAPI (Generic Security Service Application Programming Interface) is a function interface that provides

security services for applications in a mechanism independent way. This allows different security mechanisms

to be used via one standardized API. GSSAPI is often linked with Kerberos, which is the most common

mechanism of GSSAPI.



Kerberos libraries are installed by default on Linux platforms. They are also available for most other Unix

platforms, but have to be installed separately.

For Windows, GSSAPI offers integrated authentication for Windows 2000/2003 networks with Kerberos.

This method utilizes domain accounts, since local accounts are not transferable across machine boundaries.

The GSSAPI authentication method has no user interface (besides configuration). It does not ask anything

from the user. If something fails during GSSAPI exchange, the reason for the failure can be seen in the client

debug log.


To enable GSSAPI authentication on the client, make sure that you have the following line in the ssh-broker-

config.xml file:


<authentication-method name="gssapi-with-mic" />

...


Other authentication methods can be listed in the configuration file as well. Place the least interactive method

first.


Using the SSH Tectia Configuration tool to manage authentication methods is described in Section 4.1.5.2.

When connecting from a Windows 5.x client to a Windows 4.x server using GSSAPI authentication, if authen-

tication fails although GSSAPI has been correctly configured, you may have to disable the LMHOSTS lookup

on the client-side computer:

1. Select Control Panel → Network Connections.

2. In Local Area Connection, right-click and select Properties.

3. In the Local Area Connection Properties dialog box, General tab, select Internet Protocol (TCP/IP)

and click the Properties button.

4. In the Internet Protocol (TCP/IP) Properties dialog box, in the General tab, click the Advanced...

button.

5. In the Advanced TCP/IP Settings dialog box, in the WINS tab, clear the Enable LMHOSTS lookup

check box.

6. Restart the client-side computer.


Authentication148

Chapter 7 Transferring Files

All versions of SSH Tectia Client and SSH Tectia Server provide the secure file transfer functionality. In

addition to that, the EFT Expansion Pack available with SSH Tectia Client and SSH Tectia Server provides

enhanced file transfer (EFT) functionality, such as checkpoint/restart for the transfer of very large files,

streaming for high-speed file transfers, and C and Java APIs for customization.

This chapter gives instructions on secure file transfer using the command-line tools and the Windows file

transfer GUI.

For more information on the enhanced file transfer features available with the EFT Expansion Pack, see SSH

Tectia Client/Server Product Description and the documentation for the C and Java APIs (in the CD-ROM).

7.1 File Transfer with the Command-Line Client

SSH Tectia Client provides secure file transfer functionality with the scpg3 (secure copy) and sftpg3 (secure

file transfer protocol) commands.

7.1.1 Using scpg3

scpg3 (sshg3.exe on Windows) is used to securely copy files over the network. scpg3 launches ssh-broker-

g3 to provide a secure transport using the Secure Shell version 2 protocol. The remote host(s) must be running

a Secure Shell version 2 server with the sftp-server subsystem enabled.

The basic syntax of scpg3 is:

scpg3 user@source:/directory/file user@destination:/directory/file

scpg3 can be used to copy files in either direction; from the local system to the remote system or vice versa.

Copies between two remote hosts are also permitted. Local paths can be specified without the user@system:

prefix. Relative paths can also be used, they are interpreted in relation to the user's home directory.

Windows paths should be preceded by a slash ("/"). For example, copying a local file to a remote Windows

server:


149

scpg3 localfile user@destination:/C:/directory/file

For more information on the command-line options, see scpg3(1).

7.1.2 Using sftpg3

sftpg3 (sftpg3.exe on Windows) is an FTP-like client that can be used for file transfer over the network.

sftpg3 launches ssh-broker-g3 to provide a secure transport using the Secure Shell version 2 protocol.

Even though it functions like ftp, sftpg3 does not use the FTP daemon or the FTP client for its connections.

sftpg3 can be used to connect to any host that is running a Secure Shell version 2 server with the sftp-

server subsystem enabled.

The basic syntax of sftpg3 is:

sftpg3 user@host

The actual usage of sftpg3 is similar to the traditional ftp program.

For more information on the command-line options and commands, see sftpg3(1).

7.2 File Transfer with the File Transfer GUI (Windows)

7.2.1 Defining File Transfer Settings

Configuring file transfer settings is explained in Section 5.1.5.

7.2.2 Downloading Files with the File Transfer GUI

With the file transfer window it is easy to download files from the remote host computer into your local

computer. There are different ways to download a file, or several files at the same time. Selecting multiple

files with the Shift and Control keys works the same way as in Windows Explorer.

Drag and drop

Dragging and dropping is probably the easiest way to download files. Simply click on the file(s) you

want to download, hold down the mouse button and move the file to a location where you want it - for

example on the Windows desktop - and release the button.

Download button

Click the Download button on the toolbar to download the selected file(s).

Shortcut menu

When you right-click a file in the Remote View, a shortcut menu appears. Select the Download or

Download Dialog option from the menu.


Transferring Files150

If you have selected the Download Dialog option, a Download - Select Folder dialog appears, allowing you

to select where the downloaded file(s) should be saved. After you have selected the appropriate folder (or

other location), the Transfer View shows the current downloading status.

Selecting Folders

When you start a download operation, a Download - Select Folder dialog is displayed. This is a standard

Windows file selection dialog, where you can select the location where you want the selected file(s) to be

downloaded.

You can use the Look in selection box to select a folder, a local or network drive or your desktop.

Another way to select a folder is to type its directory path in the Folder field. Note that you can use this field

only to specify the folder name. Do not write in a file name after the selected directory path. The file name

is the same as the file name on the remote host computer.

Figure 7.1. Creating a new directory for downloaded files

The most common operations can be completed by clicking on the four controls on the right-hand side of the

Look in selection box. You can click the Go To Last Folder Visited to return to the last folder you opened

before the current one. The Up One Level button opens the parent folder of the current folder. If you want


151

to create a new folder, click the Create New Folder button. You can also select between Large Icons, Small

Icons, List, Details, and Thumbnails views by selecting the appropriate option from the drop-down menu.

7.2.3 Uploading Files with the File Transfer GUI

The file transfer window can be used to upload files from your local computer to the remote host computer.

There are different ways to upload a file, or several files at the same time. Selecting multiple files with the

Shift and Control keys works the same way as in Windows Explorer.

Drag and drop

Dragging and dropping is probably the easiest way to upload files. Simply click on the local file(s) you

want to upload (for example on the desktop or Windows Explorer), hold down the mouse button, move

the file(s) into the file view in the File Transfer window, and release the button.

Upload button

Click the Upload button on the file transfer window toolbar to upload the selected file(s).

Shortcut menu

When you right-click a file in the Local View, or an empty space in the Remote View, a shortcut menu

appears. Select the Upload or Upload Dialog option from the menu.

If you have selected the Upload Dialog option, an Upload - Select Files dialog appears, allowing you to select

the file(s) to upload. After you have selected the files, the Transfer View shows the current uploading status.

Selecting Files

When you start an upload operation, a Upload - Select Files dialog is displayed. This is a standard Windows

file selection dialog, where you can select which file(s) you want to upload.

You can use the Look in selection box to select the location of the file(s): a folder, a local or network drive

or your desktop.



Figure 7.2. Select the file you want to upload

Note that the grayed out File name field displayed at the bottom of the dialog displays the selected file name.

The field is read-only - you cannot type in the desired file name. Select the files by clicking them with the

mouse instead.

The most common operations can be completed by clicking on the four controls on the right-hand side of the

Look in selection box. You can click on the Go To Last Folder Visited to return to the last folder you opened

before the current one. The Up One Level button opens the parent folder of the current folder. If you want

to create a new folder, click on the Create New Folder button. You can also select between Large Icons,

Small Icons, List, Details, and Thumbnails views by selecting the appropriate option from the drop-down

menu.

7.2.4 Defining File Properties

Selecting a file in the Local View or Remote View and selecting Operations → Properties (or Properties

on the shortcut menu) opens the File Properties dialog which allows you to view and change some of the file

properties.


1537.2.4 Defining File Properties

Figure 7.3. Properties page for a file

File Name

At the top of the page the file name and icon are shown. If multiple files are selected, a count of the

number of files and folders is displayed.

Type

The type of the selected file(s).

Location

The directory where the selected file(s) are located on the remote host.

Size

The size of the selected file. If multiple files are selected the total size of all the files is diplayed.

Modified Date

The date the selected file was last modified.

Permissions

The Permissions check boxes are displayed for files residing in a Unix system. The nine checkboxes can

be used to set the permissions of a file or a group of files. If multiple files are selected with conflicting



permissions, some of the check boxes will appear grayed out. Clicking on a grayed out check box clears

the selection. If any check boxes are grayed out when the OK button is pressed, the value is left unchanged

on the remote file.

Permissions can also be set by entering standard octal Unix permissions (as with the Unix chmod command)

in the Permission mode field. Values entered here override and update the checkbox values.

For more information on file permissions, see Section C.2.4.1.

Attributes

The Attributes checkboxes are displayed for files residing in a Windows system. The five checkboxes

(Read-only, Hidden, Archive, System, and Compressed) can be used to set the attributes of a local file

or a local group of files. If multiple files are selected with conflicting permissions, then some of the check

boxes will appear grayed out. Clicking on a grayed out checkbox clears the selection. If any check boxes

are grayed out when the OK button is pressed, the value is left unchanged on the remote file.

Note

Due to the limitations of the Windows architecture, it is not possible to set the Windows file

attributes for remote files residing on a Windows server.

For more information on file attributes, see Section C.2.4.1.

7.2.5 Differences from Windows Explorer

The file transfer window operates very much the same way as Windows Explorer. However, due to the different

nature of handling files locally in your own computer (as per Windows Explorer) and handling them over a

secured remote connection in the host computer (as per SSH Tectia Client file transfer), there are some differ-

ences in operation.

Deleting folders

It is not possible to delete a remote folder that is not empty. Delete the files and subfolders in the folder

first.

Multiple paste operations

During copy and paste operations, the file names are not changed when the files are pasted. Therefore it

is not possible to paste files several times into one location, creating "copies of" the pasted files as in

Windows Explorer.

Note

The maximum size of transferred files is limited only by the file system. (On many systems the

maximum file size is 2 gigabytes.)


1557.2.5 Differences from Windows Explorer

7.3 FTP-SFTP Conversion (EFT Expansion Pack)

The FTP-SFTP conversion component optionally available with SSH Tectia Client with EFT Expansion Pack.

See Section 2.1.2.

With FTP-SFTP conversion, SSH Tectia Client can automatically capture FTP connections on the client and

convert them to SFTP and direct them to an SFTP server. The server must be running SSH Tectia Server with

EFT Expansion Pack, SSH Tectia Server with Tunneling Expansion Pack, or SSH Tectia Server for IBM

z/OS.

The FTP-SFTP conversion rules are defined in the filter-engine element of the ssh-broker-config.xml

file. See the section called “The filter-engine Element (EFT Expansion Pack, SSH Tectia Connector)”.

On Windows, the conversion rules can be set in the SSH Tectia Configuration tool on the FTP-SFTP

Conversion page. See Section 4.1.9.

7.3.1 Enabling FTP-SFTP Conversion (Windows)

On Windows, FTP-SFTP conversion is automatically active when the Connection Broker is running.

7.3.2 Enabling FTP-SFTP Conversion (Unix)

On Unix, the ssh-convert-ftp command has to be run to activate FTP-SFTP conversion.

For example, to start an FTP session to ftp.example.org with FTP-SFTP conversion enabled, run the fol-

lowing command:

$ ssh-convert-ftp ftp ftp.example.org

To start a bash shell session with FTP-SFTP conversion enabled for all commands, run the following command:

$ ssh-convert-ftp bash

For more information, see ssh-convert-ftp (EFT Expansion Pack on Unix)(1).

7.4 Enhanced File Transfer (EFT Expansion Pack)

The enhanced file transfer features are available in the scpg3 and sftpg3 command-line tools with SSH

Tectia Client with EFT Expansion Pack. The server must be running SSH Tectia Server with EFT Expansion

Pack, SSH Tectia Server with Tunneling Expansion Pack, or SSH Tectia Server for IBM z/OS.

With SSH Tectia Client 5.1, the following features can be used:

• Checkpoint-restart for transferring large files



• Streaming for improved file transfer speed

• Prefix for ensuring that a file is fully transferred before it is used

Fore more information, see scpg3(1) and sftpg3(1).

7.5 FTP Tunneling



1577.5 FTP Tunneling



Chapter 8 Tunneling

Tunneling is a way to forward otherwise unsecured TCP traffic through Secure Shell. Tunneling can provide

secure application connectivity, for example, to POP3, SMTP, and HTTP-based applications that would oth-

erwise be unsecured.

The Secure Shell v2 connection protocol provides channels that can be used for a wide range of purposes.

All of these channels are multiplexed into a single encrypted tunnel and can be used for tunneling (forwarding)

arbitrary TCP/IP ports and X11 connections.

The client-server applications using the tunnel will carry out their own authentication procedures, if any, the

same way they would without the encrypted tunnel.

The protocol/application might only be able to connect to a fixed port number (e.g. IMAP 143). Otherwise

any available port can be chosen for tunneling. For remote (incoming) tunnels, the ports under 1024 (the well-

known service ports) are not allowed for the regular users, but are available only for system administrators

(root privileges).

There are two basic kinds of tunnels: local and remote. They are also called outgoing and incoming tunnels,

respectively. X11 forwarding and agent forwarding are special cases of a remote tunnel. The different tunneling

options are handled in the following sections.

8.1 Local Tunnels

A local (outgoing) tunnel forwards traffic coming to a local port to a specified remote port.

With sshg3 on the command line, the syntax of the local tunneling command is the following:

client$ sshg3 -L [protocol/][listen-address:]listen-port:dst-host:dst-port server

Setting up local tunneling allocates a listener port on the local client. Whenever a connection is made to this

listener, the connection is tunneled over Secure Shell to the remote server and another connection is made

from the server to a specified destination host and port. The connection from the server onwards will not be

secure, it is a normal TCP connection.


159

Figure 8.1 shows the different hosts and ports involved in local port forwarding.

listen-addressclient

Secure ShellClient

server

Secure ShellServer

src

ApplicationClient

dst

ApplicationServer

listen-port

dst-portsrc-host dst-host

Local tunnel

Figure 8.1. Local tunneling terminology

For example, using SSH Tectia Client on the command line, when you issue the following command, all

traffic coming to port 1234 on the client will be forwarded to port 23 on the server. See Figure 8.2.

client$ sshg3 -L 1234:localhost:23 username@sshserver

The forwarding address in the command is resolved at the (remote) end point of the tunnel. In this case loc-

alhost refers to the server host (sshserver).

Internet

Outgoing tunnel

SSH Tectia Client /SSH Tectia Connector SSH Tectia Server

Figure 8.2. Simple local (outgoing) tunnel

To use the tunnel, the application to be tunneled is set to connect to the local listener port instead of connecting

to the server directly. SSH Tectia Client forwards the connection securely to the remote server.

If you have three hosts, for example, sshclient, sshserver, and imapserver, and you forward the traffic

coming to the sshclient's port 143 to the imapserver's port 143, only the connection between the sshclient

and sshserver will be secured. The command you use would be similar to the following:

sshclient$ sshg3 -L 143:imapserver:143 username@sshserver

Figure 8.3 shows an example where the Secure Shell server resides in the DMZ network. Connection is en-

crypted from the Secure Shell client to the Secure Shell server and continues unencrypted in the corporate

network to the IMAP server.


Tunneling160

Corporatenetwork

Internet

Outgoing tunnel

IMAPSSH Tectia Client/SSH Tectia Connector

SSH TectiaServer

Figure 8.3. Local (outgoing) tunnel to an IMAP server

Tunnels can also be defined for connection profiles in the Connection Broker configuration file. The defined

tunnels are opened automatically when a connection with the profile is made. The following is an example

from a ssh-broker-config.xml file:

<profile id="id1" host="sshserver.example.com">

...

<tunnels>

<local-tunnel type="tcp"

listen-port="143"

dst-host="imap.example.com"

dst-port="143"

allow-relay="no" />

...

</tunnels>

</profile>

By default, local tunnels originating only from the client host itself are allowed. To allow also other machines

to connect to the tunnel listener port, set the allow-relay to yes.

When using SSH Tectia Client with the Windows GUI, the tunneling settings can be made under Profile

Settings → Tunneling. See Section 4.1.5.7.

8.1.1 Dynamic Tunneling

Dynamic tunneling is a transparent mechanism available for applications that support the SOCKS4 or SOCKS5

client protocol. Instead of configuring port forwarding from specific ports on the local host to specific ports

on the remote server, you can specify a SOCKS server which can be used by the user's applications. Each

application is configured in the regular way except that it is configured to use a SOCKS server on a localhost

port. The Secure Shell client application opens a port in the localhost and mimics a SOCKS4 and SOCKS5

server for any SOCKS client application.


1618.1.1 Dynamic Tunneling

When the applications connect to services such as IMAP4, POP3, SMTP, HTTP, and FTP, they provide the

necessary information to the SOCKS server, which is actually the Secure Shell client mimicking a SOCKS

server. The client will use this information in creating port forwarding to the Secure Shell server and relaying

the traffic back and forth securely, as with user-specified port forwarding.

With sshg3 on the command line, the syntax of the dynamic tunneling command is the following:

client$ sshg3 -L socks/[listen-address:]listen-port server

For example, the following command will set up dynamic tunneling from port 1234 on the client to sshserver.

The applications are set to use a SOCKS server at port 1234 on the client. From the server, the connections

are forwarded unsecured to the destination hosts requested by the applications.

sshclient$ sshg3 -L socks/1234 username@sshserver

Dynamic tunnels can also be defined for connection profiles in the Connection Broker configuration file. The

following is an example from a ssh-broker-config.xml file:


...

<tunnels>

<local-tunnel type="socks"

listen-port="1234"

allow-relay="no" />

...

</tunnels>

</profile>

8.1.2 Transparent Tunneling with SSH Tectia Connector

With SSH Tectia Connector, there is no need to separately configure application software to use local ports

to set up the tunnels. The applications to be tunneled are defined in the Connection Broker configuration (SSH

Tectia Connector → Filters). SSH Tectia Connector automatically captures the defined applications and the

Connection Broker creates Secure Shell tunnels to the defined SSH Tectia Server. See Section 4.1.8.2.

8.2 Remote Tunnels

A remote (incoming) tunnel it forwards traffic coming to a remote port to a specified local port.

With sshg3 on the command line, the syntax of the remote tunneling command is the following:

client$ sshg3 -R [protocol/][listen-address:]listen-port:dst-host:dst-port server

Setting up remote tunneling allocates a listener port on the remote server. Whenever a connection is made to

this listener, the connection is tunneled over Secure Shell to the local client and another connection is made

from the client to a specified destination host and port. The connection from the client onwards will not be

secure, it is a normal TCP connection.


Tunneling162

Figure 8.4 shows the different hosts and ports involved in remote port forwarding.

listen-addressclient

Secure ShellClient

server

Secure ShellServer

dst

ApplicationServer

src

ApplicationClient

listen-port

dst-portsrc-hostdst-host

Remote tunnel

Figure 8.4. Remote tunneling terminology

For example, if you issue the following command, all traffic which comes to port 1234 on the server will be

forwarded to port 23 on the client. See Figure 8.5.

sshclient$ sshg3 -R 1234:localhost:23 username@sshserver

The forwarding address in the command is resolved at the (local) end point of the tunnel. In this case localhost

refers to the client host.

Internet

Incoming tunnel

SSH Tectia Client SSH Tectia Server

Figure 8.5. Remote (incoming) tunnel

Tunnels can also be defined for connection profiles in the Connection Broker configuration file. The defined

tunnels are opened automatically when a connection with the profile is made. The following is an example

from a ssh-broker-config.xml file:


...

<tunnels>

<remote-tunnel type="tcp"

listen-port="11000"

dst-host="localhost"

dst-port="99" />

...

</tunnels>

</profile>


163



8.3 FTP Tunneling

FTP tunneling is an extension to the generic tunneling mechanism. The FTP control channel can be secured

by using generic port forwarding, but since the FTP protocol requires creating separate TCP connections for

the files to be transferred, all the files would be transferred unencrypted when using generic port forwarding,

as these separate TCP connections would not be forwarded automatically.

To protect also the transferred files, FTP forwarding can be used instead. It works similarly to generic port

forwarding, except that the FTP forwarding code monitors the forwarded FTP control channel and dynamically

creates new port forwardings for the data channels as they are requested.

FTP tunneling works for both local and remote tunnels, but it must always be explicitly requested.

On the command line, this can be done by using a command with the following syntax:

sshclient$ sshg3 -L ftp/1234:localhost:21 username@sshserver

FTP tunnels can also be defined for connection profiles in the Connection Broker configuration file. The fol-

lowing is an example from a ssh-broker-config.xml file:


...

<tunnels>

<local-tunnel type="ftp"

listen-port="1234"

dst-host="127.0.0.1"

dst-port="21" />

...

</tunnels>

</profile>

The FTP connection can then be made with a command like the following:

sshclient$ ftp localhost 1234

The FTP connection to port 1234 on client is now tunneled to port 21 on the Secure Shell server.



The typical use case is that the FTP client is located on the same host as SSH Tectia Client and the FTP

server is on the same host as the Secure Shell server. However, other configurations are also supported.


Tunneling164

Where end-to-end encryption of FTP data channels is desired, the FTP server and Secure Shell server need

to reside on the same host, and the FTP client and SSH Tectia Client will likewise need to reside on the same

host.

Note

Consider using sftpg3 or scpg3 instead of FTP forwarding to secure file transfers. It will require

less configuration than FTP forwarding, since SSH Tectia Server already has sft-server-g3 as a

subsystem, and sftpg3 and scpg3 clients are included with SSH Tectia Client. Managing remote

user restrictions on the server machine will be easier, since you do not have to do it also for FTP.

8.4 X11 Forwarding

X11 forwarding is a special case of remote tunneling.

SSH Tectia Server supports X11 forwarding on Unix platforms. SSH Tectia Client supports X11 forwarding

on both Unix and Windows platforms.

Internet

X11 tunnel

SSH Tectia Clientwith 3rd-party X Server

SSH Tectia Server (Unix)with X Client applications

Figure 8.6. X11 forwarding

X11 forwarding needs to be enabled in the client by setting the following line in the ssh-broker-config.xml

file:

<forwards>

<forward type="X11" state="on"/>

</forwards>

With the Windows GUI, X11 forwarding can be enabled under Profile Settings → Tunneling. See Sec-

tion 4.1.5.7.

To test that X11 forwarding works, log into the remote system and type xclock &. This starts an X clock

program that can be used for testing the forwarding connection. If the X clock window is displayed properly,

you have X11 forwarding working.


1658.4 X11 Forwarding

Note

Do not set the DISPLAY variable on the client. You will most likely disable encryption. (X connections

forwarded through Secure Shell use a special local display setting.)

8.5 Agent Forwarding

Agent forwarding is a special case of remote tunneling. In agent forwarding, Secure Shell connections and

public-key authentication data are forwarded from one server to another without the user having to authenticate

separately for each server. Authentication data does not have to be stored on any other machine than the local

machine, and authentication passphrases or private keys never go over the network.

SSH Tectia Client provides authentication agent functionality on Windows and Unix platforms. SSH Tectia

Server supports agent forwarding on Unix platforms. Thus, the start point of the agent forwarding chain can

be a Windows or Unix host, but all destination hosts must be Unix hosts. The hosts in the middle of the for-

warding chain must have both the Secure Shell client and server components installed.

Internet

Agent tunnel

SSH Tectia Client SSH Tectia Server (Unix)SSH Tectia Client (Unix)

Internet

Agent tunnel

SSH Tectia Server (Unix)

Figure 8.7. Agent forwarding

Agent forwarding needs to be enabled in the client by setting the following line in the ssh-broker-config.xml

file:

<forwards>

<forward type="agent" state="on" />

</forwards>


Tunneling166

Appendix A Command-Line ToolsSSH Tectia Client is shipped with several command-line tools. Their functionality is briefly explained in the

following appendices.

For information on the command-line options of SSH Tectia Client GUI (ssh-client-g3.exe) on Windows,

see Section 5.2.

ssh-broker-g3

ssh-broker-g3 -- SSH Connection Broker - Generation 3

Synopsisssh-broker-g3 [-f, --config-file=FILE] [-D, --debug=LEVEL] [-l, --debug-log-file=FILE]

[--exit] [--reconfig] [--no-gui] [--start-gui] [-h] [-V]

Description

ssh-broker-g3 (ssh-broker-g3.exe on Windows) is a component of SSH Tectia Client. It handles all

cryptographic operations and authentication-related tasks for the SSH Tectia Client programs sshg3, scpg3,

sftpg3, and ssh-client-g3.exe (on Windows only).

ssh-broker-g3 uses the Secure Shell version 2 protocol to communicate with a Secure Shell server.

You can start the Connection Broker manually by using the ssh-broker-g3 command. This starts ssh-

broker-g3 in the background and all following uses of sshg3, sftpg3, or scpg3 will connect via this instance

of the Connection Broker instead of starting a new Broker session.

If a command-line client (sshg3, sftpg3, or scpg3) is started when the Connection Broker is not running in

the background, the client starts the Broker in run-by-need mode. In this mode, ssh-broker-g3 will exit after

the last client has disconnected.

If there is an ssh-broker-g3 process running in the run-by-need mode and the Connection Broker is started

from the command line, the new ssh-broker-g3 process sends a message to the old ssh-broker-g3 process


167

to change from the run-by-need mode to the background mode, keeping the Broker running after the clients

disconnect.

Authentication

The Connection Broker operates automatically as an authentication agent, storing user's public keys and for-

warding the authentication over Secure Shell connections. Key pairs can be created with ssh-keygen-g3.

The public key pairs used for user authentication are by default stored in the $HOME/.ssh2 directory

("%USERPROFILE%\Application Data\SSH\UserKeys" on Windows). See the section called “Files” for

more information.

The Connection Broker automatically maintains and checks a database containing the public host keys used

for authenticating Secure Shell servers. When logging in to a server host for the first time, the host's public

key is stored in the user's $HOME/.ssh2/hostkeys directory ("%USERPROFILE%\Application

Data\SSH\HostKeys" on Windows). See the section called “Files” for more information.

Options

The most important options of ssh-broker-g3 are the following:

-f, --config-file=FILE

Reads the Connection Broker configuration file from FILE instead of the default location.

-D, --debug=LEVEL

Sets the debug level string to LEVEL.

-l, --debug-log-file=FILE

Dumps debug messages to FILE.

--exit

Make the currently running Connection Broker exit. This will terminate all connections.

--reconfig

Re-reads the configuration file (ssh-broker-config.xml) and takes it into use.

--no-gui

On Windows, starts the Connection Broker but does not start the GUI.

This option is used internally when a command-line client is started when the Connection Broker is not

running.

--start-gui

On Windows, starts the Connection Broker GUI if it is not already running.

-V, --version

Displays program version and exits.


Command-Line Tools168

-h, --help

Displays a short summary of command-line options and exits.

On Windows, the help is only shown when running "ssh-broker-cli.exe -h" directly from the

"C:\Program Files\SSH Communications Security\SSH Tectia\SSH Tectia AUX\Support Bin-

aries" directory. Normally, ssh-broker-cli.exe is never run by the user, but it is automatically called

by ssh-broker-g3.exe.

Files

ssh-broker-g3 uses the following files:

$HOME/.ssh2/ssh-broker-config.xml

This is the user-specific configuration file used by ssh-broker-g3 (and sshg3, scpg3, and sftpg3).

The format of this file is described in ssh-broker-config(5). This file does not usually contain any sensitive

information, but the recommended permissions are read/write for the user, and not accessible for others.

On Windows, the user-specific configuration file is located in "%USERPROFILE%\Application

Data\SSH\ssh-broker-config.xml".

$HOME/.ssh2/random_seed

This file is used for seeding the random number generator. It contains sensitive data and its permissions

should be read/write for the user and not accessible for others. This file is created the first time the program

is run and it is updated automatically. You should never need to read or modify this file.

On Windows, the random seed file is located in "%USERPROFILE%\Application Data\SSH\random_seed".

$HOME/.ssh2/identification

This file contains information on public keys and certificates used for user authentication when contacting

remote hosts.

With SSH Tectia Client 5.x, using the identification file is not necessary if all user keys are stored



$HOME/.ssh2 directory.

The identification file contains a list of private key filenames each preceded by the keyword IdKey. An

example file is shown below:

IdKey mykey

This directs the Connection Broker to use $HOME/.ssh2/mykey when attempting login using public-key

authentication.


169Files

The files are by default assumed to be in the $HOME/.ssh2 directory, but also an absolute or a relative

path to the key file can be given. If there is more than one IdKey, they are tried in the order that they

appear in the identification file.

On Windows, the identification file is located in "%USERPROFILE%\Application Data\SSH\User-

Keys\identification". The default user key directory is "%USERPROFILE%\Application

Data\SSH\UserKeys".

$HOME/.ssh2/hostkeys

This is the user-specific directory for storing the public keys of server hosts. You are prompted to accept

new or changed keys automatically when you connect to a server, unless you have set strict-host-

key-checking to yes in the ssh-broker-config.xml file. You should verify the key fingerprint before

accepting new or changed keys.

When the host key is received during the first connection to a remote host (or when the host key has

changed) and you choose to save the key, its filename is stored in hashed format. The hashed host key

format is a security feature to make address harvesting on the hosts difficult.

If you are adding the keys manually, the keys should be named with key_<port>_<host>.pub pattern,

where <port> is the port the Secure Shell server is running on and <host> is the hostname you use when

connecting to the server (for example, key_22_alpha.example.com.pub).

If both the hashed and clear-text format keys exist, the hashed format takes precedence.

Note that the identification is different based on the host and port the client is connecting to. For example,

the short hostname alpha is considered different from the fully qualified domain name alpha.ex-

ample.com. Also a connection with an IP, for example 10.1.54.1, is considered a different host, as is

a connection to the same host but different port, for example alpha.example.com#222.

On Windows, the user-specific host key files are located in "%USERPROFILE%\Application

Data\SSH\HostKeys".

For more information on host keys, see Section 6.1.

$HOME/.ssh2/hostkeys/salt

This is the initialization file for hashed host key names.

On Windows, the salt file is located in "%USERPROFILE%\Application Data\SSH\HostKeys\salt".

/etc/ssh2/hostkeys

If a host key is not found in the user-specific $HOME/.ssh2/hostkeys directory, this is the next location

to be checked for all users. Host key files are not automatically put here but they have to be updated

manually by the system administrator (root) or by using SSH Tectia Manager.



If the administrator obtains the host keys by connecting to each host, the keys will be in the hashed format.

In this case, also the administrator's $HOME/.ssh2/hostkeys/salt file has to be copied to the

/etc/ssh2/hostkeys directory.

On Windows, the system-wide host key files are located in %ALLUSERSPROFILE%\Application

Data\SSH\HostKeys.

/etc/ssh2/hostkeys/salt

This is the initialization file for hashed host key names. The file has to be copied here manually by the

same administrator that obtains the host keys.

On Windows, the salt file for all users is located in "%ALLUSERSPROFILE%\Application

Data\SSH\HostKeys\salt".

$HOME/.ssh/known_hosts

This is the default file used by OpenSSH clients that contains the public key data of known server hosts.

It is supported also by SSH Tectia Client from version 5.1 onwards. The location of the file must be

defined in the ssh-broker-config.xml file by using the known-hosts element. See known-hosts.

The file is never automatically updated by SSH Tectia Client. New host keys are always stored in the

SSH Tectia $HOME/.ssh2/hostkeys directory.

The file contains one known host per row. The format of each row is the following:

hostnames bits exponent modulus comment


For more information on the format of this file, see the OpenSSH sshd(8) man page.

$HOME/.ssh2/authorized_keys (on the server host)

This directory is the default location used by SSH Tectia Server 5.x for the user public keys that are au-

thorized for login.

On SSH Tectia Server 5.x on Windows, the default directory for user public keys is %USERPRO-

FILE%\.ssh2\authorized_keys.

$HOME/.ssh2/authorization (on the server host)

This is the default file used by SSH Tectia Server 4.x (and SSH Secure Shell server 3.x) that lists the user

public keys that are authorized for login. The file can be optionally be used with SSH Tectia Server 5.x

as well.

On Windows, the authorization file is by default located in %USERPROFILE%\.ssh2\authorization.

For information on the format of this file, see Section 6.4.


171

$HOME/.ssh/authorized_keys (on the server host)

This is the default file used by OpenSSH server that contains the user public keys that are authorized for

login.

For information on the format of this file, see the OpenSSH sshd(8) man page.

sshg3

sshg3 -- Secure Shell terminal client - Generation 3

Synopsissshg3 [options...]

[user@] host [#port]

[command]

Description

sshg3 (sshg3.exe on Windows) is a program for logging in to a remote machine and executing commands

on a remote machine. sshg3 provides secure, encrypted communication channels between two hosts over an

unsecured network. It can be used to replace the unsecured rlogin, rsh, and telnet programs. Also X11

connections and arbitrary TCP/IP ports can be forwarded over secure channels with sshg3.

sshg3 connects to the specified remote host using the Secure Shell version 2 protocol. The users must prove

their identities to the remote machine using some authentication method.

sshg3 launches ssh-broker-g3 as a transport. ssh-broker-g3 will ask for passwords or passphrases if they

are needed for authentication. sshg3 uses the configuration specified in the ssh-broker-config.xml file.

When the user's identity has been accepted by the server, the server either executes the given command, or

logs in to the machine and gives the user a normal shell. All communication with the remote command or

shell will be automatically encrypted.

If no pseudo-tty has been allocated, the session is transparent and can be used to securely transfer binary data.

The session terminates when the command or shell on the remote machine exits and all X11 and TCP/IP

connections have been closed. The exit status of the remote program is returned as the exit status of sshg3.

Agent Forwarding (Unix)

ssh-broker-g3 acts as an authentication agent, and the connection to the agent is automatically forwarded

to the remote side unless disabled in the ssh-broker-config.xml file or on the sshg3 command line (with

the -a option).



X11 Forwarding

If the user is using X11 (the DISPLAY environment variable is set), the connection to the X11 display can be

automatically forwarded to the remote side in such a way that any X11 programs started from the shell (or

command) will go through the encrypted channel, and the connection to the real X server will be made from

the local machine. The user should not manually set DISPLAY. X11 connection forwarding can be allowed in

the ssh-broker-config.xml file or on the sshg3 command line (with the +x option). By default, X11 for-

warding is disabled.

The DISPLAY value set by sshg3 will point to the server machine, but with a display number greater than

zero. This is normal, and happens because sshg3 creates a "proxy" X server on the server machine for for-

warding the connections over the encrypted channel.

sshg3 will also automatically set up the Xauthority data on the server machine. For this purpose, it will gen-

erate a random authentication cookie, store it in the Xauthority data on the server, and verify that any forwarded

connections carry this cookie and replace it with the real cookie when the connection is opened. The real au-

thentication cookie is never sent to the server machine (and no cookies are sent in the plain).

TCP Port Forwarding

Forwarding of arbitrary TCP/IP connections over the secure channel can be specified either in the ssh-broker-

config.xml file or on the sshg3 command line (with the -L and -R options).

Options

Command-line options override the settings in the ssh-broker-config.xml file if the same option has been

configured in both places. The following options are available:

-a, --no-agent-forwarding

Disables authentication agent forwarding.

+a

Enables authentication agent forwarding. This is the default value.

-B, --batch-mode

Uses batch mode. Fails authentication if it requires user interaction on the terminal.

-D, --debug=LEVEL

Sets the debug level. LEVEL is a number from 0 to 99, where 99 specifies that all debug information should

be displayed. This should be the first argument on the command line.

-e, --escape-char=CHAR

Sets escape character (none: disabled, default: ~).

-f

Forks into background mode (Unix).


173X11 Forwarding

-g, --gateway

Gateways ports, which means that also other hosts may connect to locally forwarded ports. This option

has to be specified before the "-L" option. Note the logic of + and - in this option.

+g

Does not gateway ports. Listens to tunneling connections originating only from the localhost. This is the

default value. Note the logic of + and - in this option.

-l, --user=USERNAME

Logs in using this username.

-L [protocol/][listen-address:]listen-port:dst-host:dst-port

Forwards a port on the local (client) host to a remote destination host and port.

This allocates a listener port (listen-port) on the local client. Whenever a connection is made to this

listener, the connection is tunneled over Secure Shell to the remote server and another connection is made

from the server to a specified destination host and port (dst-host:dst-port). The connection from the

server onwards will not be secure, it is a normal TCP connection.

Giving the argument protocol enables protocol-specific forwarding. The protocols implemented are

tcp (default, no special processing), ftp (temporary forwarding is created for FTP data channels, effect-

ively securing the whole FTP session), and socks.

With the socks protocol, the syntax of the argument is "-L socks/[listen-address:]listen-port".

When this is set, SSH Tectia Client will act as a SOCKS server for other applications, creating forwards

as requested by the SOCKS transaction. This supports both SOCKS4 and SOCKS5.

If listen-address is given, only that interface on the client is listened. If it is omitted, all interfaces are

listened.

-n

Redirects input from /dev/null (Unix).

-o option

Processes an option as if it was read from a SSH Tectia Client 4.x-style configuration file. The supported

options are ForwardX11 and ForwardAgent (for example, -o "ForwardX11=yes").

-p, --port=PORT

Connects to this port on the remote host. A Secure Shell server must be listening on the same port.

-R [protocol/][listen-address:]listen-port:dst-host:dst-port

Forwards a port on the remote (server) host to a destination host and port on the local side.

This allocates a listener port (listen-port) on the remote server. Whenever a connection is made to

this listener, the connection is tunneled over Secure Shell to the local client and another connection is

made from the client to a specified destination host and port (dst-host:dst-port). The connection from

the client onwards will not be secure, it is a normal TCP connection.



Giving the argument protocol enables protocol-specific forwarding. The protocols implemented are

tcp (default, no special processing) and ftp (temporary forwarding is created for FTP data channels,

effectively securing the whole FTP session).

If listen-address is given, only that interface on the server is listened. If it is omitted, all interfaces

are listened.

-s, --subsystem

Sets the executed command to be a subsystem rather than a shell executable.

-S, --no-session-channel

Does not request a session channel. This can be used with port-forwarding requests if a session channel

(and tty) is not needed, or the server does not give one.

+S

Requests a session channel. This is the default value.

-t, --tty

Allocates a tty even if a command is given.

-v, --verbose

Uses verbose mode (equal to -D 2).

-w

Does not try an empty password.

+w, --try-empty-password

Tries an empty password.

+x, +X

Enables X11 connection forwarding.

-x, -X, --no-x11-forwarding

Disables X11 connection forwarding. This is the default value.

-z, --broker-log-file=FILE

Sets the Connection Broker log file to FILE. This option works only if ssh-broker-g3 gets started by

this process).

--abort-on-failing-tunnel

Aborts if creating a tunnel listener fails (for example, if the port is already reserved).

--password= PASSWORD|file://PASSWORDFILE|extprog://PROGRAM

Sets user password that the client will send as a response to password authentication. The PASSWORD can

be given directly as an argument to this option (not recommended), or a path to file containing the password

can be given, or a path to a program or a script that outputs the password can be given.


175

Caution

Supplying the password on the command line is not a secure option. For example, in a multi-

user environment, the password given directly on the command line is trivial to recover from

the process table. You should set up a more secure way to authenticate. For non-interactive

batch jobs, it is more secure to use public-key authentication without a passphrase, or host-based

authentication. At a minimum, use a file or a program to supply the password.

-V, --version


-h, --help


The command can be either of the following:

remote_command [arguments] ...

Runs the command on a remote host.

-s service

Enables a service in remote server.

Escape Sequences

sshg3 supports escape sequences to manage a running session. For an escape sequence to take effect, it must

be typed directly after a newline character (press Enter first). The escape sequences are not displayed on

screen during typing.

The following escape sequences are supported:

~.

Terminates the connection.

~Ctrl-Z

Suspends the session.

~~

Sends the escape character literally.

~#

Lists forwarded connections.

~-

Disables the escape character irrevocably.



~?

Displays a summary of escape sequences.

~r

Initiates rekeying manually.

~s

Gives connection statistics, including server and client version, packets in, packets out, compression, key

exchange algorithms, public-key algorithms, and symmetric ciphers.

~c

Gives statistics for individual channels (data window sizes etc). This is for debugging purposes.

~V

Dumps the client version number to stderr (useful for troubleshooting).

Environment Variables

Upon connection, the Secure Shell server will automatically set a number of environment variables that can

be used by sshg3. The exact variables set depend on the Secure Shell server. The following variables can be

used by sshg3:

DISPLAY

The DISPLAY variable indicates the location of the X11 server. It is automatically set by the server to

point to a value of the form hostname:n where hostname indicates the host on which the server and the

shell are running, and n is an integer greater or equal than 1. sshg3 uses this special value to forward

X11 connections over the secure channel.

The user should normally not set DISPLAY explicitly, as that will render the X11 connection unsecured

(and will require the user to manually copy any required authorization cookies).

HOME

The user's home directory.

LOGNAME

Synonym for USER; set for compatibility with systems using this variable.

MAIL

The user's mailbox.

PATH

Set to the default PATH, depending on the operating system or, on some systems, /etc/environment

or /etc/default/login.

SSH_SOCKS_SERVER

The address of the SOCKS server used by sshg3.


177Environment Variables

SSH2_AUTH_SOCK

If this exists, it is used to indicate the path of a Unix-domain socket used to communicate with the authen-

tication agent (or its local representative).

SSH2_CLIENT

Identifies the client end of the connection. The variable contains three space-separated values: client IP

address, client port number, and server port number.

SSH2_ORIGINAL_COMMAND

This will be the original command given to sshg3 if a forced command is run. It can be used, for example,

to fetch arguments from the other end. This does not have to be a real command, it can be the name of a

file, device, parameters or anything else.

SSH2_TTY

This is set to the name of the tty (path to the device) associated with the current shell or command. If the

current session has no tty, this variable is not set.

TZ

The time-zone variable is set to indicate the present time zone if it was set when the server was started

(the server passes the value to new connections).

USER

The name of the user.

For a list of varibles set by SSH Tectia Server, see the ssh-server-g3(8) man page.

Exit Values

On normal execution, sshg3 exits with the status of the command run. On successful runs this is normally 0

(zero).

If sshg3 encounters an error, you usually see the reason in an error message. In this case, the exit value is 1.

scpg3

scpg3 -- Secure Shell file copy client - Generation 3

Synopsisscpg3 [options...]

[[user@] src_host [#port]:]src_file...

[[user@] dst_host [#port]:]dst_file_or_dir



Description

scpg3 (scpg3.exe on Windows) is used to securely copy files over the network. scpg3 launches ssh-broker-

g3 to provide a secure transport using the Secure Shell version 2 protocol. ssh-broker-g3 will ask for pass-

words or passphrases if they are needed for authentication. scpg3 uses the configuration specified in the ssh-

broker-config.xml file.

Any filename may contain a host, user, and port specification to indicate that the file is to be copied to or

from that host. Copies between two remote hosts are permitted. The remote host(s) must be running a Secure

Shell version 2 server with the sftp-server subsystem enabled.

The host parameter can optionally be enclosed in square brackets ([]) to allow the use of semicolons. The

file argument can contain simple wild cards: asterisk (*) for any number of characters and question mark

(?) for any one character.

Options

The following command-line parameters can be used to further specify the scpg3 options.

-a[arg]

Transfers files using the ASCII mode, that is, newlines will be converted on the fly. See the ascii com-

mand in the section called “Commands”.

If the server does not advertise the newline convention, you can give it a hint by giving an argument after

-a. The default is to set the destination newline convention, but you can specify either one by prefixing

the argument with src: or dest: for source or destination convention, respectively. The available con-

ventions are dos, unix, and mac, using \r\n, \n, and \r as newlines, respectively. An example is shown

below:

$ scpg3 -asrc:unix -adest:dos src_host:src_file dest_host:dest_file

-b buffer_size

Defines maximum buffer size for one request (default: 32768 bytes).

-B, --batch-mode

Uses batch mode.

-d

Forces target to be a directory.

-D, --debug=LEVEL



-I, --interactive

Prompts whether to overwrite an existing destination file (does not work with -B).


179Description

-N max_requests

Defines maximum number of requests sent in parallel (default: 10).

-O, --offset=r<offset>|w<offset>|l<length>|t<length>

Sets offset. Offset r<offset> specifies the start offset in the source file. Offset w<offset> specifies the

start offset in the destination file. Length l<length> specifies the amount of data to be copied. Truncate

length t<length>, if given, specifies the length to which the destination file is truncated or expanded

after the file data has been copied.

-p

Preserves file attributes (Unix) and timestamps (Unix and Windows).

-P port

Connects to this Secure Shell port on the remote machine (default: 22).

-q

Uses quiet mode (only fatal errors are shown).

-Q

Does not show progress indicator.

-r

Recurses subdirectories.

-u, --unlink-source

Removes source files after copying (file move).

-v, --verbose


--fips

Uses the FIPS mode.

--force-lower-case

Destination filename will be converted to lowercase characters.

--overwrite [={yes|no}]

Decides whether to overwrite existing destination file(s) (default: yes).







Caution






--plugin-path=PATH

Sets plugin path to PATH. This is only used in the FIPS mode.

--prefix=PREFIX

Adds prefix to filename during the file transfer. The prefix is removed after the file has been successfully

transferred.

--statistics[=yes|no|simple]

Chooses the statistics style (default: yes).

--streaming[=yes|no|force]

Uses streaming in file transfer, if server supports it. Files smaller than buffer_size are not transferred

using streaming. Use force with small files (default: yes).

--checksum[=yes|no|md5|sha1|md5-force|sha1-force|checkpoint]

Uses MD5 or SHA-1 checksums or a separate checkpoint database to determine the point in the file where

file transfer can be resumed. Files smaller than buffer_size are not checked. Use md5-force or sha1-

force with small files (default: yes, i.e. use MD5 checksums).

-W, --whole-file

Does not try incremental checks (default: no, i.e. try incremental checks).

--checkpoint=s<seconds>

Time interval between checkpoint updates (default: 10 seconds).

--checkpoint=b<bytes>

Byte interval between checkpoint updates (default: 10 MB).

-V, --version


-?, -h, --help


Exit Values

scpg3 returns the following values based on the success of the operation:


181Exit Values

0 Operation was successful.

1 Internal error.

2 Connection aborted by the user.

3 Destination is not a directory, but a directory was specified by the user.

4 Connecting to the host failed.

5 Connection lost.

6 File does not exist.

7 No permission to access file.

8 Undetermined error from sshfilexfer.

101 Wrong command-line arguments specified by the user.

Examples

Copy files from your local system to a remote Unix system:

$ scpg3 localfile user@remotehost:/dest/dir/for/file/

Copy files from your local system to a remote Windows system:

$ scpg3 localfile user@remotehost:/C:/dest/dir/for/file/

Copy files from a remote system to your local disk:

$ scpg3 user@remotehost:/dir/for/file/remotefile /dest/dir/for/file

sftpg3

sftpg3 -- Secure Shell file transfer client - Generation 3

Synopsissftpg3 [options...]

[user@] host [#port]

Description

sftpg3 (sftpg3.exe on Windows) is an FTP-like client that can be used for file transfer over the network.

sftpg3 launches ssh-broker-g3 to provide a secure transport using the Secure Shell version 2 protocol.

ssh-broker-g3 will ask for passwords or passphrases if they are needed for authentication. sftpg3 uses the

configuration specified in the ssh-broker-config.xml file.

However, it should be noted that sftpg3 is not designed to be a drop-in replacement for an FTP client. It is

an application that implements secure file transfer functionality and has most features that common FTP ap-

plications have.

To connect to a remote host using sftpg3, the remote host must be running a Secure Shell version 2 server

with the sftp-server subsystem enabled.



Options

The following options are available:

-b buffer_size

Defines maximum buffer size for one request (default: 32768 bytes).

-B batch_file

Uses batch file.

-D, --debug=LEVEL



-N max_requests

Defines maximum number of requests sent in parallel (default: 10).

-P port

Connects to this Secure Shell port on the remote machine (default: 22).

-v, --verbose


--fips

Uses the FIPS mode.





Caution






--plugin-path=PATH

Sets plugin path to PATH. This is only used in the FIPS mode.

-V, --version


-?, -h, --help



183Options

Commands

When sftpg3 is ready to accept commands, it will display the prompt sftp>. The user can then enter any of

the following commands:

open [ <hostname> | -l ]

Tries to connect the remote side to the host <hostname>.

Options:

-l

Connects the remote side to the local filesystem (which does not require a server).

lopen [ <hostname> | -l ]

Tries to connect the local side to the host <hostname>. If this is successful, <lls> and friends will operate

on the filesystem on that host.

Options:

-l

Connects the local side to the local filesystem (which does not require a server).

close

Closes the remote connection.

lclose

Closes the local connection.

quit

Quits the application.

cd <directory>

Changes the current remote working directory.

lcd <directory>

Changes the current local working directory.

pwd

Prints the name of the current remote working directory.

lpwd

Prints the name of the current local working directory.

ls [-R] [-l] [-S] [-r] [-p] [ <file> ... ]

Lists the names of files on the remote server. For directories, contents are listed. If no arguments are

given, the contents of current working directory are listed.

Options:



-R

Directory trees are listed recursively. By default, subdirectories of the arguments are not visited.

-l

Permissions, owners, sizes and modification times are also shown (long format).

-S

Sorting is done based on file sizes (default: alphabetically).

-r

The sort order is reversed.

-p

Only one page of listing is shown at one time.

lls [-R] [-l] [-S] [-r] [-p] [ <file> ... ]

Same as ls, but operates on local files.

get [-p] [--preserve-attributes] [-u] [--unlink-source] [-I] [--interactive] [--overwrite]

[--checksum] [-W] [--whole-file] [--checkpoint] [--streaming] [--force-lower-case] [--

prefix=PREFIX] [ <file> ... ]

Transfers the specified files from the remote end to the local end. Directories are recursively copied with

their contents.

Options:

-p, --preserve-attributes

Tries to retain permissions and timestamps.

-u, --unlink-source

Removes the source file after file transfer. Also directories are removed, if they become empty (move

mode).

-I, --interactive

Prompts whether to overwrite an existing destination file (does not work with batch mode).

--overwrite[=yes|no]

Decides whether to overwrite existing destination file(s) (default: yes).

--checksum[=yes|no|md5|sha1|md5-force|sha1-force|checkpoint]

Uses MD5 or SHA-1 checksums or a separate checkpoint database to determine the point in the file

where file transfer can be resumed. Files smaller than buffer_size are not checked. Use md5-force

or sha1-force with small files (default: yes, i.e. use MD5 checksums).

-W, --whole-file

Does not try incremental checks (default: no, i.e. try incremental checks).


185

--checkpoint=s<seconds>

Time interval between checkpoint updates (default: 10 seconds).

--streaming[=yes|no|force]

Uses streaming in file transfer if the server supports it. Files smaller than buffer_size are not

transferred using streaming. Use force with small files (default: yes).

--checkpoint=b<bytes>

Byte interval between checkpoint updates (default: 10 MB).

--force-lower-case

Destination filename will be converted to lowercase characters.

--prefix=PREFIX

Adds prefix PREFIX to filename during the file transfer. The prefix is removed after the file has been

successfully transferred.

mget [options] [ <file> ... ]

Synonymous to get.

put [options] [ <file> ... ]

Transfers the specified files from the local end to the remote end. Directories are recursively copied with

their contents.

Options are the same as for get.

mput [options][ <file> ... ]

Synonymous to put.

rm [-I] [--interactive] [ <file> ... ]

Tries to delete file or directory specified in <file>. Directories are removed recursively.

Options:

-I, --interactive

Prompts whether to remove a file or directory (does not work with batch mode).

lrm [options] [ <file> ... ]

Same as rm, but operates on local files.

mkdir <directory>

Tries to create the directory specified in <directory>.

lmkdir <directory>

Same as mkdir, but operates on local files.



rmdir <directory>

Tries to delete the directory specified in <directory>.

lrmdir <directory>

Same as rmdir, but operates on local files.

rename <oldfile> <newfile>

Tries to rename the <oldfile> to <newfile>. If <newfile> already exists, the files are left intact.

lrename <oldfile> <newfile>

Same as rename, but operates on local files.

readlink <path>

Provided that <path> is a symbolic link, shows where the link is pointing to.

lreadlink <path>

Same as readlink, but operates on local files.

symlink <targetpath> <linkpath>

Creates symbolic link <linkpath>, which will point to <targetpath>.

lsymlink <targetpath> <linkpath>

Same as symlink, but operates on local files.

ascii [-s] [<remote_nl_conv>] [<local_nl_conv>]

Sets the transfer mode to ASCII. <remote_nl_conv> sets a remote newline convention. <local_nl_conv>

operates on the local side, but is not as useful (the correct local newline convention is usually compiled

in, so this is mainly for testing). Please note that these are only hints for the underlying transfer layer,

which tries to use the newline convention given by the server wherever possible. You can set either of

these to ask, which will cause sftp to prompt you for the newline convention when needed. The available

conventions are dos, unix, and mac, using \r\n, \n, and \r as newlines, respectively.

Options:

-s

Only shows current newline convention. Does not set the transfer mode to ASCII.

binary

Files will be transfered in binary mode.

auto

File transfer mode will be selected automatically from the file extension.

setext [ <extension> ... ]

Sets the file extensions that will be ASCII in the auto transfer mode. Normal zsh-fileglob regexps can be

used in the file extensions.


187

getext

Displays the extensions that will be ASCII in the auto transfer mode.

lsroots

Dumps the virtual roots of the server. (This is a VShell extension. Without this you cannot know the

filesystem structure of a VShell server.)

llsroots

Same as lsroots, but operates on local files (when the local side has been opened to a VShell server).

chmod [-R] [-f] [-v] OCTAL-MODE [<file> ...], chmod [-R] [-f] [-v] [ugoa][+-=][rwxs]

[<file> ...]

Sets file permissions of the specified file or files to the bit pattern OCTAL-MODE or changes permissions

according to the symbolic mode [ugoa][+-=][rwxs]. Only one symbolic mode combination is supported.

Options:

-R

Recursively changes files and directories.

-f

Uses silent mode (error messages are suppressed).

-v

Uses verbose mode (lists every file processed).

lchmod [-R] [-f] [-v] OCTAL-MODE [<file> ...], lchmod [-R] [-f] [-v] [ugoa][+-=][rwxs]

[<file> ...]

Same as chmod, but operates on local files.

digest [-H] [--hash] [-o] [--offset] [-l] [--length] <file>

Calculates MD5 or SHA-1 digest over file data.

Options:

-H, --hash=[md5|sha1]

Use md5 or sha1 hash alorithm (default: md5).

-o, --offset=OFFSET

Start reading from file offset OFFSET.

-l, --length=LENGTH

Read LENGTH bytes of file data.

ldigest [-H] [--hash] [-o] [--offset] [-l] [--length] <file>

Same as digest, but operates on local files.



setperm <fileperm[:dirperm]>

Sets the default file or directory permission bits for upload. (Prefix fileperm with p to preserve permissions

of existing files or directories.)

debug [disable | no | <debuglevel>]

Disables or enables debug. With disable or no, debugging is disabled. Otherwise, sets <debuglevel>

as debug level string, as per command-line option -D.

verbose

Enables verbose mode (identical to the debug 2 command). You may later disable verbose mode by

debug disable.

help [ <topic> ]

If <topic> is not given, lists the available topics. If <topic> is given, outputs available online help about

the topic.

helpall

Outputs available online help about all topics.

Command Interpretation

sftpg3 understands both backslashes (\) and quotation marks (") on the command line. A backslash can be

used for ignoring the special meaning of any character in the command-line interpretation. It will be removed

even if the character it precedes has no special meaning.

Quotation marks can be used for specifying filenames with spaces.

Also, if you do 'get .' or 'put .' you will get or put every file in the current directory and possibly override

files in your current directory.

sftpg3 supports wild cards (also known as glob patterns) given to commands chmod, lchmod, ls, lls, rm,

lrm, get, and put.

Exit Values

sftpg3 returns the following values based on the success of the operation:

0 Operation was successful.

1 Internal error.

2 Connection aborted by the user.

3 Destination is not a directory, but a directory was specified by the user.

4 Connecting to the host failed.

5 Connection lost.

6 File does not exist.

7 No permission to access file.

8 Undetermined error from sshfilexfer.

101 Wrong command-line arguments specified by the user.


189Command Interpretation

In batch mode, the exit value is based on the succes of the last operation.

ssh-convert-ftp (EFT Expansion Pack on Unix)

ssh-convert-ftp (EFT Expansion Pack on Unix) -- Convert unsecured FTP connections to secured SFTP

Synopsisssh-convert-ftp [options...] COMMAND [arguments...]

Description

ssh-convert-ftp is a component of SSH Tectia Client with EFT Expansion Pack on Unix.

The ssh-convert-ftp command runs the specified command with the given arguments. The command and

its child processes will have automatic FTP-SFTP conversion and FTP tunneling enabled. Depending on the

filter rules configured for the SSH Tectia Connection Broker, the connections may then be automatically

converted from FTP to SFTP, or automatically tunneled.

For an example of the filter rules, see the ssh-broker-config-example-ftp-sftp.xml file in the /etc/ssh2

directory.

Options


-D, --debug=LEVEL

Sets the debug level string to LEVEL.

-N, --no-fallback

Disallows unsecured connections if the Connection Broker is down.

-h, --help


Examples

Start an FTP session to ftp.example.org with FTP-SFTP conversion enabled:

$ ssh-convert-ftp ftp ftp.example.org

Start a bash shell session with FTP-SFTP conversion enabled for all commands:

$ ssh-convert-ftp bash



Exit Values

If a command was invoked, ssh-convert-ftp returns the exit status of that command. If there was an error

executing the command, the exit value is 127.

ssh-keygen-g3

ssh-keygen-g3 -- authentication key pair generator

Synopsisssh-keygen-g3 [options...]

[key1 key2...]

Description

ssh-keygen-g3 (ssh-keygen-g3.exe on Windows) is a tool that generates and manages authentication keys

for Secure Shell. Each user wishing to use a Secure Shell client with public-key authentication can run this

tool to create authentication keys. Additionally, the system administrator can use this to generate host keys

for the Secure Shell server.

By default, if no path for the key files is specified, the key pair is generated under the user's home directory

($HOME/.ssh2 on Unix, "%USERPROFILE%\Application Data\SSH\UserKeys" on Windows). If no filename

is specified, the key pair is likewise stored under the user's home directory with such filenames as

id_dsa_1024_a and id_dsa_1024_a.pub.

Options


-b bits

Specifies the length of the key in bits (default 2048).

-t dsa|rsa

Selects the type of the key. Valid options are dsa (default) and rsa.

--fips-mode [={yes|no}]

Generates the key using the FIPS mode for the cryptographic library. The default is no.

--fips-crypto-dll-path path

Specifies the location of the FIPS cryptographic DLL.

-c comment_string

Specifies the key's comment string.


191Exit Values

-e file

Edits the specified key. Makes ssh-keygen-g3 interactive. You can change the key's passphrase or

comment.

-p passphrase

Specifies the passphrase used.

-P

Specifies that the key will be saved with an empty passphrase.

-h | -?

Displays help and exits.

-q

Hides the progress indicator.

-1 file

Converts a key from the SSH1 format to the SSH2 format.

-i file

Loads and displays information on file.

-D file

Derives the public key from the private key file.

-B number

Specifies the number base for displaying key information (default 10).

-V

Displays version string and exits.

-r file

Adds entropy from file to the random pool. If file contains 'relatively random' data (i.e. data unpredict-

able by a potential attacker), the randomness of the pool is increased. Good randomness is essential for

the security of the generated keys.

--overwrite [={yes|no}]

Overwrite files with the same filenames. The default is to overwrite.

-x file

Converts a private key from the X.509 format to the SSH2 format.

-k file

Converts a PKCS #12 file to an SSH2-format certificate and private key.

-7 file

Extracts certificates from a PKCS #7 file.



-F file

Dumps the fingerprint of the given public key. The fingerprint is given in the Bubble Babble format,

which makes the fingerprint look like a string of "real" words (making it easier to pronounce).

-H, --hostkey

Generates a Secure Shell host key pair and stores the key pair in the default host key directory (/etc/ssh2

on Unix, "C:\Program Files\SSH Communications Security\SSH Tectia\SSH Tectia Server"

on Windows).

--import-public-key infile outfile

Attempts to import a public key from infile and store it to outfile in SSH2 native format.

--import-private-key infile outfile

Attempts to import an unencrypted private key from infile and store it to outfile in SSH2 native

private key format.

--import-ssh1-authorized-keys infile outfile

Imports an SSH1-style authorized_keys file infile and generates an SSH2-style authorization file outfile

and stores the keys from infile to generated files into the same directory with outfile.

ssh-cmpclient-g3

ssh-cmpclient-g3 -- CMP enrollment client

Synopsis

ssh-cmpclient-g3 command [options] access [name]

Where command is one of the following:

INITIALIZE psk|racerts keypair template

ENROLL certs|racerts keypair template

UPDATE certs [keypair]

POLL psk|certs|racerts id

RECOVER psk|certs|racerts template

REVOKE psk|certs|racerts template

TUNNEL racerts template

Most commands can accept the following options:

-B Perform key backup for subject keys.

-o prefix Save result into files with prefix.

-O filename Save the result into the specified file.

If there is more than one result file,

the remaining results are rejected.

-C file CA certificate from this file.


193Synopsis

-S url Use this SOCKS server to access the CA.

-H url Use this HTTP proxy to access the CA.

-E PoP by encryption (CA certificate needed).

-v num Protocol version 1|2 of the CA platform. Default is 2.

-y Non-interactive mode. All questions answered with 'y'.

-N file Specifies a file to stir to the random pool.

The following identifiers are used to specify options:

psk -p refnum:key (reference number and pre-shared key)

-p file (containing refnum:key)

-i number (iteration count, default 1024)

certs -c file (certificate file) -k url (private-key URL)

racerts -R file (RA certificate file) -k url (RA private-key URL)

keypair -P url (private-key URL)

id -I number (polling ID)

template -T file (certificate template)

-s subject-ldap[;type=value]

-u key-usage-name[;key-usage-name]

-U extended-key-usage-name[;extended-key-usage-name]

access URL where the CA listens for requests.

name LDAP name for the issuing CA (if -C is not given).

Key URLs are either valid external key paths or in the format:

"generate://savetype:passphrase@keytype:size/save-file-prefix"

"file://passphrase/relative-key-file-path"

"file:relative-key-file-path"

"any-key-file-path"

The key generation "savetype" can be:

- ssh2, secsh2, secsh (Secure Shell 2 key type)

- ssh1, secsh1 (legacy Secure Shell 1 key type)

- pkcs1 (PKCS #1 format)

- pkcs8s (passphrase-protected PKCS #8, "shrouded PKCS #8")

- pkcs8 (plain-text PKCS #8)

- x509 (SSH-proprietary X.509 library key type)

-h Prints usage message.

-F Prints key usage extension and keytype instructions.

-e Prints command-line examples.

Description

The ssh-cmpclient-g3 command-line tool (ssh-cmpclient-g3.exe on Windows) is a certificate enrollment

client that uses the CMP protocol. It can generate an RSA or DSA public-key pair and get certificates for their

public components. CMP is specified by the IETF PKIX Working Group for certificate life-cycle management,

and is supported by some CA platforms, such as Entrust PKI and RSA Keon.



Commands

The ssh-cmpclient-g3 command-line command keywords are listed below. Shorthands longer than three

letters can be used to identify the command. The commands are case-insensitive. The user must specify the

CA address URL for each command. Here the term "user" refers to a user, program, or hardware device.

INITIALIZE

Requests the user's initial certificate. The request is authenticated using the reference number and the

corresponding key (PSK) received from the CA or RA using some out-of-band mechanism.

The user must specify the PSK, the asymmetric key pair, and a subject name.

ENROLL

Requests a new certificate when the user already has a valid certificate for the key. This request is similar

to initialize except that it is authenticated using public-key methods.

POLL

Polls for a certificate when a request was not immediately accepted.

UPDATE

Requests an update of an existing certificate (replacement). The issued certificate will be similar to the

existing certificate (names, flags, and other extensions). The user can change the key, and the validity

times are updated by the CA. This request is authenticated by a valid existing key pair and a certificate.

RECOVER

Requests recovery of a backed-up key. This request is authenticated either by PSK-based or certificate-

based authentication. The template describes the certificate whose private key has already been backed

up and should be recovered. Users can only recover keys they have backed up themselves.

REVOKE

Requests revocation for a key specified in the template. Authentication of the request is made using a

PSK or a certificate belonging to the same user as the subject of revocation.

TUNNEL

Operates in RA tunnel mode. Reads requests and optionally modifies the subject name, alternative names,

and extensions based on the command line. Approves the request and sends it to the CA.

Options

The ssh-cmpclient-g3 command-line options are listed below. Note that when a file name is specified, an

existing file with the same name will be overwritten. When subject names or other strings that contain spaces

are given on the command line, they should be enclosed in double quotes.

-B

Requests private key backup to be performed for the initialize, enroll, and update commands.


195Commands

-o prefix

Saves resulting certificates and CRLs into files with the given prefix. The prefix is first appended by a

number, followed by the file extension .crt or .crl, depending on the type of object.

-O filename

Saves the result into the specified absolute filename. If there is more than one result file, the remaining

results are rejected.

-C file

Specifies the file path that contains the CA certificate. If key backup is done, the file name must be given,

but in most cases the LDAP name of the CA can be given instead.

-S url

Specifies the SOCKS URL if the CA is located behind a SOCKS- enabled firewall. The format of the

URL is: socks://[username@]server[:port][/network/bits[,network/bits]]

-H url

Uses the given HTTP proxy server to access the CA. The format of the URL is: http://server[:port]/

-E

Performs encryption proof of possession if the CA supports it. In this method of PoP, the request is not

signed, but instead the PoP is established based on the ability to decrypt the certificates received from

the CA. The CA encrypts the certificates with the user's public key before sending them to the user.

-v num

Selects the CMP protocol version. This is either value 1, for an RFC 2510-based protocol, or 2 (the default)

for CMPv2.

-N file

Specifies a file to be used as an entropy source during key generation.

The usage line uses the following meta commands:

psk

The reference number and the corresponding key value given by the CA or RA.

-p refnum:key|file

refnum and key are character strings shared among the CA and the user. refnum identifies the secret

key used to authenticate the message. The refnum string must not contain colon characters.

Alternatively, a filename containing the reference number and the key can be given as the argument.

-i number

number indicates the key hashing iteration count.

certs

The user's existing key and certificate for authentication.



-k url

URL specifying the private key location. This is an external key URL whose format is specified in

Section the section called “Synopsis”.

-c file

Path to the file that contains the certificate issued to the public key given in the -k option argument.

racerts

In RA mode, the RA key and certificate for authentication.

-k url



-R file

Path to the file that contains the RA certificate issued to the public key given in the -k option argument.

keypair

The subject key pair to be certified.

-P url



id

Polling ID used if the PKI action is left pending.

-I number

Polling transaction ID number given by the RA or CA if the action is left pending.

template

The subject name and flags to be certified.

-T file

The file containing the certificate used as the template for the operation. Values used to identify the

subject are read from this, but the user can overwrite the key, key-usage flags, or subject names.

-s subject-ldap[;type=value]*

A subject name in reverse LDAP format, that is, the most general component first, and alternative

subject names. The name subject-ldap will be copied into the request verbatim.

A typical choice would be a DN in the format "C=US,O=SSH,CN=Some Body", but in principle this

can be anything that is usable for the resulting certificate.

The possible type values are ip, email, dn, dns, uri, and rid.


197

-u key-usage-name[;key-usage-name]*

Requested key usage purpose code. The following codes are recognized: digitalSignature, non-

Repudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign,

encipherOnly, decipherOnly, and help. The special keyword help lists the supported key usages

which are defined in RFC 3280.

-U extended-key-usage-name[;extended-key-usage-name]*

Requested extended key usage code. The following codes, in addition to user-specified dotted OID

values are recognized: serverAuth, clientAuth, codeSigning, emailProtection, timeStamping,

ikeIntermediate, and smartCardLogon.

access

Specifies the CA address in URL format. Possible access methods are HTTP (http://host:port/path),

or plain TCP (tcp://host:port/path). If the host address is an IPv6 address, it must be enclosed in

square brackets (http://[IPv6-address]:port/).

name

Optionally specifies the destination CA name for the operation, in case a CA certificate was not given

using the option -C.

Examples

Initial Certificate Enrollment

This example provides commands for enrolling an initial certificate for digital signature use. It generates a

private key into a PKCS #8 plaintext file named initial.prv, and stores the enrolled certificate into file

initial-0.crt. The user is authenticated to the CA with the key identifier (refnum) 62154 and the key ssh.

The subject name and alternative IP address are given, as well as key-usage flags. The CA address is

pki.ssh.com, the port 8080, and the CA name to access Test CA 1.

$ ssh-cmpclient-g3 INITIALIZE \

-P generate://pkcs8@rsa:1024/initial -o initial \

-p 62154:ssh \

-s 'C=FI,O=SSH,CN=Example/initial;IP=1.2.3.4' \

-u digitalsignature \


'C=FI, O=SSH Communications Security Corp, CN=SSH Test CA 1 No Liabilities'

As a response the command presents the issued certificate to the user, and the user accepts it by typing yes

at the prompt.

Certificate =

SubjectName = <C=FI, O=SSH, CN=Example/initial>

IssuerName = <C=FI, O=SSH Communications Security Corp,

CN=SSH Test CA 1 No Liabilities>

SerialNumber= 8017690

SignatureAlgorithm = rsa-pkcs1-sha1



Validity = ...

PublicKeyInfo = ...

Extensions =

Viewing specific name types = IP = 1.2.3.4

KeyUsage = DigitalSignature

CRLDistributionPoints = ...

AuthorityKeyID =

KeyID = 3d:cb:be:20:64:49:16:1d:88:b7:98:67:93:f0:5d:42:81:2e:bd:0c

SubjectKeyID =

KeyId = 6c:f4:0e:ba:b9:ef:44:37:db:ad:1f:fc:46:e0:25:9f:c8:ce:cb:da

Fingerprints =

MD5 = b7:6d:5b:4d:e0:94:d1:1f:ec:ca:c2:ed:68:ac:bf:56

SHA-1 = 4f:de:73:db:ff:e8:7d:42:c4:7d:e1:79:1f:20:43:71:2f:81:ff:fa

Do you accept the certificate above? yes

Key update

Before the certificate expires, a new certificate with updated validity period should be enrolled. ssh-cmpcli-

ent-g3 supports key update, where a new private key is generated and the key update request is authenticated

with the old (still valid) certificate. The old certificate is also used as a template for issuing the new certificate,

so the identity of the user will not be changed during the key update. With the following command you can

update the key pair, which was enrolled in the previous example. Presenting the resulting certificate has been

left out.

$ ssh-cmpclient-g3 UPDATE \

-k initial.prv -c initial-0.crt -P \

generate://pkcs8@rsa:1024/updatedcert -o updatedcert \


"C=FI, O=SSH Communications Security Corp, CN=SSH Test CA 1 No Liabilities"

The new key pair can be found in the files with the updatedcert prefix. The policy of the issuing CA needs

to also allow automatic key updates if ssh-cmpclient-g3 is used in the UPDATE mode.

ssh-certview-g3

ssh-certview-g3 -- certificate viewer

Synopsisssh-certview-g3

[options...] file

[options...] file ...


199Key update

Description

The ssh-certview-g3 program (ssh-certview-g3.exe on Windows) is a simple command-line application,

capable of decoding and showing X.509 certificates, CRLs, and certification requests. The command output

is written to the standard output.

Options


-h

Displays a short help.

-verbose

Gives more diagnostic output.

-quiet

Gives no diagnostic output.

-auto

The next input file type is auto-detected (default).

-cert

The next input file is a certificate.

-certpair

The next input file is a cross-certificate pair.

-crmf

The next input file is a CRMF certification request.

-req

The next input file is a PKCS #10 certification request.

-crl

The next input file is a CRL.

-prv

The next input file is a private key.

-pkcs12

The next input file is a PKCS#12 package.

-ssh2

The next input file is an SSH2 public key.



-spkac

The next input file is a Netscape-generated SPKAC request.

-noverify

Does not check the validity of the signature on the input certificate.

-autoenc

Determines PEM/DER automatically (default).

-pem

Assumes that the input file is in PEM (ASCII base-64) format. This option allows both actual PEM (with

headers and footers), and plain base-64 (without headers and footers). An example of PEM header and

footer is shown below:

-----BEGIN CERTIFICATE-----

encoded data

-----END CERTIFICATE-----

-der

Assumes that the input file is in DER format.

-hexl

Assumes that the input file is in Hexl format. (Hexl is a common Unix tool for outputting binary files in

a certain hexadecimal representation.)

-skip number

Skips number bytes from the beginning of input before trying to decode. This is useful if the file contains

some garbage before the actual contents.

-ldap

Prints names in LDAP order.

-utf8

Prints names in UTF-8.

-latin1

Prints names in ISO-8859-1.

-base10

Outputs big numbers in base-10 (default).

-base16

Outputs big numbers in base-16.

-base64

Outputs big numbers in base-64.


201

-width number

Sets output width (number characters).

Example

For example, using a certificate downloaded from pki.ssh.com, when the following command is given:

$ ssh-certview-g3 -width 70 ca-certificate.cer

The following output is produced:

Certificate =

SubjectName = <C=FI, O=SSH Communications Security Corp, CN=Secure

Shell Test CA>

IssuerName = <C=FI, O=SSH Communications Security Corp, CN=Secure

Shell Test CA>

SerialNumber= 34679408

SignatureAlgorithm = rsa-pkcs1-sha1

Certificate seems to be self-signed.

* Signature verification success.

Validity =

NotBefore = 2003 Dec 3rd, 08:04:27 GMT

NotAfter = 2005 Dec 2nd, 08:04:27 GMT

PublicKeyInfo =

PublicKey =

Algorithm name (SSH) : if-modn{sign{rsa-pkcs1-md5}}

Modulus n (1024 bits) :

9635680922805930263476549641957998756341022541202937865240553

9374740946079473767424224071470837728840839320521621518323377

3593102350415987252300817926769968881159896955490274368606664

0759644131690750532665266218696466060377799358036735475902257

6086098562919363963470926690162744258451983124575595926849551

903

Exponent e ( 17 bits) :

65537

Extensions =

Available = authority key identifier, subject key identifier, key

usage(critical), basic constraints(critical), authority

information access

KeyUsage = DigitalSignature KeyEncipherment KeyCertSign CRLSign

[CRITICAL]

BasicConstraints =

PathLength = 0

cA = TRUE

[CRITICAL]

AuthorityKeyID =

KeyID =

eb:f0:4d:b5:b2:4c:be:47:35:53:a8:37:d2:8d:c8:b2:f1:19:71:79

SubjectKeyID =

KeyId =

eb:f0:4d:b5:b2:4c:be:47:35:53:a8:37:d2:8d:c8:b2:f1:19:71:79



AuthorityInfoAccess =

AccessMethod = 1.3.6.1.5.5.7.48.1

AccessLocation =

Following names detected =

URI (uniform resource indicator)

Viewing specific name types =

URI = http://pki.ssh.com:8090/ocsp-1/

Fingerprints =

MD5 = c7:af:e5:3d:f6:ea:ce:da:07:93:d0:06:8d:c0:0a:f8

SHA-1 =

27:d7:19:47:7c:08:3e:1a:27:4b:68:8e:18:83:e8:f9:23:e8:29:85

ssh-ekview-g3

ssh-ekview-g3 -- external key viewer

Synopsisssh-ekview-g3 [options...] provider

Description

The ssh-ekview-g3 program (ssh-ekview-g3.exe on Windows) allows you to export certificates from ex-

ternal key providers such as Entrust. You can further study these certificates with ssh-certview-g3.

This is useful when you want to generate, for example, entries for allowing certificate authentication in the

ssh-server-config.xml file. You might need to know the subject names on the certificate.

With ssh-ekview-g3, you can export the certificate and get the information you need from the certificates

with ssh-certview-g3.

Options


-h

Displays a short help.

-i info

Uses info as the initialization string for the provider.

-k

Prints the key paths only.

-e keypath

Exports certificates at keypath to files.


203Synopsis

-a

Exports all found certificates to files.

-b base

Uses base when printing integers. For example, the decimal 10 is 'a' in base-16.

Example

For example the following command will dump all certificates in the entrust provider to files:

ssh-ekview-g3 -a -i"ini-file($HOME/my.ini) profile-file($HOME/solo.ini)" entrust



Appendix B Egrep SyntaxThe SSH Tectia Connector tunneling filter rules and the SSH Tectia Client (with EFT) FTP-SFTP conversion

filter rules can be matched to hostname or IP address patterns specified using the egrep syntax. The egrep

syntax is explained in this section.

B.1 Egrep Patterns

The escape character is a backslash (\). You can use it to escape meta characters to use them in their plain

character form.

In the following examples literal 'E' and 'F' denote any expression, whether a pattern or a character.

(

Start a capturing subexpression.

)

End a capturing subexpression.

E|F

Disjunction, match either E or F (inclusive). E is preferred if both match.

E*

Act as Kleene star, match E zero or more times.

E+

Closure, match E one or more times.

E?

Option, match E optionally once.

.

Match any character except for newline characters (\n, \f, \r) and the NULL byte.

E{n}

Match E exactly n times.


205

E{n,} or E{n,0}

Match E n or more times.

E{,n} or E{0,n}

Match E at most n times.

E{n,m}

Match E no less than n times and no more than m times.

[

Start a character set, see Section B.3.

$

Match the empty string at the end of the input or at the end of a line.

^

Match the empty string at the start of the input or at the beginning of a line.

B.2 Escaped Tokens for Regex Syntax Egrep

\0n..n

The literal byte with octal value n..n.

\0

The NULL byte.

\[1-9]..x

The literal byte with decimal value [1-9]..x.

\xn..n or \0xn..n

The literal byte with hexadecimal value n..n.

\<

Match the empty string at the beginning of a word.

\>

Match the empty string at the end of a word.

\b

Match the empty string at a word boundary.

\B

Match the empty string provided it is not at a word boundary.

\w

Match a word-constituent character, equivalent to [a:zA:Z0:9-].


Egrep Syntax206

\W

Match a non-word-constituent character.

\a

Literal alarm character.

\e

Literal escape character.

\f

Literal line feed.

\n

Literal new line, equivalent to C's \n so it can be more than one character long.

\r

Literal carriage return.

\t

Literal tab.

All other escaped characters denote the literal character itself.

B.3 Character Sets For Egrep

A character set starts with '[' and ends at non-escaped ']' that is not part of a POSIX character set specifier and

that does not follow immediately after '['.

The following characters have a special meaning and need to be escaped if meant literally:

- (minus sign)

A range operator, except immediately after '[', where it loses its special meaning.

^

If immediately after the starting '[', denotes a complement: the whole character set will be complemented.

Otherwise literal '^'.

[:alnum:]

Characters for which 'isalnum' returns true.

[:alpha:]

Characters for which 'isalpha' returns true.

[:cntrl:]

Characters for which 'iscntrl' returns true.


207B.3 Character Sets For Egrep

[:digit:]

Characters for which 'isdigit' returns true.

[:graph:]

Characters for which 'isgraph' returns true.

[:lower:]

Characters for which 'islower' returns true.

[:print:]

Characters for which 'isprint' returns true.

[:punct:]

Characters for which 'ispunct' returns true.

[:space:]

Characters for which 'isspace' returns true.

[:upper:]

Characters for which 'isupper' returns true.

[:xdigit:]

Characters for which 'isxdigit' returns true.

Example: [[:xdigit:]XY] is typically equivalent to [0123456789ABCDEFabcdefXY] .

It is also possible to include the predefined escaped character sets into a newly defined one, so [\d\s] matches

digits and whitespace characters.

Also, escape sequences resulting in literals work inside character sets.


Egrep Syntax208

Appendix C GUI ReferenceThis section describes the main elements of the SSH Tectia Client user interface, the terminal window, the

file transfer window and their menu bars and toolbars.

C.1 Terminal Window

The terminal window is a secure replacement for Telnet connections. It offers a command-line interface to

the remote host computer. Note that the most important function of the terminal window is to allow you to

operate the remote host computer. Therefore the terminal window does not capture some common keyboard

shortcuts (such as Ctrl+C for copy), but passes them instead to the remote host computer, where they can be

used to control remote program execution.

Apart from the text display itself, a lot of connection information is visible in title and status bars of the ter-

minal window.

Figure C.1. The SSH Tectia Client terminal window

C.1.1 Terminal Window Title Bar

The title bar is located at the top of the window.


209

The leftmost item on the title bar is the window icon. Click it to display the Window menu, or double-click

it to close the window.

The next item on the title bar is the sequence number of the window that helps in distinguishing between

windows that use the same connection.

Figure C.2. The terminal window title bar

Next on the title bar is the remote computer host name. Displaying the name on the title bar is optional, and

it is shown only if defined on the Appearance page (see Section 5.1.1). For example, a second window asso-

ciated with a connection to a host computer called remote would display as 2:remote.

The next item on the title bar is the name of the settings file in use. Displaying the name on the title bar is

optional, and it is shown only if defined on the Appearance page (see Section 5.1.1). If you are not using a

settings file that has been saved with a specific file name, a settings file called default is used.

If you have changed the settings without saving them, an asterisk (*) is displayed on the title bar, after the

name of the current settings file (for example: default*). For information on saving the changed settings,

see Section 5.3.1.

C.1.2 Terminal Window Status Bar

The status bar is located at the bottom of the terminal window. When browsing through the menu options or

toolbar buttons, the status bar displays a short context-sensitive help text.

When the menus or toolbars are not browsed, the left side of the status bar indicates the remote host computer

you are currently connected to. If you are not connected, the status bar displays the text Not connected -

Press Enter/Space to connect.

Figure C.3. The terminal window status bar

The next status bar field shows the current encryption algorithm, MAC algorithm, and compression separated

by dashes (for example: 3des-cbc - hmac-md5 - none).

The next field displays the number of columns and rows of the Terminal window. If you change the size of

the terminal window, this window size indicator will be immediately updated.


GUI Reference210

C.1.3 Terminal Window Shortcut Menu

If you have not set the Paste on Right Mouse Click option (see Section 5.1.1), a shortcut menu appears when

you click the terminal window with the right mouse button.

By default, the following menu options are available:

Copy

Copies text onto the Windows clipboard.

Paste

Pastes text from the Windows clipboard.

Paste Selection

Copies the currently selected text into the cursor location without first copying it onto the Windows

clipboard.

Select All

Selects all of the scrollback buffer.

Select Screen

Selects all text currently displayed on the screen. The rest of the scrollback buffer will not be selected.

Select None

Cancels the current selection.

Find

Searches for text in the scrollback buffer.

New Terminal

Opens a new terminal window.

New File Transfer

Opens a new file transfer window.

Close Window

Closes the current window.

Settings

Opens the Settings dialog.

The available options can be configured using the Customize dialog (see Section 5.3.3).


211C.1.3 Terminal Window Shortcut Menu

C.2 File Transfer Window

SSH Tectia Client makes it easy and convenient to transfer files between your local computer and a remote

host computer (server). You can upload and download files using an intuitive graphical user interface similar

in functionality to Windows Explorer.

You can open the file transfer window by clicking on the New File Transfer Window button on the SSH

Tectia Client toolbar, or by selecting Window → New File Transfer, or the New File Transfer in the

Current Directory option. You can have an unlimited number of individual file transfer windows open at

the same time.

Figure C.4. The SSH Tectia Client File Transfer window

SSH Tectia File Transfer contains several unique features that make secure transfer operations fast and easy.

Note, however, that SSH Tectia Client is not just an alternative to an FTP client. You cannot for example use

the client to login to a normal, unsecured FTP server. The remote host computer must be running Secure Shell

server software.

The file transfer window works similarly to Windows Explorer: it displays the contents of any open directories

represented as icons and optionally gives basic information (such as size and type) on each file.

The file transfer window consists of three panes: Local View (displaying the files on your local computer),

Remote View (displaying files on the server) and Transfer View (displaying files transferred between the

local and remote computers).

By default, Local View is displayed on the left-hand side of the window, Remote View on right-hand side of

the window, and Transfer View below the Local and Remote Views. You can change the default layout on

the File Transfer page on the Global Settings section of the Settings dialog. For more information, see

Section 5.1.5.


GUI Reference212

C.2.1 File Transfer Window Title Bar

The title bar is located at the top of the file transfer window.

The leftmost item on the title bar is the window icon. Click it to display the Window menu or double-click

to close the window. If a file transfer is active when you attempt to close the window, a confirmation dialog

asks if you actually want to cancel the transfer operation.

The next item on the title bar is the sequence number of the window. This helps you to distinguish between

different windows using the same connection.

Figure C.5. The file transfer window title bar

Next on the title bar is the host name of the remote computer. Displaying the name on the title bar is optional,

and it is shown only if defined on the Appearance page (see Section 5.1.1). For example, a second window

associated with a connection to a host computer called remote would display as 2:remote.

The next item on the title bar is the name of the settings file in use. Displaying the name on the title bar is

optional, and it is shown only if defined on the Appearance page (see Section 5.1.1). If you are not using a

settings file that has been saved with a specific file name, a settings file called default is used.

If you have changed the settings without saving them, an asterisk (*) is displayed on the title bar, after the

name of the current settings file (for example default*). For information on saving the changed settings, see

Section 5.3.1.

C.2.2 File Transfer Window Menu Bar

The menu bar is located under the file transfer window status bar. Most of the menu options are the same as

in the terminal window, but the Operation menu is unique to the file transfer window, and some file-transfer-

specific options have been added to the View menu. The menu options are explained in Section C.4.

The position and contents of the menu bar can be customized. See Section 5.3.5.1 and Section 5.3.3.

C.2.3 File Transfer Window Toolbars

There are three individual toolbars available in the file transfer window, all of them initially located below

the menu bar:

Toolbar

This is the basic toolbar that is displayed also in the terminal window, with additional file-transfer-spe-

cific toolbar buttons. For more information, see Section C.3.


213C.2.1 File Transfer Window Title Bar

Profiles Bar

This is a separate toolbar for managing the server profiles and the Quick Connect option. For more in-

formation, see Section C.3.3.

File Bar

This is a separate toolbar for the most commonly used file management tasks. For more information, see

Section C.3.4.

The layout and contents of the toolbar and the profile bar can be customized. See Section 5.3.4 and Section 5.3.3.

The File bar is a dynamically created toolbar, and therefore it cannot be customized.

C.2.4 File Transfer Window Status Bar

The status bar is located at the bottom of the file transfer window. When browsing through the menu options

or toolbar buttons, the status bar displays a short context-sensitive help text on the currently active user interface

element (such as toolbar button or menu item).

When the menus or toolbars are not browsed, the left side of the status bar displays the current remote host

computer (server) and the current directory on the remote host.

Figure C.6. The file transfer status bar displays the size of the selected file

The next field of the file transfer status bar displays the number of files and subfolders in the current folder,

as well as the total size of the files. If you select one or more files in the folder view, the field changes to

display the number of files and total file size of the current selection. This is useful especially when estimating

the amount of total data to be transferred.

File Transfer Window Views

Local and Remote Views can display their contents in four different ways, as defined in the global File

Transfer page of the Settings dialog. See Section 5.1.5. The available views are the following:

Large Icons

Each file and folder has a large icon associated with it, making for a clear and uncluttered display. The

only information displayed about each file is the icon and the file name.

Small Icons

Each file and folder has a small icon associated with it. This makes it possible to display several times

more items than in the Large Icons view. Only the icon and the name of each file is displayed.

List

Each file and folder has a small icon associated with it, and the files and folders are displayed in a single

column underneath each other. Only the icons and the file names are displayed.


GUI Reference214

Details

For each file and folder, an icon, file name, file size, file type, and the last modification date are displayed.

The files in the Remote View have also their attributes visible. This is the default view.

By clicking on the Name, Size, Type, Modified or Attributes sort bars located at the top of the directory

listing, you can sort the files and folders based on their file name, file size, file type, the time they were

last modified, and file attributes. Clicking the same sort option again reverses the sorting order.

Note

The sorting function is not case-sensitive - uppercase text is sorted together with lowercase text.

The following information is displayed in each column:

Name

The file name of each file. Note that the local and remote file systems limit what file names are ac-

ceptable on which computer. (For example, Unix file names are case-sensitive while Windows file

names are not. Thus a Unix directory can contain both File.txt and file.txt, but a Windows

directory cannot.)

Size

The size of each file, shown in bytes.

Type

The type of each file is based on the file extension. The descpription given in the Type field is based

on the file types recognized by Windows Explorer. If you have defined a new file type description

for files with a certain file name extension, the files on the remote computer are also shown to be of

that file type. This makes it easy to recognize particular file types also on the remote computer.

Modified

The last time when a file was changed.

Attributes

The attributes of each file.

On Windows systems, the file may have the following attributes:

• R: The file can be read.

• W: The file can be written to.

• X: The file can be executed (run).

On Unix systems, the attributes signify the file permissions given to each file:

• d: The entry is a directory.

• r: The file can be read.


215

• w: The file can be written to.

• x: The file can be executed.

After the d attribute, the r w and x attributes may be repeated up to three times. If the file does not

have a particular attribute, the attribute is replaced with a hyphen (-).

The first three attributes specify the permissions given to the owner of the file, the second triplet

specifies the permissions for the user group associated with the file, and the last triplet specifies the

permissions given to all other users. For more information on file permissions, please consult the

server documentation.

C.2.5 Local View

The contents of current directory on your local computer are visible in the Local View pane of the file transfer

window. By default, Local View displays the contents of your local home directory - usually your Windows

desktop. You can change the home directory on the Local Favorites page of the Settings dialog. See Sec-

tion 5.1.8.

Note

Files that are marked as hidden (i.e. not by default displayed in Windows Explorer) can also be dis-

played in the Local View pane if you have selected them to be shown on the Global Settings, File

Transfer page. The size of gigantic files (over 4 gigabytes) is not displayed correctly.

C.2.6 Local Folder View

Local View can optionally contain a separate pane for the local directory structure. By default, the Local

Folder View pane is hidden. You can show and hide it again by clicking the Show/Hide Local Folders button

on the File bar.

The directory structure is presented as a tree-like folder structure. You can click on a folder to view its contents

on the right- hand side pane of Local View. The displayed folder is highlighted in the folder view.

Opening or closing a folder in the folder view does not affect the file view on the right-hand side, unless you

close the parent folder of the displayed folder. In that case the closed folder becomes the new displayed folder.

C.2.7 Remote View

The contents of current directory on the remote host computer (server) are visible on the Remote View of the

file transfer window. By default, Remote View displays the contents of your home directory on the remote

host computer.


GUI Reference216

C.2.8 Remote Folder View

Remote View can optionally contain a separate pane for the remote directory structure. By default, the Remote

Folder View pane is hidden. You can show and hide it again by clicking the Show/Hide Remote Folders

button on the File bar.

The directory structure is presented as a tree-like folder structure. You can click on a folder to view its contents

on the right-hand side pane of Remote View. The displayed folder is highlighted in the folder view.

Opening or closing a folder in the folder view does not affect the file view on the right-hand side, unless you

close the parent folder of the displayed folder. In that case the closed folder becomes the new displayed folder.

C.2.9 Transfer View

The file transfer operations between the local and remote host computers are displayed in the file transfer

window Transfer View. Transfer View consists of the Transfer page and the Queue page. Click the appropriate

tab at the top of Transfer View to view the pages.

Transfer Page

The Transfer page of the Transfer View displays a list of files that have been transferred between the computers.

The page gives the following information on the transferred files:

Direction

The direction of the transfer is depicted with an arrow. Uploads are marked with an arrow pointing up,

and downloads with an arrow pointing down.

Source File

The original name of the file in the source system.

Source Directory

The directory the file was transferred from.

Destination Directory

The directory the file was transferred to.

Size

The size of the file, expressed in bytes.

Status

The transfer status of the file. Files waiting for transfer to start are marked as Queued. The status of on-

going transfers is displayed as a progress bar. Successfully transferred files are marked as Complete.

Files whose transfer operation has been cancelled are marked as Cancelled.

Errors that prevent the file transfer from completing are displayed in the status column as well. Files that

cannot be transferred due to an error are marked with the Error tag.


217C.2.8 Remote Folder View

Speed

The speed of the transfer operation, expressed in kilobytes per second (kB/s).

Time

During the transfer operation, this column displays the estimated time to complete the transfer. After the

transfer has been completed, the actual time used for the transfer is displayed.

Transfer Shortcut Menu

Right-clicking the Transfer page opens a shortcut menu with the following options:

• To stop transferring files, select the files that you do not want to have transferred, right-click the Transfer

page and select Cancel.

• To delete files from the queue, select the files that you do not want to keep in the Transfer page, right-

click the Transfer page and select Remove.

• To transfer again files that were not succesfully transferred previously, select the files, right-click the

Transfer page and select Retry.

• To remove files from the local directory, select the files that you do not want to keep in the local directory,

right-click the Transfer page and select Delete Local File.

• To remove files from the remote directory, select the files that you do not want to keep in the remote dir-

ectory, right-click the Transfer page and select Delete Remote File.

• To remove completely transferred and cancelled files from the Transfer page, right-click the Transfer

page and select Clear Finished.

• To export the list into a text file, right-click the Transfer page and select Export List. The Save As dialog

opens, allowing you to specify the location and name of the text file. The text file will contain the path

and file names of the transferred files in both the remote and local system, and the file size, separated by

commas. This option can be used to maintain a log of your file transfers.

Queue Page

The Queue page of Transfer View can be used to create a customized list of files that are to be transferred

at a later stage. You can use the mouse to drag and drop files on the Queue page, where they wait to be

transferred.

Queue Shortcut Menu

Right-clicking the Queue page opens a shortcut menu with the following options:

• To add files to the queue, right-click on the Queue page and select Add. The Edit Transfer Queue dialog

appears. Click New above the list area to type in the path to a new file to be transferred, or click the ellipsis

button (...) to open a dialog for selecting files.


GUI Reference218

• To edit the target locations of the queued files, select a file to edit, right-click the Queue page and select

Edit. The Edit Transfer Queue dialog opens, allowing you to type in a new destination directory for the

file. You can also click the ellipsis button (...) to open a dialog that you can use to select the destination

directory.

You can use the Edit option for several files at the same time, but the direction of the transfer (upload or

download) must be the same for all of the files.

• To delete files from the queue, select the files, right-click the Queue page and select Remove.

• To transfer single files, select them, right-click the Queue page and select Transfer.

• To transfer all the queued files, right-click the Queue page and select Transfer All.

C.2.10 Navigating in the File Transfer Window

You can change the current directory in the Local or Remote View by doing one of the following:

• Double-click the folders displayed in the current view to open them. Use the Up button on the File bar to

return to the parent directory.

In Local View, you can access other drives by clicking Up until you are on the Windows desktop directory

and then double-clicking the My Computer icon.

• Select other drives and directories from the favorites drop-down list box displayed on the file bar. You

can modify the contents of the Local Favorites list on the Local Favorites page of the Settings dialog (see

Section 5.1.8).

• Type the path to the desired directory (for example C:\Program Files or ./.ssh2) in the favorites drop-

down list and press the Enter key to move to that directory.

C.2.11 File Transfer Shortcut Menus

Right-click the file transfer window to display a shortcut menu. The available menu options vary depending

on whether you click on the Local or the Remote View and whether you have selected a file or not. Multiple

files can be selected.

Right-click the file transfer window to display a shortcut menu. The available menu options vary depending

on whether you click on the Local or the Remote View and whether you have selected a file or not. Multiple

files can be selected.

Local View

The following shortcut menu options are available in Local View when you have not selected a file or a folder:


219C.2.10 Navigating in the File Transfer Window

Up

Moves the file transfer window focus to the parent directory of the current directory.

Home

Moves the file transfer window focus to your home directory.

Refresh

Updates the file transfer window.

Select All

Selects all files and folders in the current folder. The shortcut key for Select All is Ctrl+A.

View

Opens a submenu from which you can select the view type (large icons, small icons, list or details view).

New Folder

Creates a new folder and prompts you to enter a name for it. If you enter nothing, the folder will not be

created.

The following shortcut menu options are available in Local View when you have selected one or more files

or a folder:

Open

Opens the currently selected file or folder. The shortcut key for Open is Ctrl+O.

Upload

Transfers a file from the local computer to the remote host computer.

Delete

Removes the currently selected file.

Rename

Changes the name of the currently selected file. The shortcut key for Rename is F2.

Properties

Displays the attributes of the currently selected file, including the file permissions (on Unix systems).

Remote View

The following shortcut menu options are available in Remote View when you have not selected a file or a

folder:

Up

Moves the file transfer window focus to the parent directory of the current directory.

Home

Moves the file transfer window focus to your home directory. The shortcut key for Home is Ctrl+H.


GUI Reference220

Go to Folder

Opens the Go to Remote Folder dialog where you can type in a path of the folder which you want to

open.

Refresh

Updates the file transfer window. The shortcut key for Refresh is F5.

Select All

Selects all files and folders in the current folder. The shortcut key for Select All is Ctrl+A.

Paste

Pastes a file from the file transfer "clipboard". The shortcut key for Paste is Ctrl+V.

Upload Dialog

Opens the Upload - Select Files dialog that allows you to select a file and transfer it from the local

computer into the remote host computer. The shortcut key for Upload Dialog is Ctrl+U.

View

Opens a submenu from which you can select the view type (large icons, small icons, list or details view).

Arrange Icons

Opens a submenu from which you can select how the icons are arranged (by name, by type, by size or

by date).

New Folder

Creates a new folder and prompts you to enter a name for it. If you enter nothing, no folder will be created.

The shortcut key for New Folder is Ctrl+N.

The following shortcut menu options are available in Remote View when you have selected one or more files

or a folder.

The shortcut menu options can be configured using the Customize dialog (see Section 5.3.3).

Open

Opens the currently selected file or folder. The shortcut key for Open is Ctrl+O. Not available if more

than one file is selected.

Download

Transfers the currently selected file into the local computer.

Download Dialog

Opens the Download - Select Folder dialog that allows you to select a folder on the local computer and

transfer the currently selected file into it. The shortcut key for Download Dialog is Ctrl+D.

Copy

Copies the currently selected file into the file transfer "clipboard". The shortcut key for Copy is Ctrl+C.


221

Delete

Removes the currently selected file.

Rename

Changes the name of the currently selected file. The shortcut key for Rename is F2.

Properties

Displays the attributes of the currently selected file, including the file permissions (on Unix systems).

Transfer Page

The following shortcut menu options are available on the Transfer Page of the Transfer View:

Cancel

To stop transferring the files, select the files that you do not want to have transferred, right-click the

Transfer page and then select the Cancel option from the shortcut menu.

Remove

To delete files from the queue, select the files that you do not want to keep in the Transfer page, right-

click the Transfer page and then select the Remove option from the shortcut menu.

Retry

To transfer again files that were not succesfully transferred previously, select the files, right-click the

Transfer page and then select the Retry option from the shortcut menu. The option can also be used on

transfers that were successful.

Delete Local File

To remove files from the local directory, select the files that you do not want to keep in the local directory,

right-click the Transfer page and then select the Delete Local File option from the shortcut menu.

Delete Remote File

To remove files from the remote directory, select the files that you do not want to keep in the remote

directory, right-click the Transfer page and then select the Delete Remote File option from the shortcut

menu.

Clear Finished

To remove completely transferred and cancelled files from the Transfer page, right-click the Transfer

page and then select the Clear Finished option from the shortcut menu.

Export List

To export the list into a text file, right-click the Transfer page and then select the Export List option

from the shortcut menu. The Save As dialog appears, allowing you to specify the location and name of

the text file. The text file will contain the path and file names of the transferred files in both the remote

and local systems, and the file size, separated by commas. This option can be used to maintain a log of

your file transfers.


GUI Reference222

Queue Page

The following shortcut menu options are available on the Queue Page of the Transfer View:

Transfer

To transfer single files, select them, right-click the Queue page and choose Transfer from the shortcut

menu.

Transfer All

To transfer all the queued files, right-click the Queue page and choose Transfer All from the shortcut

menu.

Add

To add more files to the transfer queue, right-click on the Queue page and select the Add option from

the shortcut menu. The Edit Transfer Queue dialog appears. Click the New button above the list area to

type in the path to a new file to be transferred, or click the ellipsis button (...) to open a dialog for se-

lecting files.

Edit

To edit the target locations of the queued files, select a file to edit, right-click the Queue page and choose

Edit from the shortcut menu. The Edit Transfer Queue dialog appears, allowing you to type in a new

destination directory for the file. You can also click the ellipsis button (...) to open a file selector dialog

that you can use to select the destination directory.

You can use the Edit option for several files at the same time, but the direction of the transfer (upload

or download) must be the same for all of the files.

Remove

To delete files from the queue, select the files, right-click the Queue page and choose Remove from the

shortcut menu.

C.3 Toolbar Reference

The most commonly used functions of SSH Tectia Client terminal and file transfer windows can be accessed

using the toolbar. By default the basic toolbar is located at the top of the SSH Tectia Client window, under

the menu bar.

Figure C.7. The basic toolbar contains buttons for the most frequently used functions

Initially the Profiles bar is located under the basic toolbar and contains the Quick Connect and Profiles options.


223C.3 Toolbar Reference

Figure C.8. The Profiles bar contains the Quick Connect and Profiles buttons

In the file Transfer window, a third toolbar is available. The default position of the File bar is below the Profiles

toolbar.

Figure C.9. The File bar is specific to the file transfer window

See also Section 5.3.4.

C.3.1 Basic Toolbar

This section describes the basic toolbar buttons.

Figure C.10. The basic toolbar

Save Settings

Select File → Save Settings (or Save Settings on the toolbar) to save any changes you have made to your

current settings.

Print

Select the Print option to output the contents of the current scrollback buffer to your printer. The standard

Windows Print dialog ppears, allowing you to select the printer settings.

The print range can also be selected from this dialog. Selecting All will print the entire contents of the terminal

scrollback buffer. If the whole scrollback buffer fills more than one page when printed, a range of pages to

print can be selected. If any text is selected when you use the Print option, the default print range will be

Selection, which only prints the currently selected text.

You can use the Print Preview option (see Section C.3.1.3) to help you to determine which pages to print

and what the printout will look like.


GUI Reference224

Note

If you use a network printer, the area selected for printing is sent unencrypted over the network to

the printer. This is a security risk you should consider when printing confidential information.

The Print option is available only in the terminal window.

Print Preview

Select the Print Preview option to display the entire contents of the terminal scrollback buffer, split into

pages in the same way as the scrollback buffer will appear when printed.

The following buttons can be used to preview the print result:

Print

This button opens the Print dialog, allowing you to specify the printer settings and print the result.

Next Page

Click this button to preview the next page of output. The keyboard shortcut for Next Page is the Page

Down key.

Prev Page

Click this button to preview the previous page of output. The keyboard shortcut for Prev Page is the Page

Up key.

Toggle One Page/Two Pages Display

Click this button to display two pages of output side by side. Click the button again to return to the one-

page view. This button cannot be used when you have zoomed the page.

Zoom In

Click this button to see a closeup of the currently displayed print preview page. You can use this button

to zoom up to the natural size of the printout. You can zoom in also by clicking the left mouse button on

the preview view.

Zoom Out

Click this button to return from a zoomed-in view of the print preview page. You can zoom out until the

whole page is displayed.

Close

Click this button to close the Print Preview dialog. The dialog can be closed also by pressing the Esc key.

The Print Preview option is available only in the terminal window.

Connect

Select the Connect option to connect to a remote host computer. A Connect to Server dialog opens.


225

Figure C.11. The Connect to Server dialog

For more information on this dialog, see Section 3.4.

Disconnect

Select the Disconnect option to quit the current connection. The Confirm Disconnect dialog is displayed, al-

lowing you to confirm if you really want to disconnect. Select Cancel to keep the connection open, or OK

to end the connection. If you do not want to answer the confirmation dialog again, select the Don't ask me

again check box.

Figure C.12. The Confirm Disconnect dialog

Note that one connection can have several windows open (such as a terminal window and a file transfer

window). Disconnecting affects all windows associated with a single connection.

However, if you have started other, separate clients, they are not affected by disconnecting. Disconnecting

quits the selected connection and all of its associated windows, but no other, separate connections.

Copy

Select the Copy option to create a temporary copy of the selected text or files.

If you are copying text (in the terminal window), the text is placed on the Windows clipboard and can be

pasted in the terminal window or any Windows text window.

If you are copying files (in the file transfer window), a Download dialog is displayed, but the selected files

are not yet copied to any specific location. This resembles using the Windows clipboard: You can copy files

to a temporary storage and paste them later into another location.


GUI Reference226

You can copy also with the keyboard shortcut Ctrl+Insert. This shortcut is available in both terminal and

file transfer windows.

Paste

Select the Paste option to add previously copied text or files or folders into a new location.

If you are pasting text (in the terminal window), the text that was copied earlier onto the clipboard will be

inserted in the cursor location. You can paste text that was copied from the terminal window or any other

Windows text window.

If you are pasting files (in the file transfer window), an Upload dialog is displayed when the files are pasted

to the new location. This resembles using the Windows clipboard: You can copy files to a temporary storage

and paste them later into another location. The file names of the pasted files and folders do not change during

the operation. Therefore it is not possible to paste files or folders several times into one location.

You can paste files also by using the keyboard shortcut Shift+Insert on the keyboard. This shortcut is

available in both terminal and file transfer windows.

Paste Selection

Select the Paste Selection option to paste text into the terminal window without first copying anything onto

the clipboard. The Paste Selection operation copies whatever is currently selected in the terminal window to

the present cursor position. If no text is selected, Paste Selection pastes a single character in the current cursor

position.

This function is almost like having two different clipboards available at the same time. The Paste Selection

option is especially useful for copying text from the output of previous commands.

The Paste Selection toolbar button is available only in the terminal window.

Find

Select the Find option to locate text (or any other characters) from the scrollback buffer. Regular expressions

can be used to select characters matching a specific pattern. The Find option is only available in the terminal

window.


227

Figure C.13. The Find dialog helps you to locate text from the scrollback buffer

• Up: This option specifies that the search should start backwards from the present position.

• Down: This option specifies that the search should start forward from the present position.

Find what

Type in the characters that you want to search for in the Find what field. If you want to use regular ex-

pressions to define the search term, select the Regular expression option, or select from a list of regular

expressions by clicking the ellipsis button (...) on the right-hand side of the Find what field.

...

Click the ellipsis button (...) to select from a list of regular expressions. Using this option will turn on the

Regular expression option.

The following regular expression types can be selected:

• Any Character

• Character in Range

• Character not in Range

• Beginning of Line

• End of Line

• Or

• 0 or More Matches

• 1 or More Matches

• Optional Match

• Match exactly n times

• Match n or more times

• Match at most n times


GUI Reference228

• Match no less than n times and no more than m times

Match whole word only

Select this option to limit the search to match only whole words (i.e. so that "wave" would not match

"waves").

Match case

Select this option to specify that the search result should be case sensitive (i.e. so that "Wave" would not

match "wave" or "waVe").

Regular expression

Select this option to specify the search term using regular expressions. This option is automatically selected

if you click the ellipsis button (...) on the right-hand side of the Find what field.

Direction

Use this option to specify whether the search should start upwards on downwards from the present position

in the scrollback buffer.

The direction of the search is relative to the last match found in the current search. If there have been no

previous matches, Up will search from the bottom of the buffer upwards, and Down will search downwards

from the very beginning of the buffer.

Find Next

Click this button to find the next match for the search term. Note that the direction in which the search

will continue is defined by the Direction option.

Cancel

Click this button to close the Find dialog.

New Terminal Window

Select the New Terminal Window option to open a new SSH Tectia Client terminal window. The new window

uses the same connections to the remote host computer as the current window, saving you the trouble of typing

your password again.

Multiple windows to a single connection allow you to for example debug your code in one window, execute

it in another, display reference information in a third one, and read your e-mail in a fourth window.

The sequence number of each window is displayed on the title bar of the window, next to the remote host

computer name. For example, a second window associated with a connection to a host computer called remote

would be shown as 2:remote.

Note

To close any extra windows when you no longer need them, click on the X-shaped close button on

the title bar of the window, in the upper right-hand corner of the window. Do not click the Disconnect


229

button or select File → Disconnect, as this would close the connection in all windows associated

with this particular connection.

New File Transfer Window

Select the New File Transfer Window option to open a file transfer window. To make file handling as easy

as possible, you can open an unlimited number of file transfer windows.


computer name. For example, a third window associated with a connection to a host computer called remote


Note

To close any extra windows when you no longer need them, click on the X-shaped close button on

the title bar of the window, in the upper right-hand corner of the window. Do not click the Disconnect

button or select File → Disconnect, as this would close the connection in all windows associated

with this particular connection.

Settings

Select the Settings option to open the Settings dialog. Settings can be used to control both the global settings

and the profile settings for each particular remote host computer. For more information on the Settings dialog,

see Chapter 5.

Contents

Select the Contents option to display the contents of the SSH Tectia Client help. In the help window you can

browse, search, and print help information.

Get Help On

Select the Get Help On option to change the mouse pointer to a help pointer. You can use the help pointer

to click on buttons, menu items or other details of the user interface to see context-sensitive help on any par-

ticular item.

C.3.2 File Transfer Window, Toolbar Buttons

The following toolbar buttons are available only in the file transfer window.

Figure C.14. The buttons numbered 1 to 11 are available only in the file transfer window


GUI Reference230

Download Dialog

Select the Download Dialog option (1 in Figure C.14) to open the Download - Select Folder dialog that allows

you to select a folder on the local computer and transfer the currently selected file into it. The shortcut key

for Download Dialog is Ctrl+D.

Upload Dialog

Select the Upload Dialog option (2 in Figure C.14) to open the Upload - Select Files dialog that allows you

to select a file and transfer it from the local computer to the remote host computer. The shortcut key for Upload

Dialog is Ctrl+U.

Toggle Transfer View

Select the Toggle Transfer View option (3 in Figure C.14) to hide or show the Transfer View pane.

Large Icons

Select the Large Icons option (4 in Figure C.14) to display the file view as a Large Icons view. Each file

and folder has a large icon associated with it, making for a clear and uncluttered display.

Small Icons

Select the Small Icons option (5 in Figure C.14) to display the file view as a Small Icons view. Each file and

folder has a small icon associated with it. This makes it possible to display several times more items than the

Large Icons view.

List

Select the List option (6 in Figure C.14) to display the file view as a List view. Each file and folder has a

small icon associated with it, and the files and folders are displayed in one column.

Details

Select the Details option (7 in Figure C.14) to display the file view as a Details view. The files and folders

are displayed with a small icon, their file name, file size, file type, last modification date and attributes visible.

By clicking on the Name, Size, Type and Modified sort bars located at the top of the File view, you can sort

the files and folders based on their file name, file size, file type and the time they were last modified. Selecting

the same sort option again reverses the sorting order.


The file types are derived from your local computer. If you have defined a new file type description for files

with a certain file name extension, also the files on the remote computer are shown to be of that file type. This

makes it easy to recognize particular file types also on the remote computer.


231

ASCII

Select the ASCII option (8 in Figure C.14) to transfer files in ASCII mode.

Binary

Select the Binary option (9 in Figure C.14) to transfer files in binary mode.

Auto Select

Select the Auto Select option (10 in Figure C.14) to automatically change the transfer mode based on the file

extension. Files using a file extension specified on the ASCII Extensions list on the Mode page of the Settings

dialog will be transferred in ASCII mode. All other files will be transferred in binary mode. For more inform-

ation, see Section 5.1.7.

Cancel Transfer

Select the Cancel Transfer option (11 in Figure C.14) to stop ongoing file transfers.

C.3.3 Profiles Bar

The Profiles bar contains buttons that allow a fast way to connect to different servers.

Figure C.15. The Profiles bar

Quick Connect

Click the Quick Connect button on the Profiles toolbar to open a new connection using the default settings.


Profiles Button

Click the Profiles button on the Profiles toolbar to open the SSH Tectia Configuration tool. For more inform-

ation on how to use profiles, see Section 4.1.5.

C.3.4 File Transfer Window, File Bar

The File bar contains buttons that can be used to perform the most common file management tasks. The File

bar is dynamically created, so it cannot be customized like the other toolbars.


GUI Reference232

Note

It is possible to have the File bar trimmed down so that it shows less buttons and leaves more room

for the favorite folders lists. The File bar with the wide folder view displays only the Show/Hide

Local Folders, Local Home, and Up buttons above the Local View, and the corresponding

Show/Hide Remote Folders, Remote Home, and Up buttons above the Remote View. See Sec-

tion 5.1.5 for more information.

Figure C.16. The File bar is specific to the file transfer window

Show/Hide Local Folders

Select the Show/Hide Local Folders option to select whether the folder view of the local directory is displayed.

The folders are displayed on the left-hand side of the Local View pane.

Local Home

Select the Home option to return to your home directory on the local computer. This is useful if you are ex-

ploring a complex directory tree and want to quickly return to where you started.

Up

Select the Up option to move the view from the current folder to its parent folder.

Example: You have a directory called home and it has a subdirectory called mail. If you are currently viewing

the mail folder and click Up, the focus moves to the home folder.

Refresh Local

Select the Refresh Local option to update the contents of the Local View. This may be necessary for example

when a file you have uploaded does not immediately become visible on the remote host computer.

New Local Folder

Select the New Local Folder option to create a new subdirectory in the current local directory. A new folder

icon appears in the Local View and you can type in the name of the new folder. (If you do not enter a name

for the folder, it will not be created.)

Delete Local

Select local files or folders that you want to remove, and select the Delete Local option to remove them. A

Confirm Delete dialog is displayed, asking you to confirm the removal.


233

Local Favorites

You can use the Local Favorites drop-down list box to open the contents of other local drives and directories

in the Local View pane. You can modify the contents of the Local Favorites list on the Local Favorites page

of the Settings dialog (see Section 5.1.8).

Add

Select the Add option to add the current directory to the Local Favorites list.

Show/Hide Remote Folders

Select the Show/Hide Remote Folders option to select whether the folder view of the remote directory is

displayed. The folders are displayed on the left-hand side of the Remote View pane.

Remote Home

Select the Remote Home option to return to your home directory on the remote computer. This is useful if

you are exploring a complex directory tree and want to quickly return to where you started. The shortcut key

for the Remote Home option is Ctrl+H.

Up



the mail folder and click Up, the focus moves to the home folder.

Refresh Remote

Select the Refresh Remote option to update the contents of Remove View. This may be necessary for example

when a file you have uploaded does not immediately become visible in the Remote View. The shortcut key

for the Refresh option is F5.

New Remote Folder

Select the New Remote Folder option to create a new subdirectory in the current remote directory. A new

folder icon appears in Remote View and you can type in the name of the new folder. (If you do not enter a

name for the folder, it will not be created.) The shortcut key for the New Remote Folder option is Ctrl+N.

Delete Remote

Select remote files or folders that you want to remove, and select the Delete Remote option to remove them.

A Confirm Delete dialog will be displayed, asking you to confirm the removal.


GUI Reference234

Remote Favorites

You can use the Remote Favorites drop-down list box to open the contents of other remote drives and direct-

ories in the Remote View pane.

Add

Select the Add option to add the current directory to the Remote Favorites list.

C.4 Menu Reference

Together with the toolbar, the menus allow quick access to different terminal and file transfer operations. The

following menus are available: File, Edit, View, Operation (only in the File Transfer window), Window,

and Help.

See also Section 5.3.5.

C.4.1 File Menu

The File menu allows access to the settings file and connect/disconnect operations.

Save Settings

Select the Save Settings option to save any changes you have made to your current settings.

Save Layout

Select the Save Layout option to save both the current settings and the current window layout.

Quick Connect

Select File → Quick Connect to open a new connection using the default settings. For more information,

see Section 3.5.

Profiles

Select File → Profiles to open the SSH Tectia Configuration GUI. For more information on how to use profiles,

see Section 4.1.5.

Print

The Print option allows you output the contents of the current scrollback buffer to a printer. For more inform-

ation on printing, see Section C.3.1.2.

The Print option is available only in the terminal window.


235C.4 Menu Reference

Print Preview

Selecting the Print Preview option displays the entire contents of the scrollback buffer split into pages in the

same way it will be printed. For more information on previewing the printer output, see Section C.3.1.3.

The Print Preview option is available only in the terminal window.

Page Setup

The Page Setup option allows you to specify how printed pages will look. For more information, see Sec-

tion 5.1.10.

The Page Setup menu option is available only in the terminal window.

Log Session

Select the Log Session option to save an entire transcript of the current terminal session to a file.

When Log Session is selected, the Save As dialog opens, asking for a file name for the log file. This file is

created if it does not already exist, and it contains a transcript of the connection. Selecting the Log Session

menu item for a second time stops logging.

When logging is active, a checkmark appears next to the Log Session menu option.

The Log Session menu option is available only in the terminal window.

Connect

Select the Connect option to establish a new Secure Shell connection to a remote host computer. A Connect

to Server dialog appears, allowing you to specify the host name (or IP address), user name and password for

the new connection.

An alternative way of establishing a new connection is to press the Enter key on the keyboard when discon-

nected.

Note

The Connect option is available only when you are not connected to a remote host computer. If you

want to establish a completely new, separate Secure Shell connection, select the Quick Connect

option instead.

Disconnect

Select the Disconnect option to disconnect from the present remote host computer. A Confirm Disconnect

dialog appears, allowing you to confirm if you really want to disconnect. Select Cancel to keep the connection

open, or Yes to end the connection.


GUI Reference236

Note

One connection can have several windows open (such as a terminal window and a file transfer

window). Disconnecting affects all windows associated with a single connection.

However, if you have launched other, separate clients, they are not affected. Disconnecting quits

one connection and all of its associated windows, but none of the separate connections.

Exit

Select the Exit option to quit SSH Tectia Client. A Confirm Exit dialog appears, allowing you to confirm if

you really want to exit. Select Cancel to keep the Secure Shell client running, or Yes to exit.

Note

One connection can have several windows open (for example several file transfer windows and

several terminal windows). Exiting affects all windows associated with a single connection.

However, if you have started other, separate clients, they are not affected. Exiting quits one connection

and all of its associated windows, but none of the separate connections.

C.4.2 Edit Menu

The Edit menu allows you to copy and paste text in the terminal window and to make changes to your con-

nection settings.

Copy

In the terminal window the Copy option can be used to copy selected text to the Windows clipboard. The

keyboard shortcut for the copy option is Ctrl+Insert in the terminal window.

In the file transfer window the Copy option can be used to create a temporary copy of the selected file(s) in

the file transfer window. This resembles using the Windows clipboard: You can copy files to a temporary

storage and paste them later into another location. The keyboard shortcut for copy is Ctrl+C in the file

transfer window.

Paste

In the terminal window the Paste option can be used to attach previously copied text from Windows clipboard

into the current cursor position. The keyboard shortcut for paste is Shift+Insert in the terminal window.

In the file transfer window Paste option can be used to add previously copied files or folders into a new loc-

ation. This resembles using the Windows clipboard: You can copy files to a temporary storage and paste them

later into another location. You can do a paste operation also by pressing Ctrl+V on the keyboard in the file

transfer window.


237C.4.2 Edit Menu

The file names of the pasted files and folders do not change during the operation. Therefore it is not possible

to paste files or folders several times into one location.

Paste Selection

The Paste Selection option is only available in the terminal window.

Select Paste Selection to paste text without first copying anything to the clipboard. The Paste Selection oper-

ation copies whatever is currently selected in the terminal window to the present cursor position. If no text is

selected, Paste Selection pastes a single character in the current cursor position.

This function is almost like having two different clipboards available at the same time. The Paste Selection

option is especially useful for quickly copying text from the output of previous commands.

Select All

Choose the Select All option to select all the text in the current terminal window and the scrollback buffer,

or all the files and folders in the current directory in the file transfer window.

Note that in the terminal window, the selection can span quite a few lines backwards from what is currently

visible. If you want to select only what is currently displayed on screen, use the Select Screen menu option

instead.

When used in the terminal window, this operation makes it fast and easy for example to save long command

output strings or to create a temporary log of what is displayed on the screen.

For file transfer, this enables you to operate on the whole contents of a directory at one time. This can be es-

pecially useful when downloading, copying, or deleting files.

The keyboard shortcut for Select All is Ctrl+A in the file transfer window only.

Select Screen

The Select Screen option is available only in the terminal window.

Choose the Select Screen option to select all the text that is currently visible in the terminal window. Note

that unlike the Select All option, Select Screen does not capture the scrollback buffer. This operation can be

especially useful for screen captures and quick snapshots of the command output.

Select None

The Select None option is available only in the terminal window.

Choose the Select None option to cancel any previous selection. This operation immediately clears the selection

in the terminal window.


GUI Reference238

FindThe Find option is available only in the terminal window.

Choosing the Find option allows you to search for text within the scrollback buffer. For more information

on searching, see Section C.3.1.9.

Settings

Select the Settings option to open the Settings dialog. Settings can be used to control both the global settings

and the profile settings for each particular remote host computer. For more information on the Settings dialog,

see Chapter 5.

C.4.3 Terminal Window, View Menu

The View menu allows you to select the way the SSH Tectia Client windows are displayed.

Toolbar

Select the Toolbar option to toggle the toolbar on and off. When the toolbar is visible, a checkmark appears

next to the Toolbar option.

Status Bar

Select the Status Bar option to toggle the status bar on and off. When the status bar is visible, a checkmark

appears next to the Status Bar option.

Profiles Bar

Select the Profiles Bar option to toggle the profiles bar on and off. When the toolbar is visible, a checkmark

appears next to the Profiles Bar option.

Customize

Select the Customize option to open the Customize dialog in which you can modify menu options, toolbars,

menu settings, and general settings. For more information on customizing the user interface, see Section 5.3.3.

Reset Toolbars

Select the Reset Toolbars option to reset the toolbar and menu positions to their original state, for example

if you have misplaced a menu or toolbar option.

Reset Terminal

Select the Reset Terminal option to reset the terminal settings to the state they were in when connecting.

This will clear the terminal window and the scrollback buffer and reset the keymap, character set, and fonts.


239C.4.3 Terminal Window, View Menu

C.4.4 File Transfer Window, View Menu

The View menu allows you to select the way the SSH Tectia Client windows are displayed.

Toolbar

Select the Toolbar option to toggle the toolbar on and off. When the toolbar is visible, a checkmark appears

next to the Toolbar option.

Profiles Bar

Select the Profiles Bar option to toggle the profiles bar on and off. When the toolbar is visible, a checkmark

appears next to the Profiles Bar option.

File Bar

Select the File Bar option to toggle the File bar on and off. When the toolbar is visible, a checkmark appears

next to the File Bar option.

Status Bar

Select the Status Bar option to toggle the status bar on and off. When the status bar is visible, a checkmark

appears next to the Status Bar option.

Local View

Select the Local View option to toggle Local View on and off. When Local View is visible, a checkmark

appears next to the Local View option.

Transfer View

Select the Transfer View option to toggle Transfer View on and off. When Transfer View is visible, a

checkmark appears next to the Transfer View option.

Customize

Select the Customize option to open the Customize dialog in which you can modify menu options, toolbars,

menu settings, and general settings. For more information on customizing the user interface, see Section 5.3.3.

Reset Toolbars

Select the Reset Toolbars option to reset the toolbar and menu positions to their original state, for example

if you have misplaced a menu or toolbar option.


GUI Reference240

Large Icons

Select the Large Icons option to display the file view as a Large Icons view. Each file and folder has a large

icon associated with it, resulting in a clear and uncluttered display.

If the Large Icons option is selected, a selection marker appears next to the menu option.

Small Icons

Select the Small Icons option to display the file view as a Small Icons view. Each file and folder has a small

icon associated with it. This makes it possible to display several times more items than the Large Icons view.

If the Small Icons option is selected, a selection marker appears next to the menu option.

List

Select the List option to display the file view as a List view. Each file and folder has a small icon associated

with it, and the files and folders are displayed in one column.

If the List option is selected, a selection marker appears next to the menu option.

Details

Select the Details option to display the file view as a Details view. The files and folders are displayed with a

small icon, their file name, file size, file type, last modification date, and attributes visible.

By clicking on the Name, Size, Type, Modified or Attributes sort bars located at the top of the folder view,

you can sort the files and folders based on their file name, file size, file type, the time they were last modified

and their file attributes. Selecting the same sort option again reverses the sorting order.


The file types are derived from the your local computer. If you have defined a new file type description for

files with a certain file name extension, also the files in the remote computer are shown to be of that file type.

This makes it easy to recognize particular file types also on the host computer.

Arrange Icons

Select the Arrange Icons option to open a submenu where you can select the order in which the files and

folders are displayed in the file view. A selection marker appears next to the currently selected Arrange Icons

option.

By Name: The files and folders are arranged alphabetically based on their file name.

By Type: The files and folders are arranged alphabetically based on their file type.

By Size: The files are arranged by their file size. Folders are arranged alphabetically.


241

By Date: The files and folders are arranged by the time they were last modified.

If you have selected the Details view, you can get the same effect by clicking on the Name, Size, Type and

Modified sort bars located at the top of the folder view. Selecting the same Arrange Icons option again reverses

the sorting order.


Show Root Directory

Select the Show Root Directory option to toggle if the root directory is displayed in the folder view. If the

root directory is not displayed, you are not able to select or view any folders above your home directory in

the directory tree hierarchy. By default the root directory is not displayed.

If the Show Root Directory option is selected, a selection marker appears next to the menu option.

Show Hidden Files

Select the Show Hidden Files option to select that the normally hidden files are displayed in the folder view.

By default, Unix hosts do not display any files or directories that begin with the dot (.) character, such as

.rhosts or .profile. Selecting the Show Hidden Files option corresponds to specifying the -a switch of

the ls command.

If the Show Hidden Files option is selected, a selection marker appears next to the Show Hidden Files menu

option.

Refresh

Select the Refresh option to update the file transfer window. This may be necessary for example when a file

you have uploaded does not immediately become visible on the remote host computer.

The keyboard shortcut for Refresh is F5.

C.4.5 File Transfer Window, Operation Menu

The Operation menu is available only in the file transfer window. It allows you to copy files to and from the

remote host computer, and to navigate the remote directory structure.

Open

The Open option can be used to view a file on the remote host computer. First select a file from the file

transfer window and select the Open option. The file will be downloaded and displayed.


GUI Reference242

Upload

Select the Upload option to upload a file, which means copying it from your local computer to the remote

host computer (server). The keyboard shortcut for Upload is Ctrl+U.

Download

Select the Download option to download a file, which means copying it from the remote host computer to

your local computer.

Note that you must first select the remote file(s) before selecting Download. If no files or folders are selected,

the Download menu option is grayed out. The keyboard shortcut for Download is Ctrl+D.

Upload Dialog

Select the Upload Dialog option to open the Upload - Select Files dialog that allows you to select a file and

transfer it from the local computer to the remote host computer. The shortcut key for Upload Dialog is Ctrl+U.

Download Dialog

Select the Download Dialog option to open the Download - Select Folder dialog that allows you to select a

folder on the local computer and transfer the currently selected file into it.

Cancel

Select the Cancel option to stop ongoing file transfers.

Up



the mail folder and click Up, the focus moves to the home folder. The keyboard shortcut for Up is the Back-

space key. This has the same effect as selecting Operation → Upload, or selecting Upload on the toolbar.

Home

Select the Home option to return to your home directory. This is useful if you are exploring a complex directory

tree and want to quickly return to where you came from. The keyboard shortcut for Home is Ctrl+H.

Go To Folder

Select the Go to Folder option enter to directly to a remote folder. A Go to Remote Folder dialog appears,

allowing you to type in the path to the desired directory on the remote host computer. The current directory

path is displayed in the text field for your reference, eliminating the need to type in long directory paths from

scratch. Type in the desired directory path and press Enter. The specified directory is shown. The keyboard

shortcut for Go To Folder is Ctrl+G.


243

New Folder

Select the New Folder option to create a new folder on the remote host computer. A new folder appears on

folder view along with a text field where you can type in the name for the new folder.

If you do not type a name for the new folder but just hit Enter, a new folder is not created. The keyboard

shortcut for New Folder is Ctrl+N.

Delete

Select the Delete option to delete one or more files or folders on the remote host computer. A Confirm Delete

dialog appears, allowing you to confirm if you really want to delete the selected files or folders. Select Cancel

to keep the selected items, or Yes to delete them. The keyboard shortcut for Delete is the Delete key.

Rename

Select a file from the file transfer window and select the Rename option to give the file a new name. The

keyboard shortcut for Rename is F2.

You can also rename a file by right-clicking the file. A shortcut menu containing the Rename option opens.

Note

The renaming operation requires an SSH Secure Shell server version 2.2.0 or later. Earlier versions

do not support renaming, and using this option will produce the Error Renaming File message.

Properties

Select a file in the file transfer window and select the Properties option to view the file properties.

You can also view the file properties by right-clicking the file. A shortcut menu containing the Properties

option opens. You can select multiple files and view their properties.

For details about the Properties page, see Section 7.2.4.

File Transfer Mode

Select the File Transfer Mode option to define the transfer mode the files will be transferred in. A submenu

opens, containing the following options:

ASCII

Select the ASCII option to transfer files in ASCII mode.

Binary

Select the Binary option to transfer files in binary mode.


GUI Reference244

Auto Select

Select the Auto Select option to automatically change the transfer mode based on the file extension. Files

that have a file extension specified in the ASCII Extensions list on the Mode page of the Settings dialog are

transferred in ASCII mode. All other files are transferred in binary mode. For more information, see Sec-

tion 5.1.7.

C.4.6 Window Menu

The Window menu allows you to open and close different types of windows.

New Terminal

Select the New Terminal option to open a new terminal window. The new window uses the same connections

to the remote host computer as the current window, saving you the trouble of typing your password again.

Multiple windows to a single connection allow you to for example debug your code in one window, execute

it in another, display reference information in a third one, and read your e-mail in a fourth window.


computer name. For example, a second window associated with a connection to a host computer called remote


To close any extra windows when you no longer need them, click on the X-shaped close button located on

the title bar of the window in the upper right-hand corner of the window. Do not click Disconnect or select

File → Disconnect, as this would close the connection in all windows associated with this particular connection.

New File Transfer

Select the New File Transfer option to open a new file transfer window. To make file handling as easy as

possible, you can open an unlimited number of file transfer windows.


computer name. For example, a third window associated with a connection to a host computer called remote


To close any extra windows when you no longer need them, click on the X-shaped close button located on

the title bar of the window, in the upper right-hand corner of the window. Do not click Disconnect or select

File → Disconnect, as this would close the connection in all windows associated with this particular connection.

New Terminal in Current Directory

Select the New Terminal in Current Directory option to open a new terminal window in the current remote

directory.


245C.4.6 Window Menu

New File Transfer in Current Directory

Select the New File Transfer in Current Directory option to open a new file transfer window in the current

remote directory.

New Windows Explorer

The New Windows Explorer menu option is available only in the File Transfer window.

Select the New Windows Explorer option to open a new Windows Explorer window. The Windows Explorer

is the familiar Windows utility that can be used to manage the files and folders on your local computer. You

can have multiple Explorer windows open at the same time to make file management easier.

Close

Select the Close option to close the current window. Other windows are unaffected, even if they are associated

with the same connection.

Close All Others

Select the Close all Others option to close all the other SSH Tectia Client windows associated with the active

connection.

A single connection can have several windows open (such as an SSH Tectia Client terminal window and a

file transfer window). The Close All Others operation affects all the other windows associated with a particular

connection.

However, if you have started other, separate clients, they are not affected by this operation. Close All Others

only affects one connection and all of its associated windows but no other connections.

C.4.7 Help Menu

The Help menu allows you to access the help and copyright information.

Contents

Select Help → Contents to open the contents page and view the help as Web pages. A browser opens and

the HTML-based help files are loaded locally from your own computer. Click on a chapter you want to explore,

or click the Index link to see an alphabetical listing of keywords.

Get Help On

Select the Get Help On option to change the mouse pointer to a help pointer. You can use the help pointer

to click on buttons, menu items or other details of the user interface to see context- sensitive help on any

particular item.


GUI Reference246

SSH on the Web

Select the SSH on the Web option to open a submenu containing Web links to SSH Tectia Client Web pages.

Online Help

Select the Online Help option to load the Web version of SSH Tectia Client help (http://www.ssh.com/sup-

port/documentation/online/ssh/winhelp/). This is useful if you want to see the most up-to-date version of the

help.

Frequently Asked Questions

Select the Frequently Asked Questions option to load the online version of the SSH Tectia Client FAQ (ht-

tp://www.ssh.com/support/faq/).

Home Page

Select the Home Page option to open the SSH Communications Security home page (http://www.ssh.com).

Troubleshooting

Select the Troubleshooting option to display the Troubleshooting dialog. If you encounter problems when

using SSH Tectia Client, you can send a bug report by using the support web form at http://www.ssh.com/sup-

port. To make the support team's work easier, you should describe your system and the problem situation as

carefully as possible.

Click the Copy to Clipboard button to copy the troubleshooting report onto the Windows clipboard. You

can then paste (Ctrl+V) the report into the support web form. Describe your problem also in your own words.


247

http://www.ssh.com/support/documentation/online/ssh/winhelp/

http://www.ssh.com/support/documentation/online/ssh/winhelp/

http://www.ssh.com/support/faq/

http://www.ssh.com/support/faq/

http://www.ssh.com

http://www.ssh.com/support

http://www.ssh.com/support

Figure C.17. The Troubleshooting dialog

Debugging

Select the Debugging option to open the Debugging dialog, and to gather debugging information useful for

tracking possible errors.


GUI Reference248

Figure C.18. The Debugging dialog

Enable Debugging

Select the Enable Debugging check box to log debugging information. Enabling this option slows down the

client, so it should be only done to track error situations, for example when requested by SSH technical support.

Debug

The Debug options define how much debugging information is collected and where the data is saved.

Level

Type in a number to indicate the debug level. Higher numbers produce more debugging data. A typical

value for debug level is 3 or 4. Debug levels approaching 10 produce large amounts of debugging data

and make the software very slow.

Alternatively you can specify different debug levels for different operations. For example the debug value

4, ssheventloop=7 would define the general debug level as 4, but for activity performed in the SSH

event loop the debug level would be 7.


249

File

Select the file to save debug data in. Either type in the path and filename, or click the button on the right-

hand side of the text field to open a Save As dialog, allowing you to locate the file. If you do not specify

a path, the default user path is used.

Clear File on Startup

Select the Clear File on Startup check box to delete the debug data every time SSH Tectia Client is

launched.

Note

If this option is not selected, the log file will keep growing and must be manually manually

cleared.

Debug File

The Debug File displays a scrollable view of the currently gathered debug data. If the debug file is very large

(over 3 megabytes), it will not be displayed.

Clear File

Click the Clear File button to empty the current debug data file.

Open File in Editor

Click the Open File in Editor button to open the current debug data file in a text editor, allowing you

to view, edit, save, or print the data.

OK

Click the OK button to accept the current settings and close the Debugging dialog.

Cancel

Click the Cancel button to discard the changes and close the Debugging dialog.

Import License File

SSH Tectia Client requires a license file to function in commercial mode.

With the Import License File option you can update your evaluation copy of SSH Tectia Client to a commercial

version. Do the following:

1. Select Help → Import License File. A dialog opens, requesting a file name.

2. Locate the license file (stc51.dat or stcf51.dat by default) and click Open. A dialog opens, stating

that the license file was successfully imported and copied to the installation directory.

3. Click the OK button to continue. Your copy of SSH Tectia Client is now licensed.


GUI Reference250

About SSH Tectia

Select the About SSH Tectia option to view the copyright information on SSH Communications Security

SSH Tectia Client. Also version and license information is displayed. Click OK to close the dialog.


251


GUI Reference252

Appendix D Broker Configuration File

SyntaxThe DTD of the broker configuration file is shown below:

























<!ELEMENT secsh-broker (general?,default-settings?,profiles?,

static-tunnels?,gui?,

filter-engine?,logging?)>

<!ATTLIST secsh-broker

version CDATA #IMPLIED>



<!ELEMENT general (crypto-lib?,cert-validation?,key-stores?,

strict-host-key-checking?,host-key-always-ask?,

accept-unknown-host-keys?,known-hosts?)>



<!ELEMENT crypto-lib EMPTY>

<!ATTLIST crypto-lib

mode (fips|standard) "standard">



<!ELEMENT cert-validation (ldap-server*,ocsp-responder*,dod-pki?,

ca-certificate*)>

<!ATTLIST cert-validation

end-point-identity-check (yes|no|YES|NO) "yes"


253

default-domain CDATA #IMPLIED

http-proxy-url CDATA #IMPLIED

socks-server-url CDATA #IMPLIED>

<!ELEMENT ldap-server EMPTY>

<!ATTLIST ldap-server

address CDATA #REQUIRED

port CDATA "389">

<!ELEMENT ocsp-responder EMPTY>

<!ATTLIST ocsp-responder

url CDATA #REQUIRED

validity-period CDATA "0">



<!ELEMENT ca-certificate (#PCDATA)>

<!ATTLIST ca-certificate

name CDATA #REQUIRED

file CDATA #IMPLIED

disable-crls (yes|no|YES|NO) "no"

use-expired-crls CDATA "0" >



<!ELEMENT dod-pki EMPTY>

<!ATTLIST dod-pki

enable (yes|no|YES|NO) "no" >

<!ELEMENT key-stores (key-store*)>

<!ELEMENT key-store EMPTY>

<!ATTLIST key-store

type CDATA #REQUIRED

init CDATA #IMPLIED>

<!ELEMENT strict-host-key-checking EMPTY>

<!ATTLIST strict-host-key-checking

enable (yes|no|YES|NO) #REQUIRED>

<!ELEMENT host-key-always-ask EMPTY>

<!ATTLIST host-key-always-ask


<!ELEMENT accept-unknown-host-keys EMPTY>

<!ATTLIST accept-unknown-host-keys


<!ELEMENT known-hosts EMPTY>

<!ATTLIST known-hosts

path CDATA #REQUIRED>




Broker Configuration File Syntax254

<!ELEMENT default-settings (ciphers?, macs?,

transport-distribution?, rekey?,

authentication-methods?,

compression?, proxy?, idle-timeout?,

server-banners?, forwards?)>



<!ELEMENT server-banners EMPTY>

<!ATTLIST server-banners

visible (yes|no|YES|NO) "yes">



<!ELEMENT ciphers (cipher*)>



<!ELEMENT cipher EMPTY>

<!ATTLIST cipher

name CDATA #REQUIRED>



<!ELEMENT macs (mac*)>



<!ELEMENT mac EMPTY>

<!ATTLIST mac

name CDATA #REQUIRED>

<!ELEMENT rekey EMPTY>

<!ATTLIST rekey

bytes CDATA "0">



<!ELEMENT authentication-methods (authentication-method*)>



<!ELEMENT transport-distribution EMPTY>

<!ATTLIST transport-distribution

num-transports CDATA #REQUIRED>



<!ELEMENT authentication-method EMPTY>

<!ATTLIST authentication-method

name CDATA #REQUIRED

response CDATA #IMPLIED

response-file CDATA #IMPLIED>



<!ELEMENT proxy EMPTY>

<!ATTLIST proxy

ruleset CDATA #REQUIRED>


255



<!ELEMENT idle-timeout EMPTY>

<!ATTLIST idle-timeout

type (connection) "connection"

time CDATA #IMPLIED>



<!ELEMENT forwards (forward*)>



<!ELEMENT forward EMPTY>

<!ATTLIST forward

type (x11|agent) #REQUIRED

state (on|off|denied) #REQUIRED>



<!ELEMENT compression EMPTY>

<!ATTLIST compression

name CDATA #IMPLIED

level CDATA #IMPLIED>



<!ELEMENT profiles (profile*)>



<!ELEMENT profile (hostkey?, ciphers?, macs?,

transport-distribution?, rekey?,

authentication-methods?,

compression?, proxy?, idle-timeout?,

server-banners?, forwards?, tunnels?)>

<!ATTLIST profile

id ID #REQUIRED

name CDATA #IMPLIED

host CDATA #REQUIRED

port CDATA "22"

connect-on-startup (yes|no|YES|NO) "no"

user CDATA #IMPLIED

gateway-profile CDATA #IMPLIED>



<!ELEMENT hostkey (#PCDATA)>

<!ATTLIST hostkey

file CDATA #IMPLIED>



<!ELEMENT tunnels (local-tunnel*,remote-tunnel*)>



<!ELEMENT local-tunnel EMPTY>



<!ATTLIST local-tunnel

type CDATA "tcp"

listen-port CDATA #REQUIRED

dst-host CDATA "127.0.0.1"

dst-port CDATA #REQUIRED

allow-relay (yes|no|YES|NO) "no">



<!ELEMENT remote-tunnel EMPTY>

<!ATTLIST remote-tunnel

type CDATA "tcp"




allow-relay (yes|no|YES|NO) "no">



<!ELEMENT static-tunnels (tunnel*)>



<!ELEMENT tunnel EMPTY>

<!ATTLIST tunnel

type CDATA "tcp"




allow-relay (yes|no|YES|NO) "no"

profile CDATA #REQUIRED>



<!ELEMENT gui EMPTY>

<!ATTLIST gui

hide-tray-icon (yes|no|YES|NO) #IMPLIED

show-exit-button (yes|no|YES|NO) #IMPLIED

show-admin (yes|no|YES|NO) #IMPLIED

enable-connector (yes|no|YES|NO) #IMPLIED

show-security-notification (yes|no|YES|NO) #IMPLIED>

<!ELEMENT filter-engine (network|dns|filter)*>

<!ATTLIST filter-engine

ip-generate-start CDATA #IMPLIED>

<!ELEMENT network EMPTY>

<!ATTLIST network

id ID #REQUIRED

address CDATA #IMPLIED

domain CDATA #IMPLIED

ip-generate-start CDATA #IMPLIED>

<!ELEMENT dns EMPTY>

<!ATTLIST dns


257

id ID #REQUIRED

network-id IDREF #IMPLIED

application CDATA #IMPLIED

host CDATA #IMPLIED

ip-address CDATA #IMPLIED

pseudo-ip (yes|no|YES|NO) "no">

<!ELEMENT filter EMPTY>

<!ATTLIST filter

dns-id IDREF #REQUIRED

ports CDATA #REQUIRED

action CDATA #REQUIRED

profile-id CDATA #IMPLIED

fallback-to-plain (yes|no|YES|NO) "no">

<!ELEMENT logging (log-events*)>





<!ENTITY % default-log-event-facility '"normal"'>



<!ENTITY % default-log-event-severity '"notice"'>

<!ELEMENT log-events (#PCDATA)>

<!ATTLIST log-events

facility (normal|daemon|user|auth|local0|local1|

local2|local3|local4|local5|local6|local7|discard)

%default-log-event-facility;

severity (informational|notice|warning|error|critical|

security-success|security-failure)

%default-log-event-severity;>



Appendix E Man Pages and Help FilesOn Unix, the following manual pages are included in the SSH Tectia Client distribution:

• ssh-broker-g3.1: Connection Broker – Generation 3

• ssh-broker-config.5: Connection Broker configuration file format

• sshg3.1: Secure Shell terminal client – Generation 3

• scpg3.1: Secure Shell file copy client – Generation 3

• sftpg3.1: Secure Shell file transfer client – Generation 3

• ssh-convert-ftp.1: FTP-SFTP convertor

• ssh-keygen-g3.1: authentication key pair generator

• ssh-cmpclient-g3.1: certificate enrollment client

• ssh-certview-g3.1: certificate viewer

• ssh-ekview-g3.1: external key viewer

On Windows, SSH Tectia Client includes a context-sensitive online help that can be accessed in the configur-

ation dialogs. In addition, the SSH Tectia Server program group includes links to SSH Tectia user document-

ation in PDF format. The documents can be found in the "<INSTALLDIR>\SSH Tectia AUX\documents"

directory.


259


Man Pages and Help Files260

Appendix F Audit MessagesThis appendix lists the audit messages generated by the Connection Broker.

1000 KEX_failure

Level: warning

Origin: SSH Tectia Server, Connection Broker

The key exchange failed.

Default log facility: normal

DescriptionArgument

User's login name (not present for first KEX)Username

KEX algorithm name (not present if failure happens

before choosing the algorithm)

Algorithm

Error descriptionText

Session identifier (not present for first KEX)Session-Id

1001 Algorithm_negotiation_failure

Level: warning


Algorithm negotiation failed - there was no common algorithm in the client's and server's lists.


DescriptionArgument


Algorithm typeAlgorithm

Client's algorithm listClient algorithms

Server's algorithm listServer algorithms


1002 Algorithm_negotiation_success

Level: informational



261

Algorithm negotiation succeeded.


DescriptionArgument


Negotiated algorithmsText


1100 Certificate_validation_failure



A received certificate failed to validate correctly under any of the configured CAs.


DescriptionArgument


Resulting search states for all configured CAs.Text


1101 Certificate_validation_success



A received certificate validated correctly under one or more configured CAs.


DescriptionArgument

User's login nameUsername

A list of CAs under which the user's certificate validated

correctly.

CA List

Session identifierSession-Id

1110 CM_find_started



A low-level search was started in the certificate validation subsystem.


DescriptionArgument

Search contextCtx

Search constraints.Search constraints


Audit Messages262

1111 CM_find_finished



A low-level find operation has finished in the certificate validation subsystem.


DescriptionArgument

Context pointer that identifies the searchCtx

1112 CM_cert_not_in_search_interval



The certificate is not valid during the required time period.


DescriptionArgument

Subject name of the certificateSubjectName

Error descriptionText

Search contextCtx

1113 CM_certificate_revoked



A certificate was found to be revoked.


DescriptionArgument


The context pointer of the searchCtx

1114 CM_cert_search_constraint_mismatch



The certificate did not satisfy the constraints set for the search.


DescriptionArgument


Description of the mismatchText

Search contextCtx


263

1115 CM_ldap_search_started



An LDAP search for a CRL or a sub-CA is being started.


DescriptionArgument

Search detailsText

1116 CM_ldap_search_success



An LDAP search for a CRL or a sub-CA completed successfully.


DescriptionArgument

Search detailsText

1117 CM_ldap_search_failure



The attempt to contact an LDAP server was unsuccessful.


DescriptionArgument

Error detailsText

1118 CM_http_search_started



The certificate validation subsystem is initiating a search for a CRL or a sub-CA through the HTTP protocol.


DescriptionArgument

Search targetText

1119 CM_http_search_success




Audit Messages264

An HTTP request for a CRL or a sub-CA completed successfully.


DescriptionArgument

Status message detailing what was being retrievedText

1120 CM_http_search_failure



An HTTP request for a CRL or a sub-CA failed.


DescriptionArgument

Error detailsText

1121 CM_crl_added



A new CRL was successfully added to the certificate validation subsystem.


DescriptionArgument

CRL's issuer and validity periodText

1122 Certificate_end_point_id_check_success


Origin: Connection Broker

End point identity check succeeded.


DescriptionArgument

Host nameServer

Explanatory messageText

1123 Certificate_end_point_id_check_warning



Certificate end point identity check warning.



265

DescriptionArgument

Host nameServer

Warning messageText

1124 Certificate_end_point_id_check_failure



Certificate end point identity check failure.


DescriptionArgument

Host nameServer

Error messageText

1200 Key_store_create



Key store created.


1201 Key_store_create_failed

Level: warning


Key store creation failed.


1202 Key_store_destroy



Key store destroyed.


1204 Key_store_add_provider



Added a provider to the key store.



Audit Messages266

DescriptionArgument

Provider typeType

Initialization infoInit info

1205 Key_store_add_provider_failed

Level: warning


Adding a provider to the key store failed.


DescriptionArgument

Provider typeType

Initialization infoInit info

Error messageEK error

1206 Key_store_remove_provider



Removed a provider from the key store.


DescriptionArgument

Provider nameInit info

1208 Key_store_decrypt



A key was used successfully for decryption.


DescriptionArgument

Key pathKey path

Fwd pathFwd path

1209 Key_store_decrypt_failed

Level: warning


A key was used unsuccessfully for decryption.



267

DescriptionArgument

Key pathKey path

Fwd pathFwd path

Error stringCrypto error

1210 Key_store_sign



A key was used successfully for signing.


DescriptionArgument

Key pathKey path

Fwd pathFwd path

1211 Key_store_sign_failed

Level: warning


A key was used unsuccessfully for signing.


DescriptionArgument

Key pathKey path

Fwd pathFwd path


1212 Key_store_sign_digest



A key was used successfully for signing a digest.


DescriptionArgument

Key pathKey path

Fwd pathFwd path

1213 Key_store_sign_digest_failed

Level: warning


A key was used unsuccessfully for signing a digest.


Audit Messages268


DescriptionArgument

Key pathKey path

Fwd pathFwd path


1214 Key_store_ek_provider_failure

Level: warning


External key provider failure.


DescriptionArgument

Key pathKey path

Key labelText

6000 Broker_client_connect



A client connected to the Broker.

Default log facility: discard

DescriptionArgument

Client nameClient

Process idPid

Local user nameLocal username

6001 Broker_client_connect_failed

Level: warning


A client attempted to connect unsuccessfully to the Broker.


DescriptionArgument

Client nameClient

Process idPid


ReasonText

6002 Broker_client_disconnect


269



A client disconnected from the Broker.


DescriptionArgument

Client nameClient

Process idPid


Error textText

6004 Broker_exec_channel_open



The Broker opened an exec channel.


DescriptionArgument

Client nameClient

Client process idPid

Server hostServer

Server portServer Port

Remote user nameRemote username


CommandCommand

Exec parametersText

Channel IDChannel Id

Session IDSession-Id

6005 Broker_exec_channel_open_failed

Level: warning


The Broker failed to open an exec channel for a client.


DescriptionArgument

Client nameClient


Server hostServer



Audit Messages270

DescriptionArgument



CommandCommand

Exec parametersText


ReasonText


6006 Broker_tunnel_open



The Broker opened a tunnel for a client.


DescriptionArgument

Client nameClient


Server hostServer




Destination hostDst

Destination portDst Port

Tunnel typeTunnel type


6007 Broker_tunnel_open_failed

Level: warning


The Broker failed to open a tunnel for a client.


DescriptionArgument

Client nameClient


Server hostServer




Destination hostDst


271

DescriptionArgument



ReasonText


6008 Broker_tunnel_listener_open



The Broker opened a tunnel listener for a client.


DescriptionArgument

Client nameClient


Server hostServer




Listener hostListener

Listener portListener Port

Destination hostDst



Tunnel listener parametersText


6009 Broker_tunnel_listener_open_failed

Level: warning


The Broker failed to open a tunnel listener for a client.


DescriptionArgument

Client nameClient


Server hostServer




Listener hostListener


Audit Messages272

DescriptionArgument

Listener portListener Port

Destination hostDst



Tunnel listener parametersText

ReasonText


6010 Broker_channel_fd_strip



The Broker destroyed a channel object (and returned the underlying fd to the client).


DescriptionArgument

Client nameClient



Channel permanent?Text



6011 Broker_channel_fd_strip_failed

Level: warning


The Broker failed to destroy a channel object (and return the underlying fd to the client).


DescriptionArgument

Client nameClient



Channel permanent?Text


ReasonText


6012 Broker_channel_control




273

The Broker sent a channel control message.


DescriptionArgument

Client nameClient



CommandCommand

ArgumentsArgs



6013 Broker_channel_control_failed

Level: warning


The Broker failed to send a channel control message.


DescriptionArgument

Client nameClient



CommandCommand

ArgumentsArgs


ReasonText


6014 Broker_channel_close



The Broker closed a channel.


DescriptionArgument

Client nameClient



Exit valueExit Value




Audit Messages274

6015 Broker_channel_close_failed

Level: warning


The Broker failed to close a channel.


DescriptionArgument

Client nameClient




ReasonText

6016 Broker_profile_list_request



The Broker sent a profile list to a client.


DescriptionArgument

Client nameClient


List of profilesText


6018 Broker_server_version_request



The Broker requested (and got) the server version.


DescriptionArgument

Client nameClient



VersionVer



6019 Broker_server_version_request_failed

Level: warning


275


The Broker failed to get the server version.


DescriptionArgument

Client nameClient




ReasonText


6020 Broker_channel_process_exit



Channel process exit request was successful.


DescriptionArgument

Client nameClient




6021 Broker_channel_process_exit_failed

Level: warning


Channel process exit request failed.


DescriptionArgument

Client nameClient


ReasonText



6022 Broker_ui_auth




Audit Messages276

An UI authentication request was successful.


DescriptionArgument

Client nameClient



6023 Broker_ui_auth_failed

Level: warning


An UI authentication request failed.


DescriptionArgument

Client nameClient



ReasonText

6025 Broker_connector_license_check_failed

Level: warning


Connector license check failed.


DescriptionArgument

Error messageText


6026 Broker_server_rekey

Level: notice


The Broker requested rekeying and it was successful.


DescriptionArgument

Client nameClient




277

DescriptionArgument



6027 Broker_server_rekey_failed

Level: warning


The Broker requested rekeying but it failed.


DescriptionArgument

Client nameClient




ReasonText


6028 Broker_server_conn_statistics_request

Level: notice


The Broker requested (and got) connection statistics.


DescriptionArgument

Client nameClient




Statistics stringText


6029 Broker_server_conn_statistics_failed

Level: warning


The Broker requested connection statistics but failed.


DescriptionArgument

Client nameClient



Audit Messages278

DescriptionArgument



ReasonText


6030 Broker_server_chan_statistics_request

Level: notice


The Broker requested (and got) channel statistics.


DescriptionArgument

Client nameClient






6031 Broker_server_chan_statistics_failed

Level: warning


The Broker requested channel statistics but failed.


DescriptionArgument

Client nameClient




ReasonText


6032 Broker_server_forwards_request

Level: notice


The Broker requested (and got) a list of active forwards.



279

DescriptionArgument

Client nameClient






6033 Broker_server_forwards_request_failed

Level: notice


The Broker requested connection statistics but failed.


DescriptionArgument

Client nameClient




ReasonText


6100 Broker_starting

Level: notice


The Broker is starting.


DescriptionArgument


6101 Broker_start_failed

Level: warning


Starting the Broker failed.


DescriptionArgument


Error codeSuccess | Error

Error messageText


Audit Messages280

6102 Broker_running

Level: notice


The Broker is running.


DescriptionArgument


6104 Broker_stopping

Level: notice


The Broker is stopping.


DescriptionArgument


6106 Broker_reconfig_started

Level: notice


Reconfiguration started.


DescriptionArgument


6108 Broker_reconfig_finished

Level: notice


Reconfiguration finished.


DescriptionArgument


Error codeSuccess | Error

6200 Broker_tcp_connect




281

Broker TCP connection attempt was successful.


DescriptionArgument

Destination hostDst


Source portSrc Port

Local usernameLocal username

6201 Broker_tcp_connect_failed

Level: warning


Broker TCP connection attempt failed.


DescriptionArgument

Destination hostDst



NIO errorNIO error

6204 Broker_transport_connect



A transport was connected through TCP.


DescriptionArgument

Destination hostDst


Remote usernameRemote username

Source portSrc Port



6206 Broker_transport_gateway_connect



A transport was connected through a gateway handle.



Audit Messages282

DescriptionArgument

Destination hostDst





6208 Broker_connection_connect



The Broker got successfully a Secure Shell connection up.


DescriptionArgument

Destination hostDst




Is this going through a gateway handleUses gateway?


6209 Broker_connection_connect_failed

Level: warning


The Broker failed to get a Secure Shell connection up.


DescriptionArgument

Destination hostDst




Is this going through a gateway handleUses gateway?


Error codeText

6210 Broker_connection_disconnect



A Secure Shell connection initiated by the Broker was disconnected.


283


DescriptionArgument

Local userLocal username


6211 Broker_unknown_hostkey_accepted

Level: warning


The Broker accepted an unknown hostkey without user interaction because of configuration.


DescriptionArgument

Key digestText

Destination hostDst




6301 Broker_userauth_failure

Level: warning


User authentication failed.


DescriptionArgument

ReasonText


6302 Broker_userauth_method_success



A user authentication method succeeded.


DescriptionArgument

Authentication methodText


6303 Broker_userauth_method_failure

Level: warning


Audit Messages284


A user authentication method failed.


DescriptionArgument

Authentication methodText

ReasonText


6401 Connector_filter_rule



Connector not tunneling


DescriptionArgument

Connector actionConnector

DNS entry IDDNS entry

ApplicationApplication

AddressDst

PortDst Port


285


Audit Messages286

Index

Symbols.rhosts, 242

.ssh2, 121–122

Aaccount

local, 135

agent forwarding, 48, 159

AIX

installation, 16

uninstallation, 23

Application Data, 29, 84

application icon, 23

application tunneling, 159

ASCII file transfer mode, 115, 232, 244

association

file type, 110, 122, 215

attributes

file, 220, 222

audit messages, 261

authentication, 129, 135

certificate, 35, 83, 87, 132–133, 144

GSSAPI, 60, 69, 147

host-based, 146

Kerberos, 147

keyboard-interactive, 60, 69, 146

PAM, 147

password, 60, 69, 134, 146

public-key, 35, 60, 69, 83, 129, 135

RADIUS, 146

SecurID, 146

authentication methods, 45, 60, 69, 129

authority info access, 133

authorization file, 171

authorized_keys directory, 171

authorized_keys file, 172

Bbase-64, 201

basic configuration, 37

binary file transfer mode, 115, 232, 244

bug report, 247

CCA certificate, 41, 87, 133

canceling file transfer, 232, 243

case-sensitive search, 229

case-sensitivity, 110, 215, 241

certificate

enrolling, 145

revoked, 133

certificate authentication

server, 39, 87, 132–133

user, 83, 144

certificate enrollment, 146

certificate revocation list (CRL), 133, 145

certificate validation, 39

certificate viewer, 199

certificates, 31, 83

certification

FIPS 140-2, 39, 58

certification authority (CA), 39, 132

changing file permissions, 220, 222

channel, 159

checkpoint-restart, 156, 186

chmod, 114, 154

ciphers, 44

client configuration file, 27

closing connections, 226, 236–237

closing windows, 229, 245–246

CMP client, 193

color settings, 78, 105, 107

command-line options, 120

command-line tools, 167

Compatibility Notes, 35

components, 27

compression, 46

configuration file, 224, 235

server, 27

syntax, 253

configuring menus, 123, 126


287

configuring SSH Tectia Client, 101

configuring toolbars, 125

confirmation dialogs, 107

Connection Broker, 35, 37, 57

connection log, 31

connection profile, 48

connection profiles, 67

connection settings, 101, 230, 239

connections, 30

Connections view, 30

context-sensitive help, 230

Control Panel, 26

copying files, 231, 243

copying text, 103

copying text in terminal window, 227, 238

creating folders, 151, 153

creating local folders, 233

creating remote folders, 234, 244

CRL

disabling, 41, 133

CRL distribution point, 133

cryptographic library, 39, 58

customer support, 12

customizing settings, 123, 239–240

Ddebug file, 249

debug level, 249

debugging, 248

default domain, 39, 89

default installation directory, 22

default menus, 239–240

default profile, 121

default terminal settings, 239

default toolbars, 239–240

defining Connection Broker menu items, 59

defining date format, 111

defining favorites, 234–235

defining global settings, 101

defining pop-up menus, 124

defining settings for all connections, 101

defining shortcut menus, 124

defining SSH Tectia Connector menu items, 92

defining terminal colors, 105

defining time format, 111

deleting local files, 233

deleting local folders, 233

deleting remote files, 234, 244

deleting remote folders, 155, 234, 244

desktop, 23, 122, 216

Diffie-Hellman key exchange, 130, 132

digital signature, 135

Digital Signature Algorithm (DSA), 139

directory

default installation, 22

root directory, 109, 242

directory structure, 242

disabling CRL, 41, 88, 133

disconnecting, 226, 229–230, 236, 245

disk space requirement, 13

Document Type Definition (DTD), 253

documentation, 9

documentation conventions, 11

DoD PKI, 41, 89

DOS shell, 120

download status, 150

downloading files, 150–151, 231, 243

DSA (Digital Signature Algorithm), 139

dynamic port forwarding, 161

Eegrep syntax, 205

end-point identity check, 39, 89

enrolling certificates, 146

enrolling user certificate, 145

Entrust, 85

Entrust keys, 43

event log, 57, 65

event loop, 249

examples of using SSH Tectia Client, 35

exit values

scpg3, 181

sftpg3, 189

ssh-convert-ftp, 191


Index288

sshg3, 178

expired CRL, 41

Explorer, 212

external key viewer, 203

FFAQ, 247

Federal Information Processing Standard (FIPS), 39,

58

file attributes, 215, 220, 222, 231

file details, 241

file locations

installed files, 27

file permissions, 114, 215, 220, 222

file properties, 220, 222, 244

file size, 155

file system limitations, 215

file transfer, 149–150, 182, 217, 231–232, 243

ASCII mode, 232, 244

binary mode, 232, 244

downloading, 150–151, 231, 243

mode, 114–115, 232, 244

uploading, 152, 231

File Transfer Protocol (FTP), 95, 156, 164, 212

file transfer settings, 81, 108, 112

file transfer window, 212

navigating, 219

refreshing, 242

file transfer window default view, 110

file transfer window layout, 212

file transfer window shortcut menus, 219

file type association, 110, 122, 215

files

copying, 231, 243

hidden, 216, 242

renaming, 244

filter rules, 92

fingerprint, 130, 193

FIPS 140-2 certification, 39, 58

FIPS mode, 44–45

firewall, 133

folder

root directory, 109, 242

folder details, 241

folder management, 246

folder view

local, 216

remote, 217

fonts

installed, 105

terminal, 104

forwarding, 159

agent, 159

local, 159

remote, 162

X11, 159

forwarding FTP, 164

forwarding X11, 165

Frequently Asked Questions, 247

FTP (File Transfer Protocol), 212

FTP forwarding, 164

FTP-SFTP conversion, 95, 156

Ggenerating keys, 83, 138

Generic Security Service API (GSSAPI), 147

getting started with SSH Tectia Client, 27

getting support, 12

glob patterns, 189

global settings, 101, 230

global.dat, 101, 121, 224, 235

GSSAPI authentication, 60, 69, 147

Hhelp

context-sensitive, 230, 246

help files, 259

help pointer, 230

Hexl, 201

hidden files, 109, 216, 242

home directory, 216

host key

public, 86, 130

host name, 33


289

host settings, 27, 230, 239

host-based authentication, 146

hostkeys directory, 170

HP-UX

installation, 17

uninstallation, 24

HTTP proxy, 145

HTTP proxy URL, 40, 89

HTTP repository, 133, 145

IIBM AIX, 16

icons, 23, 122, 214

moving, 126

identification file, 137, 145, 169

idle timeout, 47

importing license file, 250

incoming tunnel, 159

incoming tunnels, 76, 162

installation

removing, 23

silent, 22

upgrading, 15

installation directory, 22

installed files, 27

installed fonts, 105

installing on AIX, 16

installing on HP-UX, 17

installing on Linux, 18

installing on Solaris, 19

installing on Windows, 20

IP addresses

pseudo IP, 92

KKerberos authentication, 147

key exchange, 130, 132

key file, 140

key fingerprint, 130, 193

Key Generation wizard, 138

key pair, 135

key providers, 84

key security, 135

key stores, 41, 43

keyboard settings, 79

keyboard shortcut, 124, 209

keyboard-interactive authentication, 60, 69, 146

keys, 31, 83, 86

Keys view, 31

known-hosts file, 132

known_hosts file, 43, 171

LLDAP servers, 40, 90

library

cryptographic, 39, 58

library certification

FIPS 140-2, 39, 58

license file, 14, 250

licensing, 14

Lightweight Directory Access Protocol (LDAP), 133,

145

limitations

file system, 215

Linux

installation, 18

uninstallation, 24

local drive, 151

local files

deleting, 233

local folders, 216, 233

creating, 233

deleting, 233

local home directory, 216

local port forwarding, 159

local tunnels, 75, 159

local user account, 135

local views

refreshing, 233

locale, 111

locating text, 227, 239

location

installed files, 27

log information, 31


Index290

logging, 31, 57, 65

Logs view, 31

MMACs, 45

man pages, 259

man-in-the-middle attack, 130, 132

maximum file size, 155

menu options, 30, 59, 92

moving, 123

menus

configuring, 126

customizing, 123

moving, 126

resetting, 127, 239–240

message, 107

Microsoft Crypto API, 85

Microsoft Office, 103

Microsoft Windows, 20

moving menu options, 123

moving menus, 126

moving toolbar buttons, 126

moving toolbars, 126

MSCAPI, 85

MSI package, 20

multiple windows, 104, 122, 212, 229–230, 245–246

multiple Windows Explorer windows, 246

Nnavigating


nested tunnel, 68

non-interactive installation, 22

OOCSP responders, 40, 88

Online Certificate Status Protocol (OCSP), 133, 145

online help, 246–247

online purchase, 14

opening file transfer windows, 246

opening new connections, 236

opening remote files, 242

opening terminal windows, 245

opening Windows Explorer windows, 246

OpenSSH authorized_keys file, 172

OpenSSH keys, 43, 144

OpenSSH known_hosts file, 43, 171

options

command-line, 120

outgoing tunnel, 159

outgoing tunnels, 75, 159

PPAM authentication, 147

pass-through

applications, 91

passphrase, 136

password authentication, 60, 69, 134, 146

pattern matching, 227

pattern syntax, 205

PEM encoding, 201

permissions, 215

file, 220, 222

PKCS #11 token, 145

PKCS #12 certificates, 146

PKCS #7 certificates, 146

PKCS #7 package, 133

PKCS#11 keys, 44

PKCS#12, 43

PKCS#7, 43

Pluggable Authentication Module (PAM), 147

pop-up menus, 124, 150, 152, 219

customizing, 123

port forwarding, 74, 159

dynamic, 161

local, 159

remote, 162

restricting, 159

port number, 33

positioning menu items, 123

positioning menus, 126

positioning toolbar buttons, 126

positioning toolbars, 126

printing, 118, 225


291

private key

user, 136, 146

process name, 91

profile

roaming, 135

profile settings, 101, 230, 239

profiles

default, 121

program group, 22

program icon, 23

program shortcuts, 122

Programs menu, 22

properties

file, 220, 222

proxy rules, 46

proxy settings, 63, 73

pseudo IP start, 92

public key

host, 86, 130

user, 136

public-key authentication, 35, 135

server, 86, 129

user, 60, 69, 83, 135

QQuick Connect, 34, 232, 235

RRADIUS authentication, 146

random_seed file, 169

Red Hat Linux, 18

refreshing file transfer window, 242

refreshing local views, 233

refreshing remote views, 234

regex syntax, 205

registering, 250

regular expression (regex), 227–228

regular expressions, 205

rekey interval, 45

related documents, 9

remote files

deleting, 234, 244

remote folders, 217, 234

creating, 234, 244

deleting, 155, 234, 244

navigating, 243

remote host computer, 101

remote port forwarding, 162

remote tunnels, 76, 162

remote views

refreshing, 234

removing from AIX, 23

removing from HP-UX, 24

removing from Linux, 24

removing from Solaris, 25

removing from Windows, 26

removing SSH Tectia Client, 23

renaming files, 244

resetting menus, 127, 239–240

resetting toolbars, 126, 239–240

return values

scpg3, 181

sftpg3, 189

ssh-convert-ftp, 191

sshg3, 178

returning menus to default, 127

returning toolbars to default, 126

revoked certificate, 133

roaming profile, 135

root folder, 242

RPM packages, 18

RSA, 139

Ssaving settings, 224, 235

saving the window layout, 235

scpg3

exit values, 181

scpg3(.exe), 149, 178

scrollback buffer, 235

searching text, 227, 239

secure application connectivity, 159

secure copy, 149

Secure Copy, 178


Index292

secure file transfer, 149

Secure File Transfer Protocol (SFTP), 150, 182

Secure Shell version 2, 172

secured application, 92

secured connections, 30

SecurID authentication, 146

security issues, 135

security notifications, 92

selecting text, 238

separate connections, 226

server authentication, 86

server authentication with certificates, 87, 132–133

server authentication with public key, 86, 129

server certificate, 132

server version, 244

session logging, 236

settings

all connections, 101

file transfer, 108, 112

global, 101, 230, 239

host, 27, 230, 239

profile, 230, 239

saving, 121, 224, 235

upload, 113

settings categories, 101

settings file, 121

SFTP

checkpoint, 156, 186

streaming, 156, 186

SFTP checkpoint, 186

sftpg3

commands, 184

exit values, 189

sftpg3(.exe), 150, 182

shortcut menus, 124, 150, 152, 211, 219

customizing, 123

silent installation, 22

smart card, 145

SOCKS server, 145, 161

SOCKS server URL, 40, 89

Solaris

installation, 19

uninstallation, 25

sorting order, 110

SSH Tectia Client, 10, 37, 57

SSH Tectia Client (with EFT), 10

SSH Tectia Client components, 27

SSH Tectia Configuration tool, 57

SSH Tectia Connector, 10, 37, 57

SSH Tectia Server, 10

SSH Tectia Server (with EFT), 11

SSH Tectia Server (with Tunneling), 11

SSH Tectia Server for IBM z/OS, 11

SSH Tectia Status, 30

ssh-certview-g3(.exe), 199

ssh-client-g3.exe, 120

ssh-cmpclient-g3(.exe), 193

ssh-convert-ftp

exit values, 191

ssh-ekview-g3(.exe), 203

ssh-keygen-g3(.exe), 136, 191

SSH2, 172

SSH2 keys, 43

ssheventloop, 249

sshg3

exit values, 178

sshg3(.exe), 172

Start menu, 22–23

starting new connections, 236

static tunnels, 97

status

download, 150

upload, 152

status bars, 210, 214

Status dialog box, 30

streaming, 156, 186

strict host key checking, 42

Sun Solaris, 19

support web form, 247

supported platforms, 13

SUSE LINUX, 18

system configuration, 37

system log, 57, 65

system message, 107

system requirements, 13


293

TTask Manager, 91

taskbar icon, 30

technical support, 12

terminal

resetting, 239

terminal answerback, 68

terminal colors, 105

terminal fonts, 104

terminal window, 209

terminal window shortcut menu, 211

terminology, 9

text

searching, 227, 239

selecting, 238

time stamp, 113

title bars, 209, 213

toolbar buttons

moving, 126

toolbars, 123, 125

moving, 126

resetting, 126, 239–240

transfer mode, 114

transport distribution, 45

tray icon, 30, 59

tray menu, 59, 92

troubleshooting, 247

trusted CA, 145

tunneled application, 92

tunneling, 74, 159

dynamic, 161

restricting, 159

tunneling FTP, 164

tunneling X11, 165

tunnels

incoming, 76, 162

local, 75, 159

outgoing, 75, 159

remote, 76, 162

static, 97

Uuninstalling from AIX, 23

uninstalling from HP-UX, 24

uninstalling from Linux, 24

uninstalling from Solaris, 25

uninstalling from Windows, 26

uninstalling SSH Tectia Client, 23

Unix file permissions, 220, 222

upgrading to 5.x

from 4.x, 15

from 5.x, 15

upload status, 152

uploading a public key, 84, 137, 142

uploading files, 152, 231, 243

uploading settings, 113

user account

local, 135

user authentication based on host, 146

user authentication with certificates, 83, 144

user authentication with GSSAPI, 147

user authentication with keyboard-interactive, 146

user authentication with password, 134

user authentication with public key, 83, 135

user certificate

enrolling, 145

user key, 137–138

user name, 33

using secure copy, 149

using secure file transfer, 150

Vviewing hidden files, 242

viewing key and certificate information, 31

viewing log information, 31

viewing status, 30

viewing tunnel information, 30

Wwell-known port, 159

wild card, 116, 179, 189

window layout



Index294

saving, 235

window positions, 121–122

window size, 105

Windows

installation, 20

uninstallation, 26

windows

closing, 229, 245

multiple, 104, 212, 229–230, 245

sequence numbers, 229–230, 245

windows associated with a connection, 226, 236

Windows desktop, 23, 122, 216

Windows Event Log, 65

Windows Explorer, 110, 155, 212

Windows password, 134

Windows Start menu, 23

XX.509 certificate, 133, 145

X.509 certificates, 43, 146

X11 forwarding, 48, 77, 159, 165

XML attribute

allow-relay, 50–52

default-domain, 39

disable-crls, 41

end-point-identity-check, 39

gateway-profile, 49

http-proxy-url, 40

socks-server-url, 40

use-expired-crls, 41

XML element

accept-unknown-host-keys, 42

authentication-method, 46

authentication-methods, 45, 49

ca-certificate, 41

cert-validation, 39

cipher, 44

ciphers, 44, 49

compression, 46, 49

crypto-lib, 39

default-settings, 44

dod-pki, 41

forward, 48

forwards, 48, 50

general, 39

host-key-always-ask, 42

hostkey, 49

idle-timeout, 47, 50

key-store, 42

key-stores, 41

known-hosts, 43

ldap-server, 40

local-tunnel, 50

log-events, 57

logging, 57

mac, 45

macs, 45, 49

ocsp-responder, 40

profile, 48

profiles, 48

proxy, 46, 49

rekey, 45, 49

remote-tunnel, 51

server-banners, 47, 50

static-tunnels, 52

strict-host-key-checking, 42

transport-distribution, 45, 49

tunnel, 52

tunnels, 50


295


Index296