252 lines
18 KiB
HTML
252 lines
18 KiB
HTML
|
<?xml version="1.0" encoding="UTF-8"?>
|
||
|
|
<!DOCTYPE html
|
||
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
|
|
<html lang="en-us" xml:lang="en-us">
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
|
|
<meta name="security" content="public" />
|
||
|
|
<meta name="Robots" content="index,follow" />
|
||
|
|
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
|
||
|
|
<meta name="DC.Type" content="concept" />
|
||
|
|
<meta name="DC.Title" content="Global Secure ToolKit (GSKit) APIs" />
|
||
|
|
<meta name="abstract" content="Global Secure ToolKit (GSKit) is a set of programmable interfaces that allow an application to be SSL enabled." />
|
||
|
|
<meta name="description" content="Global Secure ToolKit (GSKit) is a set of programmable interfaces that allow an application to be SSL enabled." />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="cssl.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/gsk_attribute_get_buffer.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/gsk_attribute_get_cert_info.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/gsk_attribute_get_enum.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/gsk_attribute_get_numeric_value.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/gsk_attribute_set_callback.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/gsk_attribute_set_buffer.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/gsk_attribute_set_enum.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/gsk_attribute_set_numeric_value.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/gsk_environment_close.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/gsk_environment_init.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/gsk_environment_open.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/gsk_secure_soc_close.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/gsk_secure_soc_init.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/gsk_secure_soc_misc.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/gsk_secure_soc_open.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/gskstartinit.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/gsk_secure_soc_read.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/gsk_secure_soc_write.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/gskstartrecv.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/gskstartsend.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/gsk_strerror.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/socket.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/bind.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/connec.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/listen.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/accept.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/close.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="xgskserver.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="xgskasynch.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="xgskclient.htm" />
|
||
|
|
<meta name="copyright" content="(C) Copyright IBM Corporation 2001, 2006" />
|
||
|
|
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 2001, 2006" />
|
||
|
|
<meta name="DC.Format" content="XHTML" />
|
||
|
|
<meta name="DC.Identifier" content="cgskit" />
|
||
|
|
<meta name="DC.Language" content="en-us" />
|
||
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
|
|
<!-- US Government Users Restricted Rights -->
|
||
|
|
<!-- Use, duplication or disclosure restricted by -->
|
||
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
|
||
|
|
<link rel="stylesheet" type="text/css" href="./ic.css" />
|
||
|
|
<title>Global Secure ToolKit (GSKit) APIs</title>
|
||
|
|
</head>
|
||
|
|
<body id="cgskit"><a name="cgskit"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">Global Secure ToolKit (GSKit) APIs</h1>
|
||
|
|
<div><p>Global Secure ToolKit (GSKit) is a set of programmable interfaces
|
||
|
|
that allow an application to be SSL enabled.</p>
|
||
|
|
<div class="p">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<sup>®</sup> 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. <div class="note"><span class="notetitle">Note:</span> The GSKit APIs only support sockets with an address family
|
||
|
|
of AF_INET or AF_INET6 and type SOCK_STREAM.</div>
|
||
|
|
The following table describes
|
||
|
|
the GSKit APIs:</div>
|
||
|
|
<div class="p">
|
||
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all"><caption>Table 1. Global secure toolkit APIs</caption><thead align="left"><tr><th valign="top" width="56.70103092783505%" id="d0e42">Function</th>
|
||
|
|
<th valign="top" width="43.29896907216495%" id="d0e44">Description</th>
|
||
|
|
</tr>
|
||
|
|
</thead>
|
||
|
|
<tbody><tr><td valign="top" width="56.70103092783505%" headers="d0e42 "><span class="apiname">gsk_attribute_get_buffer() </span></td>
|
||
|
|
<td valign="top" width="43.29896907216495%" headers="d0e44 ">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.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="56.70103092783505%" headers="d0e42 "><span class="apiname">gsk_attribute_get_cert_info()</span> </td>
|
||
|
|
<td valign="top" width="43.29896907216495%" headers="d0e44 ">Obtains specific information about either the server
|
||
|
|
or client certificate for a secure session or an SSL environment. </td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="56.70103092783505%" headers="d0e42 "><span class="apiname">gsk_attribute_get_enum_value()</span> </td>
|
||
|
|
<td valign="top" width="43.29896907216495%" headers="d0e44 ">Obtains values for specific enumerated data for a secure
|
||
|
|
session or an SSL environment. </td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="56.70103092783505%" headers="d0e42 "><span class="apiname">gsk_attribute_get_numeric_value()</span></td>
|
||
|
|
<td valign="top" width="43.29896907216495%" headers="d0e44 ">Obtains specific numeric information about a secure
|
||
|
|
session or an SSL environment. </td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="56.70103092783505%" headers="d0e42 "><span class="apiname">gsk_attribute_set_callback()</span></td>
|
||
|
|
<td valign="top" width="43.29896907216495%" headers="d0e44 ">Sets callback pointers to routines in the user application.
|
||
|
|
The application can then use these routines for special purposes.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="56.70103092783505%" headers="d0e42 "><span class="apiname">gsk_attribute_set_buffer()</span></td>
|
||
|
|
<td valign="top" width="43.29896907216495%" headers="d0e44 ">Sets a specified buffer attribute to a value inside
|
||
|
|
the specified secure session or an SSL environment. </td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="56.70103092783505%" headers="d0e42 "><span class="apiname">gsk_attribute_set_enum()</span> </td>
|
||
|
|
<td valign="top" width="43.29896907216495%" headers="d0e44 ">Sets a specified enumerated type attribute to an enumerated
|
||
|
|
value in the secure session or SSL environment. </td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="56.70103092783505%" headers="d0e42 "><span class="apiname">gsk_attribute_set_numeric_value()</span> </td>
|
||
|
|
<td valign="top" width="43.29896907216495%" headers="d0e44 ">Sets specific numeric information for a secure session
|
||
|
|
or an SSL environment. </td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="56.70103092783505%" headers="d0e42 "><span class="apiname">gsk_environment_close()</span> </td>
|
||
|
|
<td valign="top" width="43.29896907216495%" headers="d0e44 ">Closes the SSL environment and releases all storage
|
||
|
|
associated with the environment. </td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="56.70103092783505%" headers="d0e42 "><span class="apiname">gsk_environment_init()</span> </td>
|
||
|
|
<td valign="top" width="43.29896907216495%" headers="d0e44 ">Initializes the SSL environment after any required attributes
|
||
|
|
are set. </td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="56.70103092783505%" headers="d0e42 "><span class="apiname">gsk_environment_open()</span></td>
|
||
|
|
<td valign="top" width="43.29896907216495%" headers="d0e44 ">Returns an SSL environment handle that must be saved
|
||
|
|
and used on subsequent gsk calls.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="56.70103092783505%" headers="d0e42 "><span class="apiname">gsk_secure_soc_close()</span></td>
|
||
|
|
<td valign="top" width="43.29896907216495%" headers="d0e44 ">Closes a secure session and free all the associated
|
||
|
|
resources for that secure session. </td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="56.70103092783505%" headers="d0e42 "><span class="apiname">gsk_secure_soc_init()</span> </td>
|
||
|
|
<td valign="top" width="43.29896907216495%" headers="d0e44 ">Negotiates a secure session, using the attributes set
|
||
|
|
for the SSL environment and the secure session.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="56.70103092783505%" headers="d0e42 "><span class="apiname">gsk_secure_soc_misc()</span> </td>
|
||
|
|
<td valign="top" width="43.29896907216495%" headers="d0e44 ">Performs miscellaneous functions for a secure session.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="56.70103092783505%" headers="d0e42 "><span class="apiname">gsk_secure_soc_open()</span> </td>
|
||
|
|
<td valign="top" width="43.29896907216495%" headers="d0e44 ">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. </td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="56.70103092783505%" headers="d0e42 "><span class="apiname">gsk_secure_soc_read()</span> </td>
|
||
|
|
<td valign="top" width="43.29896907216495%" headers="d0e44 ">Receives data from a secure session.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="56.70103092783505%" headers="d0e42 "><span class="apiname">gsk_secure_soc_startInit()</span></td>
|
||
|
|
<td valign="top" width="43.29896907216495%" headers="d0e44 ">Starts an asynchronous negotiation of a secure session,
|
||
|
|
using the attributes set for the SSL environment and the secure session.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="56.70103092783505%" headers="d0e42 "><span class="apiname">gsk_secure_soc_write()</span> </td>
|
||
|
|
<td valign="top" width="43.29896907216495%" headers="d0e44 ">Writes data on a secure session. </td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="56.70103092783505%" headers="d0e42 "><span class="apiname">gsk_secure_soc_startRecv()</span></td>
|
||
|
|
<td valign="top" width="43.29896907216495%" headers="d0e44 ">Initiates an asynchronous receive operation on a secure
|
||
|
|
session. </td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="56.70103092783505%" headers="d0e42 "><span class="apiname">gsk_secure_soc_startSend()</span></td>
|
||
|
|
<td valign="top" width="43.29896907216495%" headers="d0e44 ">Initiates an asynchronous send operation on a secure
|
||
|
|
session. </td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" width="56.70103092783505%" headers="d0e42 "><span class="apiname">gsk_strerror()</span></td>
|
||
|
|
<td valign="top" width="43.29896907216495%" headers="d0e44 "><p>Retrieves an error message and associated
|
||
|
|
text string that describes a return value that was returned from calling a
|
||
|
|
GSKit API.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<p>An application that uses the sockets and GSKit APIs contains the following
|
||
|
|
elements:</p>
|
||
|
|
<ol><li>A call to <span class="apiname">socket()</span> to obtain a socket descriptor.</li>
|
||
|
|
<li>A call to <span class="apiname">gsk_environment_open()</span> to obtain a handle
|
||
|
|
to an SSL environment.</li>
|
||
|
|
<li>One or more calls to gsk_attribute_set_xxxxx() to set attributes of the
|
||
|
|
SSL environment. At a minimum, either a call to <span class="apiname">gsk_attribute_set_buffer()</span> 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 <span class="apiname">gsk_attribute_set_enum()</span>.</li>
|
||
|
|
<li>A call to <span class="apiname">gsk_environment_init()</span> to initialize this
|
||
|
|
environment for SSL processing and to establish the SSL security information
|
||
|
|
for all SSL sessions that run using this environment.</li>
|
||
|
|
<li>Socket calls to activate a connection. It calls <span class="apiname">connect()</span> to
|
||
|
|
activate a connection for a client program, or it calls <span class="apiname">bind()</span>, <span class="apiname">listen()</span>,
|
||
|
|
and <span class="apiname">accept()</span> to enable a server to accept incoming connection
|
||
|
|
requests.</li>
|
||
|
|
<li>A call to <span class="apiname">gsk_secure_soc_open()</span> to obtain a handle
|
||
|
|
to a secure session.</li>
|
||
|
|
<li>One or more calls to gsk_attribute_set_xxxxx() to set attributes of the
|
||
|
|
secure session. At a minimum, a call to <span class="apiname">gsk_attribute_set_numeric_value()</span> to
|
||
|
|
associate a specific socket with this secure session.</li>
|
||
|
|
<li>A call to <span class="apiname">gsk_secure_soc_init()</span> to initiate the SSL
|
||
|
|
handshake negotiation of the cryptographic parameters. <div class="note"><span class="notetitle">Note:</span> 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 <span class="apiname">gsk_attribute_set_buffer</span>(GSK_OS400_APPLICATION_ID)
|
||
|
|
or <span class="apiname">gsk_attribute_set_buffer</span>(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.</div>
|
||
|
|
|
||
|
|
</li>
|
||
|
|
<li>Calls to <span class="apiname">gsk_secure_soc_read()</span> and <span class="apiname">gsk_secure_soc_write()</span> to
|
||
|
|
receive and send data.</li>
|
||
|
|
<li>A call to <span class="apiname">gsk_secure_soc_close()</span> to end the secure
|
||
|
|
session.</li>
|
||
|
|
<li>A call to <span class="apiname">gsk_environment_close()</span> to close the SSL
|
||
|
|
environment. </li>
|
||
|
|
<li>A call to <span class="apiname">close()</span> to destroy the connected socket.</li>
|
||
|
|
</ol>
|
||
|
|
</div>
|
||
|
|
<div>
|
||
|
|
<div class="familylinks">
|
||
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="cssl.htm" title="Currently, i5/OS supports two methods of creating secure socket applications on the iSeries. The SSL_ APIs and Global Secure Toolkit (GSKit) APIs provide communications privacy over an open communications network, which in most cases is the Internet.">Secure sockets</a></div>
|
||
|
|
</div>
|
||
|
|
<div class="relref"><strong>Related reference</strong><br />
|
||
|
|
<div><a href="xgskserver.htm" title="This code example can be used to establish a secure server using Global Secure ToolKit (GSKit) APIs.">Example: GSKit secure server with asynchronous data receive</a></div>
|
||
|
|
<div><a href="xgskasynch.htm" title="The gsk_secure_soc_startInit() API allows you to create secure server applications that can handle request asynchronously.">Example: GSKit secure server with asynchronous handshake</a></div>
|
||
|
|
<div><a href="xgskclient.htm" title="This code sample provides an example of a client that uses the GSKit APIs.">Example: Establish a secure client with Global Secure ToolKit (GSKit) APIs</a></div>
|
||
|
|
</div>
|
||
|
|
<div class="relinfo"><strong>Related information</strong><br />
|
||
|
|
<div><a href="../apis/gsk_attribute_get_buffer.htm">gsk_attribute_get_buffer()</a></div>
|
||
|
|
<div><a href="../apis/gsk_attribute_get_cert_info.htm">gsk_attribute_get_cert_info()</a></div>
|
||
|
|
<div><a href="../apis/gsk_attribute_get_enum.htm">gsk_attribute_get_enum_value()</a></div>
|
||
|
|
<div><a href="../apis/gsk_attribute_get_numeric_value.htm">gsk_attribute_get_numeric_value()</a></div>
|
||
|
|
<div><a href="../apis/gsk_attribute_set_callback.htm">gsk_attribute_set_callback()</a></div>
|
||
|
|
<div><a href="../apis/gsk_attribute_set_buffer.htm">gsk_attribute_set_buffer()</a></div>
|
||
|
|
<div><a href="../apis/gsk_attribute_set_enum.htm">gsk_attribute_set_enum()</a></div>
|
||
|
|
<div><a href="../apis/gsk_attribute_set_numeric_value.htm">gsk_attribute_set_numeric_value()</a></div>
|
||
|
|
<div><a href="../apis/gsk_environment_close.htm">gsk_environment_close()</a></div>
|
||
|
|
<div><a href="../apis/gsk_environment_init.htm">gsk_environment_init()</a></div>
|
||
|
|
<div><a href="../apis/gsk_environment_open.htm">gsk_environment_open()</a></div>
|
||
|
|
<div><a href="../apis/gsk_secure_soc_close.htm">gsk_secure_soc_close()</a></div>
|
||
|
|
<div><a href="../apis/gsk_secure_soc_init.htm">gsk_secure_soc_init()</a></div>
|
||
|
|
<div><a href="../apis/gsk_secure_soc_misc.htm">gsk_secure_soc_misc()</a></div>
|
||
|
|
<div><a href="../apis/gsk_secure_soc_open.htm">gsk_secure_soc_open()</a></div>
|
||
|
|
<div><a href="../apis/gskstartinit.htm">gsk_secure_soc_startInit()</a></div>
|
||
|
|
<div><a href="../apis/gsk_secure_soc_read.htm">gsk_secure_soc_read()</a></div>
|
||
|
|
<div><a href="../apis/gsk_secure_soc_write.htm">gsk_secure_soc_write()</a></div>
|
||
|
|
<div><a href="../apis/gskstartrecv.htm">gsk_secure_soc_startRecv()</a></div>
|
||
|
|
<div><a href="../apis/gskstartsend.htm">gsk_secure_soc_startSend()</a></div>
|
||
|
|
<div><a href="../apis/gsk_strerror.htm">gsk_strerror()</a></div>
|
||
|
|
<div><a href="../apis/socket.htm">socket()</a></div>
|
||
|
|
<div><a href="../apis/bind.htm">bind()</a></div>
|
||
|
|
<div><a href="../apis/connec.htm">connect()</a></div>
|
||
|
|
<div><a href="../apis/listen.htm">listen()</a></div>
|
||
|
|
<div><a href="../apis/accept.htm">accept()</a></div>
|
||
|
|
<div><a href="../apis/close.htm">close()</a></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|