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/eimaddpolicyassociation.htm

680 lines
24 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>eimAddPolicyAssociation()--Add EIM Policy Association</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 -->
<!-- Created by Therese Dalton on 17 July 2001 -->
<!-- Edited by Kersten Jan 02 -->
<!-- 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>eimAddPolicyAssociation()--Add EIM Policy Association</h2>
<!-- ============================================================== -->
<!-- -->
<!-- S Y N T A X / P A R M T A B L E -->
<!-- -->
<!-- ============================================================== -->
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;Syntax
<pre>
#include &lt;eim.h&gt;
int eimAddPolicyAssociation(EimHandle * <em>eim</em>,
EimPolicyAssociationInfo * <em>policyAssoc</em>,
EimRC * <em>eimrc</em>)
</pre>
&nbsp;&nbsp;Service Program Name: QSYS/QSYEIM<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<!-- ============================================================== -->
<!-- -->
<!-- D E S C R I P T I O N -->
<!-- -->
<!-- ============================================================== -->
<p>The <strong>eimAddPolicyAssociation()</strong> function adds the specified
policy association to the domain. A policy association is used to specify the
target association for a mapping lookup operation without having to define
specific source associations for all users. A policy association will be used
in a mapping lookup operation (eimGetTargetFromSource or
eimGetTargetFromIdentifier) if a specific source association does not exist.
</p>
<p>
<img src="delta.gif" alt="Start of change">
EIM version 2 must be supported by the local EIM APIs to use this API
(see <a href="eimgetversion.htm">eimGetVersion()</a>--Get EIM Version).
<img src="deltaend.gif" alt="End of change">
</p>
<p>
There are 3 types of policy associations that are supported:</p>
<ol>
<li>Certificate filter policy associations</li>
<li>Default registry policy associations</li>
<li>Default domain policy associations</li>
</ol>
<p>A certificate filter policy association is used to map user (or client)
certificates with similar attributes to the same target identity in the target
registry. For example, a certificate filter policy association can be added so
that all certificates issued by the same Certificate Authority (CA) are mapped
to the same target identity in the target registry. Or, all certificates from
the same organization are mapped to the same target identity in the target
registry.</p>
<p>A default registry policy association is used to map any user in the
specified source registry to the same target identity in the target
registry.</p>
<p>A default domain association policy is used to map all users to the same
target identity in the target registry.</p>
<p>
The use of policy associations is controlled by the version of the API interface, not the
domain. If policy associations are added to a domain, they will only be
used in a mapping lookup operation if the version of the mapping lookup API
that is used to access the domain supports policy associations.
<img src="delta.gif" alt="Start of change">
See <a href="eimmappinglookup.htm">EIM Mapping Lookup Algorithm</a>
for the affect that policy associations have on the mapping lookup operation.
</p>
<p>In the mapping lookup algorithm, there is a check to see if there is a
certificate policy filter value that matches the source identity.
<img src="deltaend.gif" alt="End of change">
To locate a certificate policy filter value, a search will be done using a
series of full and partial distinguished names (DNs) until the most specific
matching certificate policy filter value is found. The following values are
used in sequence to search for a matching certificate policy filter value:</p>
<ol>
<li><em>
&lt;SDN&gt;subject's-full-DN&lt;/SDN&gt;&lt;IDN&gt;issuer's-full-DN&lt;/IDN&gt;</em></li>
<li><em>
&lt;SDN&gt;subject's-partial-DN&lt;/SDN&gt;&lt;IDN&gt;issuer's-full-DN&lt;/IDN&gt;</em></li>
<li><em>&lt;SDN&gt;subject's-full-DN&lt;/SDN&gt;</em></li>
<li><em>&lt;SDN&gt;subject's-partial-DN&lt;/SDN&gt;</em></li>
<li><em>&lt;IDN&gt;issuer's-full-DN&lt;/IDN&gt;</em></li>
<li><em>&lt;IDN&gt;issuer's-partial-DN&lt;/IDN&gt;</em></li>
</ol>
<p>Note that searching is not done for the following values:</p>
<ul>
<li><em>
&lt;SDN&gt;subject's-full-DN&lt;/SDN&gt;&lt;IDN&gt;issuer's-partial-DN&lt;/IDN&gt;</em></li>
<li><em>
&lt;SDN&gt;subject's-partial-DN&lt;/SDN&gt;&lt;IDN&gt;issuer's-partial-DN&lt;/IDN&gt;</em></li>
</ul>
<p>Each step of the search using a partial DN may actually involve a series of
searches for partial name values based on the full DN. Each partial DN value in
the series is determined by removing the next most specific node in the DN.
The nodes are removed from the most specific to the least specific, in the order
that they appear in the DN.
<br>
<br>
<!-- ============================================================== -->
<!-- -->
<!-- A U T H O R I T I E S A N D L O C K S -->
<!-- -->
<!-- ============================================================== --><br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>EIM Data</em></dt>
<dd>Access to EIM data is controlled by EIM access groups. LDAP administrators
also have access to EIM data. The access groups whose members have authority to
the EIM data for this API follow:</dd>
<dd>
<ul>
<li>EIM Administrator</li>
<li>EIM Registries Administrator</li>
<li>EIM authority to an individual registry</li>
<dl>
<dd>This authority is needed to the target registry.</dd>
</dl>
</li>
</ul>
</dd>
</dl>
<!-- ============================================================== -->
<!-- -->
<!-- P A R A M E T E R S -->
<!-- -->
<!-- ============================================================== --><br>
<h3>Parameters</h3>
<dl><!-- ============================================================== -->
<!-- eim -->
<!-- ============================================================== -->
<dt><strong>eim</strong>&nbsp;&nbsp;(Input)</dt>
<dd>The EIM handle returned by a previous call to eimCreateHandle(). A valid
connection is required for this function.<br>
<br>
</dd>
<!-- ============================================================== -->
<!-- policyAssoc -->
<!-- ============================================================== -->
<dt><strong>policyAssoc</strong>&nbsp;&nbsp;(Input)</dt>
<dd>The information about the policy association to be added.
<p>The EimPolicyAssociationInfo structure contains information about the policy
association to add.</p>
<p>For EIM_CERT_FILTER_POLICY (6) association type, the <em>
policyAssociation</em> field must contain an
EimCertificateFilterPolicyAssociation structure. The <em>sourceRegistry</em>
field must contain the name of a registry that has a type of X.509. The
certificate filter policy value specified in the <em>filterValue</em> field
must have already been added using the Add EIM Policy Filter
(eimAddPolicyFilter) API.</p>
<p>For EIM_DEFAULT_REG_POLICY (7) association type, the <em>
policyAssociation</em> field must contain an
EimDefaultRegistryPolicyAssociation structure.</p>
<p>For EIM_DEFAULT_DOMAIN_POLICY (8) association type. the <em>
policyAssociation</em> field must contain an EimDefaultDomainPolicyAssociation
structure.</p>
<p>The structure layouts follow:</p>
<pre>
enum EimAssociationType {
EIM_ALL_ASSOC, /* Not supported on this interface*/
EIM_TARGET, /* Not supported on this interface*/
EIM_SOURCE, /* Not supported on this interface*/
EIM_SOURCE_AND_TARGET, /* Not supported on this interface*/
EIM_ADMIN, /* Not supported on this interface*/
EIM_ALL_POLICY_ASSOC, /* Not supported on this interface*/
EIM_CERT_FILTER_POLICY, /* Association is a certificate
filter policy association. */
EIM_DEFAULT_REG_POLICY, /* Association is a default
registry policy association */
EIM_DEFAULT_DOMAIN_POLICY /* Policy is a default policy for
the domain. */
};
typedef struct EimCertificateFilterPolicyAssociation
{
char * sourceRegistry; /* The source registry to add the
policy association to. */
char * filterValue; /* The filter value of the policy.*/
char * targetRegistry; /* The name of the target registry
that the filter value should
map to. */
char * targetRegistryUserName; /* The name of the target registry
user name that the filter value
should map to. */
} EimCertificateFilterPolicyAssociation;
typedef struct EimDefaultRegistryPolicyAssociation
{
char * sourceRegistry; /* The source registry to add the
policy association to. */
char * targetRegistry; /* The name of the target registry
that the policy should map to. */
char * targetRegistryUserName; /* The name of the target registry
user name that the policy
should map to. */
} EimDefaultRegistryPolicyAssociation;
typedef struct EimDefaultDomainPolicyAssociation
{
char * targetRegistry; /* The name of the target registry
that the policy should map to. */
char * targetRegistryUserName; /* The name of the target registry
user name that the policy
should map to. */
} EimDefaultDomainPolicyAssociation;
typedef struct EimPolicyAssociationInfo
{
enum EimAssociationType type;
union {
EimCertificateFilterPolicyAssociation certFilter;
EimDefaultRegistryPolicyAssociation defaultRegistry;
EimDefaultDomainPolicyAssociation defaultDomain;
} policyAssociation;
} EimPolicyAssociationInfo;
</pre>
</dd>
<!-- ============================================================== -->
<!-- eimrc -->
<!-- ============================================================== -->
<dt><strong>eimrc</strong>&nbsp;&nbsp;(Input/Output)</dt>
<dd>The structure in which to return error code information. If the return
value is not 0, eimrc is set with additional information. This parameter may be
NULL. For the format of the structure, see <a href="eimrc.htm">EimRC--EIM
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. Following each return value is the list of
possible values for the <samp>messageCatalogMessageID</samp> field in the <em>
eimrc</em> parameter for that value.</p>
<dl><!-- ============================================================== -->
<!-- 0 -->
<!-- ============================================================== -->
<dt><strong>0</strong></dt>
<dd>Request was successful.<br>
<br>
</dd>
<!-- ============================================================== -->
<!-- EACCES -->
<!-- ============================================================== -->
<dt><strong>EACCES</strong></dt>
<dd>Access denied. Not enough permissions to access data.<br>
<br>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>EIMERR_ACCESS (1)</em></td>
<td align="left" valign="top">Insufficient access to EIM data.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- EBADDATA -->
<!-- ============================================================== -->
<dt><strong>EBADDATA</strong></dt>
<dd>eimrc is not valid.<br>
<br>
</dd>
<!-- ============================================================== -->
<!-- EBADNAME -->
<!-- ============================================================== -->
<dt><strong>EBADNAME</strong></dt>
<dd>Registry name is not valid or insufficient access to EIM data, or policy
filter value is not found.<br>
<br>
<table cellpadding="5">
<!-- cols="30 70" -->
<tr>
<td align="left" valign="top"><em>EIMERR_NOREG (28)</em></td>
<td align="left" valign="top">EIM Registry not found or insufficient access to
EIM data.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_NOPOLICYFILTER (61)</em></td>
<td align="left" valign="top">Policy filter value not found for the specified
EIM Registry.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- EBUSY -->
<!-- ============================================================== -->
<dt><strong>EBUSY</strong></dt>
<dd>Unable to allocate internal system object.<br>
<br>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>EIMERR_NOLOCK (26)</em></td>
<td align="left" valign="top">Unable to allocate internal system object.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- ECONVERT -->
<!-- ============================================================== -->
<dt><strong>ECONVERT</strong></dt>
<dd>Data conversion error.<br>
<br>
<table cellpadding="5">
<!-- cols="35 65" -->
<tr>
<td align="left" valign="top"><em>EIMERR_DATA_CONVERSION (13)</em></td>
<td align="left" valign="top">Error occurred when converting data between code
pages.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- EINVAL -->
<!-- ============================================================== -->
<dt><strong>EINVAL</strong></dt>
<dd>Input parameter was not valid.<br>
<br>
<table cellpadding="5">
<!-- cols="40 60" -->
<tr>
<td align="left" valign="top"><em>EIMERR_ASSOC_TYPE_INVAL (4)</em></td>
<td align="left" valign="top">Association type is not valid.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_HANDLE_INVAL (17)</em></td>
<td align="left" valign="top">EimHandle is not valid.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_PARM_REQ (34)</em></td>
<td align="left" valign="top">Missing required parameter. Please check API
documentation.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_PTR_INVAL (35)</em></td>
<td align="left" valign="top">Pointer parameter is not valid.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_FUNCTION_NOT_SUPPORTED (70)</em></td>
<td align="left" valign="top">The specified function is not supported
by the EIM version.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- ENOMEM -->
<!-- ============================================================== -->
<dt><strong>ENOMEM</strong></dt>
<dd>Unable to allocate required space.<br>
<br>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>EIMERR_NOMEM (27)</em></td>
<td align="left" valign="top">No memory available. Unable to allocate required
space.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- ENOTCONN -->
<!-- ============================================================== -->
<dt><strong>ENOTCONN</strong></dt>
<dd>LDAP connection has not been made.<br>
<br>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>EIMERR_NOT_CONN (31)</em></td>
<td align="left" valign="top">Not connected to LDAP. Use eimConnect() API and
try the request again.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- EROFS -->
<!-- ============================================================== -->
<dt><strong>EROFS</strong></dt>
<dd>LDAP connection is for read only. Need to connect to master.<br>
<br>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>EIMERR_READ_ONLY (36)</em></td>
<td align="left" valign="top">LDAP connection is for read only. Use
eimConnectToMaster() to get a write connection.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- EUNKNOWN -->
<!-- ============================================================== -->
<dt><strong>EUNKNOWN</strong></dt>
<dd>Unexpected exception.<br>
<br>
<table cellpadding="5">
<!-- cols="40 60" -->
<tr>
<td align="left" valign="top"><em>EIMERR_LDAP_ERR (23)</em></td>
<td align="left" valign="top">Unexpected LDAP error. %s</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_UNKNOWN (44)</em></td>
<td align="left" valign="top">Unknown error or unknown system state.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_UNEXP_OBJ_ VIOLATION (56)</em></td>
<td align="left" valign="top">Unexpected object violation.</td>
</tr>
</table>
</dd>
</dl>
<!-- ============================================================== -->
<!-- -->
<!-- U S A G E N O T E S -->
<!-- -->
<!-- ============================================================== -->
<!-- ============================================================== -->
<!-- -->
<!-- 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="eimremovepolicyassociation.htm">eimRemovePolicyAssociation()</a>
--Remove EIM Policy Association<br>
<br>
</li>
<li><a href="eimlistregistryassociations.htm">eimListRegistryAssociations()</a>
--List EIM Registry Associations<br>
<br>
</li>
<li><a href="eimformatpolicyfilter.htm">eimFormatPolicyFilter()</a> --Format
EIM Policy Filter<br>
<br>
</li>
<li><a href="eimaddpolicyfilter.htm">eimAddPolicyFilter()</a> --Add EIM Policy
Filter<br>
<br>
</li>
<li><a href="eimchangedomain.htm">eimChangeDomain()</a> --Change EIM Domain<br>
<br>
</li>
<li><a href="eimchangeregistry.htm">eimChangeRegistry()</a> --Change EIM
Registry<br>
<br>
</li>
<li><a href="eimgettargetfromsource.htm">eimGetTargetFromSource()</a> --Get EIM
Target Identities from the Source<br>
<br>
</li>
<li><a href="eimgettargetfromidentifier.htm">eimGetTargetFromIdentifier()</a>
--Get EIM Target Identities from the Identifier<br>
<br>
</li>
</ul>
<br>
<!-- ============================================================== -->
<!-- -->
<!-- E X A M P L E -->
<!-- -->
<!-- ============================================================== -->
<h3>Example</h3>
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
for information pertaining to code examples.</p>
<p>The following example adds a default registry policy association.</p>
<pre>
#include &lt;eim.h&gt;
#include &lt;stddef.h&gt;
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
int main (int argc, char *argv[])
{
int rc;
char eimerr[100];
EimRC * err;
EimHandle * handle;
EimPolicyAssociationInfo assocInfo;
<em>/* Set up error structure. */</em>
memset(eimerr,0x00,100);
err = (EimRC *)eimerr;
err-&gt;memoryProvidedByCaller = 100;
<em>/* Get eim handle from input arg. */</em>
<em>/* This handle is already connected to EIM. */</em>
handle = (EimHandle *)argv[1];
<em>/* Set up policy association information */</em>
assocInfo.type = EIM_DEFAULT_REG_POLICY;
assocInfo.policyAssociation.defaultRegistry.sourceRegistry = "MySourceRegistry";
assocInfo.policyAssociation.defaultRegistry.targetRegistry = "localRegistry";
assocInfo.policyAssociation.defaultRegistry.targetRegistryUserName = "mjjones";
<em>/* Add the policy association */</em>
if (0 != (rc = eimAddPolicyAssociation(handle,
&amp;assocInfo,
err)))
{
printf("Add EIM Policy Association error = %d", rc);
return -1;
}
return 0;
}
</pre>
<br>
<!-- ============================================================== -->
<!-- -->
<!-- F O O T E R -->
<!-- -->
<!-- ============================================================== -->
<br>
<hr>
API introduced: V5R3
<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