Global Secure ToolKit (GSKit) APIs

Global Secure ToolKit (GSKit) is a set of programmable interfaces that allow an application to be SSL enabled.

Just like the SSL_ APIs, the GSKit APIs allow you to implement the SSL and TLS protocols in your socket application program. However, GSKit APIs are supported across IBM^® eServer™ platforms and are easier to program than SSL_ APIs. In addition, new GSKit APIs have been added to provide asynchronous capabilities for negotiating a secure session, sending secure data, and receiving secure data. These asynchronous APIs exist only in i5/OS™ and cannot be ported to other eServer platforms.

Note: The GSKit APIs only support sockets with an address family of AF_INET or AF_INET6 and type SOCK_STREAM.

The following table describes the GSKit APIs:

Table 1. Global secure toolkit APIs
Function	Description
gsk_attribute_get_buffer()	Obtains specific character string information about a secure session or an SSL environment, such as certificate store file, certificate store password, application ID, and ciphers.
gsk_attribute_get_cert_info()	Obtains specific information about either the server or client certificate for a secure session or an SSL environment.
gsk_attribute_get_enum_value()	Obtains values for specific enumerated data for a secure session or an SSL environment.
gsk_attribute_get_numeric_value()	Obtains specific numeric information about a secure session or an SSL environment.
gsk_attribute_set_callback()	Sets callback pointers to routines in the user application. The application can then use these routines for special purposes.
gsk_attribute_set_buffer()	Sets a specified buffer attribute to a value inside the specified secure session or an SSL environment.
gsk_attribute_set_enum()	Sets a specified enumerated type attribute to an enumerated value in the secure session or SSL environment.
gsk_attribute_set_numeric_value()	Sets specific numeric information for a secure session or an SSL environment.
gsk_environment_close()	Closes the SSL environment and releases all storage associated with the environment.
gsk_environment_init()	Initializes the SSL environment after any required attributes are set.
gsk_environment_open()	Returns an SSL environment handle that must be saved and used on subsequent gsk calls.
gsk_secure_soc_close()	Closes a secure session and free all the associated resources for that secure session.
gsk_secure_soc_init()	Negotiates a secure session, using the attributes set for the SSL environment and the secure session.
gsk_secure_soc_misc()	Performs miscellaneous functions for a secure session.
gsk_secure_soc_open()	Obtains storage for a secure session, sets default values for attributes, and returns a handle that must be saved and used on secure session-related function calls.
gsk_secure_soc_read()	Receives data from a secure session.
gsk_secure_soc_startInit()	Starts an asynchronous negotiation of a secure session, using the attributes set for the SSL environment and the secure session.
gsk_secure_soc_write()	Writes data on a secure session.
gsk_secure_soc_startRecv()	Initiates an asynchronous receive operation on a secure session.
gsk_secure_soc_startSend()	Initiates an asynchronous send operation on a secure session.
gsk_strerror()	Retrieves an error message and associated text string that describes a return value that was returned from calling a GSKit API.

An application that uses the sockets and GSKit APIs contains the following elements:

A call to socket() to obtain a socket descriptor.
A call to gsk_environment_open() to obtain a handle to an SSL environment.
One or more calls to gsk_attribute_set_xxxxx() to set attributes of the SSL environment. At a minimum, either a call to gsk_attribute_set_buffer() to set the GSK_OS400_APPLICATION_ID value or to set the GSK_KEYRING_FILE value. Only one of these should be set. It is preferred that you use the GSK_OS400_APPLICATION_ID value. Also ensure you set the type of application (client or server), GSK_SESSION_TYPE, using gsk_attribute_set_enum().
A call to gsk_environment_init() to initialize this environment for SSL processing and to establish the SSL security information for all SSL sessions that run using this environment.
Socket calls to activate a connection. It calls connect() to activate a connection for a client program, or it calls bind(), listen(), and accept() to enable a server to accept incoming connection requests.
A call to gsk_secure_soc_open() to obtain a handle to a secure session.
One or more calls to gsk_attribute_set_xxxxx() to set attributes of the secure session. At a minimum, a call to gsk_attribute_set_numeric_value() to associate a specific socket with this secure session.
A call to gsk_secure_soc_init() to initiate the SSL handshake negotiation of the cryptographic parameters.
Note: Typically, a server program must provide a certificate for an SSL handshake to succeed. A server must also have access to the private key that is associated with the server certificate and the key database file where the certificate is stored. In some cases, a client must also provide a certificate during the SSL handshake processing. This occurs if the server which the client is connecting to has enabled client authentication. The gsk_attribute_set_buffer(GSK_OS400_APPLICATION_ID) or gsk_attribute_set_buffer(GSK_KEYRING_FILE) API calls identify (though in dissimilar ways) the key database file from which the certificate and private key that are used during the handshake are obtained.
Calls to gsk_secure_soc_read() and gsk_secure_soc_write() to receive and send data.
A call to gsk_secure_soc_close() to end the secure session.
A call to gsk_environment_close() to close the SSL environment.
A call to close() to destroy the connected socket.