HP OpenVMS Systems Documentation

HP OpenVMS Utility Routines Manual

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.

14.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.

14.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 14.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 14.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() .

14.8 Closing the Session

The following functions are used to unbind from the directory, close the connection, and dispose of the session handle.

        int ldap_unbind( LDAP *ld );
        int ldap_unbind_s( LDAP *ld );

Parameter is as follows:

The ldap_unbind() and ldap_unbind_s() functions both work synchronously, unbinding from the directory, closing the connection, and freeing up the ld structure before returning. There is no server response to an unbind operation. The ldap_unbind() function returns LDAP_SUCCESS (or another LDAP error code if the request cannot be sent to the LDAP server). After a call to ldap_unbind() or ldap_unbind_s() , the session handle ld is invalid and it is illegal to make any further LDAP API calls using ld.

14.9 Searching

The following functions are used to search the LDAP directory, returning a requested set of attributes for each entry matched. There are five variations.

        int ldap_search_ext(
                LDAP                      *ld,
                const char                *base,
                int                       scope,
                const char                *filter,
                char                      **attrs,
                int                       attrsonly,
                LDAPControl               **serverctrls,
                LDAPControl               **clientctrls,
                struct timeval            *timeout,
                int                       sizelimit,
                int                       *msgidp
        );

        int ldap_search_ext_s(
                LDAP                      *ld,
                const char                *base,
                int                       scope,
                const char                *filter,
                char                      **attrs,
                int                       attrsonly,
                LDAPControl               **serverctrls,
                LDAPControl               **clientctrls,
                struct timeval            *timeout,
                int                       sizelimit,
                LDAPMessage               **res
        );

        int ldap_search(
                LDAP                      *ld,
                const char                *base,
                int                       scope,
                const char                *filter,
                char                      **attrs,
                int                       attrsonly
        );

        int ldap_search_s(
                LDAP                      *ld,
                const char                *base,
                int                       scope,
                const char                *filter,
                char                      **attrs,
                int                       attrsonly,
                LDAPMessage               **res
        );

        int ldap_search_st(
                LDAP                      *ld,
                char                      *base,
                int                       scope,
                char                      *filter,
                char                      **attrs,
                int                       attrsonly,
                struct timeval            *timeout,
                LDAPMessage               **res
           );

Parameters are as follows:

There are three options in the session handle ld that potentially affect how the search is performed. They are as follows: