This document was rewritten March 2003 to reflect recent SRB improvements and NPACI Grid Security Infrastructure (GSI) and certificate infrastructure improvements of the last few years. This document was last updated May, 2004.

GSI uses X.509 certificates to securely authenticate users across the network. This same GSI authentication system that is used for Globus commands can also be used for SRB commands. For additional information on the Grid Security Infrastructure see the NPACI Globus Guide and the Globus Certificates and Distinguished Names pages.

* To Build *

To build the SRB with GSI, you'll first need the Globus system, including the GSI libraries, installed. You'll need to know the GLOBUS_LOCATION (this is a Globus environment variable) under which the SRB can find the GSI include files, static libraries, and dynamic link libraries.

The rest of the needed software is now part of the SRB release and build procedure. To enable it, include --enable-gsi-auth on the configure line. The SRB build system has predefined locations for the globus system (GLOBUS_LOCATION) based on the architecture type; if you need to override this, include --enable-globus-location=path on the configure line.

* Users running the GSI-enabled SRB Client *

Users will need to get certificates to use GSI authentication. At NPACI sites this would normally be from the NPACI/SDSC Certificate Authority (CA) system. The Globus GSI system is set up to accept certificates issued from sites with trusted Certificate Authorities (CAs), and at NPACI sites this includes the NPACI CA. Other sites may accept certificates from different sites.

As described on the NPACI Globus Certificates and Distinguished Names page, users now get GSI certificates via the hotpage or by logging in and running 'cacl'. The 'cacl' system will automatically issue the user an NPACI certificate (after verifying their password), and setting it up properly for use (putting the certificate and password-protected key in their ~/.globus directory).

The certificate will contain a Distinguished Name (DN) that is unique, via a set of attributes including items such as Country, Organization, Organizational Unit, Common Name, and User id, for example /C=US/O=NPACI/OU=SDSC/CN=Wayne Schroeder/UID=schroede. These DNs need to be entered into the MCAT to map an individual DN to a particular SRB user (this is comparable to the Globus grid-mapfile which maps DNs to local logins). This can be done via the new SRB Admin Tool (GUI-mode), or via the MCAT utility commands.

After getting established (receiving a certificate and having their DN registered into the SRB), users then run 'grid-proxy-init' and enter their certificate-key password. This generates a proxy certificate (kind of a "sub-certificate") that is good for a few hours (like a kerberos 'kinit'). This will let them run the SRB Sinit to establish an SRB session (as well as other GSI-enabled applications) during the period that the proxy certificate is valid.

Users also need to set an environment variable, SERVER_DN, to tell the GSI system the DN of the SRB server (as defined in the SRB server's certificate). At SDSC this is '/C=US/O=NPACI/OU=SDSC/UID=srb/CN=Storage Resource Broker/Email=srb@sdsc.edu'. Typically, users would add this to their ~/.srb/.MdasEnv file, for example:
SERVER_DN /C=US/O=NPACI/OU=SDSC/UID=srb/CN=Storage Resource Broker/Email=srb@sdsc.edu

To run GSI-enabled 'C' programs (Sinit and the other Scommands, for example), users need to set the environment variable LD_LIBRARY_PATH so that the GSI libraries can find the GSI dynamic link libraries. If this is not set, users will see an error something like this: "error while loading shared libraries:libglobus_gss_assist_gcc32dbg.so.0: can't open shared object, no such file or directory". The preferred way to do this would be with:

  setenv GLOBUS_LOCATION /usr/local/apps/nmi-2.1    
  source $GLOBUS_LOCATION/etc/globus-user-env.csh
as this globus script will set up various things, including the LD_LIBRARY_PATH. Of course, your installation of Globus may be at some other location, different than /user/local/apps/nmi-2.1, and so users would enter that. Instead of sourcing globus-user-env.csh, one could also just set LD_LIBRARY_PATH via something like: 'setenv LD_LIBRARY_PATH $GLOBUS_LOCATION/lib'.

* Running the GSI-enabled SRB Server *

Like for client 'C' programs, the GSI-enabled SRB Server needs to be able to find the Globus dynamic libraries. So before running 'runsrb' you need to set LD_LIBRARY_PATH as described in the paragraph above for clients.

The SRB Server also needs a certificate, so that client programs can confirm the identity of the server they are connecting to. For server to server connections we generally use ENCRYPT1 authentication to avoid certificate compatibility problems.

Getting a server certificate is not as automated as getting user certificates. At SDSC, one would contact Bill Link, our CA administrator, and he can manually create one and provide it to you. The server DNs may have a somewhat different form, usually with a hostname. For testing, for example, I used a certificate with a DN of /C=US/O=NPACI/OU=SDSC/CN=zuri.sdsc.edu. By setting SERVER_DN on the client-side to this value, my test SRB client/server code worked fine.

You need to set it up so that the SRB server software can securely access a certificate/key for authentication without requiring a password or other manual intervention. One could 'grid-proxy-init' command periodically, but that would put the password in a file so wouldn't be secure and wouldn't be very convenient either. Instead, you can create an unencrypted key file.

A certificate consists of two text files, a certificate file and a corresponding key file. The key file contains the private key needed to confirm the identity in the certificate, and it is normally encrypted via a pass-phrase. The command 'openssl rsa -in userkey.pem -out userkey2.pem' prompts for the userkey pass phrase and writes the userkey2.pem file without encryption. Or if your cert/key files are zuri.sdsc.edu.cert.pem and zuri.sdsc.edu.privkey, you would run something like 'openssl rsa -in zuri.sdsc.edu.privkey -out zuri.privkey2'. Openssl is now released with Globus and can be found in GLOBUS_LOCATION/bin.

You then need to set two GSI environment variables, X509_USER_CERT and X509_USER_KEY, to point to your cert and key files, before starting the SRB server. The 'runsrb' script sets these variables, so modify the script for your file names. Then, if the key is unencrypted, the library will authenticate without asking for a passphrase.

setenv X509_USER_CERT /scratch/slocal/zuri.sdsc.edu.cert.pem
setenv X509_USER_KEY /scratch/slocal/zuri.privkey2

It would be better to keep the key file on local disk (not NFS) to avoid sending the unencrypted key across the network. It is like a plain-text password.