Transport Level Security

Transport Security

Last Updated 06/28/2003

Note: Although we provide GSI transport layer security we strongly recommend using the message level security. The GSI transport layer security might be phased out at some point in the future.

Introduction
Configuration
Client
Service
Notifications

1 Introduction

The transport layer security is based around a new protocol called 'httpg' to indicate GSI-enabled HTTP-based protocol.

2 Configuration

2.1 Standalone Configuration

There are two ways to enable transport security in the standalone container, via the command line or by modifying the container's server-config.wsdd file. See below.

2.1.1 Command-line

To enable transport security from command line, start the container with -secure option. The transport security port can also be set by passing -sp port argument. For example:

 globus-start-container -p 8080 -secure -sp 9000

This will start a http server on port 8080 and httpg server on port 9000.

2.1.2 server-config.wsdd

Transport security can also be enabled by modifying the container's server-config.wsdd file by adding 'httpgPort' parameter in the <globalConfiguration> section of the configuration file. For example:

 ... 
 <globalConfiguration>
   ...
   <parameter name="httpgPort" value="9000"/>
   ...
 </globalConfiguration>
 ...

This will start a httpg server on port 9000

Note: A client might fail to receive secure notifications if it is using the same server-config.wsdd as the container. A workaround for this problem is to ensure that the client and the server are using separate configuration files (the client one should not have the 'httpgPort' property set)

2.2 Tomcat GSI Configuration

Please follow the instructions in section 2.8 of the User's Guide to deploy the framework in Tomcat. Once, the deployment is successful, follow these steps to configure GSI support:

If you are using J2SE 1.3.1 download and install the JAAS library. Copy the jaas.jar file into <tomcat_root>/commons/lib directory.

Edit <tomcat_root>/conf/server.xml file:

Add GSI Connector in <Service name="Tomcat-Standalone"> section and update the parameters appropriately with your local configuration:

 <!-- Define a GSI HTTP/1.1 Connector on port 8443

            Supported parameters include:
            proxy         // proxy file for server to use
              or
            cert          // server certificate file in PEM format
            key           // unencrypted server key file in PEM format
            cacertdir     // directory location containing trusted CA certs
            gridMap       // grid map file used for authorization of users
            debug         // "0" is off and "1" and greater for more info
    -->
   <Connector className="org.apache.catalina.connector.http.HttpConnector"
               port="8443" minProcessors="5" maxProcessors="75"
               enableLookups="true" authenticate="true"
               acceptCount="10" debug="1" scheme="httpg" secure="true">
      <Factory className="org.globus.tomcat.catalina.net.GSIServerSocketFactory"
               proxy="d:\certs\x509up_u945"
               cert="d:\certs\hostcert.pem"
               key="d:\certs\hostkey.pem"
               cacertdir="d:\certs\certs"
               gridMap="d:\certs\gridmap"
               debug="1"/>
    </Connector>

Add GSI Valve in <Engine name="Standalone" ... > section:

 <Valve className="org.globus.tomcat.catalina.valves.CertificatesValve" debug="1" />

Modify <tomcat_root>/bin/catalina.bat (on Windows) or <tomcat_root>/bin/catalina.sh (on Unix/Linux)

For catalina.bat, replace:

 set CLASSPATH=%CLASSPATH%;%CATALINA_HOME%\bin\bootstrap.jar

with:

4.0.6

 set CLASSPATH=%CLASSPATH%;%CATALINA_HOME%\bin\bootstrap.jar;%CATALINA_HOME%\common\lib\cog-jglobus.jar;%CATALINA_HOME%\common\lib\log4j-1.2.8.jar;%CATALINA_HOME%\common\lib\xerces.jar;%CATALINA_HOME%\common\lib\puretls.jar;%CATALINA_HOME%\common\lib\jce-jdk13-120.jar;%CATALINA_HOME%\common\lib\cryptix32.jar;%CATALINA_HOME%\common\lib\cryptix-asn1.jar;%CATALINA_HOME%\common\lib\jgss.jar;%CATALINA_HOME%\common\lib\jaas.jar

4.1.2

 set CLASSPATH=%CLASSPATH%;%CATALINA_HOME%\bin\bootstrap.jar;%CATALINA_HOME%\common\lib\cog-jglobus.jar;%CATALINA_HOME%\common\lib\log4j-1.2.8.jar;%CATALINA_HOME%\common\endorsed\xercesImpl.jar;%CATALINA_HOME%\common\endorsed\xmlParserAPIs.jar;%CATALINA_HOME%\common\lib\puretls.jar;%CATALINA_HOME%\common\lib\jce-jdk13-120.jar;%CATALINA_HOME%\common\lib\cryptix32.jar;%CATALINA_HOME%\common\lib\cryptix-asn1.jar;%CATALINA_HOME%\common\lib\jgss.jar;%CATALINA_HOME%\common\lib\jaas.jar

For catalina.sh, replace:

 CLASSPATH="$CLASSPATH":"$CATALINA_HOME"/bin/bootstrap.jar

with:

4.0.6

 CLASSPATH="$CLASSPATH":"$CATALINA_HOME"/bin/bootstrap.jar:"$CATALINA_HOME/common/lib/cog-jglobus.jar":"$CATALINA_HOME/common/lib/log4j-1.2.8.jar":"$CATALINA_HOME/common/lib/xerces.jar":"$CATALINA_HOME/common/lib/puretls.jar":"$CATALINA_HOME/common/lib/jce-jdk13-120.jar":"$CATALINA_HOME/common/lib/cryptix32.jar":"$CATALINA_HOME/common/lib/cryptix-asn1.jar":"$CATALINA_HOME/common/lib/cryptix.jar":"$CATALINA_HOME/common/lib/jgss.jar":"$CATALINA_HOME/common/lib/jaas.jar"

4.1.24

 CLASSPATH="$CLASSPATH":"$CATALINA_HOME"/bin/bootstrap.jar:"$CATALINA_HOME/common/lib/cog-jglobus.jar":"$CATALINA_HOME/common/lib/log4j-1.2.8.jar":"$CATALINA_HOME/common/endorsed/xercesImpl.jar":"$CATALINA_HOME/common/endorsed/xmlParserAPIs.jar":"$CATALINA_HOME/common/lib/puretls.jar":"$CATALINA_HOME/common/lib/jce-jdk13-120.jar":"$CATALINA_HOME/common/lib/cryptix32.jar":"$CATALINA_HOME/common/lib/cryptix-asn1.jar":"$CATALINA_HOME/common/lib/cryptix.jar":"$CATALINA_HOME/common/lib/jgss.jar":"$CATALINA_HOME/common/lib/jaas.jar"

Note: jgss.jar and jaas.jar are not needed with 1.4.x JVMs.

Modify <tomcat_build>/webapps/ogsa/WEB-INF/server-config.wsdd
1. Define 'schemaRoot' property as defined in User's Guide configuration section
2. Define 'httpPort' property in <globalConfiguration> with an appropriate port number (the same port as Tomcat is listening to)
3. Define 'httpgPort' property in <globalConfiguration> with an appropriate port number (the same port as Tomcat is listening to)
4. Add or uncomment the CredentialHandler handler in <requestFlow> section of <globalConfiguration> block:
```
 <requestFlow>
 ...
 <handler type="PersistentServiceHandler"/>
 <handler type="java:org.globus.axis.handler.CredentialHandler"/>
 ...
 <requestFlow/>
```

3 GSI Client

The Java CoG Kit must be properly configured to use GSI on the client. Make sure you have a valid proxy before running any GSI-enabled client.

A client will automatically perform GSI authentication with a service as long as the endpoint of the service specifies 'httpg' as the access protocol. The GSI authentication parameters (such as delegation type, etc.) can be controlled by setting various GSI properties. Please see section 5.1 of the Security Support page for details. There are no transport security specific properties at this time.

Also ensure the generated ServiceLocator class for your service extends org.globus.ogsa.impl.core.service.ServiceLocator class. It will initialize the httpg transport automatically. Otherwise, the transport will need to be initialized manually.

4 GSI Service

In the simplest case no code modifications are required to enable transport security for a service. Any service accessed over the httpg protocol can be thought of as a GSI-enabled service. However, if a service needs to get hold of the delegated credentials, the service must add the following code to the method that was invoked:

 public void method(String foo) throws RemoteException {
    MessageContext ctx = MessageContext.getCurrentContext();
    GSSCredential cred = 
	(GSSCredential)ctx.getProperty(GSIConstants.GSI_CREDENTIALS);
    ....
 }

Please note that the 'cred' object can be null if delegation was not performed. Also, the values of the GSIConstants.GSI_USER_DN and the GSIConstants.GSI_AUTH_USERNAME property can be retrieved from the MessageContext object using the same mechanism. These properties contain the caller's Globus ID (GSIConstants.GSI_USER_DN) and the local account that the caller was mapped to by the gridmap file (GSIConstants.GSI_AUTH_USERNAME).

To make sure that a service can be accessed via the 'httpg' protocol modify the address location urls in the <service> section of the <service>_service.wsdl file with url with httpg as the protocol type and appropriate port number. For example:

 <?xml version="1.0" encoding="UTF-8"?>
 <definitions name="NotificationCounter"
     targetNamespace="http://ogsa.globus.org/samples/counter/notification/service"
     xmlns="http://schemas.xmlsoap.org/wsdl/"
     xmlns:notificationcounterbinding="http://ogsa.globus.org/samples/counter/notification/bindings"
     xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
     <import location="gsi_counter_bindings.wsdl"
         namespace="http://ogsa.globus.org/samples/counter/notification/bindings"/>
     <service name="NotificationCounterService">
         <port
             binding="notificationcounterbinding:NotificationCounterSOAPBinding"
             name="NotificationCounterPort">
             <soap:address location="httpg://localhost:8080/ogsa/services/"/>
         </port>
     </service>
 </definitions>

The example specifies that the service can be reached via the httpg protocol on port 8080.

For an example of a GSI-enabled service take a look at Counter example in ogsa/impl/java/src/org/globus/ogsa/impl/samples/counter/secure/SecureCounterImpl.java file.

5 GSI Notifications

5.1 Sink

Use the "GSI" type of the notification sink manager to receive notifications:

 NotificationSinkManager manager = NotificationSinkManager.getInstance("GSI");

The security properties can be set on the sink manager using the manager.init() function:

 Map props = new HashMap();
 props.put(GSIConstants.GSI_CREDENTIALS, cred);
 ...
 manager.init(props);
 ...

5.2 Source

The security properties are set in exactly the same way as in the message level security. Please see section 5.2 of the message level security document for details.