Setting up the SRB to use the Grid Security Infrastructure (X.509
certificates) is, unfortunately, somewhat involved but is worthwhile
in many ways.  It provides secure authentication across the internet
using X.509 certificates -- currently a hot topic in the distributed
computing research community; fully buzzword compliant - X.509
Certificates, PKI (Public Key Infrastructure), Grid computing, etc.

See the March 8, 2000 NPACI Online article on PKI/GSI
(http://www.npaci.edu/online/v4.5/pki-gsi.html ) for some background
information.  Also check the pages under
http://security.npaci.edu/help/pki .

Since this is new, and somewhat involved, we'd be happy to help you
set it up (and improve our documentation where needed).  Contact Wayne
Schroeder at schroede@sdsc.edu.


* To Build *

To build the SRB with GSI, you'll first need to build and install the
GSI library.  This is currently described and available at
http://www.globus.org/security/v1.1/ (look for later versions).  GSI
is part of Globus, so if you already are using Globus, GSI should be
available.  But GSI is also available as a separate package and if you
only need GSI you should install this rather than the fairly extensive
Globus system.

GSI depends on the SSLeay library as described in the GSI installation
procedures (they will be moving to the follow-on, OpenSSL, shortly).
So you may also need to install SSLeay.

You'll also need to build and install the SDSC AID library.  This is a
small library that provides a simple interface to GSI and is used in
the SRB. AID is available under www.npaci.edu/DICE/security/aid.html.
See the documentation in the AID release for additional information.

Once all this is done, you can configure and build the SRB with GSI
selected. See the README.build for information on how to do this.

In summary, to use GSI you first need to install:
  1) the Globus GSI package (www.globus.org)
  2) SSLeay (or OpenSSL), since this is required by GSI, see the
     documentation that is part of the GSI release
  3) libAID, under www.npaci.edu/DICE/security.


* Users running the GSI-enabled SRB Client *

Users need to get NPACI certificates to use GSI authentication when
running the SRB applications.  See the pages under
http://security.npaci.edu/help/pki for information on how to do this.
Attachments 1 and 2 below give a listing of the pages for obtaining and
converting certificate/key for GSI use.
(At some point, we may accept certificates issued by other
organizations too.)

Once they have their certificates converted to GSI format, they then
run the GSI command 'grid-proxy-init'.  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 client and
other GSI-enabled applications with automatic GSI authentication.


* Running the GSI-enabled SRB Server *

The SRB Server also needs a certificate, with a specific name (so that
the various SRB Servers (and Clients) will know who to accept
connections from).  The full Distinguished Name in the NPACI SRB
server certificate is "CN=srb.npaci.edu, OU=Certificate, O=NPACI,
C=US".   Check with Mike Wan (mwan@sdsc.edu) for the name you should use.

You then get a certificate via your browser much like regular users
do.  See http://security.sdsc.edu/help/pki/getting_certs.shtml .

There is also a page at
http://security.sdsc.edu/help/pki/convert.shtml that explains how to
convert certificates for GSI use.  At the bottom of that is a link
"For SRB administrators, see the following for more steps to set up
SRB server certificates".  That page explains how you can set up a SRB
proxy certificate that will be valid long-term (so you don't have to
do a grid-proxy-init for the SRB each day). Attachment 3 give a listing of
this pages.

If you have any questions, contact:

Wayne Schroeder
March, 2000
schroede@sdsc.edu
----------------------------------------------------------------------------
Attachment 1 - How do I get an NPACI certificate?

It is currently a little tedious get certificates/keys and convert them for
GSI use, but you only have to do this once and the procedure may be
simlified in the future.

NPACI certificates are only issued to NPACI/SDSC staff and users. This is
not a free certificate service for general internet users.

SDSC/NPACI users can get a certificate by pointing your browser to
https://ca.sdsc.edu, filling in the request form, and clicking on submit.
This will generate a public/private keypair and send a certificate request
to the NPACI CA administor. The administrator will contact you to verify
your identity and then issue the certificate to you (digitally signing it).
This will email a notice to you with the URL. Go to the URL and your
certificate will be installed into your browser.
----------------------------------------------------------------------------
Attachment 2 - How do I convert Certificates for GSI use?

It is currently a little tedious to convert certificates/keys from the
format received (in your browser) to the format needed by GSI, but you only
have to do this once and the procedure may be simlified in the future.

After you get your certificate, this is how yoru extract/convert
certificates from Netscape to a format that can be used by the Grid
Security Infrastructure (GSI) software, for use by Globus and the SRB.

1. In Netscape, click on Security.

2. Click on Certificates, Yours.

3. Click on the Certificate you want to use, and click Export.

4. It will prompt for the password you are using for your Netscape
certificate database.

5. It then prompts for a password to use for the file being exported. Enter
what you'd like. It will prompt you to enter it again to confirm it. You'll
need this is step 7 but not after that.

6. Select a directory and filename. The file extension should be '.p12',
for example cert.p12. This is a p12 format certificate/key file.

7. Copy and paste this short certconvert.ksh script (Attachment 4) into a file 
and execute it. It will prompt for an Import Password (this is the password 
you picked at step 5). Then it prompts for a PEM pass phrase. This will be 
the pass phrase you will use when accessing your certificate for the GSI 
environment. It prompts you to reenter it for verification. The steps 
performed are described in the following: 

    A) At the unix prompt, run:
      /usr/local/bin/openssl pkcs12 -in cert.p12 -out cert.pem

    It will prompt for an Import Password (this is the password you picked at 
    step 5).

    The pkcs12 utility converts the certificate from p12 to pem format.
    (If openssl is not installed, ssleay can be used instead. openssl is a 
    newer version of the ssleay utility and library.) 

    B) Then it prompts for a PEM pass phrase. This will be the pass phrase you
    will use when accessing your certificate for the GSI environment. It
    prompts you to reenter it for verification.

    C) You can now look at your cert.pem file with a text editor. There are
    three sections, one for the private key and two for the certificates. Move
    these sections into two new files to use as your certificate and key, for
    example ~/.globus/userkey.pem and ~/.globus/usercert.pem. The certificate
    file should have the text beginning with, Bag Attribute, continuing with
    -----BEGIN CERTIFICATE-----, and including -----END CERTIFICATE-----. There
    are two certificates in this file (your's and the Certificate Manager's),
    use yours. The key file should have the lines between -----BEGIN RSA
    PRIVATE KEY----- and -----END RSA PRIVATE KEY----- inclusive. The
    userkey.pem file should be readable only by your userid (e.g. mode
    -rw-------). It is your encrypted private key and should be kept private.
    The usercert.pem does not need to be kept private, it contains identifying
    information and your public key and is signed by the Certificate Authority.
    This is the default directory and file names, there are some environment
    variables that can be used if you prefer something else (X509_USER_FILE,
    X509_USER_KEY, X509_CERT_DIR). (See Globus/GSI documentation for additional
    information.)

    D) Create a symbolic link in your ~/.globus directory to the GSI trusted 
    certificate directory that is created when GSI is installed. At SDSC this 
    is /usr/local/apps/gsi/share/certificates and the commands you would 
    execute are:
        cd ~/.globus
        ln -s /usr/local/apps/gsi/share/certificates certificates

    NOTE: There is currently a problem (in our pkcs12 configuration) causing 
    the descriptions before the certificates to have a number instead of a 
    name for one of the fields (in says "0.9.2342.19200300.100.1.1" where is 
    should say "USERID"). This is not a fatal problem as the text is there to 
    help people understand the contents (i.e. comments) and does not affect 
    the actual certificate.

GSI, via OpenSSL, may someday be able to use certs and keys in the p12 format
directly.

----------------------------------------------------------------------------
3) Steps to set up SRB Server certificates

For the SRB server, 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.

You should get a certificate with an agreed-to name, such as srb-caltech.
Check with Mike Wan, mwan@sdsc.edu for this.

Your srb-site certificate should be extracted and converted as described
previously. At this point you could do a 'grid-proxy-init' (which will
prompt for your key password) and the passwordless authentication for the
SRB server should work, but only for the next 12 hours (by default).

One option is to simply run the 'grid-proxy-init' command periodically by
hand, using the -hours option to extend it to more than the default 12
hours (-hours 168 for example). But you would still need to do this (by
hand) once a week or anytime /tmp is purged.

Alternatively you can do the following:

run /usr/local/apps/ssl/bin/openssl rsa -in userkey.pem -out userkey2.pem

It then prompts for the userkey pass phrase and writes the userkey2.pem
file without encryption.

Then set the GSI/SSL environment variables to point to the new files, the
library authenticates without having to enter a passphrase:

setenv X509_USER_KEY /tmp/test/userkey2.pem setenv X509_USER_CERT
/tmp/test/usercert.pem

Be sure to keep the key file (userkey2.pem in the example) on local disk
(not NFS) to avoid sending the unencrypted key across the network. It is
like a plain-text password.
---------------------------------------------------------------------------
Attachment 4 - Certificate conversion script

#!/bin/ksh
#
#  Script name: certconvert.ksh
#  Written by: William J. Link
#  Date: April 20, 2000
#
#  This script must be run from the user's home directory and the
#  PKCS#12 certificate exported from a browser must also be in the
#  home directory.
# 
#  USAGE EXAMPLE: Extract your cert from your browser and put it in your
#                 home directory calling it cert.p12 then, run:
#                 ./certconvert.ksh cert

if [ -d ".globus" ]
then  
   /bin/echo ""
   /bin/echo "You already have a .globus directory.  It will be moved to"
   /bin/echo ".globus.old and a new .globus directory will be created."
   /bin/echo ""
   /bin/mv .globus .globus.old
   /bin/mkdir .globus
   /bin/mv $1.p12 .globus
else 
   /bin/mkdir .globus 
   /bin/mv $1.p12 .globus
fi

/usr/local/bin/openssl pkcs12 -in .globus/$1.p12 -clcerts -out .globus/$1.pem
/bin/sed '/END RSA PRIVATE KEY/q' .globus/$1.pem > .globus/userkey.pem
/bin/sed '1,/END RSA PRIVATE KEY/d' .globus/$1.pem |\
   /bin/sed s/0.9.2342.19200300.100.1.1/USERID/ > .globus/usercert.pem
/bin/ln -s /usr/local/apps/gsi/share/certificates .globus/certificates
---------------------------------------------------------------------------