- Doc Structure
- A Globus Primer
- Globus Is Modular!
- Installing GT
- Platform Notes
- Migrating from GT2
- Migrating from GT3
- PDF version
- Best Practices
- Coding Guidelines
- API docs
- Public Interfaces
- Resource Properties
- Performance Studies
Table of Contents
- 1. Introduction
- 2. Before you begin
- 3. Architecture and design overview
- 4. Public interface
- 5. Usage scenarios
- 6. Tutorials
- 7. Debugging
- 8. Troubleshooting
- 9. Related Documentation
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.
Features new in GT 4.1.1
- 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
Protocol changes since GT 4.0.4
- GSI-enabled OpenSSH was not included in GT 3.2.
API changes since GT 4.0.4
- GSI-enabled OpenSSH was not included in GT 3.2.
Exception changes since GT 4.0.4
- Not applicable
Schema changes since GT 4.0.4
- Not applicable
GSI-enabled OpenSSH depends on the following GT components:
- Pre-WS Authentication and Authorization
GSI-enabled OpenSSH depends on the following 3rd party software:
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.
Please see the GSI-OpenSSH Command Reference.
GSI-enabled OpenSSH does not provide any domain-specific interfaces.
The GSI-enabled OpenSSH software is installed with a default set of
configuration files, described below.
You may want to modify the
ssh_config file before using the
clients and the
sshd_config file before using the server.
If the GSI-enabled OpenSSH install script finds existing SSH key pairs, it will create symbolic links to them rather than generating new key pairs. The SSH key pairs are not required for GSI authentication. However, if you wish to support other SSH authentication methods, make sure the sshd (running as root) can read the key pair files (i.e., beware of NFS mounts with root_squash). If running multiple sshds on a system, we recommend configuring them so they all use the same key pairs (i.e., use symbolic links) to avoid client-side confusion.
moduli is a crypto parameter for generating keys.
ssh_config contains options that are read by ssh, scp, and sftp at run-time. The installed version is the default provided by OpenSSH, with X11Forwarding enabled. You may need to customize this file for compatibility with your system SSH installation (i.e., compare it with /etc/ssh/ssh_config).
Your system's RSA public-/private-key pair for SSH protocol 1 communications.
Your system's DSA public-/private-key pair for SSH protocol 2 communications.
Your system's RSA public-/private-key pair for SSH protocol 2 communications.
ssh_prng_cmds contains paths to a number of files that ssh-keygen may need to use if your system does not have a built-in entropy pool (like /dev/random).
sshd_config contains options that are read by sshd when it starts up. The installed version is the default provided by OpenSSH, with X11Forwarding enabled. You may need to customize this file for compatibility with your system SSH installation (i.e., compare it with /etc/ssh/sshd_config). For example, to enable PAM authentication, you will need to set "UsePAM yes" in this file.
The GSI-enabled OpenSSHD needs to be able to find certain files and directories in order to properly function.
The items that OpenSSHD needs to be able to locate, their default location and the environment variable to override the default location are:
Default location: /etc/grid-security/hostkey.pem
Override with X509_USER_KEY environment variable
Default location: /etc/grid-security/hostcert.pem
Override with X509_USER_CERT environment variable
Default location: /etc/grid-security/grid-mapfile
Override with GRIDMAP environment variable
Default location: /etc/grid-security/certificates
Override with X509_CERT_DIR environment variable
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.
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 the proxy, use the command 'grid-proxy-init'.
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).
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 18.104.22.168 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 22.214.171.124 port 1240 ssh2 7978: debug1: gssapi received empty username 7978: debug1: failed to set username from gssapi context 7978: Failed gssapi for cphillip from 126.96.36.199 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.
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 188.8.131.52 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.
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 184.108.40.206 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 220.127.116.11 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 18.104.22.168 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'.
Please see the GSI-OpenSSH Home Page at NCSA for more information.