Secure Sockets Layer (SSL) APIs

The Secure Sockets Layer (SSL) is a popular set of security protocols that were originally developed by Netscape Communications Corporation. SSL provides communications privacy over an open communications network (that is, the Internet). The protocol allows client/server applications to communicate in a way that is designed to prevent eavesdropping, tampering, and message forgery. The SSL protocol connection security has three basic properties:

• The connection is private. Encryption is used after an initial handshake to define a secret key. (A handshake is a series of protocol packets sent in a particular sequence that will establish an SSL session.) Symmetric cryptography is used for data encryption.

• The peer's identity can be authenticated using asymmetric, or public key cryptography.

• The connection is reliable. Message transport includes a message integrity check using a keyed Message Authentication Code (MAC). Secure hash functions are used for MAC computations.

The SSL protocol is a layered protocol that is intended to be used on top of some reliable transport (for example, Transmission Control Protocol (TCP)) to provide secure communications for an application (for example, HTTPs, sFTP, sSMTP, and so forth).

An SSL-enabled application usually needs to use a different port than an application that is not SSL-enabled. For example, an SSL-enabled Hypertext Transfer Protocol (HTTP) server is accessed from an SSL-enabled browser by using a Universal Resource Locator (URL) that begins with https rather than http. By default, a URL of https will attempt to open a connection, in most cases, to port 443 of the server system instead of to port 80 used by the standard HTTP server that is not SSL-enabled.

There are multiple versions of the SSL protocol defined. The OS/400 implementation supports SSL Version 3.0, SSL Version 2.0, and SSL Version 3.0 with 2.0 compatibility.

All customers planning to use the SSL APIs to create SSL-enabled applications must first obtain and install either the Cryptographic Access Provider 40-Bit (5769AC1), Cryptographic Access Provider 56-Bit (5769AC2), or Cryptographic Access Provider 128-Bit (5769AC3) licensed products. The 5769AC1, 5769AC2, or 5769AC3 product must be installed on all AS/400s that call an SSL-enabled application and on all AS/400s that will be used to develop the SSL-enabled applications.

When creating ILE programs or service programs that use the OS/400 SSL APIs, you do not need to explicitly bind to the SSL service program, QSYS/QSOSSLSR, because it is part of the system binding directory.

The SSL API documentation only describes the SSL APIs. The SSL API documentation does not include any information about how to configure or obtain any of the cryptographic objects, such as a key ring file or certificate, that are required in order to use the SSL APIs. Some cryptographic objects, such as key ring files, are required parameters for SSL APIs. Information on how to configure the cryptographic objects required for the OS/400 SSL APIs, or how to configure a secure web server, which also uses the SSL APIs, can be found using the following references:

• HTTP Server for AS/400 Webmaster's Guide book, GC41-5434
• Web Programming Guide available from URL:

  http://www.ics.raleigh.ibm.com
  

• HTTP Server for AS/400 Quick Beginnings book, GC41-5433
• TCP/IP Configuration and Reference book, SC41-5420
• See the following URL for information related to securely configuring the HTTP server:

  
  http://www.as400.ibm.com/tstudio/workshop/webbuild.htm
  

  Note: You might need to register at the http://www.as400.ibm.com page before being allowed access to the above URL.

OS/400 SSL APIs, when used in addition to the existing OS/400 Sockets APIs, provide the functions required for applications to establish secure communications. An application using SSL for secure communications will basically be a client/server application written using sockets.

An application that uses SSL will contain the following elements:

• A socket() call to obtain a socket descriptor.

• An SSL_Init() call to initialize the job environment for SSL processing. An SSL_Init() must be performed at least once in a job.

• An SSL_Init_Application() call to establish the SSL security information for all SSL sessions for the current job.

• Socket calls to activate a connection (a connect() call for a client program or bind(), listen(), and accept() calls for a server program).

• An SSL_Create() call to enable SSL support for the connected socket.

• An SSL_Handshake() call to initiate the SSL handshake negotiation of the cryptographic parameters.

  Note: A server program and also a client program, which is communicating with a server requiring client authentication, must provide a certificate for a successful SSL handshake. A server must also provide the private key associated with its certificate or key ring file. The SSL_Init() call is used to identify the key ring file from which the certificate and private key are obtained for all SSL sessions established for a job.

• SSL_Write() and SSL_Read() calls to send and receive data.

• An SSL_Destroy() call to disable SSL support for the socket.

• A close() call to destroy the connected sockets.

Secure Sockets Layer (SSL) APIs--Summary

Figure 1-1 lists the Secure Sockets Layer functions and what they do.

Figure 1-1. Secure Sockets Layer Functions

Function	Description
SSL_Create()	Enable SSL support for the specified socket descriptor
SSL_Destroy()	End SSL support for the specified SSL session
SSL_Handshake()	Initiate the SSL handshake protocol
SSL_Init()	Initialize the current job for SSL
SSL_Inita()	Establish the SSL security information
SSL_Read()	Receive data from an SSL-enabled socket descriptor
SSL_Write()	Write data to an SSL-enabled socket descriptor

Note: These functions use header (include) files from the library QSYSINC, which is optionally installable. Make sure QSYSINC is installed on your system before using any of the functions. See Header Files for UNIX-Type Functions for the file and member name of each header file.