Message Level Security

Last Updated 09/03/2003

Introduction
Configuration
Client
Service
Notifications
Limitations
Errors

1 Introduction

The message level security is based on WS-Security, XML Encryption and XML Signature standards. GT3 provides two different message level authentication mechanisms: GSI Secure Conversation and GSI XML Signature. With the GSI Secure Conversation method, a security context is first established between a client and the service which then is used to sign/verify/encrypt/decrypt messages. With the GSI XML Signature method a message is signed with the given credentials.

2 Configuration

2.1 Handlers

Message level security is handled by a few client- and server- side Axis/JAX-RPC handlers. These handlers must be properly installed in order for the message level security to work. The server-config.wsdd file must define the following request and response flows:

  <requestFlow>
   <handler type="URLMapper"/>
   <handler type="HandleResolverHandler"/>
   <handler type="java:org.globus.ogsa.impl.security.authentication.AuthenticationServiceHandler"/>
   <handler type="java:org.globus.ogsa.utils.JAXRPCHandler">
     <parameter name="className" 
                value="org.globus.ogsa.impl.security.authentication.wssec.WSSecurityHandler"/>
   </handler>
   <handler type="java:org.globus.ogsa.impl.security.authentication.SecurityPolicyHandler"/>
   <handler type="java:org.globus.ogsa.impl.security.authorization.AuthorizationHandler"/>
   <!-- optional: only needed for credential refresh functionality -->
   <handler type="java:org.globus.ogsa.impl.security.authentication.CredentialRefreshHandler"/>
   <!-- additional handlers -->
  </requestFlow>

  <responseFlow>
    <!-- additional handlers -->
    <handler type="java:org.globus.ogsa.utils.JAXRPCHandler">
     <parameter name="className" 
                value="org.globus.ogsa.impl.security.authentication.X509SignHandler"/>
    </handler>
    <handler type="java:org.globus.ogsa.utils.JAXRPCHandler">
     <parameter name="className" 
                value="org.globus.ogsa.impl.security.authentication.GSSHandler"/>
    </handler>
  </responseFlow>

The gsi/AuthenticationService service must also be deployed.
The client-config.wsdd file must define the following request and response flows:

 <requestFlow>
  <!-- additional handlers -->
  <handler type="java:org.globus.ogsa.handlers.OnceInvocationHandler"/>
  <handler type="java:org.globus.ogsa.utils.JAXRPCHandler">
    <parameter name="className" 
               value="org.globus.ogsa.impl.security.authentication.X509SignHandler"/>
  </handler>
  <handler type="java:org.globus.ogsa.utils.JAXRPCHandler">
    <parameter name="className" 
               value="org.globus.ogsa.impl.security.authentication.SecContextHandler"/>
    <parameter name="authService" 
               value="auto"/>
  </handler>
  <handler type="java:org.globus.ogsa.utils.JAXRPCHandler">
    <parameter name="className" 
               value="org.globus.ogsa.impl.security.authentication.GSSHandler"/>
  </handler>
 </requestFlow>

 <responseFlow>
   <handler type="java:org.globus.ogsa.utils.JAXRPCHandler">
     <parameter name="className" 
                value="org.globus.ogsa.impl.security.authentication.wssec.WSSecurityClientHandler"/>
   </handler>
   <!-- additional handlers -->
 </responseFlow>

Note: All these client-side, server-side handlers and the gsi/AuthenticationService service are installed by default.

2.2 Sun JVM 1.4.0/1.4.1 Issues

The message level security code is based on Apache's XML Security library. An older version of Xalan was shipped with Sun's JVM 1.4.0/1.4.1 then the version the XML Security library requires. Please see the XML Security library installation instructions for details and solutions. The xalan.jar file found in our distribution can be used.
Most of our command line clients will pick the right version of the xalan.jar file.

2.3 Tomcat Configuration

Please follow the instructions in section 2.8 of the User's Guide to deploy the framework in Tomcat. Also, 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. If using J2SE 1.4.x with Tomcat 4.1.24 copy xalan.jar found in GT3 distribution to <tomcat root>/common/endorsed.

3 GSI Client

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.

To enable GSI Secure Conversation security set the Constants.GSI_SEC_CONV property to either Constants.SIGNATURE or Constants.ENCRYPTION to indicate the desired message level protection.
The GSI properties such as GSIConstants.GSI_MODE, GSIConstants.GSI_CREDENTIALS, and Constants.AUTHORIZATION can be used to configure the GSI Secure Conversation message level security. The actor of the GSI signed/encrypted message can be set using the "gssActor" property.

To enable GSI XML Signature security set the Constants.GSI_XML_SIGNATURE to Boolean.TRUE.
The GSI properties such as GSIConstants.GSI_CREDENTIALS, and Constants.AUTHORIZATION can also be used to configure the GSI XML Signature message level security. The actor of the signed message can be set using the "x509Actor" property.

The above properties are set in the exact same way as the other GSI properties. Please see section 5.1 for details.

4 GSI Service

No code modifications are necessary to access a service securely. Minor code modifications might be needed for specialized purposes such as setting the service owner with the caller's delegated credential (e.g. in cases where a service is supposed to be accessed only by a specific user - user that created it)

4.1 Schema

No schema changes are necessary.

4.2 Programming model

4.2.1 Setting service owner with caller's delegated credential

To set the service owner with caller's credential, use:

 import org.globus.ogsa.impl.security.SecurityManager;
 ...
 public void serviceMethod() {
   SecurityManager.getManager().setServiceOwnerFromContext(this);
 }
 ...

4.2.2 Getting caller's identity

To get the current caller's identity, use:

 import org.globus.ogsa.impl.security.SecurityManager;
 ...
 public void serviceMethod() {
    String identity = SecurityManager.getManager().getCaller();
 }
 ...

4.2.3 Getting the JAAS invocation Subject

To get the JAAS invocation Subject, use:

 import javax.security.auth.Subject;
 import org.globus.gsi.jaas.JaasSubject;
 ...
 public void serviceMethod() {
   Subject subject = JaasSubject.getCurrentSubject();
 }
 ...

The invocation Subject depends on the run-as policy specified in the security descriptor. If no security descriptor is set for the service, the invocation Subject will be null. The Subject object contains authentication and authorization artifacts such as principals, public and private credentials.
In case of GSI XML Signature, a GlobusPrincipal (the identity of the signer) is added to the principal set of the Subject. Also, the signer's certificate chain is added to the public credentials set of the Subject object.
In case of GSI Secure Conversation, a GlobusPrincipal (the identity of the initiator) is added to the principal set of the Subject. Also, if delegation was performed, the delegated credential is added to the private credential set of the Subject object.
Also, if gridmap file authorization was performed, a UserNamePrincipal is added to the principal set of the Subject object.

4.3 Deployment Descriptor

4.3.1 Operation Providers

If a service provides a NotificationSource port type it should specify the "org.globus.ogsa.impl.security.authentication.SecureNotificationSourceProvider" instead of the "org.globus.ogsa.impl.ogsi.NotificationSourceProvider". Service credentials might not be propagated correctly if the regular NotificationSourceProvider is used. All other operation providers remain the same.

4.3.2 Service credentials

Each service can also be configured with a separate set of credentials. This is done by adding either <parameter name="serviceProxy" value="<proxy file>"/> element or <parameter name="serviceCert" value="<certificate file>"/> and <parameter name="serviceKey" value="<unencrypted key file>"/> elements to the <service> block of the service in the server-config.wsdd file. Global credentials (container credentials) can also be specified in the <globalConfiguration> block in similar way by adding "containerProxy" parameter or "containerCert" and "containerKey" parameters. A service will first check for the credential parameters in the <service> section. If no credential parameters are defined in the <service> section, the service will check the <globalConfiguration> block next. If no credentials are defined in either places, the service will rely on the underlying security library to acquire credentials (the security library will try to load a proxy certificate of the user that is running the container). If the credential files change during the runtime they will be automatically reloaded.

A separate set of trusted CA certificates can also be configured for each service. This is done by adding <parameter name="trustedCertificates" value="<CA certificate locations>"/> element to the <service> block of the service in the server-config.wsdd file.. Global CA certificates can also be specified in the <globalConfiguration> block in the same way. The <CA certificate locations> can be a comma separated list of individual certificate files or directories contains certificates (files ending with .<digit> extension) A service will first check for the trustedCertificates parameter in the <service> section. If no such parameter is defined in the <service> section, the service will check the <globalConfiguration> block next. If no trusted certificates are defined in either places, the service will rely on the underlying security library to find the certificates.
The "trustedCertificates" parameter is currently ignored.

4.3.3 Service authorization settings

Each service can be configured with a separate authorization mechanism. Currently, there are three supported authorization mechanisms: none, self, and gridmap. The authorization mechanism of a service is configured by setting an "authorization" parameter in the service deployment descriptor, for example: <parameter name="authorization" value="self"/>

Authorization checks are only performed for authenticated clients. All authorized clients have the same access to all methods of a service.

If the "authorization" parameter is set to "none" no authorization is performed. If the "authorization" parameter is set to "self" only the clients with the same identity as the service are allowed to access the service (if the service does not have its own identity, the system identity is used instead for authorization). If the "authorization" parameter is set to "gridmap", gridmap file authorization is performed. A "gridmap" property pointing to the girdmap file location must be either specified in the <service> section or in the <globalConfiguration> section of the deployment descriptor. If the "authorization" parameter is not defined in the service deployment descriptor, and the "gridmap" property is not defined in the <service> or <globalConfiguration> section of the deployment descriptor, self authorization is performed. If the "authorization" parameter is not defined in the service deployment descriptor, but the "gridmap" property is defined in the <service> or <globalConfiguration> section of the deployment descriptor, gridmap authorization is performed.

For services configured to perform gridmap file authorization, the gridmap file can be updated dynamically using the SecurityManager API. Also, if the gridmap file changes during the runtime it will be automatically reloaded.

4.4 Security Deployment Descriptor

A separate security deployment descriptor is used to provide more fine-grained control over security properties of a service such as authentication mechanisms required to access a service and/or run-as identities of the service.

The security deployment descriptor file is specified by the "securityConfig" parameter in the regular service deployment descriptor. For example:

<parameter name="securityConfig" value="org/globus/ogsa/impl/security/descriptor/gsi-security-config.xml"/>

The security deployment descriptor is loaded in the same way as any other resource data (from the classpath). This allows the security descriptor to be included in the same .jar file as rest of the service code.
The "gsi-security-config.xml" file mentioned above is a generic security deployment descriptor that can be used to secure a service with GSI secure conversation authentication mechanism.

The security deployment descriptor is contained within the "<securityConfig xmlns="http://www.globus.org">" element. Method-based security properties (for some properties) can be contained within the "<method name="qname">" elements. The security deployment descriptor will not be reloaded if it has changed during the runtime.

4.4.1 Authentication Methods

The "<auth-method>" element is used to configure the authentication mechanisms required to access a service. The authentication methods can be configured on per method basis. Currently, the following authentication methods are supported:

"<none/>" - indicates none authentication method
"<pkey/>" - indicates public key authentication method
"<gsi/>" - indicates GSI secure conversation authentication method (with integrity or privacy protection) [default]

The "<protection-level>" sub element can be used to specify a specific protection level that must be applied to the message:

"<integrity/>" - indicates that the message must be integrity protected (signed)
"<privacy/>" - indicates that the message must be privacy protected (encrypted)

Multiple authentication methods can be specified under the "<auth-method>" element (expect the "<none/>" method). As long as one of the authentication methods is performed, the access to the service is allowed. The "<none/>" method cannot be specified with any other authentication method.

Note: The "org.globus.ogsa.impl.security.authentication.SecurityPolicyHandler" handler must be installed properly in order for this to work. If security deployment descriptor is not specified, authentication method enforcement is not performed.

Example:

<securityConfig xmlns="http://www.globus.org">

 <method name="ogsi:findServiceData" xmlns:ogsi="http://www.gridforum.org/namespaces/2003/03/OGSI">
   <auth-method>
     <none/>
   </auth-method>
 </method>

 <method name="ogsi:destroy" xmlns:ogsi="http://www.gridforum.org/namespaces/2003/03/OGSI">
   <auth-method>
     <pkey/>
     <gsi>
       <protection-level>
          <integrity/>
       </protection-level>
   </auth-method>
 </method>

 <!-- default auth-method for any other method -->
 <auth-method>
  <gsi/>
 </auth-method>

</securityConfig>

In the above example, the findServiceData() operation does not require any authentication while the destroy() operation requires either public key or GSI secure conversation with integrity protection authentication. Any other operation must be authenticated with GSI secure conversation with either privacy or integrity protection.

4.4.2 RunAs Modes

The "<run-as>" element is used to configure the run-as identity under which the service method will be executed. The run-as identity can be configured on per-method basis. Currently, the following run-as identities are supported:

"<caller-identity/>" - the service method will be run with the security identity of the client
"<system-identity/>" - the service method will be run with security identity of the container
"<service-identity/>" - the service method will be run with the security identity of the service itself (if the service has one, otherwise the container identity will be used [default]

Note: The "org.globus.ogsa.impl.security.authentication.SecurityPolicyHandler" handler must be installed properly in order for this to work. The run-as identity is not set, if the security deployment descriptor is not specified.

Example:

<securityConfig xmlns="http://www.globus.org">

 <method name="ogsi:findServiceData" xmlns:ogsi="http://www.gridforum.org/namespaces/2003/03/OGSI">
   <run-as>
     <caller-identity/>
   </run-as>
 </method>

 <method name="ogsi:destroy" xmlns:ogsi="http://www.gridforum.org/namespaces/2003/03/OGSI">
   <run-as>
     <system-identity/>
   </run-as>
 </method>

 <!-- default run-as for any other method -->
 <run-as>
  <service-identity/>
 </run-as>

</securityConfig>

In the above example, the findServiceData() operation will be executed with caller's identity while the destroy() call will be run with system identity. Any other operation will be run with the service identity (if the service has one set).

4.5 Credential Refresh

A credential of the service can be refreshed if:

The "org.globus.ogsa.impl.security.authentication.CredentialRefreshHandler" handler is installed.
The service is not using a default container credential. That is, the service credential was either explicitly set in the deployment descriptor or the credential was set programmatically (e.g. by SecurityManager.setOwnerFromContext())
The service implements the "org.globus.ogsa.impl.security.authentication.CredentialRefreshListener" interface.
The service credential is not yet expired
The identity of the new credential is the same as the identity of the service credential and the new credential has a longer lifetime then the service credential.

A client can cause credential refresh if it performs GSI authentication with delegation on any method of the service.

5 GSI Notifications

5.1 Sink

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

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

The security properties can be set on the callback itself:

 NotificationSinkCallback callback = ...;
 callback.setProperty(GSIConstants.GSI_CREDENTIALS, cred);
 ...

A security deployment descriptor can also be configured by setting the "securityConfig" property, e.g.:

 callback.setProperty("securityConfig", "myservice/my-security-config.xml");

Please see section 4.4 for details. By default, the gsi-security-config.xml is used.

5.2 Source

5.2.1 Service Data

The security properties can be set on the service data instance using the setProperty() function.

5.2.2 Using NotificationProvider

The security properties must be passed in a separate Map object to the appropriate notify() function.

6 Limitations

6.1 ServiceLocator/GridLocator reuse

For GSI Secure Conversation, the same ServiceLocator instance cannot be called from multiple threads at the same time or shared between two different services. A security context is currently associated with a ServiceLocator instance. If the same ServiceLocator instance is used from multiple threads or shared between two different services a wrong security context might be used to sign/encrypt a request. A simple workaround for this problem is to use separate ServiceLocator instances.

6.2 Persistent Services Activation Run-As Identity

The activation of persistent services is not executed under any run-as identity. Wrong credentials might be used if the service is making an outbound connection during the activation. JAAS API might be used to set the right identity for the outbound connection.

6.3 GSI Secure Conversation Context Reuse and Service Deactivation

Since the security context for GSI Secure Conversation is associated with a ServiceLocator instance and reused between calls on the same service it is possible that the service itself might get deactivated in-between the calls. In that case a Invalid GSI Secure Conversation context error might be raised. A simple workaround for this problem is to use separate ServiceLocator instances.

7 Errors

7.1 '[SEC05] Invocation subject not set'

The service' method is calling SecurityManager.setOwnerFromContext() but the run-as identity of the method is not set. The service is probably missing a security deployment descriptor.

7.2 '[SEC06] Invocation subject does not contain private credentials'

The service' method is calling SecurityManager.setOwnerFromContext() but the run-as identity of the method does not contain private credentials. If the method is run under the "callers-identity" make sure the client calling the service uses GSI Secure Conversation and enables delegation for the call.