Message Level Security
Last Updated 09/03/2003Contents
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>The gsi/AuthenticationService service must also be deployed.
<!-- 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 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>Note: All these client-side, server-side handlers and the gsi/AuthenticationService service are installed by default.
<handler type="java:org.globus.ogsa.utils.JAXRPCHandler">
<parameter name="className"
value="org.globus.ogsa.impl.security.authentication.wssec.WSSecurityClientHandler"/>
</handler>
<!-- additional handlers -->
</responseFlow>
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;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.
import org.globus.gsi.jaas.JaasSubject;
...
public void serviceMethod() {
Subject subject = JaasSubject.getCurrentSubject();
}
...
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)
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">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.
<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>
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]
Example:
<securityConfig xmlns="http://www.globus.org">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).
<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>
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.
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 = ...;A security deployment descriptor can also be configured by setting the "securityConfig" property, e.g.:
callback.setProperty(GSIConstants.GSI_CREDENTIALS, cred);
...
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.