Tutorial on configuring the SSH client

Printer-friendly version. Use your browser's Print command to print this version.

The purpose of this tutorial

This tutorial explains how to configure a Host On-Demand VT Display session to use the Secure Shell (SSH) protocol.

This tutorial covers the following topics:

• Requirements for the SSH server
• Requirements for the workstation from which the SSH client is launched
• Configuring the parameters in the Connection configuration window
• Information that an SSH client must provide to an SSH server
• The relationship between SSH client authentication using a password and SSH client authentication using a public key.
• Configuring a VT Display session for SSH client authentication using a password
• Configuring a VT Display session for SSH client authentication using a public key

To benefit from this tutorial you should already know:

• How to configure and run a VT Display session in Host On-Demand.

Click here for information about configuring the Host On-Demand sftp (SSH File Transfer protocol) client to use SSH.

Configuring the sftp (SSH File Transfer protocol) client for SSH

Host On-Demand Version 8.0 supports a subset of SSH Version 2 for the following session types:

• VT Display
• sftp (SSH File Transfer protocol)

Although this tutorial describes SSH configuration only for a VT Display session, SSH configuration for an sftp session is very similar to SSH configuration for a VT Display session.

In fact, the two configuration processes are almost identical.

The only difference is the location of the User ID and Password fields. As later pages of this tutorial describe, for a VT Display session the User ID and Password fields are in the SSH configuration window.

However, for the sftp client, the SSH configuration window does not include fields for the User ID and Password (click here to see the SSH configuration window for an sftp session). Instead, the sftp client uses the values in the User ID and Password fields of the Logon configuration window (click here to see the Logon configuration window for an sftp session).

The SSH configuration window for an sftp (SSH File Transfer protocol) session

The image below shows the the SSH configuration window for an sftp (SSH File Transfer protocol) session. Notice that, unlike the SSH configuration window for a VT Display session, the SSH configuration window for an sftp session does not include fields for a User ID and Password.

The Logon configuration window for an sftp (SSH File Transfer protocol) session

The image below shows the the Logon configuration window for an sftp (SSH File Transfer protocol) session. SSH configuration for an sftp session uses the values in the User ID and Password fields of this window for the User ID and Password values for SSH configuration.

Requirements for the SSH server

The SSH server must support SSH Version 2.

Host On-Demand does not support earlier versions of SSH, such as SSH version 1.3 or SSH Version 1.5.

Requirements for the workstation from which the SSH client is launched

For SSH support Host On-Demand requires the following configuration on the client workstation:

• A Java 2-enabled browser
• A Java 2 plug-in (JRE Version 1.4 or JRE Version 1.3).
• The Java Cryptography Extension (JCE)

For non-Windows client platforms, contact your system administrator to obtain a Java 2 plug-in and the corresponding version of the JCE.

For Windows client platforms, the JCE is included as part of the IBM 32-bit Runtime Environment (JRE) for Java 2, v1.4 (for Windows platforms only). This version of the Java 2 JRE is included with Host On-Demand Version 8.0 and can be downloaded by Windows platform clients from any Host On-Demand Version 8.0 server (no matter what platform the Host On-Demand server is running on). To download this JRE, an end user should follow these steps:

• Access the following URL:
  <HOD server address>\<HOD public directory>\HODMain.html
• Click IBM 32-bit Runtime Environment for Java 2 and follow the instructions.

The JCE is also included in Sun Java 2 JRE Version 1.4.

If you use Java 2 Version 1.3, then you must first install Java 2 JRE Version 1.3 and then separately install the JCE for Java 2 Version 1.3.

You must use Java 2 JRE Version 1.3 or later.

Earlier versions of the JRE will not work.

Configuring the parameters in the Connection configuration window

To configure a VT Display session for SSH, you must set the appropriate values in the Connection configuration window of the VT Display session configuration.

The values that you set in this window define the session connection.

The image below shows the Connection configuration window for a VT Display session. Notice that:

• The Connection entry is selected in the left pane (see 1).

• The Session Name is VT Display/SSH - Tutorial on SSH client (see 2).

• The Destination Address is set to the address of the host on which the SSH server resides (see 3).

• The Destination Port is set to the port for the SSH server (see 4). Port 22 is a typical port for an SSH server.

• The Protocol is set to SSH (see 5).
  • The other choices are Telnet, Telnet - TLS, and Telnet - SSL only.
  • Each of these choices excludes the others. For example, you cannot choose both SSH and Telnet - TLS.
  • To repeat:
    • You cannot use SSH and Telnet - TLS at the same time.
    • You cannot use SSH and Telnet - SSL only at the same time.

Information that an SSH client must provide to an SSH server

To successfully launch an SSH session, an SSH client must provide two types of configurable information to an SSH server:

• A user id. This user id must correspond to an actual user id (such as user1 or root) on the SSH server.
• Some form of client authentication. That is, some evidence demonstrating that the SSH client is a valid client.

Host On-Demand supports two types of client authentication for SSH:

• Password authentication
• Public key authentication

The relationship between SSH client authentication using a password and SSH client authentication using a public key.

For an SSH client, the two types of client authentication are complementary rather than mutually exclusive.

• If client authentication using a public key is specified, then the SSH client attempts to do client authentication using a public key.

• If client authentication using a public key is not specified, or if this type of client authentication is tried and fails, then the SSH client attempts to do client authentication using a password.

Sections in this tutorial

The remainder of this tutorial contains the following sections:

• Configuring a VT Display session for SSH client authentication using a password (this section has 5 topics)

• Configuring a VT Display session for SSH client authentication using a public key (this section has 11 topics)

Configuring a VT Display session for SSH client authentication using a password

This section of the tutorial describes how to configure a VT Display session for SSH client authentication using a password.

Click Back to return to the page showing the Sections in this tutorial.

You can jump directly to a topic by clicking one of the numbered icons below, or you can click Next at any time to advance to the next topic.

Information required for password authentication

Configuring the parameters in the SSH configuration window

Allowing the end user to specify the user id and password for SSH

Allowing the end user to specify the password for SSH

Summary of SSH client authentication using a password

Topic - Information required for password authentication

Password authentication of the SSH client requires a user id and a password.

This user id and password must correspond to an actual user id and password on the host on which the SSH server resides.

For example, suppose that the host on which the SSH server resides is host 9.27.63.30, and suppose also that there exists on this host a user id user1 with the password user1pass. In this situation, an SSH client could log on to the host by specifying the user id user1 and the password user1pass.

Topic - Configuring the parameters in the SSH configuration window

For SSH client authentication using a password in a VT Display session, you must type the valid user id and password (as described on the previous page of this tutorial) into the User ID and Password fields of the SSH configuration window.

The image below shows the SSH configuration window for a VT Display session, with the parameters configured for SSH client authentication using a password. Notice that:

• The SSH entry is selected in the left pane (see 1).
• The User ID and Password fields are enabled. (These fields are enabled because SSH was selected as the Protocol in the Connection configuration window. The Connection configuration window is described in a previous page of this tutorial. Click here to see a sample Connection configuration window).
• The User ID field (see 2) is set to an actual user id (user1) that exists on the host on which the SSH server resides.
• The Password field (see 3) is set to the actual password (user1pw, displayed as *********) for the user id user1 on the host.
• Public Key Authentication is set to No and its parameters are disabled (see 4), because for now this tutorial is focusing on password authentication. Nevertheless, if you want, you can specify both password authentication and public key authentication at the same time (this is described in later pages of the tutorial).

When the end user starts this session, then Host On-Demand connects to the SSH server and displays a terminal session for user1. Click here to see a sample session window for an SSH session.

Sample Connection configuration window

The image below shows a sample Connection configuration window for a VT Display session using the SSH protocol.

Notice that:

• The Connection entry is selected in the left pane (see 1).
• The Session Name is VT Display/SSH - Tutorial on SSH client (see 2).
• The Destination Address is set to the address of the host on which the SSH server resides (see 3).
• The Destination Port is set to the port for the SSH server (see 4). Port 22 is a typical port for an SSH server.
• The Protocol is set to SSH (see 5). (The other choices are Telnet, Telnet - TLS, and Telnet - SSL only).

Sample session window for an SSH session

The image below shows the session window for a VT Display session configured to use SSH. The user is logged on as user1 to the host on which the SSH server resides.

Topic - Allowing the end user to specify the user id and password for SSH

If you want to create a session profile that allows the end user to specify the user id and the password for an SSH connection, you can do so by leaving the User ID and Password fields blank in the SSH configuration window. To repeat,

• Leave the User ID field blank.
• Leave the Password field blank.

When the end user starts the session, Host On-Demand displays a window prompting for a user id and password. The user can specify any valid user id and password.

If the end user specifies an invalid user id or an incorrect password, then Host On-Demand again displays the prompt window.

The image below shows the window that appears when the end user starts the session. The end user has typed a user id (user1) and a password (user1pass, displayed as ********* ) into the input fields of the prompt window.

Topic - Allowing the end user to specify the password for SSH

If you want to create a session profile that allows the end user to specify the password for an SSH connection, but not the user id, you can do so by setting the User ID field to a valid user id and leaving the Password field blank in the SSH configuration window. To repeat,

• Set the User ID field to a valid user id.
• Leave the Password field blank.

When the end user starts the session, Host On-Demand displays a window showing the configured user id in a non-editable field and prompting for a password. The user must type the correct password.

If the end user specifies the wrong password, then Host On-Demand again displays the prompt window.

The image below shows the window that appears when the end user starts the session. The configured user id is user1. The end user has typed a password (user1pass, displayed as *********) into the input field of the prompt window.

Topic - Summary of SSH client authentication using a password

This page summarizes the information about SSH client authentication using a password. Click Next to return to the topics page of this section.

• Password authentication of the SSH client requires an actual user id and password from the host on which the SSH server resides.

• In the SSH configuration window, type the actual user id into the User ID field and the correct password into the Password field.

• You can allow the user to specify the user id and password when the session starts, by leaving the User ID and Password fields blank in the SSH configuration window.

• You can allow the user to specify the password for a configured user id when the session starts, by typing a valid user id into the User ID field and by leaving the Password field blank in the SSH configuration window.

Configuring a VT Display session for SSH client authentication using a public key

This section of the tutorial describes how to configure a VT Display session for SSH client authentication using a public key.

Click Back to return to the page showing the Sections in this tutorial.

You can jump directly to a topic by clicking one of the numbered icons below, or you can click Next at any time to advance to the next topic.

Information required for public key authentication	(5) Configuring the SSH configuration window for client authentication using a public key
Steps to follow in configuring a VT Display session for SSH client authentication using a public key	Review of the steps in configuring a VT Display session for SSH client authentication using a public key
(1) Using keytool to generate a public-private key pair	Troubleshooting
(2) Extracting the public key from the keystore into a separate file	Public key authentication with many users, multiple client platforms, or multiple user ids
(3) Configuring the SSH server with the public key	Summary of SSH client authentication using a public key
(4) Copying the keystore containing the public-private key pair to the workstation for the SSH client

Topic - Information required for public key authentication

Public key authentication of the SSH client requires a user id and a public-private key pair.

The user id must correspond to an actual user id on the host on which the SSH server resides.

The public-private key pair is a symmetrical pair of encryption keys. "Symmetrical" means that a message encrypted using the public key can be decrypted using the private key, and vice versa.

• The public key is in plain text (not encrypted).
• The private key is encrypted and protected with a password.

The image below illustrates how the public and private keys are used to configure the SSH server and SSH client. This image shows the general process for any system (not the exact process for Host On-Demand).

• The system administrator generates a public-private key pair (see 1).
• The SSH server is configured with the public key (see 2).
• The SSH client is configured with both the public key and the private key. (see 3).

Not used for encrypting message traffic after the SSH session has started

In the SSH protocol, the public-private key pair that is used for client authentication is not also used for encrypting data after the SSH session has started. Instead, the SSH server separately generates keys for encrypting data.

Client authentication when a session is started

When the end user starts a session using SSH, client authentication occurs as follows:

1. The SSH client notifies the host that it intends to use public key authentication, and sends to the SSH server:
   • The public key.
   • A signature. (A signature is a value known both to the SSH server and to the SSH client that the SSH client has encrypted using the private key.)

2. The SSH server checks its configuration and determines that it has been configured with a public key matching the one just received.

3. The SSH server verifies the signature using the public key. (For example, the SSH server could encrypt the known value and compare it to the encrypted value just received from the SSH client, or could unencrypt the encrypted value just received from the SSH client and compare it to the known value.)

Topic - Steps to follow in configuring a VT Display session for SSH client authentication using a public key

Here is a preview of the steps to follow in configuring a VT Display session for SSH client authentication using a public key:

1. Use keytool (a program distributed with Host On-Demand) to generate a public-private key pair. (This tool stores both keys of the pair as an entry in a file called a keystore.)

2. Use the Export Public Key utility (integrated into the SSH configuration window of the VT Display session configuration) to extract the public key from the keystore into a separate file.

3. Configure the SSH server with the public key.

4. Copy the keystore containing the public-private key pair to the workstation for the SSH client.

5. Configure the SSH configuration window for client authentication using a public key.

The remaining pages of this tutorial describe these steps.

Topic - (1) Using keytool to generate a public-private key pair

The first step in configuring a VT Display session for SSH client authentication using a public key is to use the keytool program to generate a public-private key pair.

About keytool

keytool is a multipurpose utility program, included in the Java 2 Version 1.4 JRE and distributed with Host On-Demand, for managing keys and certificates.

A perspective from Unix-like platforms

Because keytool is a multipurpose tool for managing keys and certificates, you may find it easier to understand the generating of a public-private key pair by looking first at a less complex tool available on Unix-like platforms, named ssh-keygen. (This is for illustration purposes only. You cannot use ssh-keygen to generate public-private keys for Host On-Demand.)

Getting keytool

You can get access to keytool from the Host On-Demand server in either of two ways:

• keytool is distributed with the Java run-time utilities installed with Host On-Demand. On the Windows platform this tool is at the following location:
  <install_directory>\jre\bin\keytool.exe

• keytool is included in the Java 2 Version 1.4 JRE for the Windows platform that is distributed with Host On-Demand. This is the JRE that clients running on Windows can download from the server. The file containing the JRE is IBM-Win32-JRE.exe. On the Windows platform of the Host On-Demand server this file is at the following location:
  <install_directory>\<publish_directory>\JREInstall\IBM-Win32-JRE.exe
  • You must run the above .EXE file on a Windows platform to install the Java 2 Version 1.4 JRE on that platform.
  • Although this Java 2 Version 1.4 JRE is for Windows platforms only, the above .EXE file is included on any installation of Host On-Demand Version 8.0, no matter what platform the Host On-Demand server is installed on.

Invoking keytool to generate a public-private key pair.

Here is an example of invoking keytool to create a public-private key pair. (In the example below the parameters are written on multiple lines for the purpose of clarity. When you invoke keytool, you must type the program name and its parameters all on one line.)

      keytool
      -genkey
      -keystore  f:\tm\keys\johnkeystore
      -alias     johnkey02
      -storepass johnstorepass
      -keypass   johnstorepass
      -dname "CN=John Smith, OU=Development, O=Standard Supplies Inc.,
             L=Anytown, S=North Carolina, C=US"
   

The parameters have the following significance:

The items in the following list provide additional comments on each parameter in the example invocation of keytool above.

• -genkey
  keytool is a multi-purpose tool. This is the option that tells keytool to generate a public-private key pair.

• -keystore f:\tm\keys\johnkeystore
  In contrast to ssh-keygen (the tool available on Unix-like platforms), which generates separate files for the public key and the private key, keytool stores both keys as a single entry in a file called a keystore. By running keytool multiple times, you can add multiple public-private key entries to the same keystore. Here the path and file name of the keystore is f:\tm\keys\johnkeystore.

• -alias johnkey02
  Because keytool allows more than one key pair to be stored in a keystore, keytool requires that an alias be specified for each new key pair. An alias is an identifying character string, such as mykey or johnkey02, that distinguishes a key pair from other key pairs stored in the same keystore. An alias must be unique within a single keystore.

• -storepass johnstorepass
  keytool requires you to specify a password for the keystore. Here the password is johnstorepass.

  If the keystore does not already exist, keytool creates the keystore and associates this password with it (encrypted). When you subsequently want to access the keystore, either to read from it or to write into it, you must specify the keystore password. If you forget the keystore password, there is no way to recover it.

  Somewhat similarly, ssh-keygen (the tool available on Unix-like platforms) allows you to specify a password that is required to access the private key file.

• -keypass johnstorepass
  keytool also requires you to specify a password for the individual entry containing the public-private key pair. That is, not only do you need a password to open the keystore, but you also need a password to access an individual entry (containing a public-private key pair) in the keystore.

  If you like, you can simplify things somewhat by using the same password for the keystore password and the key password. Here the key password is the same as the keystore password, johnstorepass.

• -dname "CN=John Smith, OU=Development, O=Standard Supplies Inc., L=Anytown, S=North Carolina, C=US"
  This information is needed to create a self-signed certificate. keytool wraps the public key in an X.509 v1 self-signed certificate.

  Although you must specify this information when you generate a public-private key pair with keytool, this certificate is not used by Host On-Demand or the SSH server during SSH client authentication using a public key.

There are a few other options that are used with the -genkey option. However, normally you should not specify these additional options. When you do not specify these options, keytool uses the default value. The following table shows the additional options and the default values that are used when you do not specify these additional options.

Other operations you can perform with keytool

Click here to see a few of the other operations that you can perform with keytool.

ssh-keygen: a less complex tool for generating a public-private key pair

Host On-Demand provides the utility program keytool for generating public-private key pairs. This tool is part of the Java 1.4 JRE and is also distributed with Host On-Demand. You should use keytool to generate keys for configuring a VT Display session for client authentication using a public key.

However, because keytool is a multipurpose utility for managing keys and certificates, you may find it easier to understand generating a public-private key pair by looking first at a less complex tool available on Unix-like platforms, named ssh-keygen. (This description is for illustration purposes only. You cannot use ssh-keygen to generate public-private key pairs for Host On-Demand.)

Here is an example of invoking ssh-keygen. This example is taken from the console of a system running Red Hat Linux 8.0:

ssh-keygen -t dsa -f johnkey02.id_dsa -N johnpass

The parameters have the following significance:

• -t dsa specifies the type of key to generate (DSA).
• -f johnkey02.id_dsa specifies name of the file that ssh-keygen is to create to hold the private key.
• -N johnpass specifies the password for the private key file.

The invocation above causes the following files to be created in the local directory. This is how the files could appear if you issued an ls -l command from the console of Red Hat Linux 8.0:

-rw-------  1  mytmp  mytmp   736 Sep 21 17:50 johnkey02.id_dsa
-rw-r--r--  1  mytmp  mytmp   625 Sep 21 17:50 johnkey02.id_dsa.pub

The file johnkey02.id_dsa contains the private key.

• The contents of this file are encrypted.
• This file is protected with the password johnpass.

The file johnkey02.id_dsa.pub contains the public key. Notice that the name of this file is created by appending .pub to the name of the file containing the private key.

• The contents of this file are plain text.
• This file is not protected with a password.

Other operations you can perform with keytool

This page describes a few of the other options that you can perform with keytool.

Listing the contents of a keystore

To list the contents of a keystore, invoke keytool as follows (not all of the possible parameters are shown here):

   keytool
   -list
   -keystore  johnkeystore
   -alias     johnkey02
   -storepass johnstorepass
   -v

Changing a keystore password

To change a keystore password, invoke keytool as follows (not all of the possible parameters are shown here):

   keytool
   -storepasswd
   -keystore  johnkeystore
   -storepass johnstorepass
   -new       newstorepass
   -v

Changing a key password

To change a key password, invoke keytool as follows (not all of the possible parameters are shown here):

   keytool
   -keypasswd
   -keystore  johnkeystore
   -storepass johnstorepass
   -alias     johnkey02
   -keypass   johnstorepass
   -new       newkeypass
   -v

Topic - (2) Extracting the public key from the keystore into a separate file

The SSH protocol requires the public key to be stored in a plain text (that is, unencrypted) file located on the host on which the SSH server resides. However, as the previous page of this tutorial describes, the keytool program places both the public key and the private key into an entry inside a keystore file. Both the keystore file and the entry are password protected.

Therefore, you need to run an Export Public Key utility to read the public key from the keystore and place a copy of the public key into a plain text file that can be used by an SSH server.

The user interface for this Export Public Key utility is included in the Public Key Authentication group of the SSH configuration window (shown below). This group includes the following parameters:

• KeyStore File Path
• KeyStore Password
• Public Key Alias
• Public Key Alias Password

These parameters in the Public Key Authentication group of the SSH configuration window are used for two purposes, either for configuring public key authentication or for extracting a public key from a keystore.

• If you click OK to close the VT Display session profile, then Host On-Demand saves the values in the Public Key Authentication group and uses these values for SSH public key authentication.
• However, if you click Export Public Key (a button that is also located in the Public Key Authentication group), then the Export Public Key utility uses the values in the Public Key Authentication group to extract a public key from a keystore.

The image below shows the SSH configuration window configured to use the Export Public Key utility.

• The SSH entry is selected in the left pane (see 1).
• The User ID field is blank (see 2). You can leave this field blank or not when you export a public key. The Export Public Key utility does not use this value.
• The Enable parameter is set to Yes (see 3). You have to set this parameter to Yes in order to enable the fields in the Public Key Authentication group.
• The KeyStore File path is set to f:\tm\keys\johnkeystore (see 4). This is the keystore that was generated with keytool in the step described on the previous page.
• The KeyStore Password is set to johnstorepass (displayed as *************) (see 5). This is the password for the keystore.
• The Public Key Alias is set to johnkey02 (see 6). This is the alias for the public-private key pair.
• The Public Key Alias Password is set to johnstorepass (displayed as *************) (see 7). This is the password for the public-private key pair. In this example, the value for the public-private key pair is the same as the value for the keystore password.
• After you have filled out the parameters for extracting the public key password, click Export Public Key to start the extraction (see 8).

When you click Export Public Key to start the extraction, then Host On-Demand displays the Export Public Key window, which prompts you for two additional parameters, a path for the output file and a format for the output file. Click here to see Export Public Key window.

For some of input fields in the Public Key Authentication group, the Export Public Key utility uses a default value if the input field is left blank. Click here to learn more about the default values.

The Export Public Key window

The image below shows the Export Public Key window. Host On-Demand displays this window when you click Export Public Key in the Public Key Authentication group of the SSH configuration window of the VT Display session configuration.

• The Destination input field contains the path and file name of the output file that is to contain the exported public key. In the image below the path is f:\tm\keys and the file name is johnkey02.id_dsa.pub.

  The default value for the path is the value specified in the Java system property user.home, and the default value for the file name is .id_dsa. For example, on a Windows client platform the default path and file name could be c:\Documents and Settings\johnsmith\id_dsa.pub. Click here for information on determining the value of user.home on a client system.

• The Use OpenSSH Format checkbox determines the format of the extracted public key.
  • If the checkbox is checked then the format is OpenSSH format.
  • If the checkbox is not checked then the format is the SSH Public Key File Format.

  Check with your system administrator to determine which format your SSH server requires. If necessary, generate a public key in each of the 2 formats, then try each on the host to see which format works with the SSH client.

Determining the value of user.home on a client system

To determine the value of user.home on a client system, follow these steps:

1. Configure the Java 2 plug-in to show the Java console.
2. Start the Host On-Demand client desktop.
3. In the Java Console window, type s.
4. In the Java Console window, look through the listing generated by the s command to find the value for user.home.

The image below shows the Java Console window with the listing from the s command showing the user.home value.

Default value used when an Export Public Key parameter is blank

The table below shows the default value that the Export Public Key utility uses if the value for the parameter is blank in the SSH configuration window.

Determining the value of user.home on a client system

To determine the value of user.home on a client system, follow these steps:

1. Configure the Java 2 plug-in to show the Java console.
2. Start the Host On-Demand client desktop.
3. In the Java Console window, type s.
4. In the Java Console window, look through the listing generated by the s command to find the value for user.home.

The image below shows the Java Console window with the listing from the s command showing the user.home value.

Topic - (3) Configuring the SSH server with the public key

When the SSH client initiates client authentication (by sending a public key and a signature to the SSH server), then the SSH server must be able to verify that it has been configured with the same public key that it receives from the client.

Therefore, the next step is to configure the SSH server with the public key. Two substeps are required:

• Transfer the public key file to the host on which the SSH server resides.
• Configure the SSH server with the public key.

Transferring the public key file to the host

You must transfer the public key file that you extracted in the previous step to the host on which the SSH server resides. Although this is a public key, you should choose a secure method for transferring the public key file. For example, you can use a secure FTP (sftp) session, or you can put the file on some physical media (such as a diskette) and have the media securely transferred.

Configuring the SSH server with the public key

Depending on the platform, on the SSH server implementation, and on the SSH server configuration, each SSH server can have somewhat different requirements for configuring the public key. Consult the system administrator of your SSH server for the requirements.

As an example, in the OpenSSH porting of SSH available on Red Hat Linux 8.0, by default the public key is appended to the file $HOME/.ssh/authorized_keys, where $HOME is the home directory of the user ID to which the SSH client logs on. For example, if you configure the SSH client with a user ID of user1, then the path for the authorized_keys file could be:
/home/user1/.ssh/authorized_keys.

Here is how you could perform the steps involved in configuring the SSH server on a system running Red Hat Linux 8.0. (This information is for illustration purposes only. Your SSH server may not require the same settings, even if the platform is Red Hat Linux 8.0). The red numerals (such as 1) refer to lines in the console listing further below.

• You are logged on as user1 on the host on which the SSH server resides (see 1).
• You change to the home directory for user1 (see 2).
• You create the directory .ssh under /home/user1 (see 3).
• You check the permission settings for .ssh (see 4).
• You change the permission settings for .ssh to rwx------ (see 5).
• You verify the new permission settings for .ssh (see 6).
• You change to the .ssh directory (see 7).
• You retrieve the public key file johnkey02.id_dsa.pub (see 8).
• You append the public key file to the file authorized_keys (see 9). If the file authorized_keys does not already exist, this command creates it.
• You check the permission settings for authorized_keys (see 10).
• You change the permission settings for authorized_keys to rw------- (see 11).
• You verify the new permission settings for authorized_keys (see 12).
• You can delete johnkey02.id_dsa.pub if you want (see 13).

Here is the console listing:

[user1@9.27.63.30]$                                                  1
[user1@9.27.63.30]$ cd /home/user1                                   2
[user1@9.27.63.30]$ mkdir .ssh                                       3
[user1@9.27.63.30]$ ls -la                                           4
drwxrwxr-x    2 user1    user1            4096 Oct 1 06:44 .ssh       
[user1@9.27.63.30]$ chmod 700 .ssh                                   5
[user1@9.27.63.30]$ ls -la                                           6
drwx------    2 user1    user1            4096 Oct 1 06:44 .ssh       
[user1@9.27.63.30]$ cd .ssh                                          7
[user1@9.27.63.30]$ cp /public_keys_received/johnkey02.id_dsa.pub .  8
[user1@9.27.63.30]$ cat johnkey02.id_dsa.pub >> authorized_keys      9
[user1@9.27.63.30]$ ls -l                                           10
-rw-rw-r--    2 user1     user1           4096 Oct 1 07:54 authorized_keys         
-rwxr-xr-x    2 user1     user1           4096 Oct 1 07:54 johnkey02.id_dsa.pub     
[user1@9.27.63.30]$ chmod 600 authorized_keys                       11
[user1@9.27.63.30]$ ls -l                                           12
-rw-------    2 user1     user1           4096 Oct 1 07:54 authorized_keys        
-rwxr-xr-x    2 user1     user1           4096 Oct 1 07:54 johnkey02.id_dsa.pub     
[user1@9.27.63.30]$ rm johnkey02.id_dsa.pub                         13

Topic - (4) Copying the keystore containing the public-private key pair to the workstation for the SSH client

The next step is to make the public-private key pair accessible to the SSH client. As with the previous step, there are two substeps.

• Transfer the keystore file containing the public-private key pair to the workstation from which the SSH client is launched.
• Place the keystore file in the directory whose path you intend to specify in the KeyStore File Path field of the SSH configuration window in the VT Display session configuration.

Transferring the keystore file to the workstation

You must transfer the keystore file containing the public-private key pair to the workstation from which the SSH client is launched. You should choose a secure method for transferring the keystore file. For example, you can attach the file to a secure electronic message (such as a Lotus Notes note).

Placing the keystore file in the correct subdirectory

You must set up the keystore file with the same path and file name that you intend to specify in the KeyStore File Path field of the SSH configuration window in the VT Display session configuration.

You can set up the keystore file using any path and file name on the client workstation, so long as the path and file name match the value of the KeyStore File Path field of the SSH configuration window.

If you leave the KeyStore File Path field blank in the SSH configuration window, then Host On-Demand looks for the keystore file in the default location. The default value for the path is the value specified in the Java system property user.home, and the default value for the file name is .keystore. For example, on a Windows client platform the default path and file name could be: c:\Documents and Settings\<userid>\.keystore. Click here for information on determining the value of user.home on a client system.

Using the example keystore file johnkeystore, and using the default value for the keystore path and file name, and assuming that the client platform is Windows and that the Windows user id is johnsmith, you would follow these steps to set up the keystore file with the default path and file name:

• Copy the file johnkeystore into the directory c:\Documents and Settings\johnsmith\.
• Rename johnkeystore to .keystore .

The complete path and file name of the keystore file in this example is:
c:\Documents and Settings\johnsmith\.keystore.

Remember that you do not have to use the default path and file name for the keystore. Nevertheless, using the default path and file name makes it much easier for users on different workstations (possibly running different client platforms) to share the same VT Display configuration file.

Determining the value of user.home on a client system

To determine the value of user.home on a client system, follow these steps:

1. Configure the Java 2 plug-in to show the Java console.
2. Start the Host On-Demand client desktop.
3. In the Java Console window, type s.
4. In the Java Console window, look through the listing generated by the s command to find the value for user.home.

The image below shows the Java Console window with the listing from the s command showing the user.home value.

Topic - (5) Configuring the SSH configuration window for client authentication using a public key

The last step is to configure the SSH configuration window for client authentication using a public key. To perform this step, type the appropriate values into the input fields of the Public Key Authentication group in the SSH configuration window.

In a previous step (step 2), you typed values into these input fields to export a public key file from the keystore file. However, in this step (step 5) you do not necessarily have to use all the same values that you used when you exported the public key file. Instead, set the values for public key authentication to correspond to the actual location, name, and contents of the keystore file on the workstation from which the SSH client is launched.

For some input fields in the Public Key Authentication group, if the input field is left blank, then Host On-Demand uses a default value when the session is started. Click here to learn more about these default values.

The image below shows the SSH configuration window for a VT Display session. Notice that:

• The SSH entry is selected in the left pane (see 1).

• The User ID field is enabled (see 2). This field (along with the Password field) is enabled because SSH was selected as the Protocol in the Connection window of the VT Display session configuration. In the example below, the User ID field is set to an actual user id (user1) of the host on which the SSH server resides. This must be the user id with which the SSH server was configured in a previous step.

• The Enable parameter for Public Key Authentication is set to Yes (see 3).

• The KeyStore File Path is set to the path and file name of the keystore file on the workstation from which the SSH client is launched (see 4).

  Here, because the KeyStore File Path is left blank, Host On-Demand uses the default path and file name for the keystore file when the SSH session is launched from the client. The default value for the path is the value specified in the Java system property user.home, and the default value for the file name is .keystore. For example, on a Windows client platform the default path and file name could be: c:\Documents and Settings\<userid>\.keystore. Click here for information on determining the value of user.home on a client system.

• The KeyStore Password (see 5) is set to the password (johnkeystore, displayed as ************) of the keystore file on the workstation from which the SSH client is launched.

• The Public Key Alias (see 6) is set to the alias (johnkey02) for the public-private key pair being used.

• The Public Key Alias Password is set to the password for the public-private key entry in the keystore file (see 7). Here, because the input field is left blank, Host On-Demand uses the default value when the SSH client is launched. The default value is the value used for the KeyStore Password. If this value fails, then Host On-Demand prompts the end user for the password.

• The password for Password Authentication is set to the actual password for the user ID on the host on which the SSH server resides (see 8). Here, because the input field is left blank, Host On-Demand prompts the user for the password if public key authentication fails.

  Leave this field blank if you want to force the end user to use public key authentication. If you specify a valid password here instead of leaving the field blank, then when the end user launches the session, and the VT Display session connects with the SSH server successfully, you cannot determine whether the connection succeeds because of public key authentication or because of password authentication.

When the end user starts this session, then Host On-Demand connects to the SSH server and displays a terminal session for user1. Click here to see a sample session window for an SSH session.

Default value used when a Public Key Authentication parameter is blank

The table below shows the value that Host On-Demand uses for an SSH parameter when an SSH session is started, if the value for the parameter is left blank in the Public Key Authentication group of the SSH configuration window.

Determining the value of user.home on a client system

To determine the value of user.home on a client system, follow these steps:

1. Configure the Java 2 plug-in to show the Java console.
2. Start the Host On-Demand client desktop.
3. In the Java Console window, type s.
4. In the Java Console window, look through the listing generated by the s command to find the value for user.home.

The image below shows the Java Console window with the listing from the s command showing the user.home value.

Sample session window for an SSH session

The image below shows the session window for a VT Display session configured to use SSH. The user is logged on as user1 to the host on which the SSH server resides.

Topic - Review of the steps in configuring a VT Display session for SSH client authentication using a public key

Here again are the steps we have covered for configuring a VT Display session for SSH client authentication using a public key:

1. Use keytool to generate a public-private key pair.

2. Use the Export Public Key utility (integrated into the SSH configuration window of the VT Display session configuration) to extract the public key from the keystore into a separate file.

3. Configure the SSH server with the public key.

4. Copy the keystore containing the public-private key pair to the workstation for the SSH client.

5. Configure the SSH configuration window for client authentication using a public key.

Topic - Troubleshooting

If public key authentication is not working, try the following checks:

1. Disable public key authentication in the SSH configuration window, and verify that you can log on to the SSH server using password authentication alone.

   If you cannot log on to the SSH server using password authentication alone, then check the Destination Address and the Port Address, and verify that you are using a valid user id on the host on which the SSH server resides.

2. Verify that you are using the correct keystore password, key alias, and key alias password in the SSH configuration window.

   You can verify these values by invoking keytool with the -list function to list the public-private key entry in the keystore file. For the list function to succeed you must specify the correct keystore password, key alias, and key alias password.

3. Verify that the keystore file on the workstation for the SSH client is in the correct subdirectory and has the correct name.

   If you have specified the default path and file name for the keystore file (by leaving this field blank in the SSH configuration window), then verify that the default path and file name are correct for the client workstation that is failing.

4. Verify that the keystore on the client workstation has the correct keystore password, key alias, and key alias password in the SSH configuration window. (See item 2 above.)

5. Verify that the configuration of the public key on the SSH server is correct, by consulting with the system administrator for the SSH server.

6. Verify that the file ownership and file permission settings on the host meet the requirements set by the SSH server, by consulting with the system administrator for the SSH server.

   As an example, the settings in the following table seem to be required by the default SSH server configuration on Red Hat Linux 8.0. (These values are provided only as an example of the type of requirements that an SSH server could impose. These values may not be correct for your SSH server, even if the platform is Red Hat Linux 8.0.) The entries in this table assume that the user id is user1.

   Item:	Setting:
   Owner and group for directory .ssh	user1
   Permission settings for directory .ssh	rwx------
   Owner and group for file authorized_keys	user1
   Permission settings for file authorized_keys	rw-------

Topic - Public key authentication with many users, multiple client platforms, or multiple user ids

Many users

The following are some considerations for public key authentication if you have many users accessing either the same user id or different user ids:

• As described earlier, if you leave the value for a parameter blank in the Public Key Authentication group of the SSH configuration window, then when the end user starts the session Host On-Demand uses the default value for the parameter. Click here for more information about these default values.

• Each workstation that launches an SSH client requires a keystore file. However, keystore files on different workstations can have the same file name (and therefore share the same session profile) even if the contents of each keystore are different.

Multiple client platforms

The following are some considerations for public key authentication if you have users accessing the same user id or different user ids from different client platforms.

• Consider leaving the File Path for KeyStore parameter blank. When the end user starts the session, if the File Path for KeyStore was left blank, Host On-Demand uses the default path and file name. Click here for more information about default values.

Multiple user ids

The following are some considerations for public key authentication if you have one or more users that need to access more than one user id on the same SSH server, or user ids on more than one SSH server.

• One keystore file can contain multiple private keys, or one keystore file with a single private key can be used for all the user ids, or multiple keystore files can be used, one for each user id.

Default value used when a Public Key Authentication parameter is blank

The table below shows the value that Host On-Demand uses for an SSH parameter when an SSH session is started, if the value for the parameter is left blank in the Public Key Authentication group of the SSH configuration window.

Topic - Summary of SSH client authentication using a public key

This page summarizes the information about SSH client authentication using a public key. Click Next to return to the topics page of this section.

• Public key authentication for SSH requires a user id and a public-private key pair. The SSH server must be configured with the public key. The SSH client must be configured with the public key and the private key.

• The steps in configuring a VT Display session for SSH client authentication using public key authentication are:
  1. Use keytool to generate a public-private key pair.
     • keytool is included in the Java 1.4 JRE and is distributed with Host On-Demand.

  2. Use the Export Public Key utility to extract the public key from the keystore into a separate file.
     • The Export Public Key utility is integrated with the SSH configuration window for the VT Display session configuration.

  3. Configure the SSH server with the public key.
     • Each SSH server has different requirements. Consult the system administrator for the SSH server that you intend to use.

  4. Copy the keystore containing the public-private key pair to the workstation for the SSH client.
     • Use the same file path and name on the workstation as you intend to specify in the KeyStore File Path field of the SSH configuration window.

  5. Configure the SSH configuration window for client authentication using a public key.
     • In the fields of the SSH configuration window, you can either specify a value or leave the field blank. If you leave the field blank, Host On-Demand uses a default value when the end user starts the session.

• If public key authentication is not working, check the list of troubleshooting suggestions.

• The flexibility of the SSH configuration for Host On-Demand allows you to create one VT Display session profile for many users, multiple client platforms, or multiple user ids.