522 lines
17 KiB
HTML
522 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>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> Syntax
|
||
|
|
<PRE>
|
||
|
|
#include <ictx.h>;
|
||
|
|
|
||
|
|
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>
|
||
|
|
Threadsafe: Yes<BR>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
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> (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> (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> (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> (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> (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 <ictx.h>
|
||
|
|
#include <string.h>
|
||
|
|
|
||
|
|
|
||
|
|
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 = "Back end App";
|
||
|
|
sender.instance = "hostess with the mostest";
|
||
|
|
sender.implemSpecific = NULL;
|
||
|
|
|
||
|
|
sendBlock.format = ICTX_APP_INFO_FORMAT_0;
|
||
|
|
sendBlock.appInfo.format0.version = 0;
|
||
|
|
sendBlock.appInfo.format0.appInfo = &sender;
|
||
|
|
|
||
|
|
/*----------------------------------------------------------------*/
|
||
|
|
/* Set up receiver application information */
|
||
|
|
/*----------------------------------------------------------------*/
|
||
|
|
receiver.appid = "On the road again";
|
||
|
|
receiver.instance = "Nelson";
|
||
|
|
receiver.implemSpecific = NULL;
|
||
|
|
|
||
|
|
recvBlock.format = ICTX_APP_INFO_FORMAT_0;
|
||
|
|
recvBlock.appInfo.format0.version = 0;
|
||
|
|
recvBlock.appInfo.format0.appInfo = &receiver;
|
||
|
|
|
||
|
|
/*----------------------------------------------------------------*/
|
||
|
|
/* Now combine all for the context information */
|
||
|
|
/*----------------------------------------------------------------*/
|
||
|
|
ctxInfo.format = ICTX_AUTHCTX_INFO_FORMAT_1;
|
||
|
|
ctxInfo.contextInfo.format1.sender = &sendBlock;
|
||
|
|
ctxInfo.contextInfo.format1.receiver = &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,
|
||
|
|
&ctxInfo,
|
||
|
|
&options,
|
||
|
|
authContext,
|
||
|
|
&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>
|