404 lines
11 KiB
HTML
404 lines
11 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
||
|
|
<title>gsk_secure_soc_startInit()--Start asynchronous operation to negotiate a
|
||
|
|
secure session</title>
|
||
|
|
<!-- Begin Header Records ========================================= -->
|
||
|
|
<!-- 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. -->
|
||
|
|
<!-- Change History: -->
|
||
|
|
<!-- Created for V5R2 -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<!-- End Header Records -->
|
||
|
|
<!--Java sync-link-->
|
||
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<a name="Top_Of_Page"></a>
|
||
|
|
|
||
|
|
<h2>gsk_secure_soc_startInit()--Start asynchronous operation to
|
||
|
|
negotiate a secure session</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 80%;">
|
||
|
|
<br>
|
||
|
|
Syntax
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
#include <gskssl.h>
|
||
|
|
#include <qsoasync.h>
|
||
|
|
|
||
|
|
int gsk_secure_soc_startInit(gsk_handle my_session_handle,
|
||
|
|
int IOCompletionPort,
|
||
|
|
Qso_OverlappedIO_t * communicationsArea)
|
||
|
|
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
Service Program Name: QSYS/QSOSSLSR<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: Yes<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The <strong>gsk_secure_soc_startInit()</strong> function is used to initiate
|
||
|
|
an asynchronous negotiation of a secure session, using the attributes set for
|
||
|
|
the SSL environment and the secure session. This API starts the SSL handshake
|
||
|
|
to the remote peer and upon successful completion of
|
||
|
|
<strong>QsoWaitForIOCompletion()</strong> a secure session is established.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Parameters</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong><em>my_session_handle</em></strong> (Input)</dt>
|
||
|
|
|
||
|
|
<dd>The handle returned from <strong>gsk_secure_soc_open()</strong> that will
|
||
|
|
be used to negotiate the secure session.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><em>int IOCompletionPort</em></strong> (Input)</dt>
|
||
|
|
|
||
|
|
<dd>The I/O completion port that should be posted when the operation
|
||
|
|
completes.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em><strong>Qso_OverlappedIO_t</strong> *
|
||
|
|
communicationsArea</em> (Input/Output)</dt>
|
||
|
|
|
||
|
|
<dd>A pointer to a structure that contains the following information:<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="25 75" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><strong><em>descriptorHandle</em></strong> </td>
|
||
|
|
<td align="left" valign="top">(Input) - The descriptor handle is application
|
||
|
|
specific and is never used by the system. This field is intended to make it
|
||
|
|
easier for the application to keep track of information regarding a given
|
||
|
|
socket connection. </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><strong><em>buffer</em></strong> </td>
|
||
|
|
<td align="left" valign="top">Not used. </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><strong><em>bufferLength</em></strong> </td>
|
||
|
|
<td align="left" valign="top">Not used. </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><strong><em>postFlag</em></strong> </td>
|
||
|
|
<td align="left" valign="top">Not used. </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><strong><em>postFlagResult</em></strong> </td>
|
||
|
|
<td align="left" valign="top">Not used. </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><strong><em>fillBuffer</em></strong> </td>
|
||
|
|
<td align="left" valign="top">Not used. </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><strong><em>returnValue</em></strong> </td>
|
||
|
|
<td align="left" valign="top">(Output) - When the negotiate operation completes
|
||
|
|
asynchronously, this field contains indication of success or failure. </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em><strong>errnoValue</strong></em> </td>
|
||
|
|
<td align="left" valign="top">(Output) - When the negotiate operation completes
|
||
|
|
asynchronously and returnValue is GSK_ERROR_IO, this field will contain an
|
||
|
|
errno further defining the failure. </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><strong><em>operationCompleted</em></strong>
|
||
|
|
</td>
|
||
|
|
<td align="left" valign="top">(Output) - If the operation is posted to the I/O
|
||
|
|
completion port, this field is updated to indicate that the operation was a
|
||
|
|
GSKSECURESOCSTARTINIT. </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><strong><em>secureDataTransferSize</em></strong>
|
||
|
|
</td>
|
||
|
|
<td align="left" valign="top">Not used. </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><strong><em>bytesAvailable</em></strong> </td>
|
||
|
|
<td align="left" valign="top">Not used. </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><strong><em>operationWaitTime</em></strong> </td>
|
||
|
|
<td align="left" valign="top">Not used. </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><strong><em>postedDescriptor</em></strong> </td>
|
||
|
|
<td align="left" valign="top">Not used - Must be set to zero. </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><strong><em>reserved1</em></strong> </td>
|
||
|
|
<td align="left" valign="top">(Output) - Must be set to hexadecimal zeroes.
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><strong><em>reserved2</em></strong> </td>
|
||
|
|
<td align="left" valign="top">(Input) - Must be set to hexadecimal zeroes.
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Authorities</h3>
|
||
|
|
|
||
|
|
<p>Authorization of *R (allow access to the object) to the certificate store
|
||
|
|
file and its associated files is required. Authorization of *X (allow use of
|
||
|
|
the object) to each directory of the path name of the certificate store file
|
||
|
|
and its associated files is required.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Return Values</h3>
|
||
|
|
|
||
|
|
<p><strong>gsk_secure_soc_startInit()</strong> returns an integer. Possible
|
||
|
|
values are:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>GSK_OS400_ASYNCHRONOUS_SOC_INIT - The function has been started. When the
|
||
|
|
function completes, the Qso_OverlappedIO_t communications structure will be
|
||
|
|
updated with the results and the I/O completion port will be posted.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>If the function fails, possible values are:<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt>[GSK_INVALID_HANDLE]</dt>
|
||
|
|
|
||
|
|
<dd><p>The handle specified was not valid.</p></dd>
|
||
|
|
|
||
|
|
<dt>[GSK_OS400_ERROR_NO_INITIALIZE]</dt>
|
||
|
|
|
||
|
|
<dd><p>A successful <strong>gsk_environment_init()</strong> was not previously
|
||
|
|
called with this handle.</p></dd>
|
||
|
|
|
||
|
|
<dt>[GSK_OS400_ERROR_NOT_TCP]</dt>
|
||
|
|
|
||
|
|
<dd><p>The <em>socket descriptor</em> type is not SOCK_STREAM or the address
|
||
|
|
family is not AF_INET or
|
||
|
|
AF_INET6.</p></dd>
|
||
|
|
|
||
|
|
<dt>[GSK_OS400_ERROR_ALREADY_SECURE]</dt>
|
||
|
|
|
||
|
|
<dd><p>The <em>socket descriptor</em> is already in use by another secure
|
||
|
|
session.</p></dd>
|
||
|
|
|
||
|
|
<dt>[GSK_OS400_ERROR_INVALID_POINTER]</dt>
|
||
|
|
|
||
|
|
<dd><p>The <em>my_session_handle</em> pointer is not valid.</p></dd>
|
||
|
|
|
||
|
|
<dt>[GSK_INTERNAL_ERROR]</dt>
|
||
|
|
|
||
|
|
<dd><p>An unexpected error occurred during SSL processing.</p></dd>
|
||
|
|
|
||
|
|
<dt>[GSK_OS400_ERROR_INVALID_OVERLAPPEDIO_T]</dt>
|
||
|
|
|
||
|
|
<dd><p>The Qso_OverLappedIO_t specified was not valid.</p></dd>
|
||
|
|
|
||
|
|
<dt>[GSK_OS400_ERROR_INVALID_IOCOMPLETIONPORT]</dt>
|
||
|
|
|
||
|
|
<dd><p>The I/O completion port specified was not valid.</p></dd>
|
||
|
|
|
||
|
|
<dt>[GSK_OS400_ERROR_BAD_SOCKET_DESCRIPTOR]</dt>
|
||
|
|
|
||
|
|
<dd><p>The socket descriptor specified within the gsk_handle was not valid.</p></dd>
|
||
|
|
|
||
|
|
<dt>[GSK_ERROR_IO]</dt>
|
||
|
|
|
||
|
|
<dd><p>An error occured in SSL processing; check the <strong>errno</strong>
|
||
|
|
value.</p></dd>
|
||
|
|
</dl>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Error Conditions</h3>
|
||
|
|
|
||
|
|
<p>When <strong>gsk_secure_soc_startInit()</strong> API fails with return code
|
||
|
|
[GSK_ERROR_IO], <em>errno</em> can be set to:</p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><em>[EIO]</em></dt>
|
||
|
|
|
||
|
|
<dd>Input/output error.</p></dd>
|
||
|
|
|
||
|
|
<dt><em>[EUNATCH]</em></dt>
|
||
|
|
|
||
|
|
<dd>The protocol required to support the specified address family is not
|
||
|
|
available at this time.</p></dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>If an <em>errno</em> is returned that is not in this list, see <a href=
|
||
|
|
"unix14.htm">Errno Values for UNIX-Type Functions</a> for a description of the
|
||
|
|
<em>errno</em>.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Error Messages</h3>
|
||
|
|
|
||
|
|
<table width="100%" cellpadding="5">
|
||
|
|
<!-- cols="15 85" -->
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="top">Message ID</th>
|
||
|
|
<th align="left" valign="top">Error Message Text</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td width="15%" valign="top">CPE3418 E</td>
|
||
|
|
<td width="85%" valign="top">Possible APAR condition or hardware failure.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF9872 E</td>
|
||
|
|
<td align="left" valign="top">Program or service program &1 in library &2 ended.
|
||
|
|
Reason code &3.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPFA081 E</td>
|
||
|
|
<td align="left" valign="top">Unable to set return value or error code.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<p><strong>Usage Notes</strong></p>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li>The <strong>gsk_secure_soc_startInit()</strong> function is valid only on
|
||
|
|
sockets that have an address family of AF_INET or AF_INET6
|
||
|
|
and a socket type of SOCK_STREAM.<br>
|
||
|
|
<br></li>
|
||
|
|
|
||
|
|
<li>The current implemention of the SSL Protocol does not allow
|
||
|
|
<strong>gsk_secure_soc_startInit()</strong> to complete synchronously. Use
|
||
|
|
<strong>gsk_secure_soc_init()</strong> if the synchronous behaviour is
|
||
|
|
needed.<br>
|
||
|
|
<br></li>
|
||
|
|
|
||
|
|
<li>
|
||
|
|
|
||
|
|
When doing the SSL handshake with a <em>GSK_SESSION_TYPE</em> value
|
||
|
|
of GSK_SERVER_SESSION or GSK_SERVER_SESSION_WITH_CL_AUTH, the
|
||
|
|
<em>GSK_CONNECT_CIPHER_SPEC</em> value will be the first cipher found in
|
||
|
|
the ordered <em>GSK_V3_CIPHER_SPECS</em>(<em>GSK_V2_CIPHER_SPECS</em>
|
||
|
|
if SSLV2 is only common protocol) list that was also found in the cipher list
|
||
|
|
provided by the client during the SSL handshake.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
<li>When doing the SSL handshake with a <em>GSK_SESSION_TYPE</em> value
|
||
|
|
of GSK_CLIENT_SESSION, the cipher specification list will be
|
||
|
|
sent to the server in the client hello in the order found in the
|
||
|
|
<em>GSK_V3_CIPHER_SPECS</em> and/or <em>GSK_V2_CIPHER_SPECS</em>
|
||
|
|
list, however the value from that list that is negotiated for
|
||
|
|
<em>GSK_CONNECT_CIPHER_SPEC</em> is determined by the server policy.
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Related Information</h3>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><a href="gsk_secure_soc_close.htm">gsk_secure_soc_close()</a>--Close a Secure
|
||
|
|
Session<br><br></li>
|
||
|
|
|
||
|
|
<li><a href="gsk_secure_soc_init.htm">gsk_secure_soc_init()</a>--Negotiate a secure
|
||
|
|
session<br><br></li>
|
||
|
|
|
||
|
|
<li><a href="gsk_secure_soc_misc.htm">gsk_secure_soc_misc()</a>--Perform
|
||
|
|
miscellaneous functions for a secure session<br><br></li>
|
||
|
|
|
||
|
|
<li><a href="gsk_secure_soc_open.htm">gsk_secure_soc_open()</a>--Get a handle for a
|
||
|
|
secure session<br><br></li>
|
||
|
|
|
||
|
|
<li><a href="gsk_secure_soc_read.htm">gsk_secure_soc_read()</a>--Receive data on a
|
||
|
|
secure session<br><br></li>
|
||
|
|
|
||
|
|
<li><a href="gsk_secure_soc_write.htm">gsk_secure_soc_write()</a>--Send data on a
|
||
|
|
secure session<br><br></li>
|
||
|
|
|
||
|
|
<li><a href="gskstartrecv.htm">gsk_secure_soc_startRecv</a>--Start Asynchronous
|
||
|
|
Recv Operation on a secure session<br><br></li>
|
||
|
|
|
||
|
|
<li><a href="gskstartsend.htm">gsk_secure_soc_startSend</a>--Start Asynchronous
|
||
|
|
Send Operation on a secure session<br><br></li>
|
||
|
|
|
||
|
|
<li><a href="createiocompletionport.htm">QsoCreateIOCompletionPort()</a>--Create
|
||
|
|
I/O Completion Port<br><br></li>
|
||
|
|
|
||
|
|
<li><a href="destroyiocompletionport.htm">QsoDestroyIOCompletionPort()</a>--Destroy
|
||
|
|
I/O Completion Port<br><br></li>
|
||
|
|
|
||
|
|
<li><a href="postiocompletion.htm">QsoPostIOCompletionPort()</a>--Post Request on
|
||
|
|
I/O Completion Port<br><br></li>
|
||
|
|
|
||
|
|
<li><a href="waitforiocompletion.htm">QsoWaitForIOCompletion()</a>--Wait for I/O
|
||
|
|
Completion Operation</li>
|
||
|
|
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
API introduced: V5R2
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<center>
|
||
|
|
<table cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
||
|
|
"unix.htm">UNIX-Type APIs</a> | <a href="aplist.htm">APIs by category</a> </td>
|
||
|
|
</tr>
|
||
|
|
</table></center>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|