eimFormatPolicyFilter()--Format EIM Policy Filter


  Syntax 
 #include <eim.h>

 int eimFormatPolicyFilter(EimUserIdentityInfo         * userIdentityInfo,
                           EimPolicyFilterSubsetInfo   * subsetInfo,
                           unsigned int                  lengthOfListData,
                           EimList                     * listData,
                           EimRC                       * eimrc)
  Service Program Name: QSYS/QSYEIM

  Default Public Authority: *USE

  Threadsafe: Yes

The eimFormatPolicyFilter() function takes unformatted user identity information and generates a policy filter value for use with the Add EIM Policy Filter (eimAddPolicyFilter) API.

Certificate policy filter details

A formatted certificate policy filter value will contain a combination of the subject and issuer full and partial distinguished names (DNs). The following are the different combinations that can be generated, based on the subjectFilter and issuerFilter values:

Note that the following combinations can be generated, but would never be used when doing a mapping lookup:

Specifying a value for the subjectFilter or issuerFilter fields in the subsetInfo parameter will determine the content of the policy filter. If the subsetInfo parameter is NULL, then all possible valid certificate policy filter values will be returned.

Specifying a value for the subjectFilter field indicates that the subject DN information should be included in the policy filter value, and where in the DN to start generating the subject DN value. For example, specifying "OU=" for the subjectFilter field will start generating the subject DN portion of the value with the OU node (will not include any nodes before the OU node). Specifying a value for the issuerFilter field indicates that the issuer DN information should be included in the policy filter value, and where in the DN to start generating the issuer DN value. If NULL is specified for both the subjectFilter field and the issuerFilter field, the policy filter value will contain the subject's full DN and the issuer's full DN.

When using the issuer or subject filter value, the value specified in the filter value must exist in the DN.

Given a certificate, where the subject DN is:

CN=John D. Smith,OU=Sales,O=IBM,L=Rochester,ST=Min,C=US

and the issuer DN is:

OU=VeriSign Class 1 Individual Subscriber,O=VeriSign,L=Internet

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 email 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 mail 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.

Authorities and Locks

No authorization is required.


Parameters

userIdentityInfo  (Input)
The user identity information from which to generate policy filter values.

The EimUserIdentityInfo structure contains information about the user identity.

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 (may be NULL).  */
       unsigned int    publicKeyLen;   /* Length of public key (may be 0)*/
   } EimCertificateInfo;

   typedef struct EimCertificate
   {
       char        * certData;         /* The certificate data           */
       unsigned int certLength;        /* The length of 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.


subsetInfo  (Input)
The information used to subset the policy filter values that are formatted. If NULL is specified for this parameter, then the returned data will contain all possible policy filter values for the specified user identity information. This option would be useful if you wanted to present the user with a list of possible policy filter values from which to choose. If this parameter is not NULL, then only one policy filter value will be returned based on the specified subset information.

The EimPolicyFilterSubsetInfo structure contains information for subsetting the return data. The information provided in the structure is dependent on the user identity type in the userIdentityInfo parameter.

For EIM_BASE64_CERT (0), EIM_DER_CERT (1), or EIM_CERT_INFO (2) user identity type, the subset field must contain an EimCertPolicyFilterSubsetInfo structure.

The structure layouts follow:

   typedef struct EimCertPolicyFilterSubsetInfo
   {
       char        * subjectFilter;    /* Subject filter value.          */
       char        * issuerFilter;     /* Issuer filter value.           */
   } EimCertPolicyFilterSubsetInfo;

   typedef struct EimPolicyFilterSubsetInfo
   {
       union {
           EimCertPolicyFilterSubsetInfo   certFilter;
       } subset;
   } EimPolicyFilterSubsetInfo;


lengthOfListData  (Input)
The number of bytes provided by the caller for the listData parameter. The minimum size required is 20 bytes.

listData  (Output)
A pointer to the EimList structure.

The EimList structure contains information about the returned data. The API will return as much data as space has been provided. The data returned is a linked list of EimPolicyFilterValue structures. firstEntry is used to get to the first EimPolicyFilterValue structure in the linked list.

EimList structure:

   typedef struct EimList
   {
       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                          */
       unsigned int entriesReturned;   /* Number of entries actually
                                        returned by the API              */
       unsigned int entriesAvailable;  /* Number of entries available to be
                                        returned by the API              */
       unsigned int firstEntry;        /* Displacement to the first linked
                                        list entry. This byte offset is
                                        relative to the start of the
                                        EimList structure.               */
   } EimList;

EimPolicyFilterValue structure:

   typedef struct EimPolicyFilterValue    
   {
       unsigned int nextEntry;         /* Displacement to next entry.  This
                                        byte offset is relative to the
                                        start of this structure          */
       EimListData filterValue;        /* Generated policy filter value. */
 } EimPolicyFilterValue;

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;
eimrc  (Input/Output)
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 EimRC--EIM Return Code Parameter.


Return Value

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.

0
Request was successful.

EBADDATA
eimrc is not valid.

ECONVERT
Data conversion error.

EIMERR_DATA_CONVERSION (13) Error occurred when converting data between code pages.

EINVAL
Input parameter was not valid.

EIMERR_EIMLIST_SIZE (16) Length of EimList is not valid. EimList must be at least 20 bytes in length.
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_CERTIFICATE_INVAL (67) Certificate data is not valid.

ENOMEM
Unable to allocate required space.

EIMERR_NOMEM (27) No memory available. Unable to allocate required space.

EUNKNOWN
Unexpected exception.

EIMERR_UNKNOWN (44) Unknown error or unknown system state.

Related Information


Example

The following example generates certificate policy filter values.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#include <eim.h>
#include <stddef.h>
#include <stdio.h>
#include <stdlib.h>

void printListResults(EimList * list);
void printListData(char * fieldName,
                   void * entry,
                   int offset);

int main (int argc, char *argv[])
{
    int           rc;
    char          eimerr[100];
    EimRC       * err;
    EimHandle   * handle;
    EimUserIdentityInfo  idInfo;
    char          listData[4000];
    EimList     * list = (EimList * ) listData;

    /* 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 EIM Policy Filter                 */
    /* This call will return all possible       */
    /* certificate policy filter values.        */
    if (0 != (rc = eimFormatPolicyFilter(&idInfo,
                                         NULL,
                                         4000,
                                         list,
                                         err)))
    {
        printf("Format EIM Policy Filter error = %d", rc);
        return -1;
    }


    /* Print the results                        */
    printListResults(list);
    
    return 0;
        
}
            
void printListResults(EimList * list)
{
    int i;
    EimPolicyFilterValue * entry;

    printf("___________\n");
    printf("   bytesReturned    = %d\n", list->bytesReturned);
    printf("   bytesAvailable   = %d\n", list->bytesAvailable);
    printf("   entriesReturned  = %d\n", list->entriesReturned);
    printf("   entriesAvailable = %d\n", list->entriesAvailable);
    printf("\n");

    entry = (EimPolicyFilterValue *)((char *)list + list->firstEntry);
    for (i = 0; i < list->entriesReturned; i++)
    {
        printf("\n");
        printf("===============\n");
        printf("Entry %d.\n", i);
        
        /* Print out results */
        printListData("Policy Filter Value",
                      entry,
                      offsetof(EimPolicyFilterValue, filterValue));

        /* advance to next entry */
        entry = (EimPolicyFilterValue *)((char *)entry + entry->nextEntry);

    }
    printf("\n");


}

void printListData(char * fieldName,
                   void * entry,
                   int offset)
{
    EimListData * listData;
    char * data;
    int dataLength;

    printf("     %s = ",fieldName);
    /* Address the EimListData object */
    listData = (EimListData *)((char *)entry + offset);
    
    /* Print out results */
    data = (char *)entry + listData->disp;
    dataLength = listData->length;
    
    if (dataLength > 0)
        printf("%.*s\n",dataLength, data);
    else
        printf("Not found.\n");
        
}


API introduced: V5R3

[ Back to top | Security APIs | APIs by category ]