Global Security Kit (GSKit) APIs
Global Security Kit (GSKit) is a set of programmable interfaces that allow an application to be SSL/TLS enabled.
The GSKit APIs allow you to implement the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols in your socket application program. The GSKit APIs provide asynchronous capabilities for negotiating a secure session, sending secure data, and receiving secure data. These asynchronous APIs exist only in the IBM® i operating system and cannot be ported to other systems.
GSKit on IBM i uses System SSL/TLS. For more information about the properties and attributes of System SSL/TLS, see System SSL/TLS system level settings.
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.| API | Description |
|---|---|
| gsk_attribute_get_buffer() | Obtains specific character string information about a secure session or 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 environment. |
| gsk_attribute_get_enum_value() | Obtains values for specific enumerated data for a secure session or environment. |
| gsk_attribute_get_numeric_value() | Obtains specific numeric information about a secure session or 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 environment. |
| gsk_attribute_set_enum() | Sets a specified enumerated type attribute to an enumerated value in the secure session or environment. |
| gsk_attribute_set_numeric_value() | Sets specific numeric information for a secure session or environment. |
| gsk_environment_close() | Closes the secure environment and releases all storage associated with the environment. |
| gsk_environment_init() | Initializes the secure environment after any required attributes are set. |
| gsk_environment_open() | Returns a secure 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 secure environment and the secure session. |
| gsk_secure_soc_misc() | Performs miscellaneous APIs 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 API 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 secure 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 a secure environment.
- One or more calls to gsk_attribute_set_xxxxx() to set attributes of the secure 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 that 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/TLS processing and to establish the SSL/TLS security information for all secure 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/TLS handshake negotiation of the cryptographic parameters.
Note: Typically, a server program must provide a certificate for an SSL/TLS 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 secure 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 secure environment.
- A call to close() to destroy the connected socket.