CICS® Transaction Gateway Programming Reference v1.1.0.0

com.ibm.ctg.security
Interface ClientSecurity


public interface ClientSecurity

All implementations of CICS Transaction Gateway client-side security classes must implement the ClientSecurity interface.

The ClientSecurity interface and partner ServerSecurity interface define a simple yet flexible model for providing security when using the CICS Transaction Gateway. Implementations of the interfaces can be as simple or as robust as deemed necessary; from simple XOR scrambling to use of Java Cryptographic toolkits.

An individual JavaGateway instance has an instance of a ClientSecurity class associated with it, until the JavaGateway is closed. Similarly, within the CICS Transaction Gateway, an instance of the partner ServerSecurity class is associated with the connected Java-client, until the connection is closed.

The basic model consists of :

- An initial handshake to exchange pertinent information. For example, this handshake could involve the exchange of public keys. However, since at the interface level the flow consists of a simple byte-array, an implementation has complete control over the contents of its handshake flows.

- The relevant ClientSecurity instance being called to encode outbound requests, and decode inbound replies.

- In the CICS Transaction Gateway, the partner ServerSecurity instance being called to decode inbound requests and to encode outbound replies.

The ClientSecurity and ServerSecurity class instances should maintain as data members sufficient information from the initial handshake to correctly encode and decode the flows.

A example implementation of the ClientSecurity interface can be found in the com.ibm.ctg.samples.security.ClientCompression class. The source for this example can be found in /samples/java/com/ibm/ctg/samples/security


Method Summary
 void afterDecode(GatewayRequest gatewayReply)
          This method is called after an in-bound reply has been decoded.
 byte[] decodeReply(byte[] encryptedReplyFlow)
          This method is called to decode a reply from the CICS Transaction Gateway, which has been encoded by its partner ServerSecurity instance's encodeReply method.
 byte[] encodeRequest(byte[] cryptRequestFlow, GatewayRequest gatewayRequest)
          This method is called to encode a request to the CICS Transaction Gateway.
 byte[] generateHandshake(java.net.InetAddress ipClient)
          This method is called to generate the initial client-to-Gateway handshake flow.
 void repliedHandshake(byte[] serverHandshake)
          This method is called in response to the replied Gateway-to-client handshake flow, that is the handshake returned by its partner ServerSecurity instance's receiveHandshake method.
 

Method Detail

generateHandshake

byte[] generateHandshake(java.net.InetAddress ipClient)
                         throws java.io.IOException
This method is called to generate the initial client-to-Gateway handshake flow. The IP address of the Gateway is passed to enable decisions based upon the target Gateway address. The method should return a byte array containing the handshake that it wishes to pass to its partner ServerSecurity instance's receiveHandshake method. This method is called when a JavaGateway instance is opened. The JavaGateway will faithfully flow the handshake data to the Gateway.

Parameters:
ipClient - the IP address of the Gateway being connected to
Returns:
byte array containing the client-to-Gateway handshake data
Throws:
java.io.IOException - if an error occurs whilst generating the handshake

repliedHandshake

void repliedHandshake(byte[] serverHandshake)
                      throws java.io.IOException
This method is called in response to the replied Gateway-to-client handshake flow, that is the handshake returned by its partner ServerSecurity instance's receiveHandshake method. The method should store any information received in the handshake for use later.

Parameters:
serverHandshake - byte array containing the replied Gateway-to-client handshake data
Throws:
java.io.IOException - if an error occurs whilst interpreting the replied handshake

encodeRequest

byte[] encodeRequest(byte[] cryptRequestFlow,
                     GatewayRequest gatewayRequest)
                     throws java.io.IOException
This method is called to encode a request to the CICS Transaction Gateway.

The method is passed a byte array which contains the data-flow, which represents the request, that is to be flowed across to the Gateway. Since the request data is in an indeterminate format, the method is also passed the GatewayRequest object that the request represents. It can use this GatewayRequest object to determine what action needs to be taken.

The method should encode the request flow, and return the encoded form. The encoded data need not be the same length as the original unencoded form.

Parameters:
cryptRequestFlow - non-encoded client request data.
gatewayRequest - GatewayRequest object that the request data represents.
Returns:
byte array containing encoded client request data-flow.
Throws:
java.io.IOException - if an error occurs whilst encoding the request

decodeReply

byte[] decodeReply(byte[] encryptedReplyFlow)
                   throws java.io.IOException
This method is called to decode a reply from the CICS Transaction Gateway, which has been encoded by its partner ServerSecurity instance's encodeReply method. This method is called to decode a reply sent by the CICS Transaction Gateway. The method should decode the reply flow, and return the decoded form. The decoded data need not be the same length as the original encoded form.

Parameters:
encryptedReplyFlow - encoded server reply data.
Returns:
byte array containing decoded server reply.
Throws:
java.io.IOException - if an error occurs whilst decoding the reply

afterDecode

void afterDecode(GatewayRequest gatewayReply)
This method is called after an in-bound reply has been decoded. It is passed the reply that was just receive and can alter its contents if required.

Parameters:
gatewayReply - the reply GatewayRequest object that was just decoded

©Copyright IBM Corp. 1994, 2014
Legal