535 lines
17 KiB
HTML
535 lines
17 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_Application()--Initialize the Current Job for SSL Processing
|
|
Based on the Application Identifier</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_Application()--Initialize the Current Job for SSL Processing Based
|
|
on the Application Identifier</h2>
|
|
|
|
<div class="box" style="width: 60%;">
|
|
<br>
|
|
Syntax<br>
|
|
<pre>
|
|
|
|
#include <qsossl.h>
|
|
|
|
|
|
int SSL_Init_Application(SSLInitApp*
|
|
<em>init_app</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 <em>SSL_Init_Application()</em> function is used to establish the SSL
|
|
security information to be used for all SSL sessions for the current job based
|
|
on the specified application identifier. The <em>SSL_Init_Application()</em>
|
|
API uses the application identifier to determine and then establish 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 situaitons where the client is connecting to
|
|
a server which has enabled and requires client authentication.</p>
|
|
|
|
<br>
|
|
<h3>Parameters</h3>
|
|
|
|
<dl>
|
|
<dt>SSLInitApp * <strong><em>init_app</em></strong> (input)</dt>
|
|
|
|
<dd>The pointer to an <strong><em>SSLInitApp</em></strong> value.
|
|
<strong><em>SSLInitApp</em></strong> is a typedef for a buffer of type struct
|
|
<strong><em>SSLInitAppStr</em></strong>. In <strong><qsossl.h></strong>,
|
|
struct <strong><em>SSLInitAppStr</em></strong> is defined as the following:<br>
|
|
<br>
|
|
<table border cellpadding="5">
|
|
<tr>
|
|
<td>
|
|
<pre>
|
|
struct SSLInitAppStr { /* SSLInitAppStr */
|
|
char* applicationID; /* application id value */
|
|
unsigned int applicationIDLen; /* length of application id */
|
|
char* localCertificate; /* local certificate */
|
|
unsigned int localCertificateLen; /* ength of local certificate */
|
|
unsigned short int* cipherSuiteList; /* List of cipher suites */
|
|
unsigned int cipherSuiteListLen; /* number of entries in
|
|
the cipher suites list */
|
|
unsigned int sessionType; /* the type of application as
|
|
registered */
|
|
unsigned int reserved1; /* reserved - must be 0 */
|
|
unsigned int protocol; /* SSL protocol version */
|
|
unsigned int timeout; /* cache timeout (seconds) */
|
|
char reserved[12]; /* reserved - must be NULL (0s)*/
|
|
|
|
};
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>The fields within the <strong><em>SSLInitApp</em></strong> structure as
|
|
pointed to by <em>init_app</em> are defined as follows:</p>
|
|
|
|
<dl>
|
|
<dt>char *<strong><em>applicationID</em></strong> (input)</dt>
|
|
|
|
<dd>A pointer to a null terminated character string identifying the
|
|
application identifier value that was used to register the application using the
|
|
Register Application for Certificate Use, (OPM, QSYRGAP; ILE,
|
|
QsyRegisterAppForCertUse) API. See the Register Application for Certificate Use
|
|
API for information on the format and values allowed for the application
|
|
identifier.<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt>char *<strong><em>applicationIDLen</em></strong> (input)</dt>
|
|
|
|
<dd>The number of characters in the application identifier string as specified
|
|
by the <strong><em>applicationID</em></strong> parameter.<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt>char *<strong><em>localCertificate</em></strong> (input)</dt>
|
|
|
|
<dd>On input, the localCertificate pointer must be set to point to storage that
|
|
has been allocated by the calling application that will be used on output to
|
|
contain the application's registered local certificate. If a certificate is not
|
|
to be returned then set this pointer's value to NULL and the
|
|
<strong><em>localCertificateLen</em></strong> value to zero (0). The storage
|
|
should be large enough to accomodate the size of the certificate. Most
|
|
certificates are less than 2K in length. On output, the
|
|
<strong><em>localCertificate</em></strong> pointer will not be changed, though
|
|
the storage it points to will contain the registered application's certificate.
|
|
The certificate will be the one registered for that application by the
|
|
Register Application for Certificate Use (OPM, QSYRGAP; ILE,
|
|
QsyRegisterAppForCertUse) API. See the Register Application for Certificate Use
|
|
API for information on the format and values allowed for the application
|
|
identifier.<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt>unsigned int <strong><em>localCertificateLen</em></strong> (input)</dt>
|
|
|
|
<dd>On input, this value must equal the number of characters available in the
|
|
storage pointed to by the <strong><em>localCertificate</em></strong> pointer.
|
|
Set this value to 0 if you do not want a certificate returned by this API. On
|
|
output, this value is equal to the length of the certificate. If the
|
|
certificate will not fit into the storage provided, then this value will be set
|
|
to the length required to contain the certificate.<br>
|
|
<br>
|
|
</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_Application()</em> API or <em>SSL_Init()</em> API or the
|
|
system default cipher specification list if the previous
|
|
<em>SSL_Init_Application()</em> API or <em>SSL_Init()</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_Application()</em> API or <em>SSL_Init()</em> API</li>
|
|
|
|
<li>Use the system default cipher specification list if a previous
|
|
<em>SSL_Init_Application()</em> API or <em>SSL_Init()</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>
|
|
|
|
<br>
|
|
<p>Notes:</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>
|
|
<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.<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt>unsigned int
|
|
<strong><em>sessionType</em></strong> (output)</dt>
|
|
|
|
<dd>The type registered for the application. The following values are returned
|
|
in <strong><em>sessionType</em></strong> and are defined in <strong><qsossl.h></strong>.
|
|
<pre> SSL_REGISTERED_AS_CLIENT 0
|
|
SSL_REGISTERED_AS_SERVER 1
|
|
SSL_REGISTERED_AS_SERVER_WITH_CLIENT_AUTH 2
|
|
SSL_REGISTERED_AS_SERVER_WITH_OPTIONAL_CLIENT_AUTH 3
|
|
SSL_REGISTERED_AS_NOT_SPECIFIED 99
|
|
</pre>
|
|
|
|
</dd>
|
|
|
|
<dt>unsigned int <strong><em>reserved1</em></strong> (input)</dt>
|
|
|
|
<dd>This reserved field must be set to 0.<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt>unsigned int <strong><em>protocol</em></strong> (input)</dt>
|
|
|
|
<dd>The protocol(s) that are acceptable as the handshake protocol for this job.
|
|
The following values may be specified for <strong><em>protocol</em></strong>
|
|
and are defined in <strong><qsossl.h></strong>.
|
|
<pre>
|
|
SSL_VERSION_CURRENT 0 (TLS with SSL Version 3.0 and SSL
|
|
Version 2.0 compatibility)
|
|
SSL_VERSION_2 2 (SSL Version 2.0 only)
|
|
SSL_VERSION_3 3 (SSL Version 3.0 only)
|
|
TLS_VERSION_1 4 (TLS Version 1 only)
|
|
TLSV1_SSLV3 5 (TLS Version 1 with SSL
|
|
Version 3.0 compatibility)
|
|
</pre>
|
|
</dd>
|
|
|
|
<dt>unsigned int <strong><em>timeout</em></strong> (input)</dt>
|
|
|
|
<dd>The time period (in seconds) for which TLS Version 1.0 and SSL Version 3.0
|
|
session parameters are cached for use with abbreviated SSL handshakes. The
|
|
valid range for <strong><em>timeout</em></strong> is from 1 to 86,400 seconds
|
|
(24 hours). Not specifying a value (0) will default to the maximum timeout, and
|
|
specifying a value of 0xffffffff will disable caching. The following values are
|
|
defined in <strong><qsossl.h></strong>.
|
|
<pre>
|
|
SSL_TIMEOUT_DEFAULT 0 (Use default timeout, 24 hours)
|
|
SSL_TIMEOUT_MAX 86400 (Use maximum timeout, 24 hours)
|
|
SSL_TIMEOUT_DISABLE 0xffffffff (Disable caching of session parameters
|
|
for abbreviated handshakes)
|
|
</pre>
|
|
</dd>
|
|
|
|
<dt>char <strong><em>reserved[12]</em></strong> (input)</dt>
|
|
|
|
<dd>This reserved field must be set to NULL (0s).</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. The certificate is stored in a key
|
|
database file.</p>
|
|
|
|
<br>
|
|
<h3>Return Value</h3>
|
|
|
|
<p>The <em>SSL_Init_Application()</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_CERT_EXPIRED]</em> </dt>
|
|
|
|
<dd>
|
|
<p>The validity time period of the certificate is expired.</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 found.</p>
|
|
</dd>
|
|
|
|
|
|
<dt><em>[SSL_ERROR_NOT_REGISTERED]</em> </dt>
|
|
|
|
<dd>
|
|
<p>The application identifier is not registered with the certificate registry
|
|
facility.</p>
|
|
</dd>
|
|
|
|
<dt><em>[SSL_ERROR_NOT_TRUSTED_ROOT]</em> </dt>
|
|
|
|
<dd>
|
|
<p>The certificate is not signed by a trusted certificate authority.</p>
|
|
</dd>
|
|
|
|
<dt><em>[SSL_ERROR_NO_CERTIFICATE]</em> </dt>
|
|
|
|
<dd>
|
|
<p>No certificate is available for SSL processing.</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_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>
|
|
|
|
<h3>Error Conditions</h3>
|
|
|
|
<p>When the <em>SSL_Init_Application()</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>applicationID</em> field contains a registered application
|
|
identifier to which the user is not authorized.</li>
|
|
|
|
<li>The user profile, which the application is operating under, is not
|
|
authorized to the key database file or its associated files.</li>
|
|
</ul>
|
|
</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_app</em> parameter or one of the address fields in the
|
|
<em>init_app</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.</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>Before the <em>SSL_Init_Application()</em> API can be used, the user must
|
|
have registered the application using the Register Application for Certificate
|
|
Use (OPM, QSYRGAP; ILE, QsyRegisterAppForCertUse) API. The Register Application
|
|
For Certificate Use API registers an application with the registry facility,
|
|
allowing an application to be associated with a specific certificate. The
|
|
Register Application for Certificate Use is described in the System Programming
|
|
Interface Reference. If the applicaiton is not registered with the registry
|
|
facility, then an error of SSL_ERROR_NOT_REGISTERED will be returned by
|
|
<em>SSL_Init_Application()</em>.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>A successful <em>SSL_Init()</em>, <em>SSL_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>SSL_Init (using NLS-enabled path name)</em>,
|
|
or multiple <em>SSL_Init()</em> APIs are
|
|
performed in a job, then only the values associated with the last
|
|
<em>SSL_Init_Application()</em>, <em>SSL_Init (using NLS-enabled path name)</em>, or <em>SSL_Init()</em> performed are
|
|
used.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>If the <em>SSL_Init_Application()</em> API or <em>SSL_Init()</em> API are
|
|
both performed in the same job, then only the values associated with the last
|
|
API performed are used.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>The reserved fields in the <strong><em>SSLInitApp</em></strong> structure
|
|
must be set to NULLs (0s) before using this API.</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="sslinit.htm">SSL_Init()</a>--Initialize the Current Job for
|
|
SSL<br><br></li>
|
|
|
|
<li><a href="sslhands.htm">SSL_Handshake()</a>--Initiate the SSL Handshake
|
|
Protocol<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: V4R4
|
|
|
|
<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>
|
|
|