The implementation of the facade for Axis signs request messages to services. The signatures are created in the client by an Axis handler, and a special sub-class of SecurityGuard, AxisClientSecurityGuard is provided to pass credentials into the handlers. Axis requires that the security handler be created when its 'Axis engine' in the client is first created. This means that the handler must set up when constructing the client-side stub for the service.
The grid credentials used to make the signatures are set by accessor methods on the SecurityGuard. Typically, the calling code will get credentials by an exchange with a community service such as MyProxy. (This is a change from earlier versions of this component in which credentials were read from file or obtained directly from a community service by the facade classes themselves.) The following credentials are required for the signature.
The private key is used, by the security-facade classes, actually to sign the message, and it is not sent with the message. The certificate chain is not needed to derive the cryptographic value of the signature, but is sent with the messages in order that the receiving service may verify the signature.
Some aspects of the client-side facade are thus specialized to Axis and the specialization shows in the APIs. Other parts are independent of Axis. If a delegate class is provided to operate the basic messaging mechansim, then this delegate will necessarily be Axis-specific and can encapsulate the Axis-specific calls to the security facade. The other, portable calls to the facade can be left in the code that calls the delagate. Alternatively, the entire client can be specific to Axis. This document describes an Axis-specific delegate in an Axis-independent client.
The Axis handler for signing the message must be configured when the AxisEngine for the client is configured. Axis' handler chains are effectively immutable and the security handler cannot easily be injected later.
The handler mechanism is specific to Axis; it is not the standard, JAX-RPC mechanism. Therefore, the handler should be set up in the delegate where Axis-specific code is normal.
If the client stub-classes, called by the delegate, are the kind created by Axis' WSDL2J, then the handlers should be configured when constructing the 'locator' object for the service in question.
import org.astrogrid.security.AxisClientSecurityGuard; XyzLocator locator = new XyzLocator(AxisClientSecurityGuard.getEngineConfiguration());
Note the use of a static method on AxisClientSecurityGuard to provide the configuration object. This configures the 'java', 'local' and 'http' transports with the signature handler and no other special handlers.
With the locator configured in this way, all proxy objects created from the locator will have the signature handler.
If the client's AxisEngine is being configured from a WSDD document, then the method above does not work. Instead, the WSDD document should declare org.astrogrid.security.AxisClientCredentialHandler as a request handler.
The portable code of the client (that part that is not specific to Axis) should instantiate the generic SecurityGuard class. This object will be used to gather the credentials.
import org.astrogrid.security.SecurityGuard; SecurityGuard guard = new SecurityGuard();
One SecurityGuard is needed per user identity but that same object can and should be reused for all delegates created by the client.
The client application should obtain a certificate chain and matching private key. These may be had, in exchange for a user name and password, from the community services. The security facade does not, currently, interact with the community services on behalf of the application.
import java.security.PrivateKey; import java.security.cert.X509Certificate; X509Certificate[] chain = ...; PrivateKey key = ...;
The client application should store the credentials in the SecurityGuard.
guard.setCertificateChain(chain); guard.setPrivateKey(key);
The Axis-specific code is assumed to be encapsulated in a delegate class. The client application should create the delegate and pass to it the generic security guard.
XyzDelegate delegate = ... delegate.setCreadentials(guard);
To get the grid credentials into the signature handler, the client must embed them in an instance of AxisClientSecurityGuard. This object should be created from the generic SecurityGuard inside the delegate.
import org.astrogrid.security.AxisClientSecurityGuard; AxisClientSecurityGuard axisGuard = new AxisClientSecurityGuard(guard);
The Axis-specific guard must then be told to pass its credentials to the handler.
XyzPortType proxy = locator.getXyzPort(endpoint); axisGuard.configureStub((org.apache.axis.client.Stub)proxy);
In this example, the locator and proxy classes are those created by WSDL2Java. Once the proxy is configured, all outgoing messages are signed, by the handler, with the credentials in the security-guard object.
If the client application uses the Axis stubs directly, without a delegate layer, then the application can create the AxisSecurityGuard directly instead of creating a generic SecurityGuard. The setCertificateChain and setPrivateKey methods can then be used on the Axis guard.
Your client will need a number of additional jars in order to operate the security handlers.