Home -> Security -> 3.2beta

Message Level Security

Last Updated 2/19/2004.

Please report any errors or suggestions to our Bugzilla system.

Contents

1. Introduction
2. Configuration
3. Client
4. Service
5. Notifications
6. Dealing with GRIM Proxies
   
7. Errors

1 Introduction

The message level security is based on the WS-Security, XML Encryption and XML Signature standards. GT3 provides two different message level authentication mechanisms: GSI Secure Conversation and GSI Secure Message. 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 Secure Message method a message is signed with the given (X509) credentials. GSI Secure Message does currently only support integrity protection and does not provide support for delegation and replay-attack prevention. On the other hand, GSI Secure Conversation requires three more round trips than GSI Secure Message, which makes GSI Secure Message more suitable for single request-response interactions where the lack of replay-attach prevention and encryption support is not a significant problem.

2 Configuration

2.1 Handlers & Authentication Service

Message level security is handled by a few client- and server- side Axis/JAX-RPC handlers and a authentication service. The handlers and the authentication service must be properly installed in order for message level security to work.

The server-config.wsdd file must define the following request and response flows:


It should also contain the entry for the gsi/AuthenticationService service:


The client-config.wsdd file must define the following request and response flows:

Note: All these client- and 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, which requires a newer version of Xalan than was shipped with Sun's JVM 1.4.0/1.4.1. Please see the XML Security library installation instructions for details and a workaround. The xalan.jar file found in our distribution can be used for the suggested workaround. Even without the workaround those of our command line clients that are invoked by a shell script wrapper will pick the right version of the xalan.jar file. When invoking a client by directly calling Java in an environment where the above suggested workaround is not in place you should use 
Java  -Djava.endorsed.dirs=$GLOBUS_LOCATION/endorsed  <other options>  <client class> <args>

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 Sun's J2SE 1.4.x with Tomcat 4.1.24 copy xalan.jar found in GT3 distribution to <tomcat root>/common/endorsed.

3 GSI Client

3.1 Prerequisites

The Java CoG Kit must be properly configured to use GSI on the client. Information on how to do so can be found in the entries concerning the cog.properties file in the Java CoG Kit FAQ. Note that the GT3 distribution only includes a subset of the CoG distribution and does not provide all the tools mentioned in the FAQ. Make sure you have a valid proxy before running any GSI-enabled client.

3.2 Client Side Programming

The current client side programming model requires that you set security properties on the stub object. For example:

These properties will later be picked up by and determine the behavior of the Axis handlers mentioned above. Note that while service side security is generally configured at deployment time (see section on service security), services acting as clients (e.g. a service interaction with another service) will have to make use of the same interface.

To enable GSI Secure Conversation set the Constants.GSI_SEC_CONV property to either Constants.SIGNATURE or Constants.ENCRYPTION to indicate the desired message protection level. The generic GSI properties that are valid in combination with the Constants.GSI_SEC_CONV property are GSIConstants.GSI_MODE, GSIConstants.GSI_CREDENTIALS, and Constants.AUTHORIZATION. More information on these properties can be found in the GSI client properties section.
Furthermore, you can set the SOAP Actor of the GSI signed/encrypted SOAP message by using the "gssActor" property. We recommend that you do not do this unless you really know what you are doing.

To enable GSI Secure Message set the Constants.GSI_SEC_MSG to Constants.SIGNATURE. The generic GSI properties that are valid in combination with the Constants.GSI_SEC_MSG property are GSIConstants.GSI_CREDENTIALS and Constants.AUTHORIZATION. More information on these properties can be found in the GSI client properties section.
Again, you can set the SOAP Actor of the signed message can be set using the "x509Actor" property, but we do not recommend it.

It should be noted that GSI Secure Message and GSI Secure Conversation are not mutually exclusive.

3.3 Limitations

3.3.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. This means that you can not reuse the same locator for two service instances, even if they are of the same type.

3.3.2 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

4 GSI Service

In general, no code modifications are necessary to secure a service. Service security properties can be specified via deployment descriptors (see section 4.3). That being said, 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 -- the user that created it) or dealing with GRIM credentials.

4.1 WSDL

No WSDL changes are necessary.

4.2 Programming model

4.2.1 Setting service owner with caller's delegated credential

Associating credentials a method invoker has delegated with a service instance can be done in the following fashion:


The SecurityManager.setServiceOwnerFromContext() operation requires a Subject object to be associated with the current thread of execution. That Subject object must also contain some private credentials.

A common scenario is to have services instances created by factory use the credentials delegated when invoking the create operation. In this context one would do the following in the postCreate method of the service instance:


and set the JAAS run-as policy (see 4.4.2) for the create method in the factory creating the service instance to <caller-identity/>.

4.2.2 Getting caller's identity

To get the current caller's (client's) identity, use:

4.2.3 Getting the current JAAS Subject

A JAAS Subject object contains authentication and authorization artifacts such as principals, and public and private credentials such as client's certificates, the delegated proxy credentials, etc. GT3 allows a service operation to be invoked using either a null subject, the system/container subject, the service subject or the caller's subject. For more information on these JAAS subjects see section 4.4.2. To get the current JAAS Subject, use:


The current Subject depends on the run-as policy specified in the security descriptor (again, see section 4.4.2). Should no security descriptor is set for the service, the current Subject will be null.

4.2.4 Performing work as a particular JAAS Subject

A piece of code can also be executed with a particular JAAS Subject object. For example, to execute a piece of code with a given Subject object do the following:

4.3 Deployment Descriptor

4.3.1 Operation Providers

If a service wants to provide a secured NotificationSource port type it should specify the "org.globus.ogsa.impl.security.authentication.SecureNotificationSourceProvider" instead of the "org.globus.ogsa.impl.ogsi.NotificationSourceProvider" in its entry in the server-config.wsdd file, e.g.:


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 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 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 proceed to checking the <globalConfiguration> block. If no credentials are defined in either place, 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). Should the credential files change while the container or service is running then they will be automatically reloaded.

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 the "authorization" parameter in the associated <service> section in the server-config.wsdd file, for example:

 <service name="my/dummy/service" provider="Handler" style="wrapped">
  ...
  <parameter name="authorization" value="self"/>
  ...
 </service>

It is currently not possible to set this parameter in the <globalConfiguration> section of the deployment descriptor. It should also be noted that authorization checks are only performed for authenticated clients, so if you allow unauthenticated access to your service all clients are authorized. Furthermore, all authorized clients have access to all methods of a service, i.e. the toolkit currently doesn't provide method/operation level authorization support.

The supported authorization mechanisms have the following semantics:

• 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 identity in the current JAAS subject associated with the service are allowed to access the service. The identity in the JAAS subject is determined through the value in the runas element in the service security deployment descriptor (see 4.4.2).
• If the "authorization" parameter is set to "gridmap", gridmap file authorization is performed. A "gridmap" property pointing to the gridmap file location must be specified in either the <service> section or in the <globalConfiguration> section of the deployment descriptor.
  
• If the "authorization" parameter is not defined in the <service> section, 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 at 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 the authentication mechanisms required/permitted to access a service and/or the run-as identity of the service.

The security deployment descriptor file is specified by the "securityConfig" parameter in the <service> section of the server-config.wsdd file. For example:


It is loaded in the same way as any other resource data, i.e. from the class path. This allows the security descriptor to be included in the same .jar file as rest of the service code.

The schema for the security descriptor is defined here. 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 name attribute of the method can just be the operation name (preferred) or the operation name with a given namespace. The security deployment descriptor will not be reloaded if it is changed at runtime.

The "gsi-security-config.xml" file in the above example is a generic security deployment descriptor that can be used to secure a service with GSI Secure Conversation authentication mechanism.

4.4.1 Authentication Methods

The authentication methods a service requires are specified using the "<auth-method>" element. The authentication methods can be configured on a per method basis. Currently, the following authentication methods are supported:

• "<none/>" - indicates that no authentication is required
  
• "<GSISecureMessage/>" - indicates the GSI Secure Message authentication method ("<pkey>" may also be used)
• 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)
• "<GSISecureConversation/>" - indicates the GSI Secure Conversation authentication method (with integrity or privacy protection) ("<gsi>" may also be used)
• 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 (signed & encrypted)
  

Multiple authentication methods can be specified under the "<auth-method>" element (expect for the "<none/>" method, see below). 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.
Also, if no "<protection-level>" sub element is specified then all protection levels are available to clients. If on the other hand the "<protection-level>" sub element is specified then the service will only accept the protection levels listed under said element.

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:


In the above example, the findServiceData() operation does not require any authentication while the destroy() operation requires either GSI Message Security authentication 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 JAAS 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. The caller Subject will contain the following:
  
• In the case of GSI Secure Message, a GlobusPrincipal (the identity of the signer) is added to the principal set of the caller-identity 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. If client authentication was performed, client's certificate chain will be added to the public credentials set of the Subject object. Also, if delegation was performed, the delegated credential is added to the private credential set of the Subject object.
• If gridmap file authorization was performed, a UserNamePrincipal is added to the principal set of the Subject object.
• "<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.

Also, if the security deployment descriptor is not specified, then the run-as identity is not set and there will be no JAAS subject associate with the execution of the operation. This means that any method calls that require credential and that are invoked by the service method itself will fail.

Example:


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.4.3 Other configuration

Some security configuration might be done as a part of the security descriptor at service level granularity. Currently, the following are supported:

• "<context-lifetime value="lifetime in seconds"/>" - This sets the lifetime of the context that is created at the server end. If this option is not specified, by default, the lifetime of the credential used is set as the lifetime of the context. Relevant for all operations requiring GSI Secure Conversation or GSI Secure Message authentication.
• "<reject-limited-proxy/>" - This requires that the credential presented by the client is not a limited proxy. Relevant for all operations requiring GSI Secure Conversation or GSI Secure Message authentication.

Example:

In the above example, if the service is accessed using limited proxy, an error is reported. Also, the contexts created at the server end are set to have a lifetime of 100seconds.

4.5 Credential Refresh

A credential used by a service can be refreshed if:

• The "org.globus.ogsa.impl.security.authentication.CredentialRefreshHandler" handler is installed.
• The service is not using the 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 has 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 than the service credential.

If the above conditions are met, a client can cause credential refresh by invoking a method on the service given that:

• The invocation is protected by GSI Secure Conversation
• The client specifies to delegate his credential during the security setup (see GSI client properties)
• The client is not reusing a existing context. This can be assured by creating a new stub instance.

4.6 Limitations

4.6.1 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.

4.6.2 Security Descriptor Requires Credentials

The presence of a security descriptor for a specific service triggers credential acquisition and as such causes the service to require credentials, even if the security descriptor only specifies the <none/> authentication method. As a workaround we suggest that you remove the security-descriptor.  Secure invocation on a service without a security descriptor will still work (given that the service has credentials available).

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 (client-side properties) for the subscribe operation (invoked by .addListener() call) can be set using the manager.init() function.


The security properties (service-side properties) for the local sink can be set on the callback itself:


A security deployment descriptor can also be configured by setting the "securityConfig" property, for example:


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

5.2 Source

5.2.1 Service Data

To enforce security on notifications you should set security properties on the service data instance by using the setProperty() function. For example:

private ServiceData serviceDataElement;
...
this.serviceDataElement.setProperty(Constants.GSI_SEC_CONV,
                                    Constants.ENCRYPTION);
this.serviceDataElement.setProperty(Constants.AUTHORIZATION,
                                    SelfAuthorization.getInstance());

5.2.2 Using NotificationProvider

It is not recommended that you use the NotificationProvider API directly. We recommend that you push out notifications using the appropriate methods on a ServiceData object. Should you still want to use the NotificationProvider API you will have to set security properties by passing in a separate properties Map object to the appropriate notify() function (notify() or notifyWithAck()).

6 Dealing with GRIM Proxies

6.1 Background

GRIM (Grid Resource Identity Mapper) proxies are proxies that contain a proxy policy which lists the identities (DNs/Subject Names) that are associated with the holder of the private key part of the GRIM proxy. The GRIM architecture also contains a mechanism for gating access to resource (e.g. host) credentials. This is done via a setuid executable which has access to longterm (resource) credentials and upon execution creates a GRIM proxy containing a policy that is populated with the a list of identities. This list of identities is generated from the <identity> <user> mappings contained in a gridmap file, where the <user> used for lookup is the one that is running the GRIM executable. More information on GRIM can be found here.
This type of proxy is currently in use by GRAM, but will in the future likely be used by a variety of higher level services.

6.2 Client Side Programming

Since GRIM proxies contain a non-standard proxy policy, they need special handling during the authentication process. This special handling takes the form of installing a handler that will deal with the GRIM policy. We currently provide two kinds of GRIM policy handlers, one that ensures that one of the identities listed in the GRIM policy matches a given identity and one that completely ignores the contents of the GRIM policy. We recommend that you do not use the second handler since it circumvents the security that GRIM provides. To use the first handler you would do the following:

import org.globus.gsi.proxy.ProxyPolicyHandler;
import org.globus.ogsa.handlers.GrimProxyPolicyHandler;
...
String identity = "identity you expect to see in GRIM policy"
ProxyPolicyHandler grimPolicyHandler = new GrimProxyPolicyHandler(identity);
stub._setProperty(Constants.GRIM_POLICY_HANDLER, grimPolicyHandler);

Where "stub" is the usual RPC stub object (see e.g. example on client side programming). You may also choose to omit passing the identity to the GrimProxyPolicyHandler constructor in which case the identity of the current credential will be used.

To use the "ignore" handler you would use something like the code below:

import org.globus.gsi.proxy.ProxyPolicyHandler;
import org.globus.gsi.proxy.IgnoreProxyPolicyHandler;
...
ProxyPolicyHandler grimPolicyHandler = new IgnoreProxyPolicyHandler();
stub._setProperty(Constants.GRIM_POLICY_HANDLER, grimPolicyHandler);

6.3 Server Side Programming

If you want to make your service accept GRIM proxies you will have to do something like the following:

import org.globus.gsi.proxy.IgnoreProxyPolicyHandler;
import org.globus.ogsa.impl.security.authentication.SecureServicePropertiesHelper;
...
public class OgsiManagement extends GridServiceImpl
{
    ...
    public OgsiManagement()
    {
        super("Management Service");
        SecureServicePropertiesHelper.setGrimProxyPolicyHandler(
                        this, new IgnoreProxyPolicyHandler());
    }
    ...
}

This will cause the service to ignore any GRIM policy in the credentials it authenticates. You may of course want to enforce the GRIM policy in which case you would use the GrimProxyPolicyHandler (see client side example) instead of the IgnoreProxyPolicyHandler.
It should be noted that the authorization identity of a GRIM proxy is treated differently than the identity of a regular proxy. The authorization identity of a GRIM proxy is not stripped of any common name (CN=) components added during proxy generation.
Also, should you decide to use GRIM proxies for your container credential you will want to make sure that you install the GrimContainerHandler (part of  GRAM) , which will create the GRIM proxy and periodically refresh it. The refresh is required since GRIM proxies have a (configurable) limited lifetime.

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.

7.3 org.globus.gsi.proxy.ProxyPathValidatorException: Unknown policy: 1.3.6.1.4.1.3536.1.1.1.7

This error is caused by trying to authenticate a GRIM proxy without having installed a handler to deal with the GRIM policy (which has the OID 1.3.6.1.4.1.3536.1.1.1.7). Instructions on how to install a GRIM policy handler can be found here.