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.