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.




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. This parameter is passed by value.

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.


EINVAL
Input parameter was not valid.


ENOMEM
Unable to allocate required space.


EUNKNOWN
Unexpected exception.


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 ]