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

522 lines
17 KiB
HTML
Raw Permalink 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>ictxDelegateAuthContext()--Delegate 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>
ictxDelegateAuthContext()--Delegate 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 ictxDelegateAuthContext
(
ictxIdContext_t * <EM>inAuthContext</EM>,
ictxAuthContextInfo_t * <EM>delegateInfo</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.
<!-- iddvc RMBR -->
<br>
</div>
<!-- ============================================================== -->
<!-- -->
<!-- D E S C R I P T I O N -->
<!-- -->
<!-- ============================================================== -->
<P>The <STRONG>ictxDelegateAuthContext()</STRONG> function
validates the authentication context represented by the
input authentication context,
and adds another context manifest to
the authentication context. The new context manifest
will contain the
information specified in the <em>contextInfo</em> parameter and
is dependent on the Authentication Context Type (OID).
The new authentication context is returned to the caller.</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>
<!-- ============================================================== -->
<!-- inAuthContext -->
<!-- ============================================================== -->
<DT>
<STRONG>inAuthContext</STRONG>&nbsp;&nbsp;(Input)
<DD>The authentication context to delegate.
The identity context OID indicates the type of authentication
context that is being delegated and returned.
This OID should match the OID in the identity context.
For the format of the structure, see the ictxIdContext structure in
the <A
href="ictxidcontext.htm">
ictxIdContext--Identity Context Parameter</A>.
<BR>
<BR>
<!-- ============================================================== -->
<!-- delegateInfo -->
<!-- ============================================================== -->
<DT>
<STRONG>delegateInfo</STRONG>&nbsp;&nbsp;(Input)
<DD>The information to be added to 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_IDCONTEXT_INVALID (4)</STRONG>
<DD>Identity context parameter is not valid.
The OID and identity context are required. The identity context
length must be greater than 0.
<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_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_AUTH_CONTEXT_INVALID (17)</STRONG>
<DD>Error occurred parsing the authentication
context.
<BR>
<BR>
<DT>
<STRONG>ICTXERR_OID_MISMATCH (18)</STRONG>
<DD>The authentication type requested does not the
authentication context type found in the context.
<BR>
<BR>
<DT>
<STRONG>ICTXERR_CTX_EXPIRED (19)</STRONG>
<DD>The authentication context has expired.
<BR>
<BR>
<DT>
<STRONG>ICTXERR_CTX_LEN_MISMATCH (20)</STRONG>
<DD>Error occurred parsing the authentication
context. Input length not correct.
<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_CTX_NOT_YET_VALID (26)</STRONG>
<DD>The authentication context is not yet valid.
<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="ictxbuildauthcontext.htm">ictxBuildAuthContext()</A>
--Build 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>
<BR>
<!-- ============================================================== -->
<!-- -->
<!-- E X A M P L E -->
<!-- -->
<!-- ============================================================== -->
<BR>
<h3>
Example
</h3>
<p>
The following example delegates 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 delegateAuthContext(ictxIdContext_t * contextToDelegate,
ictxIdContext_t ** authContext)
{
int rc;
ictxAppInfo_t sendBlock;
ictxApplicationInfo_t sender;
ictxAppInfo_t recvBlock;
ictxApplicationInfo_t receiver;
ictxAuthContextInfo_t ctxInfo;
ictxOptions_t options;
ictxError_t errorInfo;
/*----------------------------------------------------------------*/
/* Set up sender application information */
/*----------------------------------------------------------------*/
sender.appid = &quot;Back end App&quot;;
sender.instance = &quot;hostess with the mostest&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;On the road again&quot;;
receiver.instance = &quot;Nelson&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_1;
ctxInfo.contextInfo.format1.sender = &amp;sendBlock;
ctxInfo.contextInfo.format1.receiver = &amp;recvBlock;
ctxInfo.contextInfo.format1.premappedUser = NULL;
/*----------------------------------------------------------------*/
/* Set up options */
/*----------------------------------------------------------------*/
options.format = ICTX_OPTIONS_FORMAT_0;
options.options.format0.timeout = 600;
/*----------------------------------------------------------------*/
/* Delegate authentication context */
/*----------------------------------------------------------------*/
if (0 != (rc = ictxDelegateAuthContext(contextToDelegate,
&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