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

678 lines
25 KiB
HTML
Raw Normal View History

Add readme and dist folders
2024-04-02 14:02:31 +00:00
<!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>eimFormatUserIdentity()--Format User Identity</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>eimFormatUserIdentity()--Format User Identity</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 eimFormatUserIdentity(
enum EimUserIdentityFormatType <em>formatType</em>,
EimUserIdentityInfo * <em>userIdentityInfo</em>,
unsigned int <em>lengthOfUserIdentity</em>,
EimUserIdentity * <em>userIdentity</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>eimFormatUserIdentity()</strong> function
takes unformatted user identity information and formats it for use
with other EIM functions.</p>
<!-- ============================================================== -->
<!-- -->
<!-- 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>
<p>No authorization is required.</p>
<!-- ============================================================== -->
<!-- -->
<!-- P A R A M E T E R S -->
<!-- -->
<!-- ============================================================== -->
<br>
<h3>Parameters</h3>
<dl>
<!-- ============================================================== -->
<!-- formatType -->
<!-- ============================================================== -->
<dt><strong>formatType</strong>&nbsp;&nbsp;(Input)</dt>
<dd>How to format the user identity.
<table cellpadding="5">
<!-- cols="35 65" -->
<tr>
<td align="left" valign="top"><em>EIM_REGISTRY_USER_NAME (0)</em></td>
<td align="left" valign="top">Format the user identity into a registry user name.
The registry user name will be
normalized according to the normalization method for the <em>registryType</em>.
This would be the registry user name
that would be used as input to the Add EIM Association (eimAddAssociation)
API. This data will be a NULL terminated string in the default CCSID of the job.
<p>For certificates, the registry user name will be a combination of the subject DN,
issuer DN, and a hash value of the subject DN, issuer DN, and public key.
The registry user name will be in the format
<em>&lt;SDN&gt;subject-DN&lt;/SDN&gt;&lt;IDN&gt;issuer-DN&lt;/IDN&gt;&lt;HASH_VAL&gt;hash-value&lt;/HASH_VAL&gt;</em>.
</td>
</tr>
</table>
</dd>
<!-- ============================================================== -->
<!-- userIdentityInfo -->
<!-- ============================================================== -->
<dt><strong>userIdentityInfo</strong>&nbsp;&nbsp;(Input)</dt>
<dd>The user identity information to format.
<p>The EimUserIdentityInfo structure contains information about the
user identity to format.</p>
<p>For EIM_DER_CERT (0) or EIM_BASE64_CERT (1) user identity type,
the <em>userIdentityInfo</em> field must contain an EimCertificate structure.</p>
<p>For EIM_CERT_INFO (2) user identity type,
the <em>userIdentityInfo</em> field must contain an EimCertificateInfo structure.</p>
<p>The structure layouts follow:</p>
<pre>
enum EimUserIdentityType {
EIM_DER_CERT, /* Entire X.509 public key
certificate in ASN.1 DER
encoding */
EIM_BASE64_CERT, /* Base 64 encoded version of the
entire X.509 public key
certificate in ASN.1 DER
encoding. */
EIM_CERT_INFO /* Components of the certificate. */
};
typedef struct EimCertificateInfo
{
char * issuerDN; /* The issuer DN. */
char * subjectDN; /* The subject DN. */
unsigned char * publicKey; /* The public key. */
unsigned int publicKeyLen; /* Length of the public key. */
} EimCertificateInfo;
typedef struct EimCertificate
{
unsigned int certLength; /* The length of the certificate
data. */
char * certData; /* The certificate data */
} EimCertificate;
typedef struct EimUserIdentityInfo
{
enum EimUserIdentityType type;
union {
EimCertificateInfo certInfo;
EimCertificate cert;
} userIdentityInfo;
} EimUserIdentityInfo;
</pre>
<p>If the <em>userIdentityInfo</em> field contains an EimCertificateInfo
structure, the <em>issuerDN</em> and <em>subjectDN</em> fields must contain
valid DN strings (for example,
<em>CN=John D. Smith,OU=Sales,O=IBM,L=Rochester,ST=Min,C=US</em>). The
<em>publicKey</em> field must contain the DER encoded public key
information structure, including the tags and lengths.</p>
<br>
<br>
<p>NOTE: EIM recognizes all of the suggested naming attributes from RFC 3280 with a few additions.
They are defined in the following table. If EIM encounters a naming attribute in a certificate
that it does not recognize, the OID for the naming attribute will be used instead in the filter
value. If you are using the eimCertificateInfo structure, the OID value for any naming
attribute that is not in this table may be used.
<br>
<br>
<table border width="80%">
<tr>
<th align="left" valign="bottom">OID</th>
<th align="left" valign="bottom">Naming Attribute</th>
<th align="left" valign="bottom">Description</th>
</tr>
<tr>
<td align="left" valign="top" width="30%">2.5.4.6</td>
<td align="left" valign="top" width="20%">c</td>
<td align="left" valign="top" width="50%">This attribute contains a two-letter ISO 3166
country or region code (countryName). RFC 3280.</td>
</tr>
<tr>
<td align="left" valign="top" width="30%">2.5.4.3</td>
<td align="left" valign="top" width="20%">cn</td>
<td align="left" valign="top" width="50%">This is the X.500 commonName attribute,
which contains a name of an object. If the object corresponds to a person,
it is typically the persons full name. RFC 3280.</td>
</tr>
<tr>
<td align="left" valign="top" width="30%">0.9.2342.19200300.100.1.25</td>
<td align="left" valign="top" width="20%">dc</td>
<td align="left" valign="top" width="50%">Specifies one component of a domain name.
RFC 3280.</td>
</tr>
<tr>
<td align="left" valign="top" width="30%">2.5.4.46</td>
<td align="left" valign="top" width="20%">dnQualifier</td>
<td align="left" valign="top" width="50%">The dnQualifier attribute type specifies
disambiguating information to add to the relative distinguished name of an entry.
It is intended for use when merging data from multiple sources in order to prevent conflicts
between entries which would otherwise have the same name. It is recommended that the value
of the dnQualifier attribute be the same for all entries from a particular source.
RFC3280.</td>
</tr>
<tr>
<td align="left" valign="top" width="30%">1.2.840.113549.1.9.1</td>
<td align="left" valign="top" width="20%">email</td>
<td align="left" valign="top" width="50%">E-mail address</td>
</tr>
<tr>
<td align="left" valign="top" width="30%">2.5.4.44</td>
<td align="left" valign="top" width="20%">generationQualifier</td>
<td align="left" valign="top" width="50%">Contains the part of the name which
typically is the suffix, as in IIIrd. RFC 3280.</td>
</tr>
<tr>
<td align="left" valign="top" width="30%">2.5.4.42</td>
<td align="left" valign="top" width="20%">givenName</td>
<td align="left" valign="top" width="50%">Used to hold the part of a persons
name which is not their surname nor middle name. RFC 3280.</td>
</tr>
<tr>
<td align="left" valign="top" width="30%">2.5.4.43</td>
<td align="left" valign="top" width="20%">initials</td>
<td align="left" valign="top" width="50%">The initials attribute contains
the initials of some or all of an individuals names, but not the surname(s).
RFC 3280.</td>
</tr>
<tr>
<td align="left" valign="top" width="30%">2.5.4.7</td>
<td align="left" valign="top" width="20%">l</td>
<td align="left" valign="top" width="50%">This attribute contains the name of a locality,
such as a city, county or other geographic region (localityName). RFC 3280.</td>
</tr>
<tr>
<td align="left" valign="top" width="30%">0.9.2342.19200300.100.1.3</td>
<td align="left" valign="top" width="20%">mail</td>
<td align="left" valign="top" width="50%">Identifies a user's primary e-mail address
(the e-mail address retrieved and displayed by &quot;white-pages&quot; lookup applications).</td>
</tr>
<tr>
<td align="left" valign="top" width="30%">2.5.4.41</td>
<td align="left" valign="top" width="20%">name</td>
<td align="left" valign="top" width="50%">The name attribute type is the attribute
supertype from which string attribute types typically used for naming may be formed.
It is unlikely that values of this type itself will occur in an entry.
RFC 3280.</td>
</tr>
<tr>
<td align="left" valign="top" width="30%">2.5.4.10</td>
<td align="left" valign="top" width="20%">o</td>
<td align="left" valign="top" width="50%">This attribute contains the name of an
organization (organizationName). RFC 3280.</td>
</tr>
<tr>
<td align="left" valign="top" width="30%">2.5.4.11</td>
<td align="left" valign="top" width="20%">ou</td>
<td align="left" valign="top" width="50%">This attribute contains the name of an
organizational unit (organizationalUnitName).
RFC 3280</td>
</tr>
<tr>
<td align="left" valign="top" width="30%">2.5.4.17</td>
<td align="left" valign="top" width="20%">postalCode</td>
<td align="left" valign="top" width="50%">This attribute type specifies the postal code
of the object. If the attribute value is present it will be part of the object's
postal address.</td>
</tr>
<tr>
<td align="left" valign="top" width="30%">2.5.4.65</td>
<td align="left" valign="top" width="20%">pseudonym</td>
<td align="left" valign="top" width="50%">According to RFC3039: &quot;pseudonym from
(forthcoming) X.520&quot;. RFC 3280.</td>
</tr>
<tr>
<td align="left" valign="top" width="30%">2.5.4.5</td>
<td align="left" valign="top" width="20%">serialNumber</td>
<td align="left" valign="top" width="50%">This attribute contains the serial
number of a device. RFC 3280.</td>
</tr>
<tr>
<td align="left" valign="top" width="30%">2.5.4.4</td>
<td align="left" valign="top" width="20%">sn</td>
<td align="left" valign="top" width="50%">This is the X.500 surname attribute,
which contains the family name of a person. RFC 3280.</td>
</tr>
<tr>
<td align="left" valign="top" width="30%">2.5.4.8</td>
<td align="left" valign="top" width="20%">st</td>
<td align="left" valign="top" width="50%">This attribute contains the full name
of a state or province (stateOrProvinceName). RFC 3280.</td>
</tr>
<tr>
<td align="left" valign="top" width="30%">2.5.4.9</td>
<td align="left" valign="top" width="20%">street</td>
<td align="left" valign="top" width="50%">This attribute contains the physical
address of the object to which the entry corresponds,
such as an address for package delivery (streetAddress).</td>
</tr>
<tr>
<td align="left" valign="top" width="30%">2.5.4.12</td>
<td align="left" valign="top" width="20%">title</td>
<td align="left" valign="top" width="50%">This attribute contains the title,
such as Vice President, of a person in their organizational context.
The personalTitle attribute would be used for a persons title independent
of their job function. RFC 3280.</td>
</tr>
<tr>
<td align="left" valign="top" width="30%">0.9.2342.19200300.100.1.1</td>
<td align="left" valign="top" width="20%">uid</td>
<td align="left" valign="top" width="50%">Typically a user shortname or userid.</td>
</tr>
<tr>
<td align="left" valign="top" width="30%">2.5.4.45</td>
<td align="left" valign="top" width="20%">x500UniqueIdentifier</td>
<td align="left" valign="top" width="50%">Used to distinguish between objects when
a distinguished name has been reused. This is a different attribute type from both
the &quot;uid&quot; and &quot;uniqueIdentifier&quot; types.</td>
</tr>
</table>
<br>
<br>
</dd>
<!-- ============================================================== -->
<!-- lengthOfUserIdentity -->
<!-- ============================================================== -->
<dt><strong>lengthOfUserIdentity</strong>&nbsp;&nbsp;(Input)</dt>
<dd>The number of bytes provided by the caller for the formatted
user identify.
Minimal size required is 16 bytes.
<br><br></dd>
<!-- ============================================================== -->
<!-- userIdentity -->
<!-- ============================================================== -->
<dt><strong>userIdentity</strong>&nbsp;&nbsp;(Output)</dt>
<dd>A pointer to the data to be returned.
<p>The EimUserIdentity structure contains information about the returned data.
The API will return as much data as space has been provided.</p>
<p>EimUserIdentity structure:</p>
<pre>
typedef struct EimUserIdentity
{
unsigned int bytesReturned; /* Number of bytes actually returned
by the API. */
unsigned int bytesAvailable; /* Number of bytes of available data
that could have been returned by
the API. */
EimListData userIdentity; /* User identity */
} EimUserIdentity;
</pre>
<p>EimListData structure:</p>
<pre>
typedef struct EimListData
{
unsigned int length; /* Length of data */
unsigned int disp; /* Displacement to data. This byte
offset is relative to the start of
the parent structure; that is, the
structure containing this
structure. */
} EimListData;
</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>
<!-- ============================================================== -->
<!-- EBADDATA -->
<!-- ============================================================== -->
<dt><strong>EBADDATA </strong></dt>
<dd>eimrc is not valid.<br>
<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="50 50" -->
<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_SPACE (41)</em></td>
<td align="left" valign="top">Unexpected error accessing parameter.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_USER_IDENTITY_TYPE_INVAL (63)</em></td>
<td align="left" valign="top">User identity type is not valid.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_USER_IDENTITY_SIZE (64)</em></td>
<td align="left" valign="top">Length of EimUserIdentity is not valid.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_USER_IDENTITY_FORMAT_TYPE_INVAL (65)</em></td>
<td align="left" valign="top">User identity format type is not valid.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_CERTIFICATE_INVAL (67)</em></td>
<td align="left" valign="top">Certificate data is not valid.</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>
<!-- ============================================================== -->
<!-- EUNKNOWN -->
<!-- ============================================================== -->
<dt><strong>EUNKNOWN </strong></dt>
<dd>Unexpected exception.<br>
<br>
<table cellpadding="5">
<!-- cols="25 75" -->
<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>
</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="eimaddassociation.htm">eimAddAssociation()</a>
--Add EIM Association<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 formats the user identity and adds an
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;
EimIdentifierInfo id;
EimUserIdentityInfo idInfo;
char rtnData[4000];
EimUserIdentity * fmtData = (EimUserIdentity * ) rtnData;
<em>/* Set up error structure. */</em>
memset(eimerr,0x00,100);
err = (EimRC *)eimerr;
err-&gt;memoryProvidedByCaller = 100;
<em>/* Get user identity information. */</em>
idInfo.type = EIM_DER_CERT;
idInfo.userIdentityInfo.cert.certLength = *((int *)argv[2]);
idInfo.userIdentityInfo.cert.certData = argv[3];
<em>/* Format user identity */</em>
if (0 != (rc = eimFormatUserIdentity(EIM_REGISTRY_USER_NAME,
&amp;idInfo,
4000,
fmtData,
err)))
{
printf(&quot;Format user identity error = %d&quot;, rc);
return -1;
}
<em>/* Get eim handle from input arg. */</em>
<em>/* This handle is already connected to EIM. */</em>
handle = (EimHandle *)argv[1];
<em>/* Set up identifier information */</em>
id.idtype = EIM_UNIQUE_NAME;
id.id.uniqueName = &quot;mjones&quot;;
<em>/* Add the source association */</em>
if (0 != (rc = eimAddAssociation(handle,
EIM_SOURCE,
&amp;id,
&quot;MyX509Registry&quot;,
(char *)fmtData + fmtData-&amp;gtuserIdentity.disp,
err)))
{
printf(&quot;Add Association error = %d&quot;, 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 Copy Permalink