==========
README.GSI							10/22/01
==========

1. Introduction to GSI SOAP
2. Download GSI Apache SOAP
3. Requirements & Limitations
4. Building GSI enabled Apache SOAP
5. Using GSI in Apache SOAP
6. Additional Information
7. Authors

1. Introduction to GSI

The Grid Security Infrastructure (GSI) layers on top of the Secure Socket Layer (SSL) to provide secure mutual authentication between an Apache SOAP client and a GSI enabled SOAP server. The Grid Security Infrastructure includes two additional features not standard in SSL, that provide single sign-on capabilities through the use of temporary credentials known as "proxies". A proxy is a short-lived certificate/key pair used to authenticate to a GSI enabled server. Additionally, GSI provides delegation capabilities to create a new short-lived proxy that can be used to perform secure operations on the users' behalf by a GSI enabled server. A more comprehensive description of the Grid Security Infrastructure can be found at www.globus.org/security/overview.html.
 The Simple Object Access Protocol (SOAP) is used to enable webservices by providing a remote procedure call messaging protocol. The Apache SOAP implementation supports the HTTP/HTTPS protocol. GSI SOAP enhances Apache SOAP by providing a GSI enabled HTTP protocol and providing GSI delegation and authentication capabilities.  

2. Download GSI Apache SOAP

Download the latest version of GSI Apache SOAP at ftp://george.lbl.gov/pub/globus/gsi-soap-src-1.1.tar.gz. You can always cvs update -d to get recent Apache SOAP changes.

3. Requirements and Limitations

Please follow the existing Apache SOAP documentation in docs directory for requirements and installation. In addition to the Apache SOAP requirements, GSI SOAP requires the following libraries:

    * GSI support requires Java 1.2.1 or later and the Java Secure Socket Extension available at http://java.sun.com/products/jsse and included in the Sun JDK 1.4 distribution. 

    * The Java CoG libraries available at http://www.globus.org/java

4. Building GSI SOAP

Please follow the existing Apache SOAP documentation in docs directory for requirements and installation. Provided that the necessary Apache SOAP libraries and the following GSI libraries are in your CLASSPATH you simply invoke the ant command (ANT available from http://jakarta.apache.org)

Required libraries for GSI:
cog.jar
cryptix.jar
iaik_jce_full.jar
iaik_ssl.jar
jsse.jar

5. Using GSI in Apache SOAP

GSI enabled Apache SOAP uses the Java CoG security libraries for its GSI implementation available at www.cogkits.org. CoG in turn uses the IAIK SSL libraries available for research and academic use. The following steps must be performed in order to succesfully authenticate to a server using GSI:

A. Obtain personal credentials
	Either run "grid-cert-request", a script available with the Globus Toolkit (TM) at www.globus.org or obtain a certificate from your local Certificate Authority (CA).

B. Create a Proxy
	Run "grid-proxy-init", a program available as part of the Globus Toolkit (TM) or as part of the Java CoG Toolkit. You can also obtain the jmyproxy package which uses CoG to provide a GUI for creating a proxy available at ftp://george.lbl.gov/pub/globus/jmyproxy.tar.gz. Once you create a proxy, it is stored in /tmp/x509up_u<uid>.

C. Obtain the Certificate Authority (CA) trusted issuer certificates of your personal certificate and any others you tust and copy to /etc/grid-security/certificates/. 

D. Look at samples/gsi/SecureEchoClient.java for an example of creating a GSI enabled client. A typical SOAP client performs the following functions:

    // Build the call.
    Call call = new Call ();

    // Set other Call parameters
    call.set....

    // Create a SOAPHTTPConnection and associate with Call
    SOAPHTTPConnection hc = new SOAPHTTPConnection ();
    call.setSOAPTransport(hc);

To enable GSI, you must call an additional SOAPHTTPConnection method:

    // Build the call.	
    Call call = new Call ();

    // Set other Call parameters
    call.set....

    // Create a SOAPHTTPConnection and associate with Call
    SOAPHTTPConnection hc = new SOAPHTTPConnection ();
    
    // Create a SecureSocketAttributes for performing GSI
    SecureSocketAttributes ssa = new SecureSocketAttributes("GSI");
    ssa.setDelegation(true);
    ssa.setDelegationMode("LIMITED");
    ssa.setDebug(true);

    // Bind GSI SecureSocketAttributes with SOAPHTTPConnection
    hc.setSecureSocketAttributes(ssa);
    call.setSOAPTransport(hc);

Similarly, to create a standard SSL connection, use the following:

    // Create a SecureSocketAttributes for performing SSL
    SecureSocketAttributes ssa = new SecureSocketAttributes("SSL");

   The SecureSocketAttributes class provides the following options:
	setSecureSocketType()  // "GSI" or "SSL"
	setAuthorizationMode()  // "NONE", "SELF", or "HOST"
	setDelegation()        // true or false
	setDelegationMode()    // "LIMITED" or "FULL"
	setDebug()             // true or false	

6. Additional Information

Please see ChangeLog.GSI for modifications/additions to support GSI

Apache-SOAP          http://xml.apache.org/soap/docs/index.html
Tomcat 	             http://jakarta.apache.org/tomcat
Globus Toolkit (TM)  http://www.globus.org

7. Authors

Jason Novotny	<jdnovotny@lbl.gov>