#include <eim.h>
int eimFormatUserIdentity(
enum EimUserIdentityFormatType formatType,
EimUserIdentityInfo * userIdentityInfo,
unsigned int lengthOfUserIdentity,
EimUserIdentity * userIdentity,
EimRC * eimrc)
Service Program Name: QSYS/QSYEIMThe eimFormatUserIdentity() function takes unformatted user identity information and formats it for use with other EIM functions.
No authorization is required.
| EIM_REGISTRY_USER_NAME (0) | Format the user identity into a registry user name.
The registry user name will be
normalized according to the normalization method for the registryType.
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.
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 <SDN>subject-DN</SDN><IDN>issuer-DN</IDN><HASH_VAL>hash-value</HASH_VAL>. |
The EimUserIdentityInfo structure contains information about the user identity to format.
For EIM_DER_CERT (0) or EIM_BASE64_CERT (1) user identity type, the userIdentityInfo field must contain an EimCertificate structure.
For EIM_CERT_INFO (2) user identity type, the userIdentityInfo field must contain an EimCertificateInfo structure.
The structure layouts follow:
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;
If the userIdentityInfo field contains an EimCertificateInfo structure, the issuerDN and subjectDN fields must contain valid DN strings (for example, CN=John D. Smith,OU=Sales,O=IBM,L=Rochester,ST=Min,C=US). The publicKey field must contain the DER encoded public key information structure, including the tags and lengths.
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.
| OID | Naming Attribute | Description |
|---|---|---|
| 2.5.4.6 | c | This attribute contains a two-letter ISO 3166 country or region code (countryName). RFC 3280. |
| 2.5.4.3 | cn | 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. |
| 0.9.2342.19200300.100.1.25 | dc | Specifies one component of a domain name. RFC 3280. |
| 2.5.4.46 | dnQualifier | 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. |
| 1.2.840.113549.1.9.1 | E-mail address | |
| 2.5.4.44 | generationQualifier | Contains the part of the name which typically is the suffix, as in IIIrd. RFC 3280. |
| 2.5.4.42 | givenName | Used to hold the part of a persons name which is not their surname nor middle name. RFC 3280. |
| 2.5.4.43 | initials | The initials attribute contains the initials of some or all of an individuals names, but not the surname(s). RFC 3280. |
| 2.5.4.7 | l | This attribute contains the name of a locality, such as a city, county or other geographic region (localityName). RFC 3280. |
| 0.9.2342.19200300.100.1.3 | Identifies a user's primary e-mail address (the e-mail address retrieved and displayed by "white-pages" lookup applications). | |
| 2.5.4.41 | name | 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. |
| 2.5.4.10 | o | This attribute contains the name of an organization (organizationName). RFC 3280. |
| 2.5.4.11 | ou | This attribute contains the name of an organizational unit (organizationalUnitName). RFC 3280 |
| 2.5.4.17 | postalCode | 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. |
| 2.5.4.65 | pseudonym | According to RFC3039: "pseudonym from (forthcoming) X.520". RFC 3280. |
| 2.5.4.5 | serialNumber | This attribute contains the serial number of a device. RFC 3280. |
| 2.5.4.4 | sn | This is the X.500 surname attribute, which contains the family name of a person. RFC 3280. |
| 2.5.4.8 | st | This attribute contains the full name of a state or province (stateOrProvinceName). RFC 3280. |
| 2.5.4.9 | street | This attribute contains the physical address of the object to which the entry corresponds, such as an address for package delivery (streetAddress). |
| 2.5.4.12 | title | 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. |
| 0.9.2342.19200300.100.1.1 | uid | Typically a user shortname or userid. |
| 2.5.4.45 | x500UniqueIdentifier | Used to distinguish between objects when a distinguished name has been reused. This is a different attribute type from both the "uid" and "uniqueIdentifier" types. |
The EimUserIdentity structure contains information about the returned data. The API will return as much data as space has been provided.
EimUserIdentity structure:
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;
EimListData structure:
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;
The return value from the API. Following each return value is the list of possible values for the messageCatalogMessageID field in the eimrc parameter for that value.
| EIMERR_DATA_CONVERSION (13) | Error occurred when converting data between code pages. |
| EIMERR_PARM_REQ (34) | Missing required parameter. Please check API documentation. |
| EIMERR_PTR_INVAL (35) | Pointer parameter is not valid. |
| EIMERR_SPACE (41) | Unexpected error accessing parameter. |
| EIMERR_USER_IDENTITY_TYPE_INVAL (63) | User identity type is not valid. |
| EIMERR_USER_IDENTITY_SIZE (64) | Length of EimUserIdentity is not valid. |
| EIMERR_USER_IDENTITY_FORMAT_TYPE_INVAL (65) | User identity format type is not valid. |
| EIMERR_CERTIFICATE_INVAL (67) | Certificate data is not valid. |
| EIMERR_NOMEM (27) | No memory available. Unable to allocate required space. |
| EIMERR_UNKNOWN (44) | Unknown error or unknown system state. |
See Code disclaimer information for information pertaining to code examples.
The following example formats the user identity and adds an association.
#include <eim.h>
#include <stddef.h>
#include <stdio.h>
#include <stdlib.h>
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;
/* Set up error structure. */
memset(eimerr,0x00,100);
err = (EimRC *)eimerr;
err->memoryProvidedByCaller = 100;
/* Get user identity information. */
idInfo.type = EIM_DER_CERT;
idInfo.userIdentityInfo.cert.certLength = *((int *)argv[2]);
idInfo.userIdentityInfo.cert.certData = argv[3];
/* Format user identity */
if (0 != (rc = eimFormatUserIdentity(EIM_REGISTRY_USER_NAME,
&idInfo,
4000,
fmtData,
err)))
{
printf("Format user identity error = %d", rc);
return -1;
}
/* Get eim handle from input arg. */
/* This handle is already connected to EIM. */
handle = (EimHandle *)argv[1];
/* Set up identifier information */
id.idtype = EIM_UNIQUE_NAME;
id.id.uniqueName = "mjones";
/* Add the source association */
if (0 != (rc = eimAddAssociation(handle,
EIM_SOURCE,
&id,
"MyX509Registry",
(char *)fmtData + fmtData->userIdentity.disp,
err)))
{
printf("Add Association error = %d", rc);
return -1;
}
return 0;
}
| Top | Security APIs | APIs by category |