CICS® Transaction Gateway Programming Reference V3.1

com.ibm.ctg.security
Interface SystemSSLServerSecurity


public abstract interface SystemSSLServerSecurity
extends ServerSecurity

All implementations of CICS Transaction Gateway server-side security classes which require the exposure of SSL Client Certificates and use the System SSL protocol handlers (ssl: and https:) must implement the SystemSSLServerSecurity interface.

Note: Users of the pure Java SSL (SSLight) protocol handlers should implement the SSLightServerSecurity interface.

The SystemSSLServerSecurity interface and partner ClientSecurity 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 the Java Cryptographic toolkits.

The SystemSSLServerSecurity interface has been designed to work in conjunction with the Secure Sockets Layer (SSL) protocol. This interface will allow server-side security objects access to a Client Certificate passed during the initial SSL handshake. The exposure of the Client Certificate is dependant upon the necessary configuration of the CICS Transaction Gateway to support Client Authentication.

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 SystemSSLServerSecurity 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 SystemSSLServerSecurity instance being called to decode inbound requests and to encode outbound replies. The inbound request, and Client Certificate, is exposed via the afterDecode() method.

The ClientSecurity and SystemSSLServerSecurity 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 SystemSSLServerSecurity interface can be found in SystemSSLServerCompression.java. The source for this example can be found in \samples\java\com\ibm\ctg\security


Method Summary
 void afterDecode(GatewayRequest gatewayRequest, SSLCertificate clientCertificate)
          This method is called after an in-bound request has been decoded.
 byte[] decodeRequest(byte[] encryptedRequestFlow)
          This method is called to decode a client request, which has been encoded by its partner ClientSecurity instance's encodeRequest method.
 byte[] encodeReply(byte[] cryptReplyFlow, GatewayRequest gatewayRequest)
          This method is called to encode a reply to the client program.
 byte[] receiveHandshake(byte[] clientHandshake, java.net.InetAddress ipClient)
          This method is called in response to the initial client-to-Gateway handshake flow, that is the handshake returned by its partner ClientSecurity instance's generateHandshake method.
 
Methods inherited from interface com.ibm.ctg.security.ServerSecurity
afterDecode
 

Method Detail

receiveHandshake

public byte[] receiveHandshake(byte[] clientHandshake,
                               java.net.InetAddress ipClient)
                        throws java.io.IOException
This method is called in response to the initial client-to-Gateway handshake flow, that is the handshake returned by its partner ClientSecurity instance's generateHandshake method. The method should store any information received in the handshake for use later.

This method should then generate the return Gateway-to-client handshake flow. The method should return a byte array containing the handshake that it wishes to pass to its partner ClientSecurity instance's repliedHandshake method.

This method is passed the IP address of the client machine that it is handshaking with. It can make decisions based on this address and if it does not wish to allow a connection based upon the address, it should throw an appropriate IOException.

Specified by:
receiveHandshake in interface ServerSecurity
Parameters:
clientHandshake - byte array containing the client-to-Gateway handshake data
ipClient - - IP address of the client machine the handshake is for
Returns:
byte array containing the replied Gateway-to-client handshake data
Throws:
java.io.IOException - if an error occurs whilst interpreting the received handshake or when generating the reply handshake data

decodeRequest

public byte[] decodeRequest(byte[] encryptedRequestFlow)
                     throws java.io.IOException
This method is called to decode a client request, which has been encoded by its partner ClientSecurity instance's encodeRequest method. The method should decode the request flow, and return the decoded form. The decoded data need not be the same length as the original encoded form.
Specified by:
decodeRequest in interface ServerSecurity
Parameters:
encryptedRequestFlow - encoded client request data.
Returns:
byte array containing decoded client request.
Throws:
java.io.IOException - if an error occurs whilst decoding the request

encodeReply

public byte[] encodeReply(byte[] cryptReplyFlow,
                          GatewayRequest gatewayRequest)
                   throws java.io.IOException
This method is called to encode a reply to the client program.

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

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

Specified by:
encodeReply in interface ServerSecurity
Parameters:
cryptReplyFlow - non-encoded server reply data.
gatewayRequest - GatewayRequest object that the reply data represents.
Returns:
byte array containing encoded server reply data-flow.
Throws:
java.io.IOException - if an error occurs whilst encoding the reply

afterDecode

public void afterDecode(GatewayRequest gatewayRequest,
                        SSLCertificate clientCertificate)
                 throws java.io.IOException
This method is called after an in-bound request has been decoded. It is passed the request that was just receive and can alter its contents if required. If Client Authentication is supported on the connection, the Client Certificate will also be exposed in this exit. For example, userid and password information could be added to a request at this point, based off information exchanged in the handshake.
Parameters:
gatewayRequest - - the request GatewayRequest object that was just decoded
clientCertificate - - client certificate passed on the initial SSL handshake
Throws:
java.io.IOException - *can* be thrown if the Client Certificate is invalid or unacceptable

© Copyright IBM Corp. 1994, 1999