OpenSSH and GSSAPI Mechglue

NCSA maintains a patch to OpenSSH that adds support for GSSAPI authentication. GSSAPI provides a standard interface to different security services. In particular, a GSSAPI interface is available for both the Kerberos and GSI mechanisms. A GSSAPI "mechglue" library is needed to use multiple GSSAPI implementations in the same application. NCSA distributes a modified version of the MIT Kerberos GSSAPI "mechglue" library for use with the GSSAPI OpenSSH patch, to enable support for both Kerberos and GSI authentication in OpenSSH.

The instructions below assume some familiarity with OpenSSH, Kerberos, and GSI. You may need to do some porting or debugging to get this working in your environment. Please send feedback, patches, bug reports, etc., to jbasney@ncsa.uiuc.edu. You can also discuss this software on the gsi-openssh-user@globus.org mailing list. To subscribe, send email to majordomo@globus.org with "subscribe gsi-openssh-user <your email address>" in the body. The list is archived online here.

Credits

NCSA's GSSAPI patch for OpenSSH is built on Simon Wilkinson's patch. GSI support was originally added to OpenSSH by Von Welch. Dan Kouril and Doug Engert initially got GSSAPI OpenSSH working with the GSSAPI mechglue library.

News

Installing OpenSSH with GSSAPI Mechglue, GSI, and Kerberos

Follow the instructions below to build and install GSSAPI-mechglue-enabled OpenSSH server and clients. They should interoperate with Kerberos-only, GSI-only, and standard SSH clients and servers. The SSH protocol tries multiple authentication mechanisms. If the client or server doesn't support a specific GSSAPI mechanism or doesn't have valid credentials for that mechanism, OpenSSH will skip it and move on to another mechanism.

It is typically desirable to use GSSAPI Mechglue only on the server-side. GSSAPI-mechglue-enabled clients introduce a level of complexity for users that is often unwanted. Instead, it is better to use standard Kerberos-enabled ssh, scp, and sftp clients, along with GSI-enabled gsissh, gsiscp, and gsisftp clients, together with GSSAPI-mechglue-enabled servers. So while the following instructions will build both client and server executables, it is often better to leave the GSSAPI-mechglue-enabled clients out of $PATH.

  1. Install Kerberos shared libraries on your system. Recent RedHat Linux installations include Kerberos libraries in /usr/kerberos. MIT Kerberos is available here. Heimdal Kerberos is available here.
  2. Install GSI libraries on your system. The GSI libraries are a Globus Toolkit component, available in releases from http://www.globus.org/toolkit/. Using the latest GSI libraries is strongly encouraged because older versions contain known bugs and security vulnerabilities. Check the Globus Toolkit advisories page for updates.
  3. Verify that your GSI library installation is complete by running the following command:

    gpt-query globus_gssapi_gsi globus_core

    You should see globus_gssapi_gsi-flavor-dev, globus_gssapi_gsi-flavor-rtl, and globus_core-flavor-dev listed in the output for your Globus "flavor". If the globus_core package is missing from the gpt-query output, run:

    gpt-build -nosrc flavor

    to install the package, replacing "flavor" in the command with your chosen Globus "flavor" (gcc32/gcc32dbg/vendorcc32).
  4. Build the GSSAPI Mechglue library from NCSA using the gssapi.h from your GSI installation.
  5. Download OpenSSH from here.
  6. Unpack the OpenSSH distribution. For example:

    tar xvfz openssh-3.4p1.tar.gz

  7. Download the latest NCSA GSSAPI OpenSSH patch from here (named openssh-<version>.patch).
  8. Apply the patch in the top directory of the OpenSSH distribution. For example:

    patch -Np1 < openssh-3.4p1.patch

  9. Run configure in the OpenSSH directory. The following options are required: You may also want to specify: Do not use the --with-ssl-dir option. The OpenSSL library is provided with the GSI libraries.
    For example:

    ./configure --prefix=/usr/local/openssh-mechglue \
    --with-mechglue=/home/jbasney/mechglue \
    --with-globus=$GLOBUS_LOCATION --with-globus-flavor=gcc32 \
    --with-kerberos5=/usr/kerberos --with-pam

  10. After configure successfully runs, run make, then (typically as root) run make install.
  11. The make install command will install new SSH host keys in ${prefix}/etc. If you already have SSH host keys installed on your system (in /etc/ssh, for example), you should remove the new keys in ${prefix}/etc and add symbolic links in that directory to your existing keys, so your users don't get an error message about the SSH keys changing when they connect to the new sshd.
  12. Install a Kerberos host key in /etc/krb5.keytab and GSI host credentials in /etc/grid-security/hostcert.pem and /etc/grid-security/hostkey.pem for sshd to support both Kerberos and GSI authentication.
  13. Add $GLOBUS_LOCATION/lib to the dynamic linker search path. Set the LD_LIBRARY_PATH environment variable or modify /etc/ld.so.conf and run ldconfig. This applies to both the clients and the server. If the GSSAPI mechglue library fails to load the GSI libraries in $GLOBUS_LOCATION/lib, it will simply skip GSI authentication.
  14. Install a mech.conf file that lists the mechanism-specific GSSAPI libraries (both Kerberos and GSI versions) in /etc/mech.conf or in a location specified by the GSSAPI_MECH_CONF environment variable. This applies to both the clients and the server. The NCSA GSSAPI mechglue distribution includes a sample mech.conf file. You will need to edit the library paths in that file and install it in an appropriate location on your system. If the mech.conf file is not found, the GSSAPI mechglue library will not load any GSSAPI mechanisms and OpenSSH will simply skip GSSAPI authentication.
  15. Test and debug the clients with the '-vvv' option and the server with '-ddd -r' options.

Refer to the GSI-OpenSSH documentation for additional information.

Troubleshooting

Errata

Valid HTML 4.01!