Sun Mainframe Transaction Processing Software Developer's Guide

Client applications can communicate with Sun MTP regions using TCP/IP sockets or SSL (secure socket layer) sockets. Each has its own server process.

The Sun MTP socket server, unikixsock, listens on a pre-defined TCP port for incoming requests. When a request comes in, a socket connection is established, and the request is forwarded to a transaction server where it is serviced. The SSL server, unikixssl, operates in much the same way, except that before a request is forwarded to the transaction server, an exchange of certificates must occur. This is referred to as an SSL handshake. If the handshake is successful, an encrypted socket connection is established.

This chapter contains the following topics:

• TCP/IP Sockets
• Secure Socket Layer

---

TCP/IP Sockets

This section describes how the unikixsock server process works, and how to send and receive messages.

unikixsock Server Process

The unikixsock server process works as follows:

1. When a port number is specified on the unikixmain command line with the -p option, unikixmain starts the unikixsock server process, which binds to the specified port number and issues a listen call for that port. For information about unikixmain, refer to the Sun Mainframe Transaction Processing Software Reference Guide.

2. When a socket client program connects to the unikixsock process, it passes in an initial block of data that conforms to the standard IBM format described in Sending Messages.

3. unikixsock passes the client socket to a transaction server for processing.

4. The transaction server calls the socket user exit, which reads the socket message from the client. If the message conforms to the standard IBM format, the unmodified user exit parses it successfully. If the message is in a non-standard format, the user exit must be customized to parse the message. Refer to the Sun Mainframe Transaction Processing Software Administrator's Guide for information about customizing the socket user exit.

5. After the message is received and parsed, the transaction server starts the requested transaction and passes to it in the COMMAREA, the client socket file descriptor and any user data received.

At this point, the socket client program waits for data from the transaction program, which ensures that the transaction has started successfully. From this point on, the transaction program and the socket client program can exchange data using the socket connection. The transaction program uses the standard UNIX socket library calls. Because these are C language calls, the transaction program must use COBOL CALL statements. See the SOCK00.cl2 program in the $UNIKIX/src/socket directory for examples.

1. Set up the listener function.

Refer to the Sun Mainframe Transaction Processing Software Configuration Guide for information about setting up the TCP/IP socket listener function.

2. Compile the transaction program.

See the example program in $UNIKIX/src/socket/SOCK00.cl2.

3. Make entries for the program in the PCT and PPT.

4. Compile and execute the socket client program.

See the example program $UNIKIX/src/socket/sock00.c.

5. From a socket client program, send messages through the socket connection.

The following sections describe the procedures for sending and receiving messages over the socket connection.

Sending Messages

The listening process requires the remote user application to send the first transmission in a prescribed format. After the first transmission, the user waits for a response before sending any subsequent transmissions.

The default (IBM standard) input format for the first transmission is:

TRANID[,User-Data][,XX [,HHMMSS]]

where:

The example shown in CODE EXAMPLE 11-1 builds the initial message. It is located in $UNIKIX/src/socket/sock00.c . For this code to execute without error, you must configure the SOCK transaction in the region.

char ibuffer[4+1+35]; /* transid            4 bytes

                                    ','     1 byte

                                    data    35 bytes */

/* build the initial socket message */

memset(ibuffer, 0, sizeof(ibuffer));

memcpy(ibuffer,   trans,  4);

memcpy(ibuffer+4, ",",    1);

memcpy(ibuffer+5, data,  35);

/* send initial message to invoke the transaction */

if (send(fd, ibuffer, sizeof(ibuffer), 0) <= 0) {

	printf("sock00:send error %d\n", errno);

	exit(EXIT_FAILURE);

}

Receiving Messages

The COMMAREA must be defined in the transaction program as illustrated in the following example. The code in the following example is from the sample program $UNIKIX/src/socket/SOCK00.cl2.

linkage section.

01  DFHCOMMAREA.

	05 GIVE-TAKE-SOCKET      PIC 9(8) COMP.

	05 LSTN-NAME             PIC X(8).

	05 LSTN-SUBNAME          PIC X(8).

	05 CLIENT-IN-DATA        PIC X(36).

	05 SOCKADDR-IN-PARM.

		15 SIN-FAMILY        PIC 9(4) COMP.

		15 SIN-PORT          PIC 9(4) COMP.

		15 SIN-ADDRESS       PIC 9(8) COMP.

		15 SIN-ZERO          PIC X(8).

The sample program also includes code for receiving a message, displaying data, and sending a message. CODE EXAMPLE 11-3 shows the code in SOCK00.cl2 for receiving a message.

After the output area is loaded, the transaction identified in the message is executed. The user application can then display the incoming data, CLIENT-IN-DATA, without making a RECEIVE call.

working-storage section.

	*

	* program buffers

	*

	77 ws-recv-msg-size           pic s9(8) comp value 4096.

	77 ws-recv-buf                pic x(4096).

	77 ws-recv-total              pic s9(8) comp value 0.

	77 ws-recv-left               pic s9(8) comp value 0.

	77 ws-flags                   pic s9(8) comp value 0. 

...

	*

	* set up the receive buffer

	*

			move low-values to ws-recv-buf.

			set ws-recv-total to zero.

			compute ws-recv-left = ws-recv-msg-size.

	*

	* receive data

	*

	recv-1.

			call "recv" using by value GIVE-TAKE-SOCKET,

				by reference ws-recv-buf(1+ws-recv-total:ws-recv-left),

				by value ws-recv-left,

				by value ws-flags.

	*

	* test what was received and decide what we should do

	*

			if return-code < zero

				display 'SOCK00:recv error ',

				go to socket-error.

			if return-code = zero

				display 'SOCK00:client disconnected',

				go to socket-error.

	*

	* have we received all the data yet?

	*

			compute ws-recv-total = ws-recv-total + return-code.

			compute ws-recv-left = ws-recv-msg-size - ws-recv-total.

	*

	* not yet

	*

			if ws-recv-left > 0 go to recv-1.

	*

	* received all the data

	*

			display 'SOCK00:receive buffer   =', ws-recv-buf(1:50).

---

Secure Socket Layer

The secure socket layer (SSL) enables applications to use sockets for authenticated, tamper-proof, and encrypted communications. It was designed for exchanging secure information over an insecure network such as the Internet. It permits an SSL-enabled server to authenticate itself to an SSL-enabled client, the client to authenticate itself to the server, and both sides to establish an encrypted connection.

SSL server authentication enables a client to confirm a server's identity. SSL-enabled client software can use standard techniques of public-key cryptography to check that a server's certificate is valid and has been issued by a Certificate Authority (CA) listed in the client's list of trusted CAs. This confirmation might be important if the user, for example, is sending a credit card number over the network and wants to check the receiving server's identity.

SSL client authentication enables a server to confirm a client's identity. Using the same techniques as those used for server authentication, SSL-enabled server software can check that a client's certificate is valid and has been issued by a Certificate Authority (CA) listed in the server's list of trusted CAs. This confirmation might be important if the server, for example, is a bank sending confidential financial information to a customer and wants to check the recipient's identity.

An encrypted SSL connection requires all information sent between a client and a server to be encrypted by the sending software and decrypted by the receiving software, thus providing a high degree of confidentiality. Confidentiality is important for both parties in any private transaction. In addition, all data sent over an encrypted SSL connection is protected with a mechanism for detecting tampering --that is, for automatically determining whether the data has been altered in transit.

unikixssl Server Process

Client applications can communicate with a remote Sun MTP region using SSL. The SSL server process, unikixssl, listens on a pre-defined port for incoming requests. Before a request is forwarded to the transaction server to be serviced, an SSL handshake occurs. The handshake enables the client and server to validate each other and negotiate an encryption technique. If the handshake is successful, the request is forwarded to the transaction server. All data that flows between the client and server is encrypted using the encryption technique negotiated during the handshake.

The unikixssl server process works as follows:

1. When a port number is specified on the unikixmain command line with the -p option, unikixmain starts the unikixsock server process, which binds to the specified port number and issues a listen call for that port. For information about unikixmain, refer to the Sun Mainframe Transaction Processing Software Reference Guide. The unikixssl process uses unikixsock to establish a connection to a transaction server.

2. unikixssl is controlled by entries in the unikixrc.cfg file. Set SslServer*Active to True to start the unikixssl process. SslServer*Port specifies the port on which unikixssl listens for client connections. SslServer*Sockport specifies the unikixsock listen port.

3. When an SSL client program connects to unikixssl, an SSL handshake occurs. The client program authenticates the unikixssl certificate, unikixssl authenticates the client certificate, and an encryption technique is negotiated. If the handshake is successful, unikixssl passes the client socket to a transaction server for processing.

4. The transaction server calls the socket user exit, which reads the socket message from the client. If the message conforms to the standard IBM format, the unmodified user exit parses it successfully. If the message is in a non-standard format, the user exit must be customized to parse the message. Refer to the Sun Mainframe Transaction Processing Software Administrator's Guide for information about customizing the socket user exit.

5. After the message is received and parsed, the transaction server starts the requested transaction and passes to it in the COMMAREA, the client socket file descriptor and any user data received.

At this point, the SSL client program waits for data from the transaction program, which ensures that the transaction has started successfully. From this point on, the transaction program and the SSL client program can exchange data using the socket connection. The transaction program uses the standard UNIX socket library calls. Because these are C language calls, the transaction program must use COBOL CALL statements. See the SSLSOCK0.cl2 program in the $UNIKIX/src/socket directory for examples. For a complete description of this example, refer to the $UNIKIX/src/socket/README.ssl file.

Sending Messages

unikixssl requires that the client program send the first message in a prescribed format. After the first transmission, the client program waits for a response before sending any subsequent transmissions.

The input format for the first transmission is:

TRANID[,User-Data][,XX [,HHMMSS]]

where:

CODE EXAMPLE 11-4 shows the code in $UNIKIX/src/socket/sslsock00.c that builds the initial message. For this code to execute without error, you must configure the SSL0 transaction in the region. Refer to the $UNIKIX/src/socket/README.ssl file for instructions on configuring the SSL0 transaction.

char ibuffer[4+1+35]; /* transid               4 bytes

                                    ','        1 byte

                                    data       35 bytes */   

/* build initial socket message */

memset(ibuffer, 0, sizeof(ibuffer));

memcpy(ibuffer,   trans,  4);

memcpy(ibuffer+4, ",",    1);

memcpy(ibuffer+5, data,  35);

/* Initial send to invoke transaction */

if (PR_Write(sock, ibuffer, sizeof(ibuffer)) <= 0) {

       exitErr("PR_Write");

}

Receiving Messages

The output area must be defined in the transaction program as illustrated in the following example. This code is from the sample program $UNIKIX/src/socket/SSLSOCK0.cl2.

01  DFHCOMMAREA.

	05 GIVE-TAKE-SOCKET       PIC 9(8) COMP.

	05 LSTN-NAME              PIC X(8).

	05 LSTN-SUBNAME           PIC X(8).

	05 CLIENT-IN-DATA         PIC X(36).

	05 SOCKADDR-IN-PARM.

	    15 SIN-FAMILY         PIC 9(4) COMP.

	    15 SIN-PORT           PIC 9(4) COMP.

	    15 SIN-ADDRESS        PIC 9(8) COMP.

	    15 SIN-ZERO           PIC X(8). 

The initial client data is passed in CLIENT-IN-DATA. The sample program also includes code for receiving a message, displaying data, and sending a message. The following example shows the code in SSLSOCK0.cl2 for receiving a message.

working-storage section.

	*

	* program buffers

	*

	77 ws-recv-msg-size           pic s9(8) comp value 4096.

	77 ws-recv-buf                pic x(4096).

	77 ws-recv-total              pic s9(8) comp value 0.

	77 ws-recv-left               pic s9(8) comp value 0.

	77 ws-flags                   pic s9(8) comp value 0. 

...

	*

	* set up the receive buffer

	*

			move low-values to ws-recv-buf.

			set ws-recv-total to zero.

			compute ws-recv-left = ws-recv-msg-size.

	*

	* receive data

	*

	recv-1.

			call "recv" using by value GIVE-TAKE-SOCKET,

				by reference ws-recv-buf(1+ws-recv-total:ws-recv-left),

				by value ws-recv-left,

				by value ws-flags.

	*

	* test what was received and decide what we should do

	*

			if return-code < zero

				display 'SSLSOCK0:recv error ',

				go to socket-error.

			if return-code = zero

				display 'SSLSOCK0:client disconnected',

				go to socket-error.

	*

	* have we received all the data yet?

	*

			compute ws-recv-total = ws-recv-total + return-code.

			compute ws-recv-left = ws-recv-msg-size - ws-recv-total.

	*

	* not yet

	*

			if ws-recv-left > 0 go to recv-1.

	*

	* received all the data

	*

			display 'SSLSOCK0:receive buffer   =', ws-recv-buf(1:50).

Client certificate information can be obtained using the EXEC CICS EXTRACT CERTIFICATE API call. See EXTRACT CERTIFICATE.

SSL User Exit

The SSL client certificate verification user exit resides in the shared library $UNIKIX/lib/libkxsslxit.so. This user exit enables you to write code that rejects a client certificate based, for example, on your own certificate revocation check.

Refer to the Sun Mainframe Transaction Processing Software Administrator's Guide for instructions on customizing the SSL user exit.

Server Certificate Common Name Issues

During the handshake, SSL clients check to make sure that the common name (CN) of the server certificate matches the host name that the client is using to connect to the server. This must be a textual match. If there is not a match, the client will reject the server certificate with the error:

-12276 SSL_ERROR_BAD_CERT_DOMAIN

For example, a unikixssl server is running on a host named saturn, whose IP address is 123.45.67.89. The server certificate's common name could be saturn or saturn's IP address. When a client connects to the unikixssl server, it should use the host name or the IP address, whichever matches the server certificate's common name. If a client uses saturn's IP address when the certificate's common name is saturn, a connection will be made but the handshake will fail, because the IP address is not a textual match with the server certificate's common name.

Sun Mainframe Transaction Processing Software Developer's Guide

816-5329-11

Copyright © 2004, Sun Microsystems, Inc. All rights reserved.