========== README.GSI 11/04/01 ========== 1. Introduction to GSI SOAP 2. Download GSI Tomcat 3. Requirements & Limitations 4. Building GSI enabled Tomcat 5. Configuring GSI enabled Tomcat 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 Tomcat GSI Tomcat is available as both a source code release based on Tomcat 3.3 out of CVS and a binary distribution. * Download the source at ftp://george.lbl.gov/pub/globus/gsi-tomcat-src-1.1.tar.gz. * Download the binary at ftp://george.lbl.gov/pub/globus/gsi-tomcat-bin-1.1.tar.gz. You can always cvs update -d to get recent Tomcat changes. 3. Requirements and Limitations Please follow the existing Tomcat documentation in src/doc directory for requirements and installation. In addition to the Tomcat requirements, GSI Tomcat 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 Tomcat from source Please follow the existing Apache SOAP documentation in docs directory for requirements and installation. Provided that the following libraries are in your CLASSPATH you simply invoke the ant command (ANT available from http://jakarta.apache.org) or use the provided build.sh script. This will create a build/tomcat directory. Required libraries for GSI: cog.jar cryptix.jar iaik_jce_full.jar iaik_ssl.jar jsse.jar Set the TOMCAT_HOME variable to point to the build/tomcat directory. 5. Using GSI in Tomcat GSI enabled Tomcat 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 start up the GSI enabled Tomcat server: A. The Server needs credentials (follow one of the following two steps) 1. Use personal credentials (a proxy) 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. or 2. Generate server credentials a. Run grid-cert-request -dir /tmp -nopw -cn FQDN -host FQDN where FQDN is the fully qualified hostname of the web server host e.g. binkley.lbl.gov. cn or CN refers to common name and is the subject name of your certificate. Follow the directions provided by grid-cert-request to obtain a signed certificate. B. Obtain the Certificate Authority (CA) trusted issuer certificates of your personal certificate and any others you tust and copy to /etc/grid-security/certificates/. C. Modify the server.xml Tomcat configuration file if necessary. In $TOMCAT_HOME/conf.server.xml the GSI HTTP10 connector is turned on by default with the following settings: The cert and key variables refer to th elocation of the server certificate and key created in step A above. If Tomcat should be started with a personal proxy as in Step A1, then replace the keywords "cert" and "key" with "proxy" and the location of the proxy file e.g. /tmp/x509up_u500. The delegation parameter informs the server whether delegation should be permitted and should be set to either "true" or "false". The authorization variable offers an additional authorization check on the client's certificate. Valid authorziation values include "NONE", "SELF", or "HOST". If "SELF" is selected, the server will check to make sure the client certifcate used to authentciate matches the certificate used on startup by the server, while "HOST" authorization will check to make sure the clients' certifcate is a host certificate and the CN=FQDN matches the client's FQDN. Normally SELF and HOST authorization are not used an dhaven't been extensively tested. The "debug" keyword may be "true" or "false" and displays additional CoG and IAIK SSL debug information for debugging the GSI Tomcat server. D. Deploy Apache SOAP web application to server. Read the Apache (or GSI Apache SOAP) documentation for more details, but in order to add SOAP support to TOMCAT, you will need the soap.jar library in your classpath before starting Tomcat, or simply copy it over to $TOMCAT_HOME/lib. (All libraries needed by Tomcat may be copied over to $TOMCAT_HOME/lib.) The Apache SOAP web application, soap.war, must also be copied over to $TOMCAT_HOME/webapps. If you deploy any SOAP services to TOMCAT, you will also need to copy the class files or the libraries over to $TOMCAT_HOME/lib or add them to the CLASSPATH before starting Tomcat. E. Start and Shutdown Tomcat Issue the following in $TOMCAT_HOME/bin: startup.sh (startup.bat on Windows) To shutdown Tomcat, issue the following: shutdown.sh (shutdown.bat on Windows) 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