[Search] [pdf|bibtex] [Tracker] [WG] [Email] [Nits]

Versions: 00                                                            
Network Working Group                                           T. Howes
INTERNET-DRAFT                             Netscape Communications Corp.
Intended Category: Standards Track                              M. Smith
Obsoletes: RFC 1823                        Netscape Communications Corp.
Expires: January 1998                                          A. Herron
                                                         Microsoft Corp.
                                                               C. Weider
                                                         Microsoft Corp.
                                                                 M. Wahl
                                                    Critical Angle, Inc.

                                                            29 July 1997


                The C LDAP Application Program Interface
                  <draft-ietf-asid-ldap-c-api-00.txt>



1.  Status of this Memo

This draft document will be submitted to the RFC Editor as a Standards
Track document. Distribution of this memo is unlimited. Please send com-
ments to the authors.

This document is an Internet-Draft.  Internet-Drafts are working docu-
ments of the Internet Engineering Task Force (IETF), its areas, and its
working groups.  Note that other groups may also distribute working
documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time.  It is inappropriate to use Internet-Drafts as reference material
or to cite them other than as ``work in progress.''

To learn the current status of any Internet-Draft, please check the
``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow
Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe),
ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim).

2.  Introduction

This document defines a C language application program interface to the
lightweight directory access protocol (LDAP). This document replaces the
previous definition of this API, defined in RFC 1823, updating it to
include support for features found in version 3 of the LDAP protocol.
New extended operation functions were added to support LDAPv3 features
such as controls.  In addition, other LDAP API changes were made to



Expires: January 1998                                           [Page 1]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


support information hiding and thread safety.

The C LDAP API is designed to be powerful, yet simple to use. It defines
compatible synchronous and asynchronous interfaces to LDAP to suit a
wide variety of applications. This document gives a brief overview of
the LDAP model, then an overview of how the API is used by an applica-
tion program to obtain LDAP information.  The API calls are described in
detail, followed by an appendix that provides some example code demon-
strating the use of the API. This document provides information to the
Internet community. It does not specify any standard.

3.  Overview of the LDAP Model

LDAP is the lightweight directory access protocol, described in [2] and
[6]. It can provide a lightweight frontend to the X.500 directory [1],
or a stand-alone service. In either mode, LDAP is based on a client-
server model in which a client makes a TCP connection to an LDAP server,
over which it sends requests and receives responses.

The LDAP information model is based on the entry, which contains infor-
mation about some object (e.g., a person).  Entries are composed of
attributes, which have a type and one or more values. Each attribute has
a syntax that determines what kinds of values are allowed in the attri-
bute (e.g., ASCII characters, a jpeg photograph, etc.) and how those
values behave during directory operations (e.g., is case significant
during comparisons).

Entries may be organized in a tree structure, usually based on politi-
cal, geographical, and organizational boundaries. Each entry is uniquely
named relative to its sibling entries by its relative distinguished name
(RDN) consisting of one or more distinguished attribute values from the
entry.  At most one value from each attribute may be used in the RDN.
For example, the entry for the person Babs Jensen might be named with
the "Barbara Jensen" value from the commonName attribute.

A globally unique name for an entry, called a distinguished name or DN,
is constructed by concatenating the sequence of RDNs from the entry up
to the root of the tree. For example, if Babs worked for the University
of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen,
o=University of Michigan, c=US". The DN format used by LDAP is defined
in [4].

Operations are provided to authenticate, search for and retrieve infor-
mation, modify information, and add and delete entries from the tree.
The next sections give an overview of how the API is used and detailed
descriptions of the LDAP API calls that implement all of these func-
tions.




Expires: January 1998                                           [Page 2]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


4.  Overview of LDAP API Use

An application generally uses the C LDAP API in four simple steps.

-    Initialize an LDAP session with a default LDAP server. The
     ldap_init() function returns a handle to the session, allowing mul-
     tiple connections to be open at once.

-    Authenticate to the LDAP server. The ldap_bind() function and
     friends support a variety of authentication methods.

-    Perform some LDAP operations and obtain some results. ldap_search()
     and friends return results which can be parsed by
     ldap_result2error(), ldap_first_entry(), ldap_next_entry(), etc.

-    Close the session. The ldap_unbind() function closes the connec-
     tion.

Operations can be performed either synchronously or asynchronously.  The
names of the synchronous functions end in _s. For example, a synchronous
search can be completed by calling ldap_search_s(). An asynchronous
search can be initiated by calling ldap_search(). All synchronous rou-
tines return an indication of the outcome of the operation (e.g, the
constant LDAP_SUCCESS or some other error code).  The asynchronous rou-
tines return the message id of the operation initiated. This id can be
used in subsequent calls to ldap_result() to obtain the result(s) of the
operation. An asynchronous operation can be abandoned by calling
ldap_abandon().

Results and errors are returned in an opaque structure called LDAPMes-
sage.  Routines are provided to parse this structure, step through
entries and attributes returned, etc. Routines are also provided to
interpret errors. Later sections of this document describe these rou-
tines in more detail.

LDAP version 3 servers may return referrals to other servers.  By
default, implementations of this API will attempt to follow referrals
automatically for the application.  This behavior can be disabled glo-
bally (using the ldap_set_option() call) or on a per-request basis
through the use of a client control.

As in the LDAPv3 protocol itself, all DNs and string values that are
passed into or produced by the C LDAP API are represented as UTF-8[10]
characters.

For compatibility with existing applications, implementations of this
API will by default use version 2 of the LDAP protocol.  Applications
that intend to take advantage of LDAP version 3 features will need to



Expires: January 1998                                           [Page 3]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


use the ldap_set_option() call with a LDAP_OPT_PROTOCOL_VERSION to
switch to version 3.


5.  Common Data Structures

Some data structures that are common to several LDAP API functions are
defined here:

           typedef struct ldap LDAP;

           typedef struct ldapmsg LDAPMessage;

           struct berval {
                   unsigned long   bv_len;
                   char            *bv_val;
           };

           struct timeval {
                   long            tv_sec;
                   long            tv_usec;
           };

The LDAP structure is an opaque data type that represents an LDAP ses-
sion Typically this corresponds to a connection to a single server, but
it may encompass several server connections in the face of LDAPv3 refer-
rals.

The LDAPMessage structure is an opaque data type that is used to return
results and error information.

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

bv_len   Length of data in bytes.

bv_val   A pointer to the data itself.


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

tv_sec   Seconds component of time interval.

tv_usec  Microseconds component of time interval.






Expires: January 1998                                           [Page 4]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


6.  LDAP Error Codes

Many of the LDAP API routines return LDAP error codes, some of which
indicate local errors and some of which may be returned by servers.
Supported error codes are (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_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)
           LDAP_AFFECTS_MULTIPLE_DSAS (0x47)               -- new in LDAPv3
           LDAP_OTHER (0x50)
           LDAP_SERVER_DOWN (0x51)



Expires: January 1998                                           [Page 5]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


           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)


7.  Performing LDAP Operations

This section describes each LDAP operation API call in detail. All func-
tions take a "session handle," a pointer to an LDAP structure containing
per-connection information.  Many routines return results in an LDAPMes-
sage structure. These structures and others are described as needed
below.


7.1.  Initializing an LDAP Session

ldap_init() 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(
                char    *hostname,
                int     portno
        );

Use of the following routine is deprecated.

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

Parameters are:

hostname Contains a space-separated list of hostnames or dotted strings



Expires: January 1998                                           [Page 6]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


         representing the IP address of hosts running an LDAP server to
         connect to. Each hostname in the list can include an optional
         port number which is separated from the host itself with a
         colon (:) character.  The hosts are tried in the order listed,
         stopping with the first one to which a successful connection is
         made. Note that only ldap_open() attempts to make the connec-
         tion before returning to the caller. ldap_init() does not con-
         nect to the LDAP server.

portno   Contains the TCP port number to connect to. The default LDAP
         port of 389 can be obtained by supplying the constant
         LDAP_PORT.  If a host includes a port number then this parame-
         ter is ignored.

ldap_init() and ldap_open() both return a "session handle," a pointer to
an opaque structure that should be passed to subsequent calls pertaining
to the session. These routines return NULL if the session cannot be ini-
tialized 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 LDAPv2 server, one of the ldap_bind()
calls described below 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 routines described in the next section.


7.2.  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 struc-
ture could be set to control aspects of the session, such as size and
time limits on searches.

In the interest of insulating callers from inevitable changes to this
structure, these aspects of the session are now accessed through a pair
of accessor functions, described below.

ldap_get_option() is used to access the current value of various
session-wide parameters. ldap_set_option() is used to set the value of
these parameters.

           int ldap_get_option(
                   LDAP            *ld,
                   int             option,



Expires: January 1998                                           [Page 7]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


                   void            *outvalue
           );

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

Parameters are:

ld     The session handle.

option The name of the option being accessed or set. This parameter
       should be one of the following constants, which have the indi-
       cated meanings.  After the constant the actual value of the con-
       stant is listed in hexadecimal in parentheses followed by the
       type of the corresponding outvalue or invalue parameter.

   LDAP_OPT_DESC (0x01) int *
          The underlying socket descriptor corresponding to the default
          LDAP connection.

   LDAP_OPT_DEREF (0x02) int *
          Controls how aliases are handled during search. It can have
          one of the following values: LDAP_DEREF_NEVER (0x00),
          LDAP_DEREF_SEARCHING (0x01), LDAP_DEREF_FINDING (0x02), or
          LDAP_DEREF_ALWAYS (0x03).  The LDAP_DEREF_SEARCHING value
          means aliases should be dereferenced during the search but not
          when locating the base object of the search. The
          LDAP_DEREF_FINDING value means aliases should be dereferenced
          when locating the base object but not during the search.

   LDAP_OPT_SIZELIMIT (0x03) int *
          A limit on the number of entries to return from a search. A
          value of zero means no limit.

   LDAP_OPT_TIMELIMIT (0x04) int *
          A limit on the number of seconds to spend on a search. A value
          of zero means no limit

   LDAP_OPT_REBIND_FN (0x06) function pointer
          See the discussion of ldap_bind() and friends below.

   LDAP_OPT_REBIND_ARG (0x07) void *
          See the discussion of ldap_bind() and friends below.

   LDAP_OPT_REFERRALS (0x08) void *



Expires: January 1998                                           [Page 8]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


          This option controls whether the LDAP library automatically
          follows referrals returned by LDAP servers or not. It can be
          set to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF.

   LDAP_OPT_RESTART (0x09) void *
          This option controls whether LDAP I/O operations should
          automatically be restarted if they abort prematurely. It
          should be set to one of the constants LDAP_OPT_ON or
          LDAP_OPT_OFF. This option is useful if an LDAP I/O operation
          may be interrupted prematurely, for example by a timer going
          off, or other interrrupt.

   LDAP_OPT_PROTOCOL_VERSION (0x11) int *
          This option indicates the version of the default LDAP server.
          It can be one of the constants LDAP_VERSION2 or LDAP_VERSION3.
          If no version is set the default is LDAP_VERSION2.

   LDAP_OPT_SERVER_CONTROLS (0x12) LDAPControl **
          A default list of LDAP server controls to be sent with each
          request.  See the Using Controls section below.

   LDAP_OPT_CLIENT_CONTROLS (0x13) LDAPControl **
          A default list of client controls that affect the LDAP ses-
          sion.  See the Using Controls section below.

   LDAP_OPT_HOST_NAME (0x30) char **
          The host name of the default LDAP server.

   LDAP_OPT_ERROR_NUMBER (0x31) int *
          The code of the most recent LDAP error that occurred for this
          session.

   LDAP_OPT_ERROR_STRING (0x32) char **
          The message returned with the most recent LDAP error that
          occurred for this session.


outvalue The address of a place to put the value of the option. The
         actual type of this parameter depends on the setting of the
         option parameter.

invalue  A pointer to the value the option is to be given. The actual
         type of this parameter depends on the setting of the option
         parameter. The constants LDAP_OPT_ON and LDAP_OPT_OFF can be
         given for options that have on or off settings.






Expires: January 1998                                           [Page 9]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


7.3.  Working with controls

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:

ldctl_oid        The control type, represented as a string.

ldctl_value      The data associated with the control (if any).

ldctl_iscritical Indicates whether the control is critical of not. If
                 this field is non-zero, the operation will only be car-
                 ried out if the control is recognized by the server
                 and/or client.

Some LDAP API calls allocate an ldapcontrol structure or a NULL-
terminated array of ldapcontrol structures.  The following routines 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 (see above).  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 server-side sorting of
search results [7].

No client controls are defined by this document but they may be defined
in future revisions or in any document that extends this API.



Expires: January 1998                                          [Page 10]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


7.4.  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 [8].  The routines 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 ("") can be passed to
request simple authentication, or the simplified routines
ldap_simple_bind() or ldap_simple_bind_s() can be used.

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

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

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

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

   The use of the following routines is deprecated:




Expires: January 1998                                          [Page 11]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


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

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

           int ldap_kerberos_bind( LDAP *ld, char *dn );

           int ldap_kerberos_bind_s( LDAP *ld, char *dn );

Parameters are:

ld           The session handle.

dn           The name of the entry to bind as.

mechanism    Either LDAP_AUTH_SIMPLE_OID to get simple authentication,
             or a dotted text string representing an OID identifying the
             SASL method.

cred         The credentials with which to authenticate. Arbitrary
             credentials can be passed using this parameter. The format
             and content of the credentials depends on the setting of
             the mechanism parameter.

passwd       For ldap_simple_bind(), the password to compare to the
             entry's userPassword attribute.

serverctrls  List of LDAP server controls.

clientctrls  List of client controls.

msgidp       This result parameter will be set to the message id of the
             request if the ldap_sasl_bind() call succeeds.

servercredp  This result parameter will be set to the credentials
             returned by the server.  This should be freed by calling
             ldap_If no credentials are returned it will be set to NULL.

Additional parameters for the deprecated routines are not described.
Interested readers are referred to RFC 1823.

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 the section below on error
handling 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(), described below,
can be used to obtain the result of the bind.




Expires: January 1998                                          [Page 12]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


The ldap_simple_bind() function initiates a simple asynchronous bind
operation and returns the message id of the operation initiated.  A sub-
sequent call to ldap_result(), described below, 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 appropri-
ately.

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 the section below on error handling for more informa-
tion about possible errors and how to interpret them.

Note that if an LDAPv2 server is contacted, no other operations over the
connection should be attempted before a bind call has successfully com-
pleted.

Subsequent bind calls can be used to re-authenticate over the same con-
nection, and multistep SASL sequences can be accomplished through a
sequence of calls to ldap_sasl_bind() or ldap_sasl_bind_s().


7.5.  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 );

Parameters are:

ld   The session handle.

ldap_unbind() and ldap_unbind_s() both work synchronously, unbinding
from the directory, closing the connection, and freeing up the ld struc-
ture before returning.   There is no server response to an unbind opera-
tion.  ldap_unbind() 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.


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



Expires: January 1998                                          [Page 13]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


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

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

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

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

           int ldap_search_st(



Expires: January 1998                                          [Page 14]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


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

Parameters are:

ld           The session handle.

base         The dn of the entry at which to start the search.

scope        One of LDAP_SCOPE_BASE (0x00), LDAP_SCOPE_ONELEVEL (0x01),
             or LDAP_SCOPE_SUBTREE (0x02), indicating the scope of the
             search.

filter       A character string as described in [3], representing the
             search filter.

attrs        A NULL-terminated array of strings indicating which attri-
             butes to return for each matching entry. Passing NULL for
             this parameter causes all available attributes to be
             retrieved.

attrsonly    A boolean value that should be zero if both attribute types
             and values are to be returned, non-zero if only types are
             wanted.

timeout      For the ldap_search_st() function, this specifies the local
             search timeout value.  For the ldap_search_ext() and
             ldap_search_ext_s() functions, this specifies both the
             local search timeout value and the operation time limit
             that is sent to the server within the search request.

res          For the synchronous calls, this is a result parameter which
             will contain the results of the search upon completion of
             the call.

serverctrls  List of LDAP server controls.

clientctrls  List of client controls.

msgidp       This result parameter will be set to the message id of the
             request if the ldap_search_ext() call succeeds.



Expires: January 1998                                          [Page 15]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


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

LDAP_OPT_SIZELIMIT
             A limit on the number of entries to return from the search.
             A value of zero means no limit.  Note that the value from
             the session handle is ignored when using the
             ldap_search_ext() or ldap_search_ext_s() functions.

LDAP_OPT_TIMELIMIT
             A limit on the number of seconds to spend on the search. A
             value of zero means no limit.  Note that the value from the
             session handle is ignored when using the ldap_search_ext()
             or ldap_search_ext_s() functions.

LDAP_OPT_DEREF
             One of LDAP_DEREF_NEVER (0x00), LDAP_DEREF_SEARCHING
             (0x01), LDAP_DEREF_FINDING (0x02), or LDAP_DEREF_ALWAYS
             (0x03), specifying how aliases should be handled during the
             search. The LDAP_DEREF_SEARCHING value means aliases should
             be dereferenced during the search but not when locating the
             base object of the search. The LDAP_DEREF_FINDING value
             means aliases should be dereferenced when locating the base
             object but not during the search.

The ldap_search_ext() function initiates an asynchronous search opera-
tion and returns the constant LDAP_SUCCESS if the request was success-
fully sent, or another LDAP error code if not.  See the section below on
error handling for more information about possible errors and how to
interpret them.  If successful, ldap_search_ext() places the message id
of the request in *msgidp. A subsequent call to ldap_result(), described
below, can be used to obtain the results from the search.  These results
can be parsed using the result parsing routines described in detail
later.

Similar to ldap_search_ext(), the ldap_search() function initiates an
asynchronous search operation and returns the message id of the opera-
tion initiated.  As for ldap_search_ext(), a subsequent call to
ldap_result(), described below, can be used to obtain the result of the
bind. In case of error, ldap_search() will return -1, setting the ses-
sion error parameters in the LDAP structure appropriately.

The synchronous ldap_search_ext_s(), ldap_search_s(), and
ldap_search_st() functions all 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 the section below on error
handling for more information about possible errors and how to interpret
them.  Entries returned from the search (if any) are contained in the



Expires: January 1998                                          [Page 16]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


res parameter. This parameter is opaque to the caller.  Entries, attri-
butes, values, etc., should be extracted by calling the parsing routines
described below. The results contained in res should be freed when no
longer in use by calling ldap_msgfree(), described later.

The ldap_search_ext() and ldap_search_ext_s() functions support LDAPv3
server controls, client controls, and allow varying size and time limits
to be easily specified for each search operation.  The ldap_search_st()
function is identical to ldap_search_s() except that it takes an addi-
tional parameter specifying a local timeout for the search.

7.7.  Reading an Entry

LDAP does not support a read operation directly. Instead, this operation
is emulated by a search with base set to the DN of the entry to read,
scope set to LDAP_SCOPE_BASE, and filter set to "(objectclass=*)". attrs
contains the list of attributes to return.


7.8.  Listing the Children of an Entry

LDAP does not support a list operation directly. Instead, this operation
is emulated by a search with base set to the DN of the entry to list,
scope set to LDAP_SCOPE_ONELEVEL, and filter set to "(objectclass=*)".
attrs contains the list of attributes to return for each child entry.

7.9.  Comparing a Value Against an Entry

The following routines are used to compare a given attribute value
assertion against an LDAP entry.  There are four variations:

           int ldap_compare_ext(
                   LDAP            *ld,
                   char            *dn,
                   char            *attr,
                   struct berval   *bvalue
                   LDAPControl     **serverctrls,
                   LDAPControl     **clientctrls,
                   int             *msgidp
           );

           int ldap_compare_ext_s(
                   LDAP            *ld,
                   char            *dn,
                   char            *attr,
                   struct berval   *bvalue,
                   LDAPControl     **serverctrls,
                   LDAPControl     **clientctrls



Expires: January 1998                                          [Page 17]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


           );

           int ldap_compare(
                   LDAP            *ld,
                   char            *dn,
                   char            *attr,
                   char            *value
           );

           int ldap_compare_s(
                   LDAP            *ld,
                   char            *dn,
                   char            *attr,
                   char            *value
           );

Parameters are:

ld           The session handle.

dn           The name of the entry to compare against.

attr         The attribute to compare against.

bvalue       The attribute value to compare against those found in the
             given entry. This parameter is used in the extended rou-
             tines and is a pointer to a struct berval so it is possible
             to compare binary values.

value        A string attribute value to compare against, used by the
             ldap_compare() and ldap_compare_s() functions.  Use
             ldap_compare_ext() or ldap_compare_ext_s() if you need to
             compare binary values.

serverctrls  List of LDAP server controls.

clientctrls  List of client controls.

msgidp       This result parameter will be set to the message id of the
             request if the ldap_compare_ext() call succeeds.

The ldap_compare_ext() function initiates an asynchronous compare opera-
tion and returns the constant LDAP_SUCCESS if the request was success-
fully sent, or another LDAP error code if not.  See the section below on
error handling for more information about possible errors and how to
interpret them.  If successful, ldap_compare_ext() places the message id
of the request in *msgidp. A subsequent call to ldap_result(), described
below, can be used to obtain the result of the compare.



Expires: January 1998                                          [Page 18]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


Similar to ldap_compare_ext(), the ldap_compare() function initiates an
asynchronous compare operation and returns the message id of the opera-
tion initiated.  As for ldap_compare_ext(), a subsequent call to
ldap_result(), described below, can be used to obtain the result of the
bind. In case of error, ldap_compare() will return -1, setting the ses-
sion error parameters in the LDAP structure appropriately.

The synchronous ldap_compare_ext_s() and ldap_compare_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 the section below on error handling for more information about pos-
sible errors and how to interpret them.

The ldap_compare_ext() and ldap_compare_ext_s() functions support LDAPv3
server controls and client controls.


7.10.  Modifying an entry

The following routines are used to modify an existing LDAP entry.  There
are four variations:

           typedef struct ldapmod {
                   int             mod_op;
                   char            *mod_type;
                   union {
                           char            **modv_strvals;
                           struct berval   **modv_bvals;
                   } mod_vals;
           } LDAPMod;
           #define mod_values      mod_vals.modv_strvals
           #define mod_bvalues     mod_vals.modv_bvals

           int ldap_modify_ext(
                   LDAP            *ld,
                   char            *dn,
                   LDAPMod         **mods,
                   LDAPControl     **serverctrls,
                   LDAPControl     **clientctrls,
                   int             *msgidp
           );

           int ldap_modify_ext_s(
                   LDAP            *ld,
                   char            *dn,
                   LDAPMod         **mods,
                   LDAPControl     **serverctrls,
                   LDAPControl     **clientctrls



Expires: January 1998                                          [Page 19]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


           );

           int ldap_modify(
                   LDAP            *ld,
                   char            *dn,
                   LDAPMod         **mods
           );

           int ldap_modify_s(
                   LDAP            *ld,
                   char            *dn,
                   LDAPMod         **mods
           );

Parameters are:

ld           The session handle.

dn           The name of the entry to modify.

mods         A NULL-terminated array of modifications to make to the
             entry.

serverctrls  List of LDAP server controls.

clientctrls  List of client controls.

msgidp       This result parameter will be set to the message id of the
             request if the ldap_modify_ext() call succeeds.

The fields in the LDAPMod structure have the following meanings:

mod_op       The modification operation to perform. It should be one of
             LDAP_MOD_ADD (0x00), LDAP_MOD_DELETE (0x01), or
             LDAP_MOD_REPLACE (0x02).  This field also indicates the
             type of values included in the mod_vals union. It is logi-
             cally ORed with LDAP_MOD_BVALUES (0x80) to select the
             mod_bvalues form. Otherwise, the mod_values form is used.

mod_type     The type of the attribute to modify.

mod_vals     The values (if any) to add, delete, or replace. Only one of
             the mod_values or mod_bvalues variants should be used,
             selected by ORing the mod_op field with the constant
             LDAP_MOD_BVALUES. mod_values is a NULL-terminated array of
             zero-terminated strings and mod_bvalues is a NULL-
             terminated array of berval structures that can be used to
             pass binary values such as images.



Expires: January 1998                                          [Page 20]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


For LDAP_MOD_ADD modifications, the given values are added to  the
entry, creating the attribute if necessary.

For LDAP_MOD_DELETE modifications, the given values are deleted from the
entry, removing the attribute if no values remain. If the entire attri-
bute is to  be deleted, the mod_vals field should be set to NULL.

For LDAP_MOD_REPLACE modifications, the attribute will have the listed
values after the modification, having been created if necessary, or
removed if the mod_vals field is NULL. All modifications are performed
in the order in which they are listed.

The ldap_modify_ext() function initiates an asynchronous modify opera-
tion and returns the constant LDAP_SUCCESS if the request was success-
fully sent, or another LDAP error code if not.  See the section below on
error handling for more information about possible errors and how to
interpret them.  If successful, ldap_modify_ext() places the message id
of the request in *msgidp. A subsequent call to ldap_result(), described
below, can be used to obtain the result of the modify.

Similar to ldap_modify_ext(), the ldap_modify() function initiates an
asynchronous modify operation and returns the message id of the opera-
tion initiated.  As for ldap_modify_ext(), a subsequent call to
ldap_result(), described below, can be used to obtain the result of the
modify. In case of error, ldap_modify() will return -1, setting the ses-
sion error parameters in the LDAP structure appropriately.

The synchronous ldap_modify_ext_s() and ldap_modify_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 the section below on error handling for more information about pos-
sible errors and how to interpret them.

The ldap_modify_ext() and ldap_modify_ext_s() functions support LDAPv3
server controls and client controls.


7.11.  Modifying the Name of an Entry

In LDAPv2, the ldap_modrdn() and ldap_modrdn_s() routines were used to
change the name of an LDAP entry. They could only be used to change the
least significant component of a name (the RDN or relative distinguished
name). LDAPv3 provides the Modify DN protocol operation that allows more
general name change access. The ldap_rename() and ldap_rename_s() rou-
tines are used to change the name of an entry, and the use of the
ldap_modrdn() and ldap_modrdn_s() routines is deprecated.

           int ldap_rename(



Expires: January 1998                                          [Page 21]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


                   LDAP            *ld,
                   char            *dn,
                   char            *newrdn,
                   char            *newparent,
                   int             deleteoldrdn,
                   LDAPControl     **serverctrls,
                   LDAPControl     **clientctrls,
                   int             *msgidp

           );
           int ldap_rename_s(
                   LDAP            *ld,
                   char            *dn,
                   char            *newrdn,
                   char            *newparent,
                   int             deleteoldrdn,
                   LDAPControl     **serverctrls,
                   LDAPControl     **clientctrls
           );

   Use of the following routines is deprecated.

           int ldap_modrdn(
                   LDAP    *ld,
                   char    *dn,
                   char    *newrdn,
                   int     deleteoldrdn
           );
           int ldap_modrdn_s(
                   LDAP    *ld,
                   char    *dn,
                   char    *newrdn,
                   int     deleteoldrdn
           );

Parameters are:

ld           The session handle.

dn           The name of the entry whose DN is to be changed.

newrdn       The new RDN to give the entry.

newparent    The new parent, or superior entry.  If this parameter is
             NULL, only the RDN of the entry is changed.  The root DN
             may be specified by passing a zero length string, "".  The
             newparent parameter should always be NULL when using ver-
             sion 2 of the LDAP protocol; otherwise the server's



Expires: January 1998                                          [Page 22]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


             behavior is undefined.

deleteoldrdn This parameter only has meaning on the rename routines if
             newrdn is different than the old RDN. It is a boolean
             value, if non-zero indicating that the old RDN value(s)
             should be removed, if zero indicating that the old RDN
             value(s) should be retained as non-distinguished values of
             the entry.

serverctrls  List of LDAP server controls.

clientctrls  List of client controls.

msgidp       This result parameter will be set to the message id of the
             request if the ldap_rename() call succeeds.

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

The synchronous ldap_rename_s() returns 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 the section below on error
handling for more information about possible errors and how to interpret
them.

The ldap_rename() and ldap_rename_s() functions both support LDAPv3
server controls and client controls.


7.12.  Adding an entry

The following functions are used to add entries to the LDAP directory.
There are four variations:

           int ldap_add_ext(
                   LDAP            *ld,
                   char            *dn,
                   LDAPMod         **attrs,
                   LDAPControl     **serverctrls,
                   LDAPControl     **clientctrls,
                   int             *msgidp
           );




Expires: January 1998                                          [Page 23]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


           int ldap_add_ext_s(
                   LDAP            *ld,
                   char            *dn,
                   LDAPMod         **attrs,
                   LDAPControl     **serverctrls,
                   LDAPControl     **clientctrls
           );

           int ldap_add(
                   LDAP            *ld,
                   char            *dn,
                   LDAPMod         **attrs
           );

           int ldap_add_s(
                   LDAP            *ld,
                   char            *dn,
                   LDAPMod         **attrs
           );

Parameters are:

ld           The session handle.

dn           The name of the entry to add.

attrs        The entry's attributes, specified using the LDAPMod struc-
             ture defined for ldap_modify(). The mod_type and mod_vals
             fields should be filled in.  The mod_op field is ignored
             unless ORed with the constant LDAP_MOD_BVALUES, used to
             select the mod_bvalues case of the mod_vals union.

serverctrls  List of LDAP server controls.

clientctrls  List of client controls.

msgidp       This result parameter will be set to the message id of the
             request if the ldap_add_ext() call succeeds.

Note that the parent of the entry being added must already exist or the
parent must be empty (i.e., equal to the root DN) for an add to succeed.

The ldap_add_ext() function initiates an asynchronous add operation and
returns the constant LDAP_SUCCESS if the request was successfully sent,
or another LDAP error code if not.  See the section below on error han-
dling for more information about possible errors and how to interpret
them.  If successful, ldap_add_ext() places the message id of the
request in *msgidp. A subsequent call to ldap_result(), described below,



Expires: January 1998                                          [Page 24]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


can be used to obtain the result of the add.

Similar to ldap_add_ext(), the ldap_add() function initiates an asyn-
chronous add operation and returns the message id of the operation ini-
tiated.  As for ldap_add_ext(), a subsequent call to ldap_result(),
described below, can be used to obtain the result of the add. In case of
error, ldap_add() will return -1, setting the session error parameters
in the LDAP structure appropriately.

The synchronous ldap_add_ext_s() and ldap_add_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
the section below on error handling for more information about possible
errors and how to interpret them.

The ldap_add_ext() and ldap_add_ext_s() functions support LDAPv3 server
controls and client controls.



7.13.  Deleting an entry

The following functions are used to delete a leaf entry from the LDAP
directory.  There are four variations:

           int ldap_delete_ext(
                   LDAP            *ld,
                   char            *dn,
                   LDAPControl     **serverctrls,
                   LDAPControl     **clientctrls,
                   int             *msgidp
           );

           int ldap_delete_ext_s(
                   LDAP            *ld,
                   char            *dn,
                   LDAPControl     **serverctrls,
                   LDAPControl     **clientctrls
           );

           int ldap_delete(
                   LDAP            *ld,
                   char            *dn
           );

           int ldap_delete_s(
                   LDAP            *ld,
                   char            *dn



Expires: January 1998                                          [Page 25]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


           );

Parameters are:

ld           The session handle.

dn           The name of the entry to delete.

serverctrls  List of LDAP server controls.

clientctrls  List of client controls.

msgidp       This result parameter will be set to the message id of the
             request if the ldap_delete_ext() call succeeds.

Note that the entry to delete must be a leaf entry (i.e., it must have
no children). Deletion of entire subtrees in a single operation is not
supported by LDAP.

The ldap_delete_ext() function initiates an asynchronous delete opera-
tion and returns the constant LDAP_SUCCESS if the request was success-
fully sent, or another LDAP error code if not.  See the section below on
error handling for more information about possible errors and how to
interpret them.  If successful, ldap_delete_ext() places the message id
of the request in *msgidp. A subsequent call to ldap_result(), described
below, can be used to obtain the result of the delete.

Similar to ldap_delete_ext(), the ldap_delete() function initiates an
asynchronous delete operation and returns the message id of the opera-
tion initiated.  As for ldap_delete_ext(), a subsequent call to
ldap_result(), described below, can be used to obtain the result of the
delete. In case of error, ldap_delete() will return -1, setting the ses-
sion error parameters in the LDAP structure appropriately.

The synchronous ldap_delete_ext_s() and ldap_delete_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 the section below on error handling for more information about pos-
sible errors and how to interpret them.

The ldap_delete_ext() and ldap_delete_ext_s() functions support LDAPv3
server controls and client controls.


7.14.  Extended Operations

The ldap_extended_operation() and ldap_extended_operation_s() routines
allow extended LDAP operations to be passed to the server, providing a



Expires: January 1998                                          [Page 26]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


general protocol extensibility mechanism.

           int ldap_extended_operation(
                   LDAP            *ld,
                   char            *exoid,
                   struct berval   *exdata,
                   LDAPControl     **serverctrls,
                   LDAPControl     **clientctrls,
                   int             *msgidp
           );

           int ldap_extended_operation_s(
                   LDAP            *ld,
                   char            *exoid,
                   struct berval   *exdata,
                   LDAPControl     **serverctrls,
                   LDAPControl     **clientctrls,
                   char            **retoidp,
                   struct berval   **retdatap
           );

Parameters are:

ld           The session handle.

requestoid   The dotted-OID text string naming the request.

requestdata  The arbitrary data required by the operation (if NULL, no
             data is sent to the server).

serverctrls  List of LDAP server controls.

clientctrls  List of client controls.

msgidp       This result parameter will be set to the message id of the
             request if the ldap_extended_operation() call succeeds.

retoidp      Pointer to a character string that will be set to an allo-
             cated, dotted-OID text string returned by the server.  This
             string should be disposed of using the ldap_memfree() func-
             tion.  If no OID was returned, *retoidp is set to NULL.

retdatap     Pointer to a berval structure pointer that will be set an
             allocated copy of the data returned by the server.  This
             struct berval should be disposed of using ber_bvfree().  If
             no data is returned, *retdatap is set to NULL.

The ldap_extended_operation() function initiates an asynchronous



Expires: January 1998                                          [Page 27]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


extended operation and returns the constant LDAP_SUCCESS if the request
was successfully sent, or another LDAP error code if not.  See the sec-
tion below on error handling for more information about possible errors
and how to interpret them.  If successful, ldap_extended_operation()
places the message id of the request in *msgidp. A subsequent call to
ldap_result(), described below, can be used to obtain the result of the
extended operation which can be passed to ldap_parse_extended_result()
to obtain the OID and data contained in the response.

The synchronous ldap_extended_operation_s() function returns 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 the section
below on error handling for more information about possible errors and
how to interpret them.  The retoid and retdata parameters are filled in
with the OID and data from the response.  If no OID or data was
returned, these parameters are set to NULL.

The ldap_extended_operation() and ldap_extended_operation_s() functions
both support LDAPv3 server controls and client controls.


8.  Abandoning An Operation

The following calls are used to abandon an operation in progress:

           int ldap_abandon_ext(
                   LDAP            *ld,
                   int             msgid,
                   LDAPControl     **serverctrls,
                   LDAPControl     **clientctrls
           );

           int ldap_abandon(
                   LDAP            *ld,
                   int             msgid
           );


ld           The session handle.

msgid        The message id of the request to be abandoned.

serverctrls  List of LDAP server controls.

clientctrls  List of client controls.

ldap_abandon_ext() abandons the operation with message id msgid and
returns the constant LDAP_SUCCESS if the abandon was successful or



Expires: January 1998                                          [Page 28]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


another LDAP error code if not.  See the section below on error handling
for more information about possible errors and how to interpret them.

ldap_abandon() is identical to ldap_abandon_ext() except that it returns
zero if the abandon was successful, -1 otherwise and does not support
LDAPv3 server controls or client controls.

After a successful call to ldap_abandon() or ldap_abandon_ext(), results
with the given message id are never returned from a subsequent call to
ldap_result().  There is no server response to LDAP abandon operations.


9.  Obtaining Results and Peeking Inside LDAP Messages

ldap_result() is used to obtain the result of a previous asynchronously
initiated operation. Note that depending on how it is called,
ldap_result() may actually return a list or "chain" of messages.

ldap_msgfree() frees the results obtained from a previous call to
ldap_result(), or a synchronous search routine.

ldap_msgtype() returns the type of an LDAP message.  ldap_msgid()
returns the message ID of an LDAP message.

           int ldap_result(
                   LDAP            *ld,
                   int             msgid,
                   int             all,
                   struct timeval  *timeout,
                   LDAPMessage     **res
           );

           int ldap_msgfree( LDAPMessage *res );

           int ldap_msgtype( LDAPMessage *res );

           int ldap_msgid( LDAPMessage *res );

Parameters are:

ld       The session handle.

msgid    The message id of the operation whose results are to be
         returned, or the constant LDAP_RES_ANY (-1) if any result is
         desired.

all      Specifies how many messages will be retrieved in a single call
         to ldap_result().  This parameter only has meaning for search



Expires: January 1998                                          [Page 29]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


         results.  Pass the constant LDAP_MSG_ONE (0x00) to retrieve one
         message at a time.  Pass LDAP_MSG_ALL (0x01) to request that
         all results of a search be received before returning all
         results in a single chain.  Pass LDAP_MSG_RECEIVED (0x02) to
         indicate that all results retrieved so far should be returned
         in the result chain.

timeout  A timeout specifying how long to wait for results to be
         returned.  A NULL value causes ldap_result() to block until
         results are available.  A timeout value of zero seconds speci-
         fies a polling behavior.

res      For ldap_result(), a result parameter that will contain the
         result(s) of the operation. For ldap_msgfree(), the result
         chain to be freed, obtained from a previous call to
         ldap_result(), ldap_search_s(), or ldap_search_st().

Upon successful completion, ldap_result() returns the type of the first
result returned in the res parameter. This will be one of the following
constants.

             LDAP_RES_BIND (0x61)
             LDAP_RES_SEARCH_ENTRY (0x64)
             LDAP_RES_SEARCH_REFERENCE (0x73)      -- new in LDAPv3
             LDAP_RES_SEARCH_RESULT (0x65)
             LDAP_RES_MODIFY (0x67)
             LDAP_RES_ADD (0x69)
             LDAP_RES_DELETE (0x6B)
             LDAP_RES_MODDN (0x6D)
             LDAP_RES_COMPARE (0x6F)
             LDAP_RES_EXTENDED (0x78)              -- new in LDAPv3

ldap_result() returns 0 if the timeout expired and -1 if an error
occurs, in which case the error parameters of the LDAP session handle
will be set accordingly.

ldap_msgfree() frees the result structure pointed to by res and returns
the type of the message it freed.

ldap_msgtype() returns the type of the LDAP message it is passed as a
parameter. The type will be one of the types listed above, or -1 on
error.

ldap_msgid() returns the message ID associated with the LDAP message
passed as a parameter.






Expires: January 1998                                          [Page 30]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


10.  Handling Errors and Parsing Results

The following calls are used to extract information from results and
handle errors returned by other LDAP API routines.

           int ldap_parse_result(
                   LDAP            *ld,
                   LDAPMessage     *res,
                   int             *errcodep,
                   char            **matcheddnp,
                   char            **errmsgp,
                   char            ***referralsp,
                   LDAPControl     ***serverctrlsp,
                   int             freeit
           );

           int ldap_parse_sasl_bind_result(
                   LDAP            *ld,
                   LDAPMessage     *res,
                   struct berval   **servercredp,
                   int             freeit
           );

           int ldap_parse_extended_result(
                   LDAP            *ld,
                   LDAPMessage     *res,
                   char            **resultoidp,
                   struct berval   **resultdata,
                   int             freeit
           );

           char *ldap_err2string( int err );

   The use of the following routines is deprecated.

           int ldap_result2error(
                   LDAP            *ld,
                   LDAPMessage     *res,
                   int             freeit
           );

           void ldap_perror( LDAP *ld, char *msg );

Parameters are:

ld           The session handle.

res          The result of an LDAP operation as returned by



Expires: January 1998                                          [Page 31]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


             ldap_result() or one of the synchronous API operation
             calls.

errcodep     This result parameter will be filled in with the LDAP error
             code field from the LDAPResult message.  This is the indi-
             cation from the server of the outcome of the operation.
             NULL may be passed to ignore this field.

matcheddnp   In the case of a return of LDAP_NO_SUCH_OBJECT, this result
             parameter will be filled in with a DN indicating how much
             of the name in the request was recognized. NULL may be
             passed to ignore this field.  The matched DN string should
             be freed by calling ldap_memfree() which is described later
             in this document.

errmsgp      This result parameter will be filled in with the contents
             of the error message field from the LDAPResult message.
             The error message string should be freed by calling
             ldap_memfree() which is described later in this document.
             NULL may be passed to ignore this field.

referralsp   This result parameter will be filled in with the contents
             of the referrals field from the LDAPResult message, indi-
             cating zero or more alternate LDAP servers where the
             request should be retried.  The referrals array should be
             freed by calling ldap_value_free() which is described later
             in this document.  NULL may be passed to ignore this field.

serverctrlsp This result parameter will be filled in with an allocated
             array of controls copied out of the LDAPResult message.
             The control array should be freed by calling
             ldap_controls_free() which was described earlier.

freeit       A boolean that determines whether the res parameter is
             disposed of or not.  Pass any non-zero value to have these
             routines free res after extracting the requested informa-
             tion.  This is provided as a convenience; you can also use
             ldap_msgfree() to free the result later.

servercredp  For SASL bind results, this result parameter will be filled
             in with the credentials passed back by the server for
             mutual authentication, if given. An allocated berval struc-
             ture is returned that should be disposed of by calling
             ldap_ber_free().  NULL may be passed to ignore this field.

resultoidp   For extended results, this result parameter will be filled
             in with the dotted-OID text representation of the name of
             the extended operation response.  This string should be



Expires: January 1998                                          [Page 32]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


             disposed of by calling ldap_memfree().  NULL may be passed
             to ignore this field.

resultdatap  For extended results, this result parameter will be filled
             in with a pointer to a struct berval containing the data in
             the extended operation response.  It should be disposed of
             by calling ldap_ber_free(). NULL may be passed to ignore
             this field.

err          For ldap_err2string(), an LDAP error code, as returned by
             ldap_result2error() or another LDAP API call.

Additional parameters for the deprecated routines are not described.
Interested readers are referred to RFC 1823.

All of the ldap_parse_*_result() routines skip over messages of type
LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_REFERENCE when looking for a
result message to parse.  They return the constant LDAP_SUCCESS if the
result was successfully parsed and another LDAP error code if not.  Note
that the LDAP error code that indicates the outcome of the operation
performed by the server is placed in the errcodep ldap_parse_result()
parameter.

ldap_err2string() is used to convert a numeric LDAP error code, as
returned by one of the ldap_parse_*_result() routines, or one of the
synchronous API operation calls, into an informative NULL-terminated
character string message describing the error.  It returns a pointer to
static data.


11.  Stepping Through a List of Results

The ldap_first_message() and ldap_next_message() routines are used to
step through the list of messages in a result chain returned by
ldap_result().  For search operations, the result chain may actually
include referral messages, entry messages, and result messages.
ldap_count_messages() is used to count the number of messages returned.
The ldap_msgtype() function, described above, can be used to distinguish
between the different message types.

           LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *res );

           LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *msg );

           int ldap_count_messages( LDAP *ld, LDAPMessage *res );

Parameters are:




Expires: January 1998                                          [Page 33]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


ld     The session handle.

res    The result chain, as obtained by a call to one of the synchronous
       search routines or ldap_result().

msg    The message returned by a previous call to ldap_first_message()
       or ldap_next_message().

ldap_first_message() and ldap_next_message() will return NULL when no
more messages exist in the result set to be returned.  NULL is also
returned if an error occurs while stepping through the entries, in which
case the error parameters in the session handle ld will be set to indi-
cate the error.

ldap_count_messages() returns the number of messages contained in a
chain of results. It can also be used to count the number of messages
that remain in a chain if called with a message, entry, or reference
returned by ldap_first_message(), ldap_next_message(),
ldap_first_entry(), ldap_next_entry(), ldap_first_reference(),
ldap_next_reference().


12.  Parsing Search Results

The following calls are used to parse the entries and references
returned by ldap_search() and friends. These results are returned in an
opaque structure that should only be accessed by calling the routines
described below. Routines are provided to step through the entries and
references returned, step through the attributes of an entry, retrieve
the name of an entry, and retrieve the values associated with a given
attribute in an entry.


12.1.  Stepping Through a List of Entries

The ldap_first_entry() and ldap_next_entry() routines are used to step
through and retrieve the list of entries from a search result chain.
The ldap_first_reference() and ldap_next_reference() routines are used
to step through and retrieve the list of continuation references from a
search result chain.  ldap_count_entries() is used to count the number
of entries returned. ldap_count_references() is used to count the number
of references returned.

           LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *res );

           LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry );

           LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *res );



Expires: January 1998                                          [Page 34]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


           LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *ref );

           int ldap_count_entries( LDAP *ld, LDAPMessage *res );

           int ldap_count_references( LDAP *ld, LDAPMessage *res );

Parameters are:

ld     The session handle.

res    The search result, as obtained by a call to one of the synchro-
       nous search routines or ldap_result().

entry  The entry returned by a previous call to ldap_first_entry() or
       ldap_next_entry().

ldap_first_entry() and ldap_next_entry() will return NULL when no more
entries or references exist in the result set to be returned.  NULL is
also returned if an error occurs while stepping through the entries, in
which case the error parameters in the session handle ld will be set to
indicate the error.

ldap_count_entries() returns the number of entries contained in a chain
of entries. It can also be used to count the number of entries that
remain in a chain if called with a message, entry or reference returned
by ldap_first_message(), ldap_next_message(), ldap_first_entry(),
ldap_next_entry(), ldap_first_reference(), ldap_next_reference().

ldap_count_references() returns the number of references contained in a
chain of search results. It can also be used to count the number of
references that remain in a chain.


12.2.  Stepping Through the Attributes of an Entry

The ldap_first_attribute() and ldap_next_attribute() calls are used to
step through the list of attribute types returned with an entry.

           char *ldap_first_attribute(
                   LDAP            *ld,
                   LDAPMessage     *entry,
                   BerElement      **ptr
           );

           char *ldap_next_attribute(
                   LDAP            *ld,
                   LDAPMessage     *entry,
                   BerElement      *ptr



Expires: January 1998                                          [Page 35]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


           );

           void ldap_memfree( char *mem );

Parameters are:

ld     The session handle.

entry  The entry whose attributes are to be stepped through, as returned
       by ldap_first_entry() or ldap_next_entry().

ptr    In ldap_first_attribute(), the address of a pointer used inter-
       nally to keep track of the current position in the entry. In
       ldap_next_attribute(), the pointer returned by a previous call to
       ldap_first_attribute().

mem    A pointer to memory allocated by the LDAP library, such as the
       attribute names returned by ldap_first_attribute() and
       ldap_next_attribute, or the DN returned by ldap_get_dn().

ldap_first_attribute() and ldap_next_attribute() will return NULL when
the end of the attributes is reached, or if there is an error, in which
case the error parameters in the session handle ld will be set to indi-
cate the error.

Both routines return a pointer to an allocated buffer containing the
current attribute name. This should be freed when no longer in use by
calling ldap_memfree().

ldap_first_attribute() will allocate and return in ptr a pointer to a
BerElement used to keep track of the current position. This pointer
should be passed in subsequent calls to ldap_next_attribute() to step
through the entry's attributes. After a set of calls to
ldap_first_attribute() and ldap_next_attibute(), if ptr is non-NULL, it
should be freed by calling ldap_ber_free( ptr, 0 ). Note that it is very
important to pass the second parameter as 0 (zero) in this call.

The attribute names returned are suitable for passing in a call to
ldap_get_values() and friends to retrieve the associated values.


12.3.  Retrieving the Values of an Attribute

ldap_get_values() and ldap_get_values_len() are used to retrieve the
values of a given attribute from an entry. ldap_count_values() and
ldap_count_values_len() are used to count the returned values.
ldap_value_free() and ldap_value_free_len() are used to free the values.




Expires: January 1998                                          [Page 36]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


           char **ldap_get_values(
                   LDAP            *ld,
                   LDAPMessage     *entry,
                   char            *attr
           );

           struct berval **ldap_get_values_len(
                   LDAP            *ld,
                   LDAPMessage     *entry,
                   char            *attr
           );

           int ldap_count_values( char **vals );

           int ldap_count_values_len( struct berval **vals );

           int ldap_value_free( char **vals );

           int ldap_value_free_len( struct berval **vals );

Parameters are:

ld     The session handle.

entry  The entry from which to retrieve values, as returned by
       ldap_first_entry() or ldap_next_entry().

attr   The attribute whose values are to be retrieved, as returned by
       ldap_first_attribute() or ldap_next_attribute(), or a caller-
       supplied string (e.g., "mail").

vals   The values returned by a previous call to ldap_get_values() or
       ldap_get_values_len().

Two forms of the various calls are provided. The first form is only
suitable for use with non-binary character string data. The second _len
form is used with any kind of data.

Note that the values returned are dynamically allocated and should be
freed by calling either ldap_value_free() or ldap_value_free_len() when
no longer in use.


12.4.  Retrieving the name of an entry

ldap_get_dn() is used to retrieve the name of an entry.
ldap_explode_dn() and ldap_explode_rdn() are used to break up a name
into its component parts. ldap_dn2ufn() is used to convert the name into



Expires: January 1998                                          [Page 37]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


a more "user friendly" format.

           char *ldap_get_dn( LDAP *ld, LDAPMessage *entry );

           char **ldap_explode_dn( char *dn, int notypes );

           char **ldap_explode_rdn( char *rdn, int notypes );

           char *ldap_dn2ufn( char *dn );

Parameters are:

ld      The session handle.

entry   The entry whose name is to be retrieved, as returned by
        ldap_first_entry() or ldap_next_entry().

dn      The dn to explode, such as returned by ldap_get_dn().

rdn     The rdn to explode, such as returned in the components of the
        array returned by ldap_explode_dn().

notypes A boolean parameter, if non-zero indicating that the dn or rdn
        components should have their type information stripped off
        (i.e., "cn=Babs" would become "Babs").

ldap_get_dn() will return NULL if there is some error parsing the dn,
setting error parameters in the session handle ld to indicate the error.
It returns a pointer to malloc'ed space that the caller should free by
calling ldap_memfree() when it is no longer in use.  Note the format of
the DNs returned is given by [4].

ldap_explode_dn() returns a NULL-terminated char * array containing the
RDN components of the DN supplied, with or without types as indicated by
the notypes parameter. The array returned should be freed when it is no
longer in use by calling ldap_value_free().

ldap_explode_rdn() returns a NULL-terminated char * array containing the
components of the RDN supplied, with or without types as indicated by
the notypes parameter. The array returned should be freed when it is no
longer in use by calling ldap_value_free().

ldap_dn2ufn() converts the DN into the user friendly format described in
[5]. The UFN returned is malloc'ed space that should be freed by a call
to ldap_memfree() when no longer in use.






Expires: January 1998                                          [Page 38]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


13.  Encoded ASN.1 Value Manipulation

This section describes routines which may be used to encode and decode
BER-encoded ASN.1 values, which are often used inside of control and
extension values.

With the exceptions of two new functions ber_flatten() and ber_init(),
these functions are compatible with the University of Michigan LDAP 3.3
implementation of BER.


13.1.  General

           struct berval {
                   unsigned long   bv_len;
                   char            *bv_val;
           };

A struct berval contains a sequence of bytes and an indication of its
length.  The bv_val is not null terminated.  bv_len must always be a
nonnegative number.  Applications may allocate their own berval struc-
tures.

           typedef struct berelement {
                   /* opaque */
           } BerElement;

The BerElement structure contains not only a copy of the encoded value,
but also state information used in encoding or decoding.  Applications
cannot allocate their own BerElement structures.  The internal state is
neither thread-specific nor locked, so two threads should not manipulate
the same BerElement value simultaneously.

A single BerElement value cannot be used for both encoding and decoding.

           void ber_bvfree ( struct berval *bv);

ber_bvfree() frees a berval returned from this API.  Both the bv->bv_val
string and the berval itself are freed.  Applications should not use
ber_bvfree() with bervals which the application has allocated.

           void ber_bvecfree ( struct berval **bv );

ber_bvecfree() frees an array of bervals returned from this API.  Each
of the bervals in the array are freed using ber_bvfree(), then the array
itself is freed.

           struct berval *ber_bvdup (struct berval *bv );



Expires: January 1998                                          [Page 39]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


ber_bvdup() returns a copy of a berval.  The bv_val field in the
returned berval points to a different area of memory as the bv_val field
in the argument berval.  The null pointer is returned on error (e.g. out
of memory).

           void ber_free ( BerElement *ber, int fbuf );

ber_free() frees a BerElement which is returned from the API calls
ber_alloc_t() or ber_init().  Each BerElement must be freed by the
caller.  The second argument fbuf should always be set to 1.


13.2.  Encoding

           BerElement *ber_alloc_t(int options);

ber_alloc_t() constructs and returns BerElement.  The null pointer is
returned on error.  The options field contains a bitwise-or of options
which are to be used when generating the encoding of this BerElement.
One option is defined and must always be supplied:

           #define LBER_USE_DER 0x01

When this option is present, lengths will always be encoded in the
minimum number of octets.  Note that this option does not cause values
of sets and sequences to be rearranged in tag and byte order, so these
functions are not suitable for generating DER output as defined in X.509
and X.680.

Unrecognized option bits are ignored.

The BerElement returned by ber_alloc_t() is initially empty.  Calls to
ber_printf() will append bytes to the end of the ber_alloc_t().

           int ber_printf(BerElement *ber, char *fmt, ... )

The ber_printf() routine is used to encode a BER element in much the
same way that sprintf() works.  One important difference, though, is
that state information is kept in the ber argument so that multiple
calls can be made to ber_printf() to append to the end of the BER ele-
ment. ber must be a pointer to a BerElement returned by ber_alloc_t().
ber_printf() interprets and formats its arguments according to the for-
mat string fmt.  ber_printf() returns -1 if there is an error during
encoding.  As with sprintf(), each character in fmt refers to an argu-
ment to ber_printf().

The format string can contain the following format characters:




Expires: January 1998                                          [Page 40]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


't'     Tag.  The next argument is an int specifying the tag to override
        the next element to be written to the ber.  This works across
        calls.  The int value must contain the tag class, constructed
        bit, and tag value.  The tag value must fit in a single octet
        (tag value is less than 32).  For example, a tag of "[3]" for a
        constructed type is 0xA3.

'b'     Boolean.  The next argument is an int, containing either 0 for
        FALSE or 0xff for TRUE.  A boolean element is output.  If this
        format character is not preceded by the 't' format modifier, the
        tag 0x01 is used for the element.

'i'     Integer.  The next argument is an int, containing the integer in
        the host's byte order.  An integer element is output. If this
        format character is not preceded by the 't' format modifier, the
        tag 0x02 is used for the element.

'X'     Bitstring.  The next two arguments are a char * pointer to the
        start of the bitstring, followed by an int containing the number
        of bits in the bitstring.  A bitstring element is output, in
        primitive form.  If this format character is not preceded by the
        't' format modifier, the tag 0x03 is used for the element.

'n'     Null.  No argument is required.  An ASN.1 NULL element is out-
        put.  If this format character is not preceded by the 't' format
        modifier, the tag 0x05 is used for the element.

'o'     Octet string.  The next two arguments are a char *, followed by
        an int with the length of the string.  The string may contain
        null bytes and need not by null-terminated.   An octet string
        element is output, in primitive form.  If this format character
        is not preceded by the 't' format modifier, the tag 0x04 is used
        for the element.

's'     Octet string.  The next argument is a char * pointing to a
        null-terminated string.  An octet string element in primitive
        form is output, which does not include the trailing ' ' byte. If
        this format character is not preceded by the 't' format modif-
        ier, the tag 0x04 is used for the element.

'v'     Several octet strings.  The next argument is a char **, an array
        of char * pointers to null-terminated strings.  The last element
        in the array must be a null pointer. The octet strings do not
        include the trailing SEQUENCE OF octet strings.  The 't' format
        modifier cannot be used with this format character.

'V'     Several octet strings.  A null-terminated array of berval *'s is
        supplied. Note that a construct like '{V}' is required to get an



Expires: January 1998                                          [Page 41]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


        actual SEQUENCE OF octet strings. The 't' format modifier cannot
        be used with this format character.

'{'     Begin sequence.  No argument is required.  If this format char-
        acter is not preceded by the 't' format modifier, the tag 0x30
        is used.

'}'     End sequence.  No argument is required.  The 't' format modifier
        cannot be used with this format character.

'['     Begin set.  No argument is required.  If this format character
        is not preceded by the 't' format modifier, the tag 0x31 is
        used.

']'     End set.  No argument is required.  The 't' format modifier can-
        not be used with this format character.

Each use of a '{' format character must be matched by a '}' character,
either later in the format string, or in the format string of a subse-
quent call to ber_printf() for that BerElement.  The same applies to the
'[' and

Sequences and sets nest, and implementations of this API must maintain
internal state to be able to properly calculate the lengths.

           int ber_flatten (BerElement *ber, struct berval **bvPtr);

The ber_flatten routine allocates a struct berval whose contents are a
BER encoding taken from the ber argument. The bvPtr pointer points to
the returned berval, which must be freed using ber_bvfree().  This rou-
tine returns 0 on success and -1 on error.

The ber_flatten API call is not present in U-M LDAP 3.3.

The use of ber_flatten on a BerElement in which all '{' and '}' format
modifiers have not been properly matched can result in a berval whose
contents are not a valid BER encoding.


13.3.  Encoding Example

The following is an example of encoding the following ASN.1 data type:

      Example1Request ::= SEQUENCE {
           s     OCTET STRING, -- must be printable
           val1  INTEGER,
           val2  [0] INTEGER DEFAULT 0
      }



Expires: January 1998                                          [Page 42]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


      int encode_example1(char *s,int val1,int val2,struct berval **bvPtr)
      {
           BerElement *ber;
           int rc;

           ber = ber_alloc_t(LBER_USE_DER);

           if (ber == NULL) return -1;

           if (ber_printf(ber,"{si",s,val1) == -1) {
                   ber_free(ber,1);
                   return -1;
           }

           if (val2 != 0) {
                   if (ber_printf(ber,"ti",0x80,val2) == -1) {
                           ber_free(ber,1);
                           return -1;
                   }
           }

           if (ber_printf(ber,"}") == -1) {
                   ber_free(ber,1);
                   return -1;
           }

           rc = ber_flatten(ber,bvPtr);
           ber_free(ber,1);
           return -1;
      }


13.4.  Decoding

The following two symbols are available to applications.

           #define LBER_ERROR   0xffffffffL
           #define LBER_DEFAULT 0xffffffffL

           BerElement *ber_init (struct berval *bv);

The ber_init functions construct BerElement and returns a new BerElement
containing a copy of the data in the bv argument.  ber_init returns the
null pointer on error.

           unsigned long ber_scanf (BerElement *ber, char *fmt, ... );

The ber_scanf() routine is used to decode a BER element in much the same



Expires: January 1998                                          [Page 43]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


way that sscanf() works.  One important difference, though, is that some
state information is kept with the ber argument so that multiple calls
can be made to ber_scanf() to sequentially read from the BER element.
The ber argument must be a pointer to a BerElement returned by
ber_init().  ber_scanf interprets the bytes according to the format
string fmt, and stores the results in its additional arguments.
ber_scanf() returns LBER_ERROR on error, and a nonnegative number on
success.

The format string contains conversion specifications which are used to
direct the interpretation of the BER element.  The format string can
contain the following characters:

'a'     Octet string.  A char ** argument should be supplied.  Memory is
        allocated, filled with the contents of the octet string, null-
        terminated, and the pointer to the string is stored in the argu-
        ment.  The returned value must be freed using ldap_memfree.  The
        tag of the element must indicate the primitive form (constructed
        strings are not supported) but is otherwise ignored and dis-
        carded during the decoding.  This format cannot be used with
        octet strings which could contain null bytes.

'O'     Octet string.  A struct berval ** argument should be supplied,
        which upon return points to a allocated struct berval containing
        the octet string and its length.  ber_bvfree() must be called to
        free the allocated memory.  The tag of the element must indicate
        the primitive form (constructed strings are not supported) but
        is otherwise ignored during the decoding.

'b'     Boolean.  A pointer to an int should be supplied. The int value
        stored will be 0 for FALSE or nonzero for TRUE.  The tag of the
        element must indicate the primitive form but is otherwise
        ignored during the decoding.

'i'     Integer.  A pointer to an int should be supplied. The int value
        stored will be in host byte order.  The tag of the element must
        indicate the primitive form but is otherwise ignored during the
        decoding.  ber_scanf() will return an error if the integer can-
        not be stored in an int.

'B'     Bitstring.  A char ** argument should be supplied which will
        point to the allocated bits, followed by an unsigned long *
        argument, which will point to the length (in bits) of the bit-
        string returned.  ldap_memfree must be called to free the bit-
        string.  The tag of the element must indicate the primitive form
        (constructed bitstrings are not supported) but is otherwise
        ignored during the decoding.




Expires: January 1998                                          [Page 44]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


'n'     Null.  No argument is required.  The element is simply skipped
        if it is recognized as a zero-length element.  The tag is
        ignored.

'v'     Several octet strings.  A char *** argument should be supplied,
        which upon return points to a allocated null-terminated array of
        char *'s containing the octet strings.  NULL is stored if the
        sequence is empty.  ldap_memfree must be called to free each
        element of the array and the array itself.  The tag of the
        sequence and of the octet strings are ignored.

'V'     Several octet strings (which could contain null bytes).  A
        struct berval *** should be supplied, which upon return points
        to a allocated null-terminated array of struct berval *'s con-
        taining the octet strings and their lengths.  NULL is stored if
        the sequence is empty. ber_bvecfree() can be called to free the
        allocated memory.  The tag of the sequence and of the octet
        strings are ignored.

'x'     Skip element.  The next element is skipped.  No argument is
        required.

'{'     Begin sequence.  No argument is required.  The initial sequence
        tag and length are skipped.

'}'     End sequence.  No argument is required.

'['     Begin set.  No argument is required.  The initial set tag and
        length are skipped.

']'     End set.  No argument is required.

           unsigned long ber_peek_tag (BerElement *ber, unsigned long *lenPtr);

ber_peek_tag() returns the tag of the next element to be parsed in the
BerElement argument.  The length of this element is stored in the
*lenPtr argument.  LBER_DEFAULT is returned if there is no further data
to be read.  The ber argument is not modified.

           unsigned long ber_skip_tag (BerElement *ber, unsigned long *lenPtr);

ber_skip_tag() is similar to ber_peek_tag(), except that the state
pointer in the BerElement argument is advanced past the first tag and
length, and is pointed to the value part of the next element.  This rou-
tine should only be used with constructed types and situations when a
BER encoding is used as the value of an OCTET STRING.  The length of the
value is stored in *lenPtr.




Expires: January 1998                                          [Page 45]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


           unsigned long ber_first_element(BerElement *ber,
                   unsigned long *lenPtr, char **opaquePtr);

           unsigned long ber_next_element  (BerElement *ber,
                   unsigned long *lenPtr, char *opaque);

ber_first_element() and ber_next_element() are used to traverse a SET,
SET OF, SEQUENCE or SEQUENCE OF data value. ber_first_element() calls
ber_skip_tag(), stores internal information in *lenPtr and *opaquePtr,
and calls ber_peek_tag() for the first element inside the constructed
value. LBER_DEFAULT is returned if the constructed value is empty.
ber_next_element() positions the state at the start of the next element
in the constructed type.  LBER_DEFAULT is returned if there are no
further values.

The len and opaque values should not be used by applications other than
as arguments to ber_next_element(), as shown in the example below.


13.5.  Decoding Example

The following is an example of decoding an ASN.1 data type:

      Example2Request ::= SEQUENCE {
           dn    OCTET STRING, -- must be printable
           scope ENUMERATED { b (0), s (1), w (2) },
           ali   ENUMERATED { n (0), s (1), f (2), a (3) },
           size  INTEGER,
           time  INTEGER,
           tonly BOOLEAN,
           attrs SEQUENCE OF OCTET STRING, -- must be printable
           [0] SEQUENCE OF SEQUENCE {
              type  OCTET STRING -- must be printable,
              crit  BOOLEAN DEFAULT FALSE,
              value OCTET STRING
           } OPTIONAL }

      #define LDAP_TAG_CONTROL_LIST 0xA0L /* context specific cons 0 */

      int decode_example2(struct berval *bv)
      {
           BerElement *ber;
           unsigned long len;
           int scope, ali, size, time, tonly;
           char *dn = NULL, **attrs = NULL;
           int res,i,rc = 0;

           ber = ber_init(bv);



Expires: January 1998                                          [Page 46]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


           if (ber == NULL) {
                   printf("ERROR ber_init failed0);
                   return -1;
           }

           res = ber_scanf(ber,"{aiiiiib{v}",&dn,&scope,&ali,
                           &size,&time,&tonly,&attrs);

           if (res == -1) {
                   printf("ERROR ber_scanf failed0);
                   ber_free(ber,1);
                   return -1;
           }

           /* *** use dn */
           ldap_memfree(dn);

           for (i = 0; attrs != NULL && attrs[i] != NULL; i++) {
                   /* *** use attrs[i] */
                   ldap_memfree(attrs[i]);
           }
           ldap_memfree(attrs);

           if (ber_peek_tag(ber,&len) == LDAP_TAG_CONTROL_LIST) {
                   char *opaque;
                   unsigned long tag;

                   for (tag = ber_first_element(ber,&len,&opaque);
                        tag != LBER_DEFAULT;
                        tag = ber_next_element (ber,&len,opaque)) {

                           unsigned long ttag, tlen;
                           char *type;
                           int crit;
                           struct berval *value;

                           if (ber_scanf(ber,"{a",&type) == LBER_ERROR) {
                                   printf("ERROR cannot parse type0);
                                   break;
                           }
                           /* *** use type */
                           ldap_memfree(type);

                           ttag = ber_peek_tag(ber,&tlen);
                           if (ttag == 0x01) {  /* boolean */
                                   if (ber_scanf(ber,"b",
                                                 &crit) == LBER_ERROR) {
                                           printf("ERROR cannot parse crit0);



Expires: January 1998                                          [Page 47]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


                                           rc = -1;
                                           break;
                                   }
                           } else if (ttag == 0x04) { /* octet string */
                                   crit = 0;
                           } else {
                                   printf("ERROR extra field in controls0);
                                   break;
                           }

                           if (ber_scanf(ber,"O}",&value) == LBER_ERROR) {
                                   printf("ERROR cannot parse value0);
                                   rc = -1;
                                   break;
                           }
                           /* *** use value */
                           ldap_bvfree(value);
                   }
           }

           ber_scanf(ber,"}");

           ber_free(ber,1);

           return rc;
       }



14.  Security Considerations

LDAPv2 supports security through protocol-level authentication using
clear-text passwords.  LDAPv3 adds support for SASL [8] (Simple Authen-
tication Security Layer) methods.  LDAPv3 also supports operation over a
secure transport layer using Transport Layer Security TLS [8].  Readers
are referred to the protocol documents for discussion of related secu-
rity considerations.

Implementations of this API should be cautious when handling authentica-
tion credentials.  In particular, keeping long-lived copies of creden-
tials without the application's knowledge is discouraged.


15.  Acknowledgements

Many members of the IETF ASID working group as well as members of the
Internet at large have provided useful comments and suggestions that
have been incorporated into this revision.



Expires: January 1998                                          [Page 48]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


This original material upon which this revision is based was based upon
work supported by the National Science Foundation under Grant No.  NCR-
9416667.


16.  Bibliography

[1]  The Directory: Selected Attribute Syntaxes.  CCITT, Recommendation
     X.520.

[2]  M. Wahl, A. Coulbeck, T. Howes, S. Kille, W. Yeong, C. Robbins,
     "Lightweight Directory Access Protocol Attribute Syntax Defini-
     tions", INTERNET-DRAFT <draft-ietf-asid-ldapv3-attributes-06.txt>,
     11 July 1997.

[3]  T. Howes, "A String Representation of LDAP Search Filters,"
     INTERNET-DRAFT <draft-ietf-asid-ldapv3-filter-02.txt>, May 1997.

[4]  S. Kille, M. Wahl, "A UTF-8 String Representation of Distinguished
     Names", INTERNET-DRAFT <draft-ietf-asid-ldapv3-dn-03.txt>, 29 April
     1997.

[5]  S. Kille, "Using the OSI Directory to Achieve User Friendly Nam-
     ing," RFC 1781, March 1995.

[6]  M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
     (v3)", INTERNET-DRAFT <draft-ietf-asid-ldapv3-protocol-06.txt>, 11
     July 1997.

[7]  A. Herron, T. Howes, M. Wahl, "LDAP Control Extension for Server
     Side Sorting of Search Result," INTERNET-DRAFT <draft-ietf-asid-
     ldapv3-sorting-00.txt>, 16 April 1997.

[8]  J. Meyers, "Simple Authentication and Security Layer", INTERNET-
     DRAFT <draft-myers-auth-sasl-11.txt>, April 1997.

[9]  "Lightweight Directory Access Protocol (v3) Extension for Transport
     Layer Security", INTERNET-DRAFT <draft-ietf-asid-ldapv3-tls-
     01.txt>, June 1997.

[10] "UTF-8, a transformation format of Unicode and ISO 10646", RFC
     2044, October 1996.

[11] "IP Version 6 Addressing Architecture,", RFC 1884, December 1995.







Expires: January 1998                                          [Page 49]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


17.  Author's Addresses

   Tim Howes
   Netscape Communications Corp.
   501 E. Middlefield Rd., Mailstop MV068
   Mountain View, CA 94043
   USA
   +1 415 937-3419
   howes@netscape.com


   Mark Smith
   Netscape Communications Corp.
   501 E. Middlefield Rd., Mailstop MV068
   Mountain View, CA 94043
   USA
   +1 415 937-3477
   mcs@netscape.com

   Andy Herron
   Microsoft Corp.
   1 Microsoft Way
   Redmond, WA 98052
   USA
   +1 425 882-8080
   andyhe@microsoft.com

   Chris Weider
   Microsoft Corp.
   1 Microsoft Way
   Redmond, WA 98052
   USA
   +1 425 882-8080
   cweider@microsoft.com

   Mark Wahl
   Critical Angle Inc.
   4815 W Braker Lane #502-385
   Austin, TX 78759
   USA
   M.Wahl@critical-angle.com


18.  Appendix A - Sample LDAP API Code

   #include <ldap.h>

   main()



Expires: January 1998                                          [Page 50]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


   {
           LDAP            *ld;
           LDAPMessage     *res, *e;
           int             i;
           char            *a, *dn;
           BerElement      *ptr;
           char            **vals;

           /* open an LDAP session */
           if ( (ld = ldap_init( "dotted.host.name", LDAP_PORT )) == NULL )
                   exit( 1 );

           /* authenticate as nobody */
           if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {
                   ldap_perror( ld, "ldap_simple_bind_s" );
                   exit( 1 );
           }

           /* search for entries with cn of "Babs Jensen", return all attrs  */
           if ( ldap_search_s( ld, "o=University of Michigan, c=US",
               LDAP_SCOPE_SUBTREE, "(cn=Babs Jensen)", NULL, 0, &res )
               != LDAP_SUCCESS ) {
                   ldap_perror( ld, "ldap_search_s" );
                   exit( 1 );
           }

           /* step through each entry returned */
           for ( e = ldap_first_entry( ld, res ); e != NULL;
               e = ldap_next_entry( ld, e ) ) {
                   /* print its name */
                   dn = ldap_get_dn( ld, e );
                   printf( "dn: %s\n", dn );
                   ldap_memfree( dn );

                   /* print each attribute */
                   for ( a = ldap_first_attribute( ld, e, &ptr ); a != NULL;
                       a = ldap_next_attribute( ld, e, ptr ) ) {
                           printf( "attribute: %s\n", a );

                           /* print each value */
                           vals = ldap_get_values( ld, e, a );
                           for ( i = 0; vals[i] != NULL; i++ ) {
                                   printf( "value: %s\n", vals[i] );
                           }
                           ldap_value_free( vals );
                   }
                   if ( ptr != NULL ) {
                           ldap_ber_free( ptr, 0 );



Expires: January 1998                                          [Page 51]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


                   }
           }
           /* free the search results */
           ldap_msgfree( res );

           /* close and free connection resources */
           ldap_unbind( ld );
   }



19.  Appendix B - Outstanding Issues


19.1.  Support for multithreaded applications

In order to support multithreaded applications in a platform-independent
way, some additions to the LDAP API are needed.  Different implementors
have taken different paths to solve this problem in the past.  A common
set of thread-related API calls must be defined so that application
developers are not unduly burdened.  These will be added to a future
revision of this specification.


19.2.  Using Transport Layer Security (TLS)

The API calls used to support TLS must be specified.  They will be added
to a future revision of this specification.


19.3.  Client control for chasing referrals

A client control has been defined that can be used to specify on a per-
operation basis whether references and external referrals are automati-
cally chased by the client library.  This will be added to a future
revision of this specification.


19.4.  Potential confusion between hostname:port and IPv6 addresses

String representations of IPv6 network addresses [11] can contain colon
characters.  The ldap_init() call is specified to take strings of the
form "hostname:port" or "ipaddress:port".  If IPv6 addresses are used,
the latter could be ambiguous.  A future revision of this specification
will resolve this issue.






Expires: January 1998                                          [Page 52]


C LDAP API      The C LDAP Application Program Interface    29 July 1997


19.5.  Need to track SASL API standardization efforts

If a standard Simple Authentication and Security Layer API is defined,
it may be necessary to modify the LDAP API to accommodate it.


19.6.  Support for character sets other than UTF-8?

Some application developers would prefer to pass string data using a
character set other than UTF-8.  This could be accommodated by adding a
new option to ldap_set_option() that supports choosing a character set.
If this feature is added, the number of different character sets sup-
ported should definitely be minimized.


19.7.  Use of UTF-8 with LDAPv2 servers

Strings are always passed as UTF-8 in this API but LDAP version 2
servers do not support the full range of UTF-8 characters.  The expected
behavior of this API when using LDAP version 2 with unsupported charac-
ters should be specified.






























Expires: January 1998                                          [Page 53]

1.     Status of this Memo............................................1
2.     Introduction...................................................1
3.     Overview of the LDAP Model.....................................2
4.     Overview of LDAP API Use.......................................3
5.     Common Data Structures.........................................4
6.     LDAP Error Codes...............................................5
7.     Performing LDAP Operations.....................................6
7.1.      Initializing an LDAP Session................................6
7.2.      LDAP Session Handle Options.................................7
7.3.      Working with controls.......................................10
7.4.      Authenticating to the directory.............................11
7.5.      Closing the session.........................................13
7.6.      Searching...................................................13
7.7.      Reading an Entry............................................17
7.8.      Listing the Children of an Entry............................17
7.9.      Comparing a Value Against an Entry..........................17
7.10.     Modifying an entry..........................................19
7.11.     Modifying the Name of an Entry..............................21
7.12.     Adding an entry.............................................23
7.13.     Deleting an entry...........................................25
7.14.     Extended Operations.........................................26
8.     Abandoning An Operation........................................28
9.     Obtaining Results and Peeking Inside LDAP Messages.............29
10.    Handling Errors and Parsing Results............................31
11.    Stepping Through a List of Results.............................33
12.    Parsing Search Results.........................................34
12.1.     Stepping Through a List of Entries..........................34
12.2.     Stepping Through the Attributes of an Entry.................35
12.3.     Retrieving the Values of an Attribute.......................36
12.4.     Retrieving the name of an entry.............................37
13.    Encoded ASN.1 Value Manipulation...............................39
13.1.     General.....................................................39
13.2.     Encoding....................................................40
13.3.     Encoding Example............................................42
13.4.     Decoding....................................................43
13.5.     Decoding Example............................................46
14.    Security Considerations........................................48
15.    Acknowledgements...............................................48
16.    Bibliography...................................................49
17.    Author's Addresses.............................................50
18.    Appendix A - Sample LDAP API Code..............................50
19.    Appendix B - Outstanding Issues................................52
19.1.     Support for multithreaded applications......................52
19.2.     Using Transport Layer Security (TLS)........................52
19.3.     Client control for chasing referrals........................52
19.4.     Potential confusion between hostname:port and IPv6 addresses52
19.5.     Need to track SASL API standardization efforts..............53
19.6.     Support for character sets other than UTF-8?................53
19.7.     Use of UTF-8 with LDAPv2 servers............................53