Quest PuTTY

Quest's GSSAPI-enabled PuTTY - a quick guide

About Quest PuTTY

The Quest PuTTY Secure SHell (SSH) client provided by Resource Central is based on the popular Windows based client by Simon Tatham. Quest have extended PuTTY's capabilities to include GSSAPI-with-MIC (Message Integrity Check) based user authentication, enabling secure, enterprise single sign-on. Full documentation of the PuTTY-based tools is found at the upstream project web site. These notes describe the Quest extended features only.

The SSH protocol can achieve single sign-on with Active Directory by using GSSAPI and the Kerberos protocol. Kerberos uses cryptographically-secure tickets obtained from a trusted source called the Key Distribution Center (KDC), normally obtained from a Windows domain controller by the workstation when the user logs in. Tickets obtained during the SSH connection reveal the username to the server in a secure way.

Quest PuTTY uses Microsoft's Security Service Provider Interface (SSPI), which is Microsoft's version of the GSSAPI, with which it is wire compatible. SSPI takes care of obtaining Kerberos tickets from Active Directory. When Quest Authentication Services (QAS) is used on the remote unix host, it can be joined to the same Active Directory domain as the Windows client. A GSSAPI-with-mic enabled SSH server process running on the remote host can examine the ticket and authenticate the user without needing to prompt for a password.


The Windows user running Quest PuTTY must first have a valid unix user on the target system. Quest PuTTY, by default, assumes the username to use on the target system is the same as the Windows logon name. This can be changed in the auto-login username field, as shown in Figure 1.

Figure 1: Changing the Auto-login username field

The importance of Service Principal Names

Host authentication relies heavily on getting the Service Principal Name right. A Service Principal Name ("SPN") is the unique name given to a security entity by Kerberos/Active Directory. The SPN used by the client must match exactly that given to the server, or authentication will not succeed.

Service Principal Names take the form of: service/hostname@REALM where

How PuTTY determines the SPN from the hostname

Quest PuTTY normally deduces the server's SPN from the hostname entered in the session configuration (shown in Figure 2).

This is how it works:

  1. PuTTY attempts to determine whether the hostname entered is an IP address. If it looks like one, and the Trust DNS checkbox is enabled, it will try a 'reverse DNS lookup' to get the hostname. If the reverse lookup is not successful, no SSPI-based connection will be attempted.
  2. PuTTY checks to see if the hostname contains a . character. If it doesn't, and Trust DNS is enabled, then it uses the system's gethostbyname() call in an attempting to retrieve the fully qualified host name from DNS.
  3. Finally, PuTTY prepends the hostname with host/ to form the SPN. Note that no realm is appended: it is left to the SSPI (Windows) to automatically append the current domain to form a complete SPN.

Complete details on how SPNs are determined are documented in the Quest PuTTY User Manual (F.5 Determining Kerberos service prinicpal names).

Figure 2: Specifying the target host name

Overriding the SPN

The Service Principal Name isn't always deduced correctly by PuTTY. This can happen when

In these cases, the target SPN can be specified directly during configuration. Figure 3 shows where this field is located.

Figure 3: Overiding the deduced SPN with an explicit principal name

Checking the SPN

When attempting the connection to the target system, PuTTY will display the SPN that it decided to use (See figure 4). If the connection is not successful, look closely at the SPN. This string can be used as a starting point for specifying the correct one in the override field.

Figure 4: PuTTY reporting the authenticated SPN of the remote server

Quest PuTTY comes with a command-line sister executable called PuTTY Link, invoked as Plink. Plink is a console version of PuTTY and allows most PuTTY options to be specified on the command line.

The installer places the plink.exe program (as well as pscp.exe) in the folder Program Files\Quest Software\PuTTY. The path to these tools is added to the system's PATH environment variable by the installer, or it can be manually added through the "Advanced" tab on the "My Computer" Properties display.

Plink is a console application, which means it requires a console window to run. If plink is being used for automation, this may cause unwanted 'flashing' of black console windows. A separate program, plinkw is provided that has no console output. Plinkw is identical to plink, except that there is no console window created for output.

Figure 5 shows plink's options. Plink is convenient for running X-Windows based executables from the target system.

X11 tunnels

PuTTY, plink and plinkw are capable of tunneling X traffic through the encypted SSH connection. This enables X-based applications to display on the client machine, when an X-Server such as XFree86 is running on it.

Plink command line options

Quest PuTTY has added a few more command line parameters to plink for convenience, and are listed below. Summary help on these and other commands can be obtained by running plink without arguments, as shown in Figure 5.

Please see the user manual (Appendix F.2: Extended options) for more options, and details.

Figure 5: Running plink to show the usage message

An example of using the SSPI-based plink on the command line is shown in Figure 6

plink -X -ssh willy-wagtail /usr/X11R6/bin/xterm

Figure 6: Plink example


PuTTY's scp clone, pscp, is also SSPI enabled. Like plink, when pscp is invoked, it attempts Kerberos authentication. An example of the pscp command line is shown in Figure 7.

pscp alice@targetmachine:/home/alice/filename .

Figure 7: pscp example, copying a remote file to . (the current directory)


This section contains some tips on solving authentication problems when using PuTTY.

Internal Error 2755

When installing PuTTY inside a Terminal Server session, you may encounter the error Internal Error 2755. Please see KB 254841. The workaround is to copy the installer file to a local drive and install from there.

Trouble delegating credentials

For credential forwarding (also known as delegation) to work from a Windows client to an SSH server, the conditions in KB 283201 must be met. You can also verify the delegation flag is set in the client's acquired service ticket by using the kerbtray tool.

Logging for bug reports

Bug reports are welcome through our bug system. Before sending a bug report, please make note of the version of Quest PuTTY you are using. It can also be helpful if you turn on full logging in the configuration panel and attach as much information to report as possible.