friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
8826eae394
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/ictxbuildauthcontext.htm

500 lines
17 KiB
HTML
Raw Blame History

<!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>ictxBuildAuthContext()--Build Authentication Context</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: -->
<!-- YYMMDD USERID Change description -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</HEAD>
<BODY>
<!--Java sync-link-->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<A name=Top_Of_Page>
</A>
<!-- ============================================================== -->
<!-- -->
<!-- -->
<!-- ============================================================== -->
<H2>
ictxBuildAuthContext()--Build Authentication Context
</H2>
<!-- ============================================================== -->
<!-- -->
<!-- S Y N T A X / P A R M T A B L E -->
<!-- -->
<!-- ============================================================== -->
<div class="box" style="width: 90%;">
<BR>&nbsp;&nbsp;Syntax
<PRE>
#include &lt;ictx.h&gt;;
int ictxBuildAuthContext
(
char * <EM>contextTypeOID</EM>,
ictxAuthContextInfo_t * <EM>contextInfo</EM>,
ictxOptions_t * <EM>options</EM>,
ictxIdContext_t ** <EM>authContext</EM>,
ictxError_t * <EM>errorInfo</EM>
)
</PRE>
<BR>
&nbsp;&nbsp;Threadsafe: Yes<BR>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;See <a href="#eserver_notes">eServer Implementation Notes</a>
for details on platform-specific details for this API.<br>
<!-- iddvc RMBR -->
<br>
</div>
<!-- ============================================================== -->
<!-- -->
<!-- D E S C R I P T I O N -->
<!-- -->
<!-- ============================================================== -->
<P>The <STRONG>ictxBuildAuthContext()</STRONG> function
builds a new authentication context and returns the context to the caller.
The authentication context will contain the
information specified in the <em>contextInfo</em> parameter and
is dependent on the Authentication Context Type (OID).
</P>
<!-- ============================================================== -->
<!-- -->
<!-- A U T H O R I T I E S A N D L O C K S -->
<!-- -->
<!-- ============================================================== -->
<!-- See eServer notes. -->
<!-- ============================================================== -->
<!-- -->
<!-- P A R A M E T E R S -->
<!-- -->
<!-- ============================================================== -->
<BR>
<H3>Parameters</H3>
<DL>
<!-- ============================================================== -->
<!-- contextTypeOID -->
<!-- ============================================================== -->
<DT>
<STRONG>contextTypeOID</STRONG>&nbsp;&nbsp;(Input)
<DD>The type of authentication context to build. This is a NULL
terminated string that contains the object identifier (OID) that
identifies the context information.
<P>Valid values are:
<UL>
<LI>
0.0.0.0.0 Authentication Context Type 1
</LI>
</UL>
<BR>
<!-- ============================================================== -->
<!-- contextInfo -->
<!-- ============================================================== -->
<DT>
<STRONG>contextInfo</STRONG>&nbsp;&nbsp;(Input)
<DD>The information that is used to build the authentication context.
This information is dependent on the type of authentication context
that is to be built.
For the format of the structure, see the ictxAuthContextInfo structure in
the <A
href="ictxauthcontextinfo.htm">
ictxAuthContextInfo--Authentication Context Information Parameter</A>.
<BR>
<BR>
<!-- ============================================================== -->
<!-- options -->
<!-- ============================================================== -->
<DT>
<STRONG>options</STRONG>&nbsp;&nbsp;(Input)
<DD>The options that can be specified for the identity context
reference.
This parameter may be NULL. If this parameter is NULL, the default
values will be used for the options. For the format of the structure,
see <A href="ictxoptions.htm">
ictxOptions--Identity Context Options Parameter</A>.
<BR>
<BR>
<!-- ============================================================== -->
<!-- authContext -->
<!-- ============================================================== -->
<DT>
<STRONG>authContext</STRONG>&nbsp;&nbsp;(Output)
<DD>Return pointer to an authentication context object.
When this context is no longer needed,
it must be freed using the Free Identity Context (ictxFreeIdContext) API.
For the format of the structure, see the ictxIdContext structure in
the <A
href="ictxidcontext.htm">
ictxIdContext--Identity Context Parameter</A>.
<BR>
<BR>
<!-- ============================================================== -->
<!-- errorInfo -->
<!-- ============================================================== -->
<DT>
<STRONG>errorInfo</STRONG>&nbsp;&nbsp;(Output)
<DD>The structure in which to return error code information. If the return
value is not 0, <EM>errorInfo</EM> is set with additional information. This
parameter may be NULL. For the format of the structure, see <A
href="ictxerror.htm">ictxError--Identity
Context Return Code Parameter</A>.
<BR>
<BR>
</DD>
</DL>
<!-- ============================================================== -->
<!-- -->
<!-- R E T U R N V A L U E -->
<!-- -->
<!-- ============================================================== -->
<BR>
<H3>Return Value</H3>
<P>The return value from the API.</P>
<DL>
<!-- ============================================================== -->
<!-- 0 -->
<!-- ============================================================== -->
<DT>
<STRONG>0</STRONG>
<DD>Request was successful.
<BR>
<BR>
<!-- ============================================================== -->
<!-- Errors -->
<!-- ============================================================== -->
<DT>
<STRONG>ICTXERR_PARM_REQ (1)</STRONG>
<DD>Missing required parameter. Please check API documentation.
<BR>
<BR>
<DT>
<STRONG>ICTXERR_NOMEM (2)</STRONG>
<DD>No memory available. Unable to allocate required space.
<BR>
<BR>
<DT>
<STRONG>ICTXERR_OPTIONS_NOT_SUPPORTED (6)</STRONG>
<DD>Options are not supported.
<BR>
<BR>
<DT>
<STRONG>ICTXERR_TIMEOUT_INVALID (7)</STRONG>
<DD>Timeout value in options is not valid.
<BR>
<BR>
<DT>
<STRONG>ICTXERR_AUTH_CTX_TYPE_NOT_SUPPORTED (10)</STRONG>
<DD>Authentication Context Type is not supported.
<BR>
<BR>
<DT>
<STRONG>ICTXERR_CTXINFO_FORMAT_NOT_SUPPORTED (11)</STRONG>
<DD>Format for ictxAuthContextInfo is not supported for
this authentication context type.
<BR>
<BR>
<DT>
<STRONG>ICTXERR_AUTHINFO_FORMAT_NOT_SUPPORTED (12)</STRONG>
<DD>Format for ictxAuthInfo is not supported for
this authentication context type.
<BR>
<BR>
<DT>
<STRONG>ICTXERR_AUTHINFO_INVALID (13)</STRONG>
<DD>Error occurred with the ictxAuthInfo parameter.
May be missing required field for
this authentication context type.
<BR>
<BR>
<DT>
<STRONG>ICTXERR_DATA_CONVERSION (14)</STRONG>
<DD>Error occurred when converting data between code pages.
<BR>
<BR>
<DT>
<STRONG>ICTXERR_APPINFO_FORMAT_NOT_SUPPORTED (15)</STRONG>
<DD>Format for ictxAppInfo is not supported for
this authentication context type.
<BR>
<BR>
<DT>
<STRONG>ICTXERR_APPINFO_INVALID (16)</STRONG>
<DD>Error occurred with the ictxAppInfo parameter.
May be missing required field for
this authentication context type.
<BR>
<BR>
<DT>
<STRONG>ICTXERR_AUTHINFO_VERSION_NOT_SUPPORTED (21)</STRONG>
<DD>Error occurred with the ictxAuthInfo parameter.
The requested version is not supported.
<BR>
<BR>
<DT>
<STRONG>ICTXERR_APPINFO_VERSION_NOT_SUPPORTED (22)</STRONG>
<DD>Error occurred with the ictxAppInfo parameter.
The requested version is not supported.
<BR>
<BR>
<DT>
<STRONG>ICTXERR_PREMAPPEDINFO_VERSION_NOT_SUPPORTED (23)</STRONG>
<DD>Error occurred with the ictxPremappedInfo parameter.
The requested version is not supported.
<BR>
<BR>
<DT>
<STRONG>ICTXERR_PREMAPPEDINFO_FORMAT_NOT_SUPPORTED (24)</STRONG>
<DD>Format for ictxPremappedInfo is not supported for
this authentication context type.
<BR>
<BR>
<DT>
<STRONG>ICTXERR_PREMAPPEDINFO_INVALID (25)</STRONG>
<DD>Error occurred with the ictxPremappedInfo parameter.
May be missing required field for
this authentication context type.
<BR>
<BR>
<DT>
<STRONG>ICTXERR_CTXINFO_INVALID (27)</STRONG>
<DD>Error occurred with the ictxAuthContextInfo parameter.
May be missing required field for
this authentication context type.
<BR>
<BR>
</DD>
</DL>
<!-- ============================================================== -->
<!-- -->
<!-- U S A G E N O T E S -->
<!-- -->
<!-- ============================================================== -->
<!-- ============================================================== -->
<!-- -->
<!-- E S E R V E R N O T E S -->
<!-- -->
<!-- ============================================================== -->
<BR>
<h3>
<a name="eserver_notes">eServer Implementation Notes</a>
</h3>
<ol>
<li>
<strong>AIX implementation details:</strong>
<ul>
<li>
Authority: None
</li>
</ul>
</li>
<li>
<strong>Linux implementation details:</strong>
<ul>
<li>
Authority: None
</li>
</ul>
</li>
<li>
<strong>i5/OS implementation details:</strong><br>
<ul>
<li>
Service Program Name: QSYS/QSYICTX<br>
</li>
<li>
Authority: Default public authority *USE
</li>
</ul>
</li>
<li>
<strong>Windows implementation details:</strong>
<ul>
<li>
Authority: Users must have administrative privilege to
install and work with the APIs.
</li>
</ul>
</li>
<li>
<strong>z/OS implementation details:</strong><br>
<ul>
<li>
Authority: The caller of the API must be APF-authorized.
</li>
</ul>
</li>
</ol>
<!-- ============================================================== -->
<!-- -->
<!-- R E L A T E D I N F O R M A T I O N -->
<!-- -->
<!-- ============================================================== -->
<BR>
<H3>Related Information</H3>
<UL>
<LI>
<A href="ictxdelegateauthcontext.htm">ictxDelegateAuthContext()</A>
--Delegate Authentication Context<BR>
<BR>
</LI>
<LI>
<A href="ictxparseauthcontext.htm">ictxParseAuthContext()</A>
--Parse Authentication Context<BR>
<BR>
</LI>
<LI>
<A href="ictxfreeidcontext.htm">ictxFreeIdContext()</A>
--Free Identity Context Storage<BR>
<BR>
</LI>
<LI>
<A href="ictxfreeparseinfo.htm">ictxFreeParseInfo()</A>
--Free Authentication Context Parse Info Storage<BR>
<BR>
</LI>
</UL>
<BR>
<!-- ============================================================== -->
<!-- -->
<!-- E X A M P L E -->
<!-- -->
<!-- ============================================================== -->
<BR>
<h3>
Example
</h3>
<p>
The following example builds an authentication context.
<b>Note:</b> Read the <a href="codedisclaimer.htm">Code example disclaimer</a>
for important legal information.
</p>
<pre>
#include &lt;ictx.h&gt;
#include &lt;string.h&gt;
int buildAuthContext(ictxIdContext_t ** authContext)
{
int rc;
ictxAuthenticationInfo_t authInfo;
ictxAuthInfo_t authBlock;
ictxAppInfo_t sendBlock;
ictxApplicationInfo_t sender;
ictxAppInfo_t recvBlock;
ictxApplicationInfo_t receiver;
ictxAuthContextInfo_t ctxInfo;
ictxOptions_t options;
ictxError_t errorInfo;
/*----------------------------------------------------------------*/
/* Set up authentication information */
/*----------------------------------------------------------------*/
authInfo.user = &quot;MARY&quot;;
authInfo.registry = &quot;ldap084.rchland.ibm.com&quot;;
authInfo.hostName = &quot;toro4lab.ibm.com&quot;;
authInfo.authMech = &quot;LDAP&quot;;
authInfo.securityLabel = NULL;
authInfo.implemSpecific = NULL;
authBlock.format = ICTX_AUTH_INFO_FORMAT_0;
authBlock.authInfo.format0.version = 0;
authBlock.authInfo.format0.authInfo = &amp;authInfo;
/*----------------------------------------------------------------*/
/* Set up sender application information */
/*----------------------------------------------------------------*/
sender.appid = &quot;Favorite App&quot;;
sender.instance = &quot;PremierUsage/xxx/yyy&quot;;
sender.implemSpecific = NULL;
sendBlock.format = ICTX_APP_INFO_FORMAT_0;
sendBlock.appInfo.format0.version = 0;
sendBlock.appInfo.format0.appInfo = &amp;sender;
/*----------------------------------------------------------------*/
/* Set up receiver application information */
/*----------------------------------------------------------------*/
receiver.appid = &quot;Back end App&quot;;
receiver.instance = &quot;hostess with the mostest&quot;;
receiver.implemSpecific = NULL;
recvBlock.format = ICTX_APP_INFO_FORMAT_0;
recvBlock.appInfo.format0.version = 0;
recvBlock.appInfo.format0.appInfo = &amp;receiver;
/*----------------------------------------------------------------*/
/* Now combine all for the context information */
/*----------------------------------------------------------------*/
ctxInfo.format = ICTX_AUTHCTX_INFO_FORMAT_0;
ctxInfo.contextInfo.format0.authData = &amp;authBlock;
ctxInfo.contextInfo.format0.sender = &amp;sendBlock;
ctxInfo.contextInfo.format0.receiver = &amp;recvBlock;
ctxInfo.contextInfo.format0.premappedUser = NULL;
/*----------------------------------------------------------------*/
/* Set up options */
/*----------------------------------------------------------------*/
options.format = ICTX_OPTIONS_FORMAT_0;
options.options.format0.timeout = 600;
/*----------------------------------------------------------------*/
/* Build authentication context */
/*----------------------------------------------------------------*/
if (0 != (rc = ictxBuildAuthContext(ICTX_AUTH_CTX_TYPE1,
&amp;ctxInfo,
&amp;options,
authContext,
&amp;errorInfo)))
{
.
.
.
return -1;
}
return 0;
}
</pre>
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center">
<a href="#Top_Of_Page">Top</a> |
<a href="sec.htm">Security APIs</a> |
<a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</center>
</BODY>
</HTML>
Reference in New Issue View Git Blame Copy Permalink