HP OpenVMS Systems Documentation

Two modules that include LDAP.H can be compiled with different pointer sizes and linked together. While each module may use the LDAP API on its own, it may not be possible for both modules to share LDAP-related data.

None of the public LDAP data structures is directly compatible between 32- and 64-bit modules. For example, a BerValue that has been allocated by a 32-bit module does not have the same layout as a BerValue which a 64-bit module expects to see, and consequently cannot be exchanged between two such modules without some sort of data conversion taking place.

Opaque data structures (such as LDAP *) have only a single structure definition inside the library, and so pointers to such structures may be exchanged between 32- and 64-bit callers. Note that these structures are allocated only by the library itself, and, in the case of a 64-bit caller, these structures may be allocated in 64-bit space. So while the LDAP handle returned to a 32-bit caller of ldap_init() could safely be used by a 64-bit module, the reverse may not be true.

12.1.5 Multithreading Support

The OpenVMS LDAP API may be used by a multi-threaded application. Two of the functions in the library, ldap_perror() and ldap_result2error() , are not thread-safe.

12.2 Common Data Structures and Memory Handling

The following are definitions of some data structures that are common to several LDAP API functions.

typedef struct ldap LDAP;

typedef struct berelement BerElement;

typedef struct ldapmsg LDAPMessage;

typedef struct berval {
    ber_len_t       bv_len;
    char            *bv_val;
} BerValue;


struct timeval;

The LDAP structure is an opaque data type that represents an LDAP session. Typically, this corresponds to a connection to a single server, but it may encompass several server connections in LDAPv3 referrals.

The LDAPMessage structure is an opaque data type that is used to return entry, reference, result, and error information. An LDAPMessage structure may represent the beginning of a list or a chain of messages that contain a series of entries, references, and result messages that are returned by LDAP operations, such as search. LDAP API functions, such as ldap_parse_result() , that operate on message chains which may contain more than one result message, always operate on the first result message in the chain. See Section 12.17 for more information.

The BerElement structure is an opaque data type that is used to hold data and state information about encoded data.

The berval structure is used to represent arbitrary binary data, and its fields have the following meanings:

The timeval structure is used to represent an interval of time, and its fields have the following meanings:

All memory that is allocated by a function in this C LDAP API and returned to the caller should be disposed of by calling the appropriate free function provided by this API. The correct free function to call is documented in each section of this chapter where a function that allocates memory is described.

Memory that is allocated outside of the C LDAP API must not be disposed of using a function provided by this API.

The following is a complete list of free functions that are used to dispose of allocated memory:

   ber_bvecfree()

   ber_bvfree()

   ber_free()

   ldap_control_free()

   ldap_controls_free()

   ldap_memfree()

   ldap_msgfree()

   ldap_value_free()

   ldap_value_free_len()

Many of the LDAP API functions return LDAP error codes, some of which indicate local errors and some of which may be returned by servers. All of the LDAP error codes returned will be positive integers; those between 0x00 and 0x50 are returned from the LDAP server, those above 0x50 are generated by the API itself. Supported error codes are as follows (hexadecimal values are given in parentheses after the constant):

     LDAP_SUCCESS (0x00)

     LDAP_OPERATIONS_ERROR (0x01)

     LDAP_PROTOCOL_ERROR (0x02)

     LDAP_TIMELIMIT_EXCEEDED (0x03)

     LDAP_SIZELIMIT_EXCEEDED (0x04)

     LDAP_COMPARE_FALSE (0x05)

     LDAP_COMPARE_TRUE (0x06)

     LDAP_STRONG_AUTH_NOT_SUPPORTED (0x07)

     LDAP_STRONG_AUTH_REQUIRED (0x08)

     LDAP_REFERRAL (0x0a)                            -- new in LDAPv3

     LDAP_ADMINLIMIT_EXCEEDED (0x0b)                 -- new in LDAPv3

     LDAP_UNAVAILABLE_CRITICAL_EXTENSION (0x0c)      -- new in LDAPv3

     LDAP_CONFIDENTIALITY_REQUIRED (0x0d)            -- new in LDAPv3

     LDAP_SASL_BIND_IN_PROGRESS (0x0e)               -- new in LDAPv3

     LDAP_NO_SUCH_ATTRIBUTE (0x10)

     LDAP_UNDEFINED_TYPE (0x11)

     LDAP_INAPPROPRIATE_MATCHING (0x12)

     LDAP_CONSTRAINT_VIOLATION (0x13)

     LDAP_TYPE_OR_VALUE_EXISTS (0x14)

     LDAP_INVALID_SYNTAX (0x15)

     LDAP_NO_SUCH_OBJECT (0x20)

     LDAP_ALIAS_PROBLEM (0x21)

     LDAP_INVALID_DN_SYNTAX (0x22)

     LDAP_IS_LEAF (0x23)                        -- not used in LDAPv3

     LDAP_ALIAS_DEREF_PROBLEM (0x24)

     LDAP_INAPPROPRIATE_AUTH (0x30)

     LDAP_INVALID_CREDENTIALS (0x31)

     LDAP_INSUFFICIENT_ACCESS (0x32)

     LDAP_BUSY (0x33)

     LDAP_UNAVAILABLE (0x34)

     LDAP_UNWILLING_TO_PERFORM (0x35)

     LDAP_LOOP_DETECT (0x36)

     LDAP_NAMING_VIOLATION (0x40)

     LDAP_OBJECT_CLASS_VIOLATION (0x41)

     LDAP_NOT_ALLOWED_ON_NONLEAF (0x42)

     LDAP_NOT_ALLOWED_ON_RDN (0x43)

     LDAP_ALREADY_EXISTS (0x44)

     LDAP_NO_OBJECT_CLASS_MODS (0x45)

     LDAP_RESULTS_TOO_LARGE (0x46)                -- reserved for CLDA

     LDAP_AFFECTS_MULTIPLE_DSAS (0x47)            -- new in LDAPv3

     LDAP_OTHER (0x50)

     LDAP_SERVER_DOWN (0x51)

     LDAP_LOCAL_ERROR (0x52)

     LDAP_ENCODING_ERROR (0x53)

     LDAP_DECODING_ERROR (0x54)

     LDAP_TIMEOUT (0x55)

     LDAP_AUTH_UNKNOWN (0x56)

     LDAP_FILTER_ERROR (0x57)

     LDAP_USER_CANCELLED (0x58)

     LDAP_PARAM_ERROR (0x59)

     LDAP_NO_MEMORY (0x5a)

     LDAP_CONNECT_ERROR (0x5b)

     LDAP_NOT_SUPPORTED (0x5c)

     LDAP_CONTROL_NOT_FOUND (0x5d)

     LDAP_NO_RESULTS_RETURNED (0x5e)

     LDAP_MORE_RESULTS_TO_RETURN (0x5f)

     LDAP_CLIENT_LOOP (0x60)

     LDAP_REFERRAL_LIMIT_EXCEEDED (0x61)

The ldap_init() function initializes a session with an LDAP server. The server is not actually contacted until an operation is performed that requires it, allowing various options to be set after initialization.

        LDAP *ldap_init(
              const char    *hostname,
              int           portno);

Use of the following function is deprecated.

        LDAP *ldap_open(
              const char    *hostname,
              int           portno);

Unlike ldap_init() , the ldap_open() function attempts to make a server connection before returning to the caller. A more complete description can be found in RFC 1823.

Parameters are as follows:

The ldap_init() and ldap_open() functions both return a session handle, a pointer to an opaque structure that should be passed to subsequent calls pertaining to the session. These functions return NULL if the session cannot be initialized, in which case the operating system error reporting mechanism can be checked to see why the call failed.

Note that if you connect to an LDAP Version 2 server, one of the ldap_bind() calls must be completed before other operations can be performed on the session. LDAPv3 does not require that a bind operation be completed before other operations can be performed.

The calling program can set various attributes of the session by calling the functions described in the next section.

12.5 LDAP Session Handle Options

The LDAP session handle returned by ldap_init() is a pointer to an opaque data type representing an LDAP session. Formerly, this data type was a structure exposed to the caller, and various fields in the structure could be set to control aspects of the session, such as size and time limits on searches.

To insulate callers from inevitable changes to this structure, these aspects of the session are now accessed through a pair of accessor functions.

The ldap_get_option() function is used to access the current value of various session-wide parameters. The ldap_set_option() function is used to set the value of these parameters. Note that some options are READ-ONLY and cannot be set; it is an error to call ldap_set_option() and attempt to set a READ-ONLY option.

        int ldap_get_option(
                LDAP            *ld,
                int             option,
                void            *outvalue
        );

        int ldap_set_option(
                LDAP            *ld,
                int             option,
                const void      *invalue
        );

Parameters are as follows:

LDAPv3 operations can be extended through the use of controls. Controls may be sent to a server or returned to the client with any LDAP message. These controls are referred to as server controls.

The LDAP API also supports a client-side extension mechanism through the use of client controls. These controls affect the behavior of the LDAP API only and are never sent to a server. A common data structure is used to represent both types of controls:

        typedef struct ldapcontrol {
                char                            *ldctl_oid;
                struct berval                   ldctl_value;
                char                            ldctl_iscritical;
        } LDAPControl, *PLDAPControl;

The fields in the ldapcontrol structure have the following meanings:

Some LDAP API calls allocate an ldapcontrol structure or a NULL-terminated array of ldapcontrol structures. The following functions can be used to dispose of a single control or an array of controls:

     void ldap_control_free( LDAPControl *ctrl );

     void ldap_controls_free( LDAPControl **ctrls );

A set of controls that affect the entire session can be set using the ldap_set_option() function. A list of controls can also be passed directly to some LDAP API calls, such as ldap_search_ext() , in which case any controls set for the session through the use of ldap_set_option() are ignored. Control lists are represented as a NULL-terminated array of pointers to ldapcontrol structures.

Server controls are defined by LDAPv3 protocol extension documents; for example, a control has been proposed to support paging of search results. No client controls are currently implemented in this version of the API.

12.7 Authenticating to the Directory

The following functions are used to authenticate an LDAP client to an LDAP directory server.

The ldap_sasl_bind() and ldap_sasl_bind_s() functions can be used to do general and extensible authentication over LDAP through the use of the Simple Authentication Security Layer. The functions both take the DN to bind as, the method to use, as a dotted-string representation of an OID identifying the method, and a struct berval holding the credentials. The special constant value LDAP_SASL_SIMPLE (NULL) can be passed to request simple authentication, or the simplified functions ldap_simple_bind() or ldap_simple_bind_s() can be used.

        int ldap_sasl_bind(
                LDAP                                    *ld,
                const char                              *dn,
                const char                              *mechanism,
                const struct berval                     *cred,
                LDAPControl                             **serverctrls,
                LDAPControl                             **clientctrls,
                int                                     *msgidp
        );

        int ldap_sasl_bind_s(
                LDAP                                    *ld,
                const char                              *dn,
                const char                              *mechanism,
                const struct berval                     *cred,
                LDAPControl                             **serverctrls,
                LDAPControl                             **clientctrls,
                struct berval                           **servercredp
        );

        int ldap_simple_bind(
                LDAP                                    *ld,
                const char                              *dn,
                const char                              *passwd
        );

        int ldap_simple_bind_s(
                LDAP                                    *ld,
                const char                              *dn,
                const char                              *passwd
        );

The use of the following functions is deprecated:

     int ldap_bind( LDAP *ld, char *dn, char *cred, int method );

     int ldap_bind_s( LDAP *ld, char *dn, char *cred, int method );

Parameters are as follows:

Additional parameters for the deprecated functions are not described. See the RFC 1823 documentation for more information.

The ldap_sasl_bind() function initiates an asynchronous bind operation and returns the constant LDAP_SUCCESS if the request was successfully sent or another LDAP error code if not. See Section 12.18 for more information about possible errors and how to interpret them. If successful, ldap_sasl_bind() places the message id of the request in *msgidp. A subsequent call to ldap_result() can be used to obtain the result of the bind.

The ldap_simple_bind() function initiates a simple asynchronous bind operation and returns the message id of the operation initiated. A subsequent call to ldap_result() can be used to obtain the result of the bind. In case of error, ldap_simple_bind() will return -1, setting the session error parameters in the LDAP structure appropriately.

The synchronous ldap_sasl_bind_s() and ldap_simple_bind_s() functions both return the result of the operation, either the constant LDAP_SUCCESS if the operation was successful, or another LDAP error code if it was not. See Section 12.18 for more information about possible errors and how to interpret them.

Note that if an LDAP Version 2 server is contacted, no other operations over the connection should be attempted before a bind call has successfully completed.

Subsequent bind calls can be used to reauthenticate over the same connection, and multistep SASL sequences can be accomplished through a sequence of calls to ldap_sasl_bind() or ldap_sasl_bind_s() .