IPv6/VSE SSL Programming

IPv6/VSE SSL Programming

Before you start writing your application, let's look at how SSL programming works.

The SSL protocol begins with a “handshake.” During the handshake, the client authenticates the server,

the server optionally authenticates the client, and the client and server agree on how to encrypt and

decrypt information.

X.509 certificates are used by both the client and server when securing communications using System

SSL. The client must verify the server's certificate based on the certificate of the Certificate Authority (CA) that signed the certificate or based on a self-signed certificate from the server. The server must verify the client's certificate (if requested) using the certificate of the CA that signed the client's certificate. The client and the server then use the session keys and begin encrypted communications.

Using the IPv6/VSE GSK SSL API

The figure on the next page describes the basic structure of the elements needed in your System SSL source program. These elements are:

1. A socket() call to obtain a socket descriptor.
2. A gsk_initialize() call to set up the application's environment for secure communications. In most cases, this means extracting and verifying the certificate from the specified key database file to be used by the application (to eventually authenticate itself to the peer system in later processing).
3. Socket calls to activate a connection (a connect() call for a client program or bind(), listen(), and
   accept() calls for a server program).
4. A gsk_secure_soc_init() call to initiate the SSL handshake negotiation of the cryptographic
   parameters. gsk_secure_soc_init() initiates the handshaking process. The z/VSE application
   programmer does not have to write the "handshaking" function. This is a function of the SSL support. gsk_secure_soc_init() makes calls to the user supplied *skwrite() and *skread() routines.
5. A gsk_secure_soc_write() call to encrypt data and pass it to the user supplied *skwrite() routine for transmission.
6. A gsk_secure_soc_read() call to read data by calling the user supplied *skread() routine, to decrypt the data, and to return the decrypted data.
7. A gsk_secure_soc_close() call to disable System SSL support for the socket.
8. A close() call to destroy the connected sockets.
   
   
   
   

SSL Handshaking

The type of SSL handshake used determines the level of security used in the connection. 

Normally a server application uses handshake mode 1 and a client application uses handshake mode 0. This type of handshaking is normally used by a web browser connecting to a web server. The type of connection created is both secure (encrypted) and trusted (authenticated via certificates). However, often certificate authentication is not necessary if all you are interested in is a secure (encrypted) connection. In this case, the client application would use handshake mode 3.  This type of SSL connection is used by a TN3270E client connecting via SSL to an SSL proxy server. The connection is secure (encrypted) but not trusted (in the SSL sense of the word). Trust is not necessary since the user will be logging on to a host application and the host application (CICS) will authenticate the user.

Handshake	Description
GSK_AS_CLIENT: (0)	Client receives server's public key and cert. Client authenticates server's public key and cert. Client checks its local CA-cert file to authenticate. DNAME = Dummy RSA key and CA-cert for authentication *(1)
GSK_AS_SERVER: (1)	Server sends its public key and cert to client. DNAME = Public RSA key and cert *(1)
GSK_AS_SERVER_WITH_CLIENT_AUTH: (2)	Server sends its public key and cert to client. Client authenticates server's public key and cert. Client checks its local CA-cert file to authenticate. DNAME = public RSA key and cert AND CA-cert for authentication Client sends its public key and cert to server. Server authenticates client's public key and cert. Server checks its local CA-cert file to authenticate. DNAME = public RSA key and cert AND CA-cert for authentication
GSK_AS_CLIENT_NO_AUTH: (3)	Client receives server's public key and cert. Client accepts server's pubic key and cert without authentication. DNAME not used! no RSA key or cert required.

*(1) In the case of a server and client running on the same system they can use the same DNAME file (identical RSA key and cert - self-signed).

A typical web (HTTP) server is (1) and the browser is (0).

CICS TS web services with client authentication is (2).

SSL tunneling (SMTPS or TELNETS) is a (3) connecting to a (1).

IPv6/VSE provides access to secure sockets (SSL) through the LE/C, EZASMI and EZASOKET APIs. The various GSK function calls provide simple access to OpenSSL secure socket routines.

For information about calling OpenSSL routines directly please refer to the IBM OpenSSL programming manual. Directly calling OpenSSL routines is available only to C language applications.

For detailed information about the EZASMI GSK macro calls and HLL EZASOKET GSK calls, refer to the IBM z/OS System Secure Sockets Layer Programming SC24-5901-00 manual.

GSK Functions Provided

Function	Description
GSKINIT	GSK Initialize
GSKSSOCINIT	GSK Secure Socket Initialize
GSKSSOCREAD	GSK Secure Socket Read
GSKSSOCWRITE	GSK Secure Socket Write
GSKSSOCCLOSE	GSK Secure Socket Close
GSKSSOCRESET	GSK Secure Socket Reset
GSKUNINIT	GSK Uninitialize
GSKFREEMEM	GSK Free Memory
GSKGETCIPHINF	GSK Get Cypher Information
GSKGETDNBYLAB	GSK Get DName By Label

Basic Design

Non-SSL Simple Server	Non-SSL Client
EZASMI TYPE=INITAPI EZASMI TYPE=SOCKET EZASMI TYPE=BIND ACPT EZASMI TYPE=ACCEPT READ EZASMI TYPE=READ EZASMI TYPE=WRITE B READ EOD EZASMI TYPE=CLOSE (Accept socket) B ACPT EOJ EZASMI TYPE=CLOSE (Listen socket) EZASMI TYPE=TERMAPI EOJ	EZASMI TYPE=INITAPI EZASMI TYPE=SOCKET EZASMI TYPE=CONNECT EZASMI TYPE=WRITE EZASMI TYPE=READ EZASMI TYPE=CLOSE EZASMI TYPE=TERMAPI EOJ
SSL Simple Server	SSL Simple Client
EZASMI TYPE=INITAPI EZASMI TYPE=GSKINIT EZASMI TYPE=SOCKET EZASMI TYPE=BIND ACPT EZASMI TYPE=ACCEPT EZASMI TYPE=GSKSSOCOPEN READ EZASMI TYPE=GSKSSOCREAD EZASMI TYPE=GSKSSOCWRITE B READ EOD EZASMI TYPE=GSKSSOCCLOSE EZASMI TYPE=CLOSE (Accept socket) B ACPT EOJ EZASMI TYPE=CLOSE (Listen socket) EZASMI TYPE=GSKUNINIT EZASMI TYPE=TERMAPI EOJ	EZASMI TYPE=INITAPI EZASMI TYPE=GSKINIT EZASMI TYPE=SOCKET EZASMI TYPE=CONNECT EZASMI TYPE=GSKSSOCOPEN EZASMI TYPE=GSKSSOCWRITE EZASMI TYPE=GSKSSOCREAD EZASMI TYPE=GSKSSOCCLOSE EZASMI TYPE=CLOSE EZASMI TYPE=GSKUNINIT EZASMI TYPE=TERMAPI EOJ

See the IPv6/VSE SSL Installation, Programming and User's Guide for full details on the SSL GSK API.

Using the BSI SSL Proxy Server

BSTTPRXY SSL Proxy Server

The BSTTPRXY SSL proxy server allows non-SSL server applications running in z/VSE to accept connections from SSL based client applications. Or, BSTTPRXY will allow non-SSL client applications to connect to SSL based server applications.

The BSTTPRXY SSL proxy server will also proxy IPv4 connections to an IPv6 destination or IPv6 connections to an IPv4 destination.

Proxy Types

Source	Destination
Accept clear text connection	Proxy to clear text connection
Accept SSL connection	Proxy to SSL connection
Accept clear text connection	Proxy to SSL connection
Accept SSL connection	Proxy to clear text connection
Accept IPv4 or IPv6 connection	Proxy to IPv4 or IPv6 connection

Proxy Examples

Accept a clear text connection from BSTTMTPC on port 25 and proxy the connection to an SMTP server listening on SSL port 465. This type of connection is commonly called smtps.

Accept an SSL connection on port 443 and proxy the connection to CICS TS Web Services on clear text port 80. This type of connections commonly called https.

Accept an SSL connection on port 992 and proxy the connection to the BSTTVNET TN3270E server on clear text port 23. This type of connection is commonly called telnets.

Accept a clear text connection from BSTTFTPC on port 21 and proxy the connection to an FTP server listening on SSL port 990. This type of connection is commonly called ftps.

Accept an SSL connection on port 990 and proxy the connection to the BSTTFTPS FTP server on clear text port 21. This type of connection is commonly called ftps.

BSTTPRXY Examples

BSTTVNET TN3270E Server

x3270
x3270 is an IBM 3270 terminal emulator for the X Window System and Windows. It runs on most Unix-like operating systems -- e.g., Linux, Mac OS X, Solaris and Cygwin. It also runs natively on Windows.
X3270 is distributed as source code, and can be used for free. See http://x3270.bgp.nu

x3270 runs over a TELNET connection, emulating either an IBM 3279 (color) or 3278 (monochrome). It supports:

• The full TN3270E protocol
• SSL/TLS (via the OpenSSL library) for encrypted sessions
• APL2 characters
• Non-English character sets, including Hebrew and DBCS Chinese and Japanese
• IND$FILE file transfer
• NVT mode (emulating a color xterm)
• A pop-up keypad for 3270-specific keys
• A scrollbar
• Printer session integration
• Extensive debugging and scripting facilities

Command format: X3270 [prefix:]...[LUname@]hostname[:port] E.g., x3270 L:192.168.1.238:992

Prepending an L: onto hostname causes x3270 to first create an SSL tunnel to the host, and then create a TN3270 session inside the tunnel.

// OPTION SYSPARM='66' // SETPARM IPTRACE='NNNNNNN' // LIBDEF *,SEARCH=(ssllib.slib,bsilib.slib) // EXEC BSTTPRXY,SIZE=BSTTPRXY ID 66 KEYRING PRD2.CONFIG DNAME BSICERT SECTYPE TLSV1 OPTION SERVER PROXY TCP V4 992 SSL * TO V4 23 TXT * LOCALHOST /*

The above example executes the BSTTPRXY SSL proxy server in SERVER mode, accepting SSL connections on port 992 (implicit telnets) and proxies the connection in clear text to port 23. Port 23 is being used by BSTTVNET to accept connections to the TN3270E server.

The KEYRING parameter indicates the RSA key and certificate to be used by the BSTTPRXY server is located in PRD2.CONFIG and the DNAME parameter indicates BSICERT.PEM is the member name.

BSTTMTPC Mail Transport Client

The following sample JCL shows BSTTMTPC connecting to the BSTTPRXY server on port 25 (SMTP) and sending an email.

// EXEC BSTTMTPC,SIZE=BSTTMTPC ID 00 OPEN 127.0.0.1 25 * EHLO gmail.com AUTH LOGIN jeffrey.webmail ???????? MAIL From: RCPT To: SUBJ Subject: Test Email ORGA Organization: Barnard Software, Inc. * DATA * QUIT /* This is a test email text. See http://www.bsiopti.com Jeff /*

The following sample BSTTPRXY JCL shows the proxy server accepting connections on port 25 (SMTP) and proxying the connection to smtp.gmail.com port 465. This configuration uses SMTPS or SMTP through an SSL tunnel. Note: The KEYFILE parameter must specify an RSA key/certificate member with a valid RSA key and certificate. However, the certificate is not used.

// EXEC BSTTPRXY,SIZE=BSTTPRXY,PARM='TRAP(OFF)/' ID 00 * KEYRING PRD2.CONFIG KEYFILE ZVSE51 SECTYPE TLSV1 * OPTION CLIENT * 74.125.157.108 IS SMTP.GMAIL.COM PROXY TCP V4 25 TXT * TO V4 465 SSL * 74.125.157.108 /*

CICS TS Web Interface

The following sample BSTTPRXY JCL shows the proxy server accepting connections on port 443 (HTTPS) and proxying the connection to the CICS TS Web Server on port 8080.

// EXEC BSTTPRXY,SIZE=BSTTPRXY,PARM='TRAP(OFF)/' ID 00 * KEYRING PRD2.CONFIG KEYFILE CICSTS SECTYPE TLSV1 * OPTION SERVER * PROXY TCP V4 443 SSL * TO V4 8080 TXT * 127.0.0.1 /*

BSTTFTPC Batch FTP Client

The following sample JCL shows BSTTFTPC connecting to the BSTTPRXY server on port 2121 (FTP) and sending commands to a remote host FTP server on port 990(FTPS). BSTTPRXY supports Implicit-FTPS where the command connection is automatically encrypted using TLS.

// EXEC BSTTFTPC,SIZE=BSTTFTPC,OS390,TASKS=ANY ID 00 OPEN 127.0.0.1 2121 PBSZ 0 PROT P USER jcb PASS bsi PWD STAT QUIT /*

The BSTTFTPC JCL/commands looks pretty typical but notice the PBSZ 0 and PROT P commands that immediately follow the OPEN command. These two commands, exactly as shown, must immediately follow the OPEN command. When using an Implicit-FTPS connection the command connection is automatically encrypted. The PBSZ 0 and PROT P commands tell the remote host FTP server that any data transfer done should also be encrypted. If these two commands are missing any data transfer will be done in clear text mode.


The following sample BSTTPRXY JCL shows the proxy server accepting connections on port 2121 (FTP) and proxying the connection to 192.168.1.60 port 990. This configuration uses FTPS or FTP through an implicit SSL tunnel. Note: The KEYFILE parameter must specify an RSA key/certificate member with a valid RSA key and certificate. Port mapping, for the FTP data connection, is handled automatically by BSTTPRXY.

// EXEC BSTTPRXY,SIZE=BSTTPRXY,PARM='TRAP(OFF)/' ID 00 * KEYRING PRD2.CONFIG KEYFILE BSICERT SECTYPE TLSV1 * OPTION FTP OPTION CLIENT * PROXY TCP V4 2121 TXT * TO V4 990 SSL * 192.168.1.60 /*

BSTTFTPS FTP Server

The following sample BSTTPRXY JCL shows the proxy server accepting connections on port 990 (Implicit-FTPS) and proxying the connection to 192.168.1.60 port 21 (FTP). This configuration uses FTPS or FTP through an implicit SSL tunnel. Note: The KEYFILE parameter must specify an RSA key/certificate member with a valid RSA key and certificate. Port mapping, for the FTP data connection, is handled automatically by BSTTPRXY.

// EXEC BSTTPRXY,SIZE=BSTTPRXY,PARM='TRAP(OFF)/' ID 00 * KEYRING PRD2.CONFIG KEYFILE BSICERT SECTYPE TLSV1 * OPTION SERVER * PROXY TCP V4 990 SSL * TO V4 21 TXT * 127.0.0.1 /*

This example assumes you also are running the BSTTFTPS FTP server listening on port 21.
To test this function of BSTTPRXY we used the Linux LFTP FTP client. The LFTP client connected to BSTTPRXY using the 'lftp -d -u userid,password -p 990 ftps://192.168.1.238' command. The LFTP client connected to the BSTTPRXY server using an SSL connection on port 990. BSTTPRXY then proxied the connection to the BSTTFTPS FTP server on port 21.

The IPv6/VSE SSL proxy server is simple and easy to use. In addition to the examples shown in this post, many other types of connections can be proxied including MQSeries, DB2 UDB connections, etc.