426 lines
12 KiB
HTML
426 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>SSL_Init()--Initialize the Current Job for SSL</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 -->
|
||
|
|
<!-- Direct1 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
|
||
|
|
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
|
||
|
|
<!-- 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>SSL_Init()--Initialize the Current Job for SSL</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 60%;">
|
||
|
|
<br>
|
||
|
|
Syntax<br>
|
||
|
|
<pre>
|
||
|
|
#include <qsossl.h>
|
||
|
|
|
||
|
|
int SSL_Init(SSLInit* <em>init</em>)
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
Service Program Name: QSOSSLSR <br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: Yes<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The <strong><em>SSL_Init()</em></strong> function is used to establish the
|
||
|
|
SSL security information to be used for all SSL sessions for the current job.
|
||
|
|
The <em>SSL_Init()</em> API establishes the certificate and the associated
|
||
|
|
public and private key information for use by the SSL handshake protocol
|
||
|
|
processing when acting as a server or when acting as a client. The
|
||
|
|
certificate and key information is needed by an application that is acting as a
|
||
|
|
client in the situations where the client is connecting to a server which has
|
||
|
|
enabled and requires client authentication.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Parameters</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt>SSLInit * <strong><em>init</em></strong> (input)</dt>
|
||
|
|
|
||
|
|
<dd>The pointer to an <strong><em>SSLInit</em></strong> structure.
|
||
|
|
<strong><em>SSLInit</em></strong> is a typedef for a buffer of type struct
|
||
|
|
<strong><em>SSLInitStr</em></strong>. In <strong><qsossl.h></strong>, struct
|
||
|
|
<strong><em>SSLInitStr</em></strong> is defined as the following:</dd>
|
||
|
|
|
||
|
|
<dd><br>
|
||
|
|
<br>
|
||
|
|
<table border cellpadding="5">
|
||
|
|
<tr>
|
||
|
|
<td>
|
||
|
|
<pre>
|
||
|
|
struct SSLInitStr { /* SSLInitStr */
|
||
|
|
|
||
|
|
char* 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>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>The fields within the <strong><em>SSLInit</em></strong> structure as pointed
|
||
|
|
to by <em>init</em> are defined as follows:</p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt>char *<strong><em>keyringFileName</em></strong> (input)</dt>
|
||
|
|
|
||
|
|
<dd>A pointer to a null-terminated character string, identifying the path to
|
||
|
|
the key database file to be used for this job's SSL processing. The path must
|
||
|
|
be a fully qualified integrated file system file name.
|
||
|
|
|
||
|
|
<p>This parameter is assumed to be represented in the CCSID (coded character
|
||
|
|
set identifier) currently in effect for the job. If the CCSID of the job is
|
||
|
|
65535, this parameter is assumed to be represented in the default CCSID of the
|
||
|
|
job.</p>
|
||
|
|
|
||
|
|
<p>See <a href=
|
||
|
|
"sslinitu.htm">QlgSSL_Init()--Initialize the Current Job for SSL (using
|
||
|
|
NLS-enabled path name)</a> for a description of supplying the
|
||
|
|
<strong><em>keyringFileName</em></strong> in any CCSID.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt>char *<strong><em>keyringPassword</em></strong> (input)</dt>
|
||
|
|
|
||
|
|
<dd>A pointer to a null-terminated character string, identifying the password
|
||
|
|
for the key database file named in the <em>keyringFileName</em> field.
|
||
|
|
|
||
|
|
<p>If this parameter's value is equal to NULL, then the <em>SSL_Init()</em>
|
||
|
|
support will attempt to extract the key database password that has been
|
||
|
|
securely stored on the system.</p>
|
||
|
|
|
||
|
|
<p>This parameter is assumed to be represented in the CCSID (coded character
|
||
|
|
set identifier) currently in effect for the job. If the CCSID of the job is
|
||
|
|
65535, this parameter is assumed to be represented in the default CCSID of the
|
||
|
|
job.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt>unsigned short int* <strong><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>SSL_Init()</em> API or <em>SSL_Init_Application()</em> API or the system
|
||
|
|
default cipher specification list if the previous <em>SSL_Init()</em> API or
|
||
|
|
<em>SSL_Init_Application()</em> API did not provide a cipher specification
|
||
|
|
list. A value of NULL for this parameter indicates one of the following:<br>
|
||
|
|
<br>
|
||
|
|
<ul>
|
||
|
|
<li>Use the cipher specification list provided by a previous
|
||
|
|
<em>SSL_Init()</em> API or <em>SSL_Init_Application()</em> API</li>
|
||
|
|
|
||
|
|
<li>Use the system default cipher specification list if a previous
|
||
|
|
<em>SSL_Init()</em> API or <em>SSL_Init_Application()</em> API was not
|
||
|
|
done</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>The caller specifies the preferred order of the cipher specifications. The
|
||
|
|
cipher specification values, shown here not in preferred or strength order, 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_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">
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
<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>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt>unsigned int <strong><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 database file
|
||
|
|
and its associated files is required.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Return Value</h3>
|
||
|
|
|
||
|
|
<p>The <em>SSL_Init()</em> API returns an integer. Possible values are:</p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><em>[0]</em> </dt>
|
||
|
|
|
||
|
|
<dd>
|
||
|
|
<p>Successful return</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[SSL_ERROR_BAD_CIPHER_SUITE]</em> </dt>
|
||
|
|
|
||
|
|
<dd>
|
||
|
|
<p>A cipher suite that is not valid was specified.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[SSL_ERROR_IO]</em> </dt>
|
||
|
|
|
||
|
|
<dd>
|
||
|
|
<p>An error occurred in SSL processing; check the <em>errno</em> value.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[SSL_ERROR_KEYPASSWORD_EXPIRED]</em> </dt>
|
||
|
|
|
||
|
|
<dd>
|
||
|
|
<p>The specified key ring password has expired.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[SSL_ERROR_NO_KEYRING]</em> </dt>
|
||
|
|
|
||
|
|
<dd>
|
||
|
|
<p>No key ring file was specified.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[SSL_ERROR_SSL_NOT_AVAILABLE]</em> </dt>
|
||
|
|
|
||
|
|
<dd>
|
||
|
|
<p>SSL is not available for use.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[SSL_ERROR_UNKNOWN]</em> </dt>
|
||
|
|
|
||
|
|
<dd>
|
||
|
|
<p>An unknown or unexpected error occurred during SSL processing.</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
<h3>Error Conditions</h3>
|
||
|
|
|
||
|
|
<p>When the <em>SSL_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>
|
||
|
|
<p>Parameter not valid.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EACCES]</em> </dt>
|
||
|
|
|
||
|
|
<dd>
|
||
|
|
<p>Permission denied.</p>
|
||
|
|
|
||
|
|
<p>This error code indicates one of the following:</p>
|
||
|
|
|
||
|
|
<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>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EBADF]</em> </dt>
|
||
|
|
|
||
|
|
<dd>
|
||
|
|
<p>Descriptor not valid.</p>
|
||
|
|
|
||
|
|
<p>This error code indicates one of the following:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The <em>keyringFileName</em> value does not specify a valid key ring file
|
||
|
|
name.</li>
|
||
|
|
</ul><br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EFAULT]</em> </dt>
|
||
|
|
|
||
|
|
<dd>
|
||
|
|
<p>Bad address.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EUNATCH]</em> </dt>
|
||
|
|
|
||
|
|
<dd>
|
||
|
|
<p>The protocol required to support the specified address family is not
|
||
|
|
available at this time.<br>
|
||
|
|
<br>
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><em>[EUNKNOWN]</em> </dt>
|
||
|
|
|
||
|
|
<dd>
|
||
|
|
<p>Unknown system state.</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<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>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Usage Notes</h3>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li>A successful
|
||
|
|
<em>SSL_Init()</em>, <em>QlgSSL_Init (using NLS-enabled path name)</em>, or an
|
||
|
|
<em>SSL_Init_Application()</em> API must be used to enable a job for SSL
|
||
|
|
processing before attempting to use any other SSL API.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>If multiple <em>SSL_Init_Application ()</em>, <em>QlgSSL_Init</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</em>,
|
||
|
|
or or <em>SSL_Init()</em> performed are used.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>If the <em>keyringPassword</em> parameter pointer value is equal to NULL,
|
||
|
|
then <em>SSL_Init()</em> will attempt to extract the password value as stored
|
||
|
|
on the system with the <em>keyringFileName</em> parameter's value. The
|
||
|
|
existence of the securely stored key database password is based on a
|
||
|
|
configuration selection made during the creation of the key database file.</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Related Information</h3>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><a href= "sslinitu.htm">QlgSSL_Init()</a>--Initialize the Current Job for SSL (using
|
||
|
|
NLS-enabled path name)<br><br></li>
|
||
|
|
|
||
|
|
<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=
|
||
|
|
"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 Socket
|
||
|
|
Descriptor<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: V4R3
|
||
|
|
|
||
|
|
<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>
|
||
|
|
|