362 lines
12 KiB
HTML
362 lines
12 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>QlgSSL_Init()--Initialize the Current Job for SSL (using NLS-enabled path name)</title>
|
||
|
|
<!-- 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. -->
|
||
|
|
<!-- Begin Header Records -->
|
||
|
|
<!-- Created by Yvonne Griffin for V5R1-->
|
||
|
|
<!-- End Header Records -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<a name="Top_Of_Page"></a>
|
||
|
|
<!--Java sync-link-->
|
||
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<h2>QlgSSL_Init()--Initialize the Current Job for SSL
|
||
|
|
(using NLS-enabled path name)</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 60%;">
|
||
|
|
<br>
|
||
|
|
Syntax<br>
|
||
|
|
<pre>
|
||
|
|
#include <qsossl.h>
|
||
|
|
|
||
|
|
int QlgSSL_Init(QlgSSLInit* <em>init</em>)
|
||
|
|
</pre>
|
||
|
|
Service Program Name: *SRVPGM<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: Yes<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The <em>QlgSSL_Init()</em> function is used to establish the SSL security
|
||
|
|
information to be used for all SSL sessions for the current job. The
|
||
|
|
<em>QlgSSL_Init()</em> API establishes a certificate and private
|
||
|
|
key for use by the handshake protocol processing when acting as a server.
|
||
|
|
The <em>QlgSSL_Init()</em> API establishes a certificate for use by the
|
||
|
|
handshake protocol processing when acting as a client that is connected to
|
||
|
|
a server performing client authentication.</p>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3>Parameters</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>QlgSSLInit * <em>init</em></strong> (input) </dt>
|
||
|
|
<dd>The pointer to a <strong><em>QlgSSLInit</em></strong> structure.
|
||
|
|
<strong><em>QlgSSLInit</em></strong> is a typedef for a buffer of type
|
||
|
|
struct <strong><em>QlgSSLInitStr</em></strong>.
|
||
|
|
In <strong><qsossl.h></strong>,
|
||
|
|
struct <strong><em>QlgSSLInitStr</em></strong> is defined as the following:</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<table border><tr><td><br>
|
||
|
|
<pre>
|
||
|
|
struct QlgSSLInitStr { /* QlgSSLInitStr */
|
||
|
|
|
||
|
|
Qlg_Path_Name* keyringFileName; /* Key ring file name */
|
||
|
|
char* keyringPassword; /* Key ring file password */
|
||
|
|
unsigned short int* cipherSuiteList; /* List of cipher suites */
|
||
|
|
unsigned int cipherSuiteListLen; /* number of entries in
|
||
|
|
the cipher suites list */
|
||
|
|
};
|
||
|
|
</pre>
|
||
|
|
</td></tr></table>
|
||
|
|
|
||
|
|
<p>The fields within the <strong><em>QlgSSLInit</em></strong>
|
||
|
|
structure as pointed to by <em>init</em> are defined as follows:</p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Qlg_Path_Name_T *<em>keyringFileName</em></strong> (input) </dt>
|
||
|
|
<dd>A pointer to a structure defining the path to the key ring file.
|
||
|
|
This structure defines the coded character set identifier (CCSID)
|
||
|
|
and the path to the key ring file to be used for this job's SSL processing.
|
||
|
|
The path must be a fully qualified integrated file system file name.<br><br></dd>
|
||
|
|
|
||
|
|
|
||
|
|
<dd><strong>char *<em>keyringPassword</em></strong> (input) </dd>
|
||
|
|
<dd>A pointer to the password for the key ring file named in the
|
||
|
|
<em>keyringFileName</em> field.</dd>
|
||
|
|
</dl>
|
||
|
|
<p>If this parameter's value is equal to NULL, then the <em>QlgSSL_Init()</em>
|
||
|
|
support will attempt to extract a password from a key-ring password file.</p>
|
||
|
|
|
||
|
|
<p>This parameter is assumed to be represented in the
|
||
|
|
same CCSID (coded character set identifier) as the
|
||
|
|
<strong><em>keyringFileName</em></strong>.<br><br></p>
|
||
|
|
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
|
||
|
|
<dt><strong>unsigned short int* <em>cipherSuiteList</em></strong> (input) </dt>
|
||
|
|
<dd>A pointer to the cipher specification list to be used during the SSL
|
||
|
|
handshake protocol for this job. This list is a string of concatenated
|
||
|
|
cipher specification values. A cipher specification value is an unsigned short integer.
|
||
|
|
Any value provided will override any values provided by a previous
|
||
|
|
<em>QlgSSL_Init()</em> API or the system default cipher specification
|
||
|
|
list if the previous <em>QlgSSL_Init()</em> API did not provide a
|
||
|
|
cipher specification list. A value of NULL for this parameter
|
||
|
|
indicates one of the following:<br><br></dd>
|
||
|
|
</dl>
|
||
|
|
<ul compact>
|
||
|
|
<li>Use the cipher specification list provided by a
|
||
|
|
previous <em>QlgSSL_Init()</em> API</li>
|
||
|
|
<li>Use the system default cipher specification
|
||
|
|
list if a previous <em>QlgSSL_Init()</em> API was not done</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>The caller specifies the preferred order of the cipher specifications.
|
||
|
|
The cipher specification values are defined in <strong><qsossl.h></strong>
|
||
|
|
as the following:</p>
|
||
|
|
<pre>
|
||
|
|
TLS_RSA_WITH_NULL_MD5 0x0001
|
||
|
|
TLS_RSA_WITH_NULL_SHA 0x0002
|
||
|
|
TLS_RSA_EXPORT_WITH_RC4_40_MD5 0x0003
|
||
|
|
TLS_RSA_WITH_RC4_128_MD5 0x0004
|
||
|
|
TLS_RSA_WITH_RC4_128_SHA 0x0005
|
||
|
|
TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 0x0006
|
||
|
|
TLS_RSA_EXPORT_WITH_DES40_CBC_SHA 0x0008
|
||
|
|
TLS_RSA_WITH_DES_CBC_SHA 0x0009
|
||
|
|
TLS_RSA_WITH_3DES_EDE_CBC_SHA 0x000A
|
||
|
|
TLS_RSA_WITH_AES_128_CBC_SHA 0x002F
|
||
|
|
TLS_RSA_WITH_AES_256_CBC_SHA 0x0035
|
||
|
|
TLS_RSA_WITH_RC2_CBC_128_MD5 0xFF01
|
||
|
|
TLS_RSA_WITH_DES_CBC_MD5 0xFF02
|
||
|
|
TLS_RSA_WITH_3DES_EDE_CBC_MD5 0xFF03
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p><strong>Notes:</strong></p>
|
||
|
|
<ol>
|
||
|
|
<li>The SSL_RSA_EXPORT_WITH_DES40_CBC_SHA cipher is not supported by
|
||
|
|
i5/OS.<br><br></li>
|
||
|
|
<li>
|
||
|
|
<img src="delta.gif" alt="Start of change">
|
||
|
|
The default cipher suite list in preference order is as follows:
|
||
|
|
<img src="deltaend.gif" alt="End of change">
|
||
|
|
<pre>
|
||
|
|
TLS_RSA_WITH_RC4_128_MD5
|
||
|
|
TLS_RSA_WITH_RC4_128_SHA
|
||
|
|
TLS_RSA_WITH_AES_128_CBC_SHA
|
||
|
|
TLS_RSA_WITH_AES_256_CBC_SHA
|
||
|
|
TLS_RSA_WITH_3DES_EDE_CBC_SHA
|
||
|
|
TLS_RSA_WITH_DES_CBC_SHA
|
||
|
|
TLS_RSA_WITH_DES_CBC_MD5
|
||
|
|
TLS_RSA_WITH_3DES_EDE_CBC_MD5
|
||
|
|
TLS_RSA_WITH_RC2_CBC_128_MD5
|
||
|
|
TLS_RSA_EXPORT_WITH_RC4_40_MD5
|
||
|
|
TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5
|
||
|
|
</pre>
|
||
|
|
</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>unsigned int <em>cipherSuiteListLen</em></strong> (input) </dt>
|
||
|
|
<dd>The number of cipher suite entries specified in the
|
||
|
|
list pointed to by the <strong><em>cipherSuiteList</em></strong> parameter.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3>Authorities</h3>
|
||
|
|
|
||
|
|
<p>Authorization of *R (allow access to the object)
|
||
|
|
to the key ring file and its associated files is required.</p>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3>Return Value</h3>
|
||
|
|
|
||
|
|
<p>The <em>QlgSSL_Init()</em> API returns an integer. Possible values are:</p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><em>[0]</em></dt>
|
||
|
|
<dd>Successful return</dd>
|
||
|
|
<dd><em>[SSL_ERROR_BAD_CIPHER_SUITE]</em></dd>
|
||
|
|
<dd>A cipher suite that is not valid was specified.</dd>
|
||
|
|
<dd><em>[SSL_ERROR_IO]</em></dd>
|
||
|
|
<dd>An error occurred in SSL processing; check the <em>errno</em> value.</dd>
|
||
|
|
<dd><em>[SSL_ERROR_KEYPASSWORD_EXPIRED]</em></dd>
|
||
|
|
<dd>The specified key ring password has expired.</dd>
|
||
|
|
<dd><em>[SSL_ERROR_NO_KEYRING]</em></dd>
|
||
|
|
<dd>No key ring file was specified.</dd>
|
||
|
|
<dd><em>[SSL_ERROR_SSL_NOT_AVAILABLE]</em></dd>
|
||
|
|
<dd>SSL is not available for use.</dd>
|
||
|
|
<dd><em>[SSL_ERROR_UNKNOWN]</em></dd>
|
||
|
|
<dd>An unknown or unexpected error occurred during SSL processing.</dd>
|
||
|
|
</dl>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3>Error Conditions</h3>
|
||
|
|
|
||
|
|
<p>When the <em>QlgSSL_Init()</em> API fails with return code
|
||
|
|
[SSL_ERROR_IO], <em>errno</em> can be set to:</p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><em>[EINVAL]
|
||
|
|
</em></dt>
|
||
|
|
<dd>Parameter not valid.</dd>
|
||
|
|
<dd>This error code indicates that the Qlg_Path_Name_T structure was not valid:</dd>
|
||
|
|
</dl>
|
||
|
|
<ul>
|
||
|
|
<li>The path type was less than 0 or greater than 3.</li>
|
||
|
|
<li>A reserved field was not initialized to zeros.</li>
|
||
|
|
</ul><br>
|
||
|
|
<dl>
|
||
|
|
|
||
|
|
<dt><em>[ECONVERT]</em></dt>
|
||
|
|
<dd>Conversion error.</dd>
|
||
|
|
<dd>This error code indicates one of the following:</dd>
|
||
|
|
</dl>
|
||
|
|
<ul>
|
||
|
|
<li>The CCSID specified
|
||
|
|
in the <strong><em>keyringFileName</em></strong>
|
||
|
|
cannot be converted to
|
||
|
|
the current default CCSID for integrated file system path names.</li>
|
||
|
|
<li>There was an incomplete character or
|
||
|
|
shift state sequence at the end of the <strong><em>keyringFileName</em></strong>
|
||
|
|
path or <strong><em>keyringPassword</em></strong>.</li>
|
||
|
|
</ul><br>
|
||
|
|
<dl>
|
||
|
|
|
||
|
|
<dt><em>[EACCES]</em></dt>
|
||
|
|
<dd>Permission denied.</dd>
|
||
|
|
<dd>This error code indicates one of the following:</dd>
|
||
|
|
</dl>
|
||
|
|
<ul>
|
||
|
|
<li>The <em>keyringFileName</em> field contains a file name
|
||
|
|
to which the user is not authorized.</li>
|
||
|
|
<li>The <em>keyringPassword</em> value is not valid for
|
||
|
|
the specified <em>keyringFileName</em>.</li>
|
||
|
|
</ul><br>
|
||
|
|
<dl>
|
||
|
|
<dt><em>[EBADF]</em></dt>
|
||
|
|
<dd>Descriptor not valid.</dd>
|
||
|
|
<dd>This error code indicates one of the following:</dd>
|
||
|
|
</dl>
|
||
|
|
<ul>
|
||
|
|
<li>The <em>keyringFileName</em> value does not specify
|
||
|
|
a valid key ring file name.
|
||
|
|
</ul><br>
|
||
|
|
<dl>
|
||
|
|
|
||
|
|
<dt><em>[EFAULT]</em></dt>
|
||
|
|
<dd>Bad address.</dd>
|
||
|
|
<dd>The system detected an address that was not valid while attempting to
|
||
|
|
access the <em>init</em> parameter or one of the address fields in the
|
||
|
|
<em>init</em> parameter.</dd>
|
||
|
|
</dl>
|
||
|
|
<dl>
|
||
|
|
|
||
|
|
<dt><em>[EUNATCH]</em></dt>
|
||
|
|
<dd>The protocol required to support the specified address family is
|
||
|
|
not available at this time.</dd>
|
||
|
|
</dl>
|
||
|
|
<dl>
|
||
|
|
|
||
|
|
<dt><em>[EUNKNOWN]</em></dt>
|
||
|
|
<dd>Unknown system state.</dd>
|
||
|
|
</dl>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3>Error Messages</h3>
|
||
|
|
|
||
|
|
<table width="100%" cellpadding="5">
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="top">Message ID</th>
|
||
|
|
<th align="left" valign="top">Error Message Text</th>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPE3418 E</td>
|
||
|
|
<td align="left" 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>
|
||
|
|
|
||
|
|
<h3>Usage Notes</h3>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li>A successful <em>SSL_Init()</em>,
|
||
|
|
<em>QlgSSL_Init (using NLS-enabled path name)</em>, or
|
||
|
|
<em>SSL_Init_Application()</em> API must be used to enable a
|
||
|
|
job for SSL processing before attempting to use any other SSL API.</li>
|
||
|
|
|
||
|
|
<li>If multiple <em>SSL_Init_Application()</em>,
|
||
|
|
<em>QlgSSL_Init (using NLS-enabled path name)</em>, or
|
||
|
|
<em>SSL_Init()</em> APIs are performed in a job,
|
||
|
|
then only the values associated with the last
|
||
|
|
<em>SSL_Init_Application()</em>,
|
||
|
|
<em>QlgSSL_Init (using NLS-enabled path name)</em>, or
|
||
|
|
<em>SSL_Init()</em> performed are used.</li>
|
||
|
|
|
||
|
|
<li>If the <em>keyringPassword</em>
|
||
|
|
parameter pointer value is equal to NULL, then
|
||
|
|
<em>QlgSSL_Init</em> will attempt to extract the
|
||
|
|
password value from the key-ring password file associated with the
|
||
|
|
<em>keyringFileName</em> parameter's value.
|
||
|
|
The existence of the associated key-ring password
|
||
|
|
file is based on a configuration selection made during
|
||
|
|
the creation of the key ring file.</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Related Information</h3>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><a href="sslcreat.htm">SSL_Create()</a>--Enable SSL Support for the Specified
|
||
|
|
Socket Descriptor<br><br></li>
|
||
|
|
|
||
|
|
<li><a href="ssldest.htm">SSL_Destroy()</a>--End SSL Support for the Specified
|
||
|
|
SSL Session<br><br></li>
|
||
|
|
|
||
|
|
<li><a href="sslhands.htm">SSL_Handshake()</a>--Initiate the SSL Handshake
|
||
|
|
Protocol<br><br></li>
|
||
|
|
|
||
|
|
<li><a href="sslinit.htm">SSL_Init()</a>--Initialize the Current Job for SSL<br><br></li>
|
||
|
|
|
||
|
|
<li><a href="sslinita.htm">SSL_Init_Application()</a>--Initialize the Current
|
||
|
|
Job for SSL Processing Based on the Application Identifier<br><br></li>
|
||
|
|
|
||
|
|
<li><a href="sslread.htm">SSL_Read()</a>--Receive Data from an SSL-Enabled
|
||
|
|
SocketDescriptor<br><br></li>
|
||
|
|
|
||
|
|
<li><a href="sslwrite.htm">SSL_Write()</a>--Write Data to an SSL-Enabled Socket
|
||
|
|
Descriptor</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
API introduced: V5R1
|
||
|
|
<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>
|