IBM LDAP Data Library, Version 1.0

The files required for the LDAP Data Library, Version 1.0 are:

  • ldapdl.so
  • ldapdl.h

The IBM LDAP Data Library provides access to generic and security-related objects (for example, certificates, certificate revocation lists) stored in LDAP-compliant directory servers. This module is semantic-free and allows the application developer to specify any attribute types specified in the schema of the destination LDAP server. Table 16 lists the OCSF LDAP Data Library API functions that this module supports.

All errors returned by this module are in ldapdl.h. If an error occurs within this module, it is possible to determine the exact cause of the error by enabling exception logging. The environment variable LDAPDL_LOG may be set to a file in which all exceptions will be logged by this module. If an error occurs, it is possible to look in the specified file to get an object dump of the exception, which will indicate the file and line number where the error occurred, therefore allowing the module developer to determine the exact cause of the failure. The use of the LDAP_DL log can supplement the information provided by CSSM since in some instances LDAP_DL can throw an exception without that necessarily resulting in a call to "CSSM_SetError".

Table 1. IBM LDAP Data Library OCSF Functions
Function Name Supported Comments
CSSM_DL_Authenticate Yes See Note 1
CSSM_DL_DbOpen Yes See Note 2.
CSSM_DL_DbClose Yes The DLHandle parameter must not be NULL. The DBHandle parameter must reference an opened LDAP session.
CSSM_DL_DbCreate No  
CSSM_DL_DbDelete No  
CSSM_DL_DbImport No  
CSSM_DL_DbExport Yes See Note 3.
CSSM_DL_DbSetRecordParsingFunctions No  
CSSM_DL_DbGetRecordParsingFunctions No  
CSSM_DL_GetDbNameFromHandle Yes DLHandle parameter must not be NULL. DBHandle parameter must reference an opened LDAP session.
CSSM_DL_DataInsert Yes The DLHandle, Attributes, and Data parameters must not be NULL. DBHandle parameter must reference an opened LDAP session.
CSSM_DL_DataDelete Yes The DLHandle parameter must not be NULL. DBHandle must reference an opened LDAP session. UniqueRecordIdentifier must not be NULL.
CSSM_DL_DataGetFirst Yes See Note 4.
CSSM_DL_DataGetNext Yes See Note 5.
CSSM_DL_FreeUniqueRecord Yes The DLHandle parameter must not be NULL. The DBHandle parameter is ignored.
CSSM_DL_AbortQuery Yes The DLHandle parameter must not be NULL. DBHandle must reference an opened LDAP session. ResultsHandle must reference a valid query.
CSSM_DL_PassThrough Yes See Note 6.
Note:
  1. CSSM_DL_Authenticate - The parameter values passed to this function must be set as follows:
    • DLHandle must not be NULL.
    • DBHandle must reference an LDAP session for which authentication is being performed.
    • AccessRequest must not be used and can be set to NULL.
    • UserAuthentication must not be NULL.
    • UserAuthentication->Credential must not be NULL.
    • UserAuthentication->Credential->Length must not be NULL.
    • UserAuthentication->Credential->Data must not be NULL. The data portion of UserAuthentication must also have been typecast from a pointer to BindParms, which contains the dn of the entry to bind as the authentication mechanism and the credentials.

    The LDAP access control model is based on the identity of the client requesting access to the directory. The format and capabilities of access control information, however, is highly dependent on the server's implementation, which varies from system to system. It is therefore the responsibility of the caller to know in advance which access rights are associated with a given entry.

  2. CSSM_DL_DbOpen - The parameter values passed to this function must be set as follows:
    • DbHandle must not be NULL.
    • DbName must not be NULL. It must be a null-terminated string containing either:
      1. A host name or dotted string representing the IP address of the target LDAP server, with optional port number separated by a colon, or
      2. An LDAP URL specifying the host/port of the LDAP server to connect and the dn of the entry to server as the default starting point for search operations.
    • AccessRequest is not used. It can be set to NULL.
    • UserAuthentication can be set to NULL if no credentials are required for the specified LDAP server. The data portion of UserAuthentication must have been typecast from a pointer to BindParms, which contains the dn of the entry to bind as the authentication mechanism and the credentials.
    • OpenParameters is ignored.
  3. CSSM_DL_DbExport - The parameter values passed to this function must be set as follows:
    • DbHandle must not be NULL.
    • DbSourceName must be a null-terminated string containing either:
      1. A host name or dotted string representing the IP address of the target LDAP server, with optional port number separated by a colon, or
      2. An LDAP URL specifying the host/port of the LDAP server to connect and the dn identifying the rest of the subtree to be exported.
    • DbDestinationName must be the full path of the file which will contain a snapshot of the requested information subtree written in LDAP Data Interchange Format (LDIF).
    • InfoOnly is ignored.
    • UserAuthentication represents the caller's credential as required for authorization to list a subtree. If access control of the portion of the directory tree to be exported requires no additional credentials to perform this operation, then user authentication can be NULL.
  4. CSSM_DL_DataGetFirst - The parameter values passed to this function must be set as follows:
    • DLHandle must not be NULL.
    • DBHandle must reference an opened LDAP session.
    • Query must not be NULL.
    • Query->Conjunctive can be CSSM_DB_NONE, CSSM_DB_AND, CSSM_DB_OR.
    • Query->SelectionPredicate must not be NULL if Query->NumselectionPredicates is 1 or more.
    • ResultsHandle must be an allocated pointer.
    • EndofDataStore must be an allocated pointer.
    • Attributes must be an allocated pointer.
    • Data must be an allocated pointer.

    The query structure specifying the selection predicates are used to query the data store. The structure contains meta-information about the search fields and the relational and conjunctive operators forming the selection predicate. The comparison values to be used in the search are specified in the Attributes and Data parameters.

    Special Attribute Names:

    URL - This attribute name, if specified, must be the only one. The attribute value will be taken to be an LDAP URL conforming to RFC XXXX. All other predicates will be ignored.

    DL SEARCH SCOPE - This is a psuedo attribute indicating to DL the scope of the search. The attribute value is one of "BASE", "ONE", or "SUB", corresponding to base object search, one-level search and subtree search, respectively.

    DL_SEARCH_BASE - This is a psuedo attribute indicating to the DL the starting point of the search. The attribute value should be the string representation of a DN.

  5. CSSM_DL_DataGetNext - The parameter values passed to this function must be set as follows:
    • DLHandle must not be NULL.
    • DBHandle must reference an opened LDAP session.
    • ResultsHandle must reference a valid query.
    • EndOfDataStore must be an allocated pointer.
    • Attributes must be an allocated pointer.
    • Data must be an allocated pointer.
  6. CSSM_DL_PassThrough - The parameter values passed to this function must be set as follows:
    • DLHandle must not be NULL.
    • DBHandle must reference an opened LDAP session.