GT 3.9.5 GSI-OpenSSH: Developer's Guide

Introduction

This document provides information for GSI-OpenSSH developers.

The changes to OpenSSH to add GSI support are limited, because we build on the existing GSSAPI support in OpenSSH for Kerberos. In addition to adding support for the GSI GSSAPI mechanism, GSI-OpenSSH includes support for GSSAPI key exchange, as specified in draft-ietf-secsh-gsskeyex-08.txt whereas OpenSSH only supports GSSAPI authentication. Visit the GSI OpenSSH Patch Page for the patch containing the differences between OpenSSH and GSI-OpenSSH.

Architecture and design overview

For information about the SSH protocol, including the latest draft of the SSH GSSAPI protocol specification, see the current documents of the IETF Secure Shell (secsh) Working Group. For information on GSSAPI, see RFC 2743 and RFC 2744.

Public interface

The semantics and syntax of the APIs and WSDL for the component, along with descriptions of domain-specific structured interface data, can be found in the public interface guide.

Usage scenarios

The GSI-OpenSSH interface is through command-line tools only.

Tutorials

There are no tutorials available at this time

Feature summary

Features new in release 3.9.5

  • This is the first Globus Toolkit release that includes GSI-enabled OpenSSH.

Other Supported Features

  • The gsissh command provides a secure remote login service with forwarding of X.509 proxy credentials.
  • The gsiscp and gsisftp commands provide a secure file transfer service, authenticated with X.509 proxy credentials, mimicking the rcp/scp and ftp/sftp commands.
  • All standard OpenSSH features are supported, excluding Kerberos authentication. Kerberos authentication is not compatible with GSI-enabled OpenSSH.
  • The GSI-OpenSSH server can replace the standard system SSH server in typical environments.
  • If no username is given on the command-line, GSI-OpenSSH automatically determines the username that corresponds to the X.509 proxy certificate subject in the server's grid-mapfile.

Deprecated Features

  • None

Tested platforms

Tested Platforms for GSI-OpenSSH

  • Mac OS X 10.3
  • i686 GNU/Linux
  • ia64 GNU/Linux

Backward compatibility summary

Protocol changes since GT version 3.2

  • GSI-enabled OpenSSH was not included in GT 3.2.

API changes since GT version 3.2

  • GSI-enabled OpenSSH was not included in GT 3.2.

Exception changes since GT version 3.2

  • Not applicable

Schema changes since GT version 3.2

  • Not applicable

Technology dependencies

GSI-enabled OpenSSH depends on the following GT components:

  • Pre-WS Authentication and Authorization

GSI-enabled OpenSSH depends on the following 3rd party software:

  • None

Security considerations

GSI-OpenSSH is a modified version of OpenSSH and includes full OpenSSH functionality. For more information on OpenSSH security, see the OpenSSH Security page.

Debugging

Pass the '-vvv' flag to the GSI-OpenSSH clients when debugging to increase the verbosity of the output. For example:

  $ gsissh -vvv <remote host>

Likewise, pass the following flags to the server when debugging:

  $ sshd -ddd -o 'UsePrivilegeSeparation no' -r

You can add the '-p <port number>' option to run the sshd on an alternate port for debugging without affecting your system sshd. Then, give the same '-p <port number>' option to gsissh to test the sshd.

The presence of a debugging flag also runs the server without detaching it from the console. The server will only handle one connection in this mode.

Troubleshooting

No proxy found

Failing to run grid-proxy-init to create a user proxy with which to connect will result in the client notifying you that no local credentials exist. Any attempt to authenticate using GSI will fail in this case. 

debug1: Local version string SSH-2.0-OpenSSH_3.2.3p1
debug1: Problem with local credentials

debug1: no proxy credentials: run grid-proxy-init or wgpi first
        Function:proxy_pw_cb
debug1: SSH2_MSG_KEXINIT sent
debug1: SSH2_MSG_KEXINIT received

Fix: Verify that your GSI proxy has been properly initialized via 'grid-proxy-info'. If you need to initialize this proxy, use the command 'grid-proxy-init'.

Host key permissions failure

The host key that the SSH server is using for GSI authentication must only be readable by the user which owns it. Any other permissions will cause the following debugging output to be generated. 

7959: debug1: Local version string SSH-1.99-OpenSSH_3.4p1
7959: debug1: list_hostkey_types: ssh-rsa,ssh-dss
7959: debug1: Problem with local credentials
7959: debug1: bad file system permissions on private key
              key must only be readable by the user
              File=/etc/grid-security/hostkey.pem
              Function:proxy_init_cred
7959: debug1: SSH2_MSG_KEXINIT sent
7959: debug1: SSH2_MSG_KEXINIT received

Fix: Make sure that the host key's UNIX permissions are mode 400 (that is, it should only have mode readable for the user that owns the file, and no other mode bits should be set).

Unable to map implicit username

If the server was passed an "implicit username" (i.e. requested to map the incoming connection to a username based on some contextual clues such as the certificate's subject), and no entry exists in the grid-mapfile for the incoming connection's certificate subject, the server should output a clue that states it is unable to set the username against which to authenticate. 

7978: debug2: input_userauth_request: try method none
7978: Failed none for cphillip from 141.142.21.10 port 1240 ssh2
7978: debug1: gssapi received empty username
7978: debug1: failed to set username from gssapi context
7978: Failed external-keyx for cphillip from 141.142.21.10 port 1240 ssh2
7978: debug1: gssapi received empty username
7978: debug1: failed to set username from gssapi context
7978: Failed gssapi for cphillip from 141.142.21.10 port 1240 ssh2
7978: debug1: userauth-request for user cphillip service ssh-connection method publickey
7978: debug1: attempt 0 failures 3

Fix: Add an entry for the user to the grid-mapfile.

Entry in grid-mapfile refers to non-existent username

If the subject name given in the system's grid-mapfile points to a non-existent user, the server will give an internal error which is best caught when it is running in debugging mode. 

8046: debug2: input_userauth_request: setting up authctxt for cphillip
8046: debug2: input_userauth_request: try method none
8046: Failed none for cphillip from 141.142.21.10 port 1259 ssh2
8046: debug1: gssapi received empty username
8046: debug1: gssapi successfully set username to cphillip2
8046: debug1: userauth-request for user cphillip2 service ssh-connection method external-keyx
8046: debug1: attempt 0 failures 1
8046: input_userauth_request: illegal user cphillip2
8046: debug2: input_userauth_request: try method external-keyx
8046: GSI user /C=US/O=National Computational Science Alliance/CN=Chase Phillips is authorized as target user cphillip2
8046: INTERNAL ERROR: authenticated invalid user cphillip2
8046: debug1: Calling cleanup 0x806bb38(0x0)

Fix: Add a new account to the system matching the username pointed at by the user's subject in the grid-mapfile.

Client proxy uninitialized or non-GSI agent

Should the user attempt to connect without first creating a proxy certificate, or if the user is connecting via a SSH client that does not support GSI authentication, the server will note that no GSSAPI data was sent to it. Verify that the client is able to connect through another GSI service (such as the gatekeeper) to make sure that the user's proxy has been created correctly. 

9597: debug2: input_userauth_request: setting up authctxt for cphillip
9597: debug2: input_userauth_request: try method none
9597: Failed none for cphillip from 141.142.21.10 port 2554 ssh2
9597: debug1: gssapi received empty username
9597: debug1: No suitable client data
9597: debug1: failed to set username from gssapi context
9597: Failed external-keyx for cphillip from 141.142.21.10 port 2554 ssh2
9597: debug1: gssapi received empty username
9597: debug1: No suitable client data
9597: debug1: failed to set username from gssapi context
9597: Failed gssapi for cphillip from 141.142.21.10 port 2554 ssh2
9597: debug1: userauth-request for user cphillip service ssh-connection method publickey
9597: debug1: attempt 0 failures 3
9597: debug2: input_userauth_request: try method publickey

Fix: Verify that you are using a GSI-enabled SSH client and that your GSI proxy has been properly initialized via 'grid-proxy-info'. If you need to initialize this proxy, use the command 'grid-proxy-init'.

Related Documentation

Please see the GSI-OpenSSH Home Page at NCSA for more information.