home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / drafts / draft_ietf_a_c / draft-ietf-asid-ldap-c-api-00.txt < prev    next >
Text File  |  1997-08-01  |  113KB  |  3,031 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Network Working Group                                           T. Howes
  8. INTERNET-DRAFT                             Netscape Communications Corp.
  9. Intended Category: Standards Track                              M. Smith
  10. Obsoletes: RFC 1823                        Netscape Communications Corp.
  11. Expires: January 1998                                          A. Herron
  12.                                                          Microsoft Corp.
  13.                                                                C. Weider
  14.                                                          Microsoft Corp.
  15.                                                                  M. Wahl
  16.                                                     Critical Angle, Inc.
  17.  
  18.                                                             29 July 1997
  19.  
  20.  
  21.                 The C LDAP Application Program Interface
  22.                   <draft-ietf-asid-ldap-c-api-00.txt>
  23.  
  24.  
  25.  
  26. 1.  Status of this Memo
  27.  
  28. This draft document will be submitted to the RFC Editor as a Standards
  29. Track document. Distribution of this memo is unlimited. Please send com-
  30. ments to the authors.
  31.  
  32. This document is an Internet-Draft.  Internet-Drafts are working docu-
  33. ments of the Internet Engineering Task Force (IETF), its areas, and its
  34. working groups.  Note that other groups may also distribute working
  35. documents as Internet-Drafts.
  36.  
  37. Internet-Drafts are draft documents valid for a maximum of six months
  38. and may be updated, replaced, or obsoleted by other documents at any
  39. time.  It is inappropriate to use Internet-Drafts as reference material
  40. or to cite them other than as ``work in progress.''
  41.  
  42. To learn the current status of any Internet-Draft, please check the
  43. ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow
  44. Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe),
  45. ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim).
  46.  
  47. 2.  Introduction
  48.  
  49. This document defines a C language application program interface to the
  50. lightweight directory access protocol (LDAP). This document replaces the
  51. previous definition of this API, defined in RFC 1823, updating it to
  52. include support for features found in version 3 of the LDAP protocol.
  53. New extended operation functions were added to support LDAPv3 features
  54. such as controls.  In addition, other LDAP API changes were made to
  55.  
  56.  
  57.  
  58. Expires: January 1998                                           [Page 1]
  59.  
  60. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  61.  
  62.  
  63. support information hiding and thread safety.
  64.  
  65. The C LDAP API is designed to be powerful, yet simple to use. It defines
  66. compatible synchronous and asynchronous interfaces to LDAP to suit a
  67. wide variety of applications. This document gives a brief overview of
  68. the LDAP model, then an overview of how the API is used by an applica-
  69. tion program to obtain LDAP information.  The API calls are described in
  70. detail, followed by an appendix that provides some example code demon-
  71. strating the use of the API. This document provides information to the
  72. Internet community. It does not specify any standard.
  73.  
  74. 3.  Overview of the LDAP Model
  75.  
  76. LDAP is the lightweight directory access protocol, described in [2] and
  77. [6]. It can provide a lightweight frontend to the X.500 directory [1],
  78. or a stand-alone service. In either mode, LDAP is based on a client-
  79. server model in which a client makes a TCP connection to an LDAP server,
  80. over which it sends requests and receives responses.
  81.  
  82. The LDAP information model is based on the entry, which contains infor-
  83. mation about some object (e.g., a person).  Entries are composed of
  84. attributes, which have a type and one or more values. Each attribute has
  85. a syntax that determines what kinds of values are allowed in the attri-
  86. bute (e.g., ASCII characters, a jpeg photograph, etc.) and how those
  87. values behave during directory operations (e.g., is case significant
  88. during comparisons).
  89.  
  90. Entries may be organized in a tree structure, usually based on politi-
  91. cal, geographical, and organizational boundaries. Each entry is uniquely
  92. named relative to its sibling entries by its relative distinguished name
  93. (RDN) consisting of one or more distinguished attribute values from the
  94. entry.  At most one value from each attribute may be used in the RDN.
  95. For example, the entry for the person Babs Jensen might be named with
  96. the "Barbara Jensen" value from the commonName attribute.
  97.  
  98. A globally unique name for an entry, called a distinguished name or DN,
  99. is constructed by concatenating the sequence of RDNs from the entry up
  100. to the root of the tree. For example, if Babs worked for the University
  101. of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen,
  102. o=University of Michigan, c=US". The DN format used by LDAP is defined
  103. in [4].
  104.  
  105. Operations are provided to authenticate, search for and retrieve infor-
  106. mation, modify information, and add and delete entries from the tree.
  107. The next sections give an overview of how the API is used and detailed
  108. descriptions of the LDAP API calls that implement all of these func-
  109. tions.
  110.  
  111.  
  112.  
  113.  
  114. Expires: January 1998                                           [Page 2]
  115.  
  116. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  117.  
  118.  
  119. 4.  Overview of LDAP API Use
  120.  
  121. An application generally uses the C LDAP API in four simple steps.
  122.  
  123. -    Initialize an LDAP session with a default LDAP server. The
  124.      ldap_init() function returns a handle to the session, allowing mul-
  125.      tiple connections to be open at once.
  126.  
  127. -    Authenticate to the LDAP server. The ldap_bind() function and
  128.      friends support a variety of authentication methods.
  129.  
  130. -    Perform some LDAP operations and obtain some results. ldap_search()
  131.      and friends return results which can be parsed by
  132.      ldap_result2error(), ldap_first_entry(), ldap_next_entry(), etc.
  133.  
  134. -    Close the session. The ldap_unbind() function closes the connec-
  135.      tion.
  136.  
  137. Operations can be performed either synchronously or asynchronously.  The
  138. names of the synchronous functions end in _s. For example, a synchronous
  139. search can be completed by calling ldap_search_s(). An asynchronous
  140. search can be initiated by calling ldap_search(). All synchronous rou-
  141. tines return an indication of the outcome of the operation (e.g, the
  142. constant LDAP_SUCCESS or some other error code).  The asynchronous rou-
  143. tines return the message id of the operation initiated. This id can be
  144. used in subsequent calls to ldap_result() to obtain the result(s) of the
  145. operation. An asynchronous operation can be abandoned by calling
  146. ldap_abandon().
  147.  
  148. Results and errors are returned in an opaque structure called LDAPMes-
  149. sage.  Routines are provided to parse this structure, step through
  150. entries and attributes returned, etc. Routines are also provided to
  151. interpret errors. Later sections of this document describe these rou-
  152. tines in more detail.
  153.  
  154. LDAP version 3 servers may return referrals to other servers.  By
  155. default, implementations of this API will attempt to follow referrals
  156. automatically for the application.  This behavior can be disabled glo-
  157. bally (using the ldap_set_option() call) or on a per-request basis
  158. through the use of a client control.
  159.  
  160. As in the LDAPv3 protocol itself, all DNs and string values that are
  161. passed into or produced by the C LDAP API are represented as UTF-8[10]
  162. characters.
  163.  
  164. For compatibility with existing applications, implementations of this
  165. API will by default use version 2 of the LDAP protocol.  Applications
  166. that intend to take advantage of LDAP version 3 features will need to
  167.  
  168.  
  169.  
  170. Expires: January 1998                                           [Page 3]
  171.  
  172. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  173.  
  174.  
  175. use the ldap_set_option() call with a LDAP_OPT_PROTOCOL_VERSION to
  176. switch to version 3.
  177.  
  178.  
  179. 5.  Common Data Structures
  180.  
  181. Some data structures that are common to several LDAP API functions are
  182. defined here:
  183.  
  184.            typedef struct ldap LDAP;
  185.  
  186.            typedef struct ldapmsg LDAPMessage;
  187.  
  188.            struct berval {
  189.                    unsigned long   bv_len;
  190.                    char            *bv_val;
  191.            };
  192.  
  193.            struct timeval {
  194.                    long            tv_sec;
  195.                    long            tv_usec;
  196.            };
  197.  
  198. The LDAP structure is an opaque data type that represents an LDAP ses-
  199. sion Typically this corresponds to a connection to a single server, but
  200. it may encompass several server connections in the face of LDAPv3 refer-
  201. rals.
  202.  
  203. The LDAPMessage structure is an opaque data type that is used to return
  204. results and error information.
  205.  
  206. The berval structure is used to represent arbitrary binary data and its
  207. fields have the following meanings:
  208.  
  209. bv_len   Length of data in bytes.
  210.  
  211. bv_val   A pointer to the data itself.
  212.  
  213.  
  214. The timeval structure is used to represent an interval of time and its
  215. fields have the following meanings:
  216.  
  217. tv_sec   Seconds component of time interval.
  218.  
  219. tv_usec  Microseconds component of time interval.
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226. Expires: January 1998                                           [Page 4]
  227.  
  228. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  229.  
  230.  
  231. 6.  LDAP Error Codes
  232.  
  233. Many of the LDAP API routines return LDAP error codes, some of which
  234. indicate local errors and some of which may be returned by servers.
  235. Supported error codes are (hexadecimal values are given in parentheses
  236. after the constant):
  237.  
  238.            LDAP_SUCCESS (0x00)
  239.            LDAP_OPERATIONS_ERROR( 0x01)
  240.            LDAP_PROTOCOL_ERROR (0x02)
  241.            LDAP_TIMELIMIT_EXCEEDED (0x03)
  242.            LDAP_SIZELIMIT_EXCEEDED (0x04)
  243.            LDAP_COMPARE_FALSE (0x05)
  244.            LDAP_COMPARE_TRUE (0x06)
  245.            LDAP_STRONG_AUTH_NOT_SUPPORTED (0x07)
  246.            LDAP_STRONG_AUTH_REQUIRED (0x08)
  247.            LDAP_REFERRAL (0x0a)                            -- new in LDAPv3
  248.            LDAP_ADMINLIMIT_EXCEEDED (0x0b)                 -- new in LDAPv3
  249.            LDAP_UNAVAILABLE_CRITICAL_EXTENSION (0x0c)      -- new in LDAPv3
  250.            LDAP_CONFIDENTIALITY_REQUIRED (0x0d)            -- new in LDAPv3
  251.            LDAP_NO_SUCH_ATTRIBUTE (0x10)
  252.            LDAP_UNDEFINED_TYPE (0x11)
  253.            LDAP_INAPPROPRIATE_MATCHING (0x12)
  254.            LDAP_CONSTRAINT_VIOLATION (0x13)
  255.            LDAP_TYPE_OR_VALUE_EXISTS (0x14)
  256.            LDAP_INVALID_SYNTAX (0x15)
  257.            LDAP_NO_SUCH_OBJECT (0x20)
  258.            LDAP_ALIAS_PROBLEM (0x21)
  259.            LDAP_INVALID_DN_SYNTAX (0x22)
  260.            LDAP_IS_LEAF (0x23)                             -- not used in LDAPv3
  261.            LDAP_ALIAS_DEREF_PROBLEM (0x24)
  262.            LDAP_INAPPROPRIATE_AUTH (0x30)
  263.            LDAP_INVALID_CREDENTIALS (0x31)
  264.            LDAP_INSUFFICIENT_ACCESS (0x32)
  265.            LDAP_BUSY (0x33)
  266.            LDAP_UNAVAILABLE (0x34)
  267.            LDAP_UNWILLING_TO_PERFORM (0x35)
  268.            LDAP_LOOP_DETECT (0x36)
  269.            LDAP_NAMING_VIOLATION (0x40)
  270.            LDAP_OBJECT_CLASS_VIOLATION (0x41)
  271.            LDAP_NOT_ALLOWED_ON_NONLEAF (0x42)
  272.            LDAP_NOT_ALLOWED_ON_RDN (0x43)
  273.            LDAP_ALREADY_EXISTS (0x44)
  274.            LDAP_NO_OBJECT_CLASS_MODS (0x45)
  275.            LDAP_RESULTS_TOO_LARGE (0x46)
  276.            LDAP_AFFECTS_MULTIPLE_DSAS (0x47)               -- new in LDAPv3
  277.            LDAP_OTHER (0x50)
  278.            LDAP_SERVER_DOWN (0x51)
  279.  
  280.  
  281.  
  282. Expires: January 1998                                           [Page 5]
  283.  
  284. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  285.  
  286.  
  287.            LDAP_LOCAL_ERROR (0x52)
  288.            LDAP_ENCODING_ERROR (0x53)
  289.            LDAP_DECODING_ERROR (0x54)
  290.            LDAP_TIMEOUT (0x55)
  291.            LDAP_AUTH_UNKNOWN (0x56)
  292.            LDAP_FILTER_ERROR (0x57)
  293.            LDAP_USER_CANCELLED (0x58)
  294.            LDAP_PARAM_ERROR (0x59)
  295.            LDAP_NO_MEMORY (0x5a)
  296.            LDAP_CONNECT_ERROR (0x5b)
  297.            LDAP_NOT_SUPPORTED (0x5c)
  298.            LDAP_CONTROL_NOT_FOUND (0x5d)
  299.            LDAP_NO_RESULTS_RETURNED (0x5e)
  300.            LDAP_MORE_RESULTS_TO_RETURN (0x5f)
  301.            LDAP_CLIENT_LOOP (0x60)
  302.            LDAP_REFERRAL_LIMIT_EXCEEDED (0x61)
  303.  
  304.  
  305. 7.  Performing LDAP Operations
  306.  
  307. This section describes each LDAP operation API call in detail. All func-
  308. tions take a "session handle," a pointer to an LDAP structure containing
  309. per-connection information.  Many routines return results in an LDAPMes-
  310. sage structure. These structures and others are described as needed
  311. below.
  312.  
  313.  
  314. 7.1.  Initializing an LDAP Session
  315.  
  316. ldap_init() initializes a session with an LDAP server. The server is not
  317. actually contacted until an operation is performed that requires it,
  318. allowing various options to be set after initialization.
  319.  
  320.         LDAP *ldap_init(
  321.                 char    *hostname,
  322.                 int     portno
  323.         );
  324.  
  325. Use of the following routine is deprecated.
  326.  
  327.         LDAP *ldap_open(
  328.                 char    *hostname,
  329.                 int     portno
  330.         );
  331.  
  332. Parameters are:
  333.  
  334. hostname Contains a space-separated list of hostnames or dotted strings
  335.  
  336.  
  337.  
  338. Expires: January 1998                                           [Page 6]
  339.  
  340. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  341.  
  342.  
  343.          representing the IP address of hosts running an LDAP server to
  344.          connect to. Each hostname in the list can include an optional
  345.          port number which is separated from the host itself with a
  346.          colon (:) character.  The hosts are tried in the order listed,
  347.          stopping with the first one to which a successful connection is
  348.          made. Note that only ldap_open() attempts to make the connec-
  349.          tion before returning to the caller. ldap_init() does not con-
  350.          nect to the LDAP server.
  351.  
  352. portno   Contains the TCP port number to connect to. The default LDAP
  353.          port of 389 can be obtained by supplying the constant
  354.          LDAP_PORT.  If a host includes a port number then this parame-
  355.          ter is ignored.
  356.  
  357. ldap_init() and ldap_open() both return a "session handle," a pointer to
  358. an opaque structure that should be passed to subsequent calls pertaining
  359. to the session. These routines return NULL if the session cannot be ini-
  360. tialized in which case the operating system error reporting mechanism
  361. can be checked to see why the call failed.
  362.  
  363. Note that if you connect to an LDAPv2 server, one of the ldap_bind()
  364. calls described below must be completed before other operations can be
  365. performed on the session.  LDAPv3 does not require that a bind operation
  366. be completed before other operations can be performed.
  367.  
  368. The calling program can set various attributes of the session by calling
  369. the routines described in the next section.
  370.  
  371.  
  372. 7.2.  LDAP Session Handle Options
  373.  
  374. The LDAP session handle returned by ldap_init() is a pointer to an
  375. opaque data type representing an LDAP session. Formerly, this data type
  376. was a structure exposed to the caller, and various fields in the struc-
  377. ture could be set to control aspects of the session, such as size and
  378. time limits on searches.
  379.  
  380. In the interest of insulating callers from inevitable changes to this
  381. structure, these aspects of the session are now accessed through a pair
  382. of accessor functions, described below.
  383.  
  384. ldap_get_option() is used to access the current value of various
  385. session-wide parameters. ldap_set_option() is used to set the value of
  386. these parameters.
  387.  
  388.            int ldap_get_option(
  389.                    LDAP            *ld,
  390.                    int             option,
  391.  
  392.  
  393.  
  394. Expires: January 1998                                           [Page 7]
  395.  
  396. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  397.  
  398.  
  399.                    void            *outvalue
  400.            );
  401.  
  402.            int ldap_set_option(
  403.                    LDAP            *ld,
  404.                    int             option,
  405.                    void            *invalue
  406.            );
  407.  
  408. Parameters are:
  409.  
  410. ld     The session handle.
  411.  
  412. option The name of the option being accessed or set. This parameter
  413.        should be one of the following constants, which have the indi-
  414.        cated meanings.  After the constant the actual value of the con-
  415.        stant is listed in hexadecimal in parentheses followed by the
  416.        type of the corresponding outvalue or invalue parameter.
  417.  
  418.    LDAP_OPT_DESC (0x01) int *
  419.           The underlying socket descriptor corresponding to the default
  420.           LDAP connection.
  421.  
  422.    LDAP_OPT_DEREF (0x02) int *
  423.           Controls how aliases are handled during search. It can have
  424.           one of the following values: LDAP_DEREF_NEVER (0x00),
  425.           LDAP_DEREF_SEARCHING (0x01), LDAP_DEREF_FINDING (0x02), or
  426.           LDAP_DEREF_ALWAYS (0x03).  The LDAP_DEREF_SEARCHING value
  427.           means aliases should be dereferenced during the search but not
  428.           when locating the base object of the search. The
  429.           LDAP_DEREF_FINDING value means aliases should be dereferenced
  430.           when locating the base object but not during the search.
  431.  
  432.    LDAP_OPT_SIZELIMIT (0x03) int *
  433.           A limit on the number of entries to return from a search. A
  434.           value of zero means no limit.
  435.  
  436.    LDAP_OPT_TIMELIMIT (0x04) int *
  437.           A limit on the number of seconds to spend on a search. A value
  438.           of zero means no limit
  439.  
  440.    LDAP_OPT_REBIND_FN (0x06) function pointer
  441.           See the discussion of ldap_bind() and friends below.
  442.  
  443.    LDAP_OPT_REBIND_ARG (0x07) void *
  444.           See the discussion of ldap_bind() and friends below.
  445.  
  446.    LDAP_OPT_REFERRALS (0x08) void *
  447.  
  448.  
  449.  
  450. Expires: January 1998                                           [Page 8]
  451.  
  452. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  453.  
  454.  
  455.           This option controls whether the LDAP library automatically
  456.           follows referrals returned by LDAP servers or not. It can be
  457.           set to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF.
  458.  
  459.    LDAP_OPT_RESTART (0x09) void *
  460.           This option controls whether LDAP I/O operations should
  461.           automatically be restarted if they abort prematurely. It
  462.           should be set to one of the constants LDAP_OPT_ON or
  463.           LDAP_OPT_OFF. This option is useful if an LDAP I/O operation
  464.           may be interrupted prematurely, for example by a timer going
  465.           off, or other interrrupt.
  466.  
  467.    LDAP_OPT_PROTOCOL_VERSION (0x11) int *
  468.           This option indicates the version of the default LDAP server.
  469.           It can be one of the constants LDAP_VERSION2 or LDAP_VERSION3.
  470.           If no version is set the default is LDAP_VERSION2.
  471.  
  472.    LDAP_OPT_SERVER_CONTROLS (0x12) LDAPControl **
  473.           A default list of LDAP server controls to be sent with each
  474.           request.  See the Using Controls section below.
  475.  
  476.    LDAP_OPT_CLIENT_CONTROLS (0x13) LDAPControl **
  477.           A default list of client controls that affect the LDAP ses-
  478.           sion.  See the Using Controls section below.
  479.  
  480.    LDAP_OPT_HOST_NAME (0x30) char **
  481.           The host name of the default LDAP server.
  482.  
  483.    LDAP_OPT_ERROR_NUMBER (0x31) int *
  484.           The code of the most recent LDAP error that occurred for this
  485.           session.
  486.  
  487.    LDAP_OPT_ERROR_STRING (0x32) char **
  488.           The message returned with the most recent LDAP error that
  489.           occurred for this session.
  490.  
  491.  
  492. outvalue The address of a place to put the value of the option. The
  493.          actual type of this parameter depends on the setting of the
  494.          option parameter.
  495.  
  496. invalue  A pointer to the value the option is to be given. The actual
  497.          type of this parameter depends on the setting of the option
  498.          parameter. The constants LDAP_OPT_ON and LDAP_OPT_OFF can be
  499.          given for options that have on or off settings.
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506. Expires: January 1998                                           [Page 9]
  507.  
  508. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  509.  
  510.  
  511. 7.3.  Working with controls
  512.  
  513. LDAPv3 operations can be extended through the use of controls.  Controls
  514. may be sent to a server or returned to the client with any LDAP message.
  515. These controls are referred to as server controls.
  516.  
  517. The LDAP API also supports a client-side extension mechanism through the
  518. use of client controls. These controls affect the behavior of the LDAP
  519. API only and are never sent to a server.  A common data structure is
  520. used to represent both types of controls:
  521.  
  522.            typedef struct ldapcontrol {
  523.                    char            *ldctl_oid;
  524.                    struct berval   ldctl_value;
  525.                    char            ldctl_iscritical;
  526.            } LDAPControl, *PLDAPControl;
  527.  
  528. The fields in the ldapcontrol structure have the following meanings:
  529.  
  530. ldctl_oid        The control type, represented as a string.
  531.  
  532. ldctl_value      The data associated with the control (if any).
  533.  
  534. ldctl_iscritical Indicates whether the control is critical of not. If
  535.                  this field is non-zero, the operation will only be car-
  536.                  ried out if the control is recognized by the server
  537.                  and/or client.
  538.  
  539. Some LDAP API calls allocate an ldapcontrol structure or a NULL-
  540. terminated array of ldapcontrol structures.  The following routines can
  541. be used to dispose of a single control or an array of controls:
  542.  
  543.            void ldap_control_free( LDAPControl *ctrl );
  544.            void ldap_controls_free( LDAPControl **ctrls );
  545.  
  546. A set of controls that affect the entire session can be set using the
  547. ldap_set_option() function (see above).  A list of controls can also be
  548. passed directly to some LDAP API calls such as ldap_search_ext(), in
  549. which case any controls set for the session through the use of
  550. ldap_set_option() are ignored. Control lists are represented as a NULL-
  551. terminated array of pointers to ldapcontrol structures.
  552.  
  553. Server controls are defined by LDAPv3 protocol extension documents; for
  554. example, a control has been proposed to support server-side sorting of
  555. search results [7].
  556.  
  557. No client controls are defined by this document but they may be defined
  558. in future revisions or in any document that extends this API.
  559.  
  560.  
  561.  
  562. Expires: January 1998                                          [Page 10]
  563.  
  564. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  565.  
  566.  
  567. 7.4.  Authenticating to the directory
  568.  
  569. The following functions are used to authenticate an LDAP client to an
  570. LDAP directory server.
  571.  
  572. The ldap_sasl_bind() and ldap_sasl_bind_s() functions can be used to do
  573. general and extensible authentication over LDAP through the use of the
  574. Simple Authentication Security Layer [8].  The routines both take the dn
  575. to bind as, the method to use, as a dotted-string representation of an
  576. OID identifying the method, and a struct berval holding the credentials.
  577. The special constant value LDAP_SASL_SIMPLE ("") can be passed to
  578. request simple authentication, or the simplified routines
  579. ldap_simple_bind() or ldap_simple_bind_s() can be used.
  580.  
  581.            int ldap_sasl_bind(
  582.                    LDAP            *ld,
  583.                    char            *dn,
  584.                    char            *mechanism,
  585.                    struct berval   *cred,
  586.                    LDAPControl     **serverctrls,
  587.                    LDAPControl     **clientctrls,
  588.                    int             *msgidp
  589.            );
  590.  
  591.            int ldap_sasl_bind_s(
  592.                    LDAP            *ld,
  593.                    char            *dn,
  594.                    char            *mechanism,
  595.                    struct berval   *cred,
  596.                    LDAPControl     **serverctrls,
  597.                    LDAPControl     **clientctrls,
  598.                    struct berval   **servercredp
  599.            );
  600.  
  601.            int ldap_simple_bind(
  602.                    LDAP            *ld,
  603.                    char            *dn,
  604.                    char            *passwd
  605.            );
  606.  
  607.            int ldap_simple_bind_s(
  608.                    LDAP            *ld,
  609.                    char            *dn,
  610.                    char            *passwd
  611.            );
  612.  
  613.    The use of the following routines is deprecated:
  614.  
  615.  
  616.  
  617.  
  618. Expires: January 1998                                          [Page 11]
  619.  
  620. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  621.  
  622.  
  623.            int ldap_bind( LDAP *ld, char *dn, char *cred, int method );
  624.  
  625.            int ldap_bind_s( LDAP *ld, char *dn, char *cred, int method );
  626.  
  627.            int ldap_kerberos_bind( LDAP *ld, char *dn );
  628.  
  629.            int ldap_kerberos_bind_s( LDAP *ld, char *dn );
  630.  
  631. Parameters are:
  632.  
  633. ld           The session handle.
  634.  
  635. dn           The name of the entry to bind as.
  636.  
  637. mechanism    Either LDAP_AUTH_SIMPLE_OID to get simple authentication,
  638.              or a dotted text string representing an OID identifying the
  639.              SASL method.
  640.  
  641. cred         The credentials with which to authenticate. Arbitrary
  642.              credentials can be passed using this parameter. The format
  643.              and content of the credentials depends on the setting of
  644.              the mechanism parameter.
  645.  
  646. passwd       For ldap_simple_bind(), the password to compare to the
  647.              entry's userPassword attribute.
  648.  
  649. serverctrls  List of LDAP server controls.
  650.  
  651. clientctrls  List of client controls.
  652.  
  653. msgidp       This result parameter will be set to the message id of the
  654.              request if the ldap_sasl_bind() call succeeds.
  655.  
  656. servercredp  This result parameter will be set to the credentials
  657.              returned by the server.  This should be freed by calling
  658.              ldap_If no credentials are returned it will be set to NULL.
  659.  
  660. Additional parameters for the deprecated routines are not described.
  661. Interested readers are referred to RFC 1823.
  662.  
  663. The ldap_sasl_bind() function initiates an asynchronous bind operation
  664. and returns the constant LDAP_SUCCESS if the request was successfully
  665. sent, or another LDAP error code if not.  See the section below on error
  666. handling for more information about possible errors and how to interpret
  667. them.  If successful, ldap_sasl_bind() places the message id of the
  668. request in *msgidp. A subsequent call to ldap_result(), described below,
  669. can be used to obtain the result of the bind.
  670.  
  671.  
  672.  
  673.  
  674. Expires: January 1998                                          [Page 12]
  675.  
  676. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  677.  
  678.  
  679. The ldap_simple_bind() function initiates a simple asynchronous bind
  680. operation and returns the message id of the operation initiated.  A sub-
  681. sequent call to ldap_result(), described below, can be used to obtain
  682. the result of the bind. In case of error, ldap_simple_bind() will return
  683. -1, setting the session error parameters in the LDAP structure appropri-
  684. ately.
  685.  
  686. The synchronous ldap_sasl_bind_s() and ldap_simple_bind_s() functions
  687. both return the result of the operation, either the constant
  688. LDAP_SUCCESS if the operation was successful, or another LDAP error code
  689. if it was not. See the section below on error handling for more informa-
  690. tion about possible errors and how to interpret them.
  691.  
  692. Note that if an LDAPv2 server is contacted, no other operations over the
  693. connection should be attempted before a bind call has successfully com-
  694. pleted.
  695.  
  696. Subsequent bind calls can be used to re-authenticate over the same con-
  697. nection, and multistep SASL sequences can be accomplished through a
  698. sequence of calls to ldap_sasl_bind() or ldap_sasl_bind_s().
  699.  
  700.  
  701. 7.5.  Closing the session
  702.  
  703. The following functions are used to unbind from the directory, close the
  704. connection, and dispose of the session handle.
  705.  
  706.            int ldap_unbind( LDAP *ld );
  707.  
  708.            int ldap_unbind_s( LDAP *ld );
  709.  
  710. Parameters are:
  711.  
  712. ld   The session handle.
  713.  
  714. ldap_unbind() and ldap_unbind_s() both work synchronously, unbinding
  715. from the directory, closing the connection, and freeing up the ld struc-
  716. ture before returning.   There is no server response to an unbind opera-
  717. tion.  ldap_unbind() returns LDAP_SUCCESS (or another LDAP error code if
  718. the request cannot be sent to the LDAP server).  After a call to
  719. ldap_unbind() or ldap_unbind_s(), the session handle ld is invalid.
  720.  
  721.  
  722. 7.6.  Searching
  723.  
  724. The following functions are used to search the LDAP directory, returning
  725. a requested set of attributes for each entry matched.  There are five
  726. variations.
  727.  
  728.  
  729.  
  730. Expires: January 1998                                          [Page 13]
  731.  
  732. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  733.  
  734.  
  735.            int ldap_search_ext(
  736.                    LDAP            *ld,
  737.                    char            *base,
  738.                    int             scope,
  739.                    char            *filter,
  740.                    char            **attrs,
  741.                    int             attrsonly,
  742.                    LDAPControl     **serverctrls,
  743.                    LDAPControl     **clientctrls,
  744.                    struct timeval  *timeoutp,
  745.                    int             sizelimit,
  746.                    int             *msgidp
  747.            );
  748.  
  749.            int ldap_search_ext_s(
  750.                    LDAP            *ld,
  751.                    char            *base,
  752.                    int             scope,
  753.                    char            *filter,
  754.                    char            **attrs,
  755.                    int             attrsonly,
  756.                    LDAPControl     **serverctrls,
  757.                    LDAPControl     **clientctrls,
  758.                    struct timeval  *timeoutp,
  759.                    int             sizelimit,
  760.                    LDAPMessage     **res
  761.            );
  762.  
  763.            int ldap_search(
  764.                    LDAP    *ld,
  765.                    char    *base,
  766.                    int     scope,
  767.                    char    *filter,
  768.                    char    **attrs,
  769.                    int     attrsonly
  770.            );
  771.  
  772.            int ldap_search_s(
  773.                    LDAP            *ld,
  774.                    char            *base,
  775.                    int             scope,
  776.                    char            *filter,
  777.                    char            **attrs,
  778.                    int             attrsonly,
  779.                    LDAPMessage     **res
  780.            );
  781.  
  782.            int ldap_search_st(
  783.  
  784.  
  785.  
  786. Expires: January 1998                                          [Page 14]
  787.  
  788. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  789.  
  790.  
  791.                    LDAP            *ld,
  792.                    char            *base,
  793.                    int             scope,
  794.                    char            *filter,
  795.                    char            **attrs,
  796.                    int             attrsonly,
  797.                    struct timeval  *timeout,
  798.                    LDAPMessage     **res
  799.            );
  800.  
  801. Parameters are:
  802.  
  803. ld           The session handle.
  804.  
  805. base         The dn of the entry at which to start the search.
  806.  
  807. scope        One of LDAP_SCOPE_BASE (0x00), LDAP_SCOPE_ONELEVEL (0x01),
  808.              or LDAP_SCOPE_SUBTREE (0x02), indicating the scope of the
  809.              search.
  810.  
  811. filter       A character string as described in [3], representing the
  812.              search filter.
  813.  
  814. attrs        A NULL-terminated array of strings indicating which attri-
  815.              butes to return for each matching entry. Passing NULL for
  816.              this parameter causes all available attributes to be
  817.              retrieved.
  818.  
  819. attrsonly    A boolean value that should be zero if both attribute types
  820.              and values are to be returned, non-zero if only types are
  821.              wanted.
  822.  
  823. timeout      For the ldap_search_st() function, this specifies the local
  824.              search timeout value.  For the ldap_search_ext() and
  825.              ldap_search_ext_s() functions, this specifies both the
  826.              local search timeout value and the operation time limit
  827.              that is sent to the server within the search request.
  828.  
  829. res          For the synchronous calls, this is a result parameter which
  830.              will contain the results of the search upon completion of
  831.              the call.
  832.  
  833. serverctrls  List of LDAP server controls.
  834.  
  835. clientctrls  List of client controls.
  836.  
  837. msgidp       This result parameter will be set to the message id of the
  838.              request if the ldap_search_ext() call succeeds.
  839.  
  840.  
  841.  
  842. Expires: January 1998                                          [Page 15]
  843.  
  844. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  845.  
  846.  
  847. There are three options in the session handle ld which potentially
  848. affect how the search is performed. They are:
  849.  
  850. LDAP_OPT_SIZELIMIT
  851.              A limit on the number of entries to return from the search.
  852.              A value of zero means no limit.  Note that the value from
  853.              the session handle is ignored when using the
  854.              ldap_search_ext() or ldap_search_ext_s() functions.
  855.  
  856. LDAP_OPT_TIMELIMIT
  857.              A limit on the number of seconds to spend on the search. A
  858.              value of zero means no limit.  Note that the value from the
  859.              session handle is ignored when using the ldap_search_ext()
  860.              or ldap_search_ext_s() functions.
  861.  
  862. LDAP_OPT_DEREF
  863.              One of LDAP_DEREF_NEVER (0x00), LDAP_DEREF_SEARCHING
  864.              (0x01), LDAP_DEREF_FINDING (0x02), or LDAP_DEREF_ALWAYS
  865.              (0x03), specifying how aliases should be handled during the
  866.              search. The LDAP_DEREF_SEARCHING value means aliases should
  867.              be dereferenced during the search but not when locating the
  868.              base object of the search. The LDAP_DEREF_FINDING value
  869.              means aliases should be dereferenced when locating the base
  870.              object but not during the search.
  871.  
  872. The ldap_search_ext() function initiates an asynchronous search opera-
  873. tion and returns the constant LDAP_SUCCESS if the request was success-
  874. fully sent, or another LDAP error code if not.  See the section below on
  875. error handling for more information about possible errors and how to
  876. interpret them.  If successful, ldap_search_ext() places the message id
  877. of the request in *msgidp. A subsequent call to ldap_result(), described
  878. below, can be used to obtain the results from the search.  These results
  879. can be parsed using the result parsing routines described in detail
  880. later.
  881.  
  882. Similar to ldap_search_ext(), the ldap_search() function initiates an
  883. asynchronous search operation and returns the message id of the opera-
  884. tion initiated.  As for ldap_search_ext(), a subsequent call to
  885. ldap_result(), described below, can be used to obtain the result of the
  886. bind. In case of error, ldap_search() will return -1, setting the ses-
  887. sion error parameters in the LDAP structure appropriately.
  888.  
  889. The synchronous ldap_search_ext_s(), ldap_search_s(), and
  890. ldap_search_st() functions all return the result of the operation,
  891. either the constant LDAP_SUCCESS if the operation was successful, or
  892. another LDAP error code if it was not. See the section below on error
  893. handling for more information about possible errors and how to interpret
  894. them.  Entries returned from the search (if any) are contained in the
  895.  
  896.  
  897.  
  898. Expires: January 1998                                          [Page 16]
  899.  
  900. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  901.  
  902.  
  903. res parameter. This parameter is opaque to the caller.  Entries, attri-
  904. butes, values, etc., should be extracted by calling the parsing routines
  905. described below. The results contained in res should be freed when no
  906. longer in use by calling ldap_msgfree(), described later.
  907.  
  908. The ldap_search_ext() and ldap_search_ext_s() functions support LDAPv3
  909. server controls, client controls, and allow varying size and time limits
  910. to be easily specified for each search operation.  The ldap_search_st()
  911. function is identical to ldap_search_s() except that it takes an addi-
  912. tional parameter specifying a local timeout for the search.
  913.  
  914. 7.7.  Reading an Entry
  915.  
  916. LDAP does not support a read operation directly. Instead, this operation
  917. is emulated by a search with base set to the DN of the entry to read,
  918. scope set to LDAP_SCOPE_BASE, and filter set to "(objectclass=*)". attrs
  919. contains the list of attributes to return.
  920.  
  921.  
  922. 7.8.  Listing the Children of an Entry
  923.  
  924. LDAP does not support a list operation directly. Instead, this operation
  925. is emulated by a search with base set to the DN of the entry to list,
  926. scope set to LDAP_SCOPE_ONELEVEL, and filter set to "(objectclass=*)".
  927. attrs contains the list of attributes to return for each child entry.
  928.  
  929. 7.9.  Comparing a Value Against an Entry
  930.  
  931. The following routines are used to compare a given attribute value
  932. assertion against an LDAP entry.  There are four variations:
  933.  
  934.            int ldap_compare_ext(
  935.                    LDAP            *ld,
  936.                    char            *dn,
  937.                    char            *attr,
  938.                    struct berval   *bvalue
  939.                    LDAPControl     **serverctrls,
  940.                    LDAPControl     **clientctrls,
  941.                    int             *msgidp
  942.            );
  943.  
  944.            int ldap_compare_ext_s(
  945.                    LDAP            *ld,
  946.                    char            *dn,
  947.                    char            *attr,
  948.                    struct berval   *bvalue,
  949.                    LDAPControl     **serverctrls,
  950.                    LDAPControl     **clientctrls
  951.  
  952.  
  953.  
  954. Expires: January 1998                                          [Page 17]
  955.  
  956. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  957.  
  958.  
  959.            );
  960.  
  961.            int ldap_compare(
  962.                    LDAP            *ld,
  963.                    char            *dn,
  964.                    char            *attr,
  965.                    char            *value
  966.            );
  967.  
  968.            int ldap_compare_s(
  969.                    LDAP            *ld,
  970.                    char            *dn,
  971.                    char            *attr,
  972.                    char            *value
  973.            );
  974.  
  975. Parameters are:
  976.  
  977. ld           The session handle.
  978.  
  979. dn           The name of the entry to compare against.
  980.  
  981. attr         The attribute to compare against.
  982.  
  983. bvalue       The attribute value to compare against those found in the
  984.              given entry. This parameter is used in the extended rou-
  985.              tines and is a pointer to a struct berval so it is possible
  986.              to compare binary values.
  987.  
  988. value        A string attribute value to compare against, used by the
  989.              ldap_compare() and ldap_compare_s() functions.  Use
  990.              ldap_compare_ext() or ldap_compare_ext_s() if you need to
  991.              compare binary values.
  992.  
  993. serverctrls  List of LDAP server controls.
  994.  
  995. clientctrls  List of client controls.
  996.  
  997. msgidp       This result parameter will be set to the message id of the
  998.              request if the ldap_compare_ext() call succeeds.
  999.  
  1000. The ldap_compare_ext() function initiates an asynchronous compare opera-
  1001. tion and returns the constant LDAP_SUCCESS if the request was success-
  1002. fully sent, or another LDAP error code if not.  See the section below on
  1003. error handling for more information about possible errors and how to
  1004. interpret them.  If successful, ldap_compare_ext() places the message id
  1005. of the request in *msgidp. A subsequent call to ldap_result(), described
  1006. below, can be used to obtain the result of the compare.
  1007.  
  1008.  
  1009.  
  1010. Expires: January 1998                                          [Page 18]
  1011.  
  1012. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  1013.  
  1014.  
  1015. Similar to ldap_compare_ext(), the ldap_compare() function initiates an
  1016. asynchronous compare operation and returns the message id of the opera-
  1017. tion initiated.  As for ldap_compare_ext(), a subsequent call to
  1018. ldap_result(), described below, can be used to obtain the result of the
  1019. bind. In case of error, ldap_compare() will return -1, setting the ses-
  1020. sion error parameters in the LDAP structure appropriately.
  1021.  
  1022. The synchronous ldap_compare_ext_s() and ldap_compare_s() functions both
  1023. return the result of the operation, either the constant LDAP_SUCCESS if
  1024. the operation was successful, or another LDAP error code if it was not.
  1025. See the section below on error handling for more information about pos-
  1026. sible errors and how to interpret them.
  1027.  
  1028. The ldap_compare_ext() and ldap_compare_ext_s() functions support LDAPv3
  1029. server controls and client controls.
  1030.  
  1031.  
  1032. 7.10.  Modifying an entry
  1033.  
  1034. The following routines are used to modify an existing LDAP entry.  There
  1035. are four variations:
  1036.  
  1037.            typedef struct ldapmod {
  1038.                    int             mod_op;
  1039.                    char            *mod_type;
  1040.                    union {
  1041.                            char            **modv_strvals;
  1042.                            struct berval   **modv_bvals;
  1043.                    } mod_vals;
  1044.            } LDAPMod;
  1045.            #define mod_values      mod_vals.modv_strvals
  1046.            #define mod_bvalues     mod_vals.modv_bvals
  1047.  
  1048.            int ldap_modify_ext(
  1049.                    LDAP            *ld,
  1050.                    char            *dn,
  1051.                    LDAPMod         **mods,
  1052.                    LDAPControl     **serverctrls,
  1053.                    LDAPControl     **clientctrls,
  1054.                    int             *msgidp
  1055.            );
  1056.  
  1057.            int ldap_modify_ext_s(
  1058.                    LDAP            *ld,
  1059.                    char            *dn,
  1060.                    LDAPMod         **mods,
  1061.                    LDAPControl     **serverctrls,
  1062.                    LDAPControl     **clientctrls
  1063.  
  1064.  
  1065.  
  1066. Expires: January 1998                                          [Page 19]
  1067.  
  1068. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  1069.  
  1070.  
  1071.            );
  1072.  
  1073.            int ldap_modify(
  1074.                    LDAP            *ld,
  1075.                    char            *dn,
  1076.                    LDAPMod         **mods
  1077.            );
  1078.  
  1079.            int ldap_modify_s(
  1080.                    LDAP            *ld,
  1081.                    char            *dn,
  1082.                    LDAPMod         **mods
  1083.            );
  1084.  
  1085. Parameters are:
  1086.  
  1087. ld           The session handle.
  1088.  
  1089. dn           The name of the entry to modify.
  1090.  
  1091. mods         A NULL-terminated array of modifications to make to the
  1092.              entry.
  1093.  
  1094. serverctrls  List of LDAP server controls.
  1095.  
  1096. clientctrls  List of client controls.
  1097.  
  1098. msgidp       This result parameter will be set to the message id of the
  1099.              request if the ldap_modify_ext() call succeeds.
  1100.  
  1101. The fields in the LDAPMod structure have the following meanings:
  1102.  
  1103. mod_op       The modification operation to perform. It should be one of
  1104.              LDAP_MOD_ADD (0x00), LDAP_MOD_DELETE (0x01), or
  1105.              LDAP_MOD_REPLACE (0x02).  This field also indicates the
  1106.              type of values included in the mod_vals union. It is logi-
  1107.              cally ORed with LDAP_MOD_BVALUES (0x80) to select the
  1108.              mod_bvalues form. Otherwise, the mod_values form is used.
  1109.  
  1110. mod_type     The type of the attribute to modify.
  1111.  
  1112. mod_vals     The values (if any) to add, delete, or replace. Only one of
  1113.              the mod_values or mod_bvalues variants should be used,
  1114.              selected by ORing the mod_op field with the constant
  1115.              LDAP_MOD_BVALUES. mod_values is a NULL-terminated array of
  1116.              zero-terminated strings and mod_bvalues is a NULL-
  1117.              terminated array of berval structures that can be used to
  1118.              pass binary values such as images.
  1119.  
  1120.  
  1121.  
  1122. Expires: January 1998                                          [Page 20]
  1123.  
  1124. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  1125.  
  1126.  
  1127. For LDAP_MOD_ADD modifications, the given values are added to  the
  1128. entry, creating the attribute if necessary.
  1129.  
  1130. For LDAP_MOD_DELETE modifications, the given values are deleted from the
  1131. entry, removing the attribute if no values remain. If the entire attri-
  1132. bute is to  be deleted, the mod_vals field should be set to NULL.
  1133.  
  1134. For LDAP_MOD_REPLACE modifications, the attribute will have the listed
  1135. values after the modification, having been created if necessary, or
  1136. removed if the mod_vals field is NULL. All modifications are performed
  1137. in the order in which they are listed.
  1138.  
  1139. The ldap_modify_ext() function initiates an asynchronous modify opera-
  1140. tion and returns the constant LDAP_SUCCESS if the request was success-
  1141. fully sent, or another LDAP error code if not.  See the section below on
  1142. error handling for more information about possible errors and how to
  1143. interpret them.  If successful, ldap_modify_ext() places the message id
  1144. of the request in *msgidp. A subsequent call to ldap_result(), described
  1145. below, can be used to obtain the result of the modify.
  1146.  
  1147. Similar to ldap_modify_ext(), the ldap_modify() function initiates an
  1148. asynchronous modify operation and returns the message id of the opera-
  1149. tion initiated.  As for ldap_modify_ext(), a subsequent call to
  1150. ldap_result(), described below, can be used to obtain the result of the
  1151. modify. In case of error, ldap_modify() will return -1, setting the ses-
  1152. sion error parameters in the LDAP structure appropriately.
  1153.  
  1154. The synchronous ldap_modify_ext_s() and ldap_modify_s() functions both
  1155. return the result of the operation, either the constant LDAP_SUCCESS if
  1156. the operation was successful, or another LDAP error code if it was not.
  1157. See the section below on error handling for more information about pos-
  1158. sible errors and how to interpret them.
  1159.  
  1160. The ldap_modify_ext() and ldap_modify_ext_s() functions support LDAPv3
  1161. server controls and client controls.
  1162.  
  1163.  
  1164. 7.11.  Modifying the Name of an Entry
  1165.  
  1166. In LDAPv2, the ldap_modrdn() and ldap_modrdn_s() routines were used to
  1167. change the name of an LDAP entry. They could only be used to change the
  1168. least significant component of a name (the RDN or relative distinguished
  1169. name). LDAPv3 provides the Modify DN protocol operation that allows more
  1170. general name change access. The ldap_rename() and ldap_rename_s() rou-
  1171. tines are used to change the name of an entry, and the use of the
  1172. ldap_modrdn() and ldap_modrdn_s() routines is deprecated.
  1173.  
  1174.            int ldap_rename(
  1175.  
  1176.  
  1177.  
  1178. Expires: January 1998                                          [Page 21]
  1179.  
  1180. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  1181.  
  1182.  
  1183.                    LDAP            *ld,
  1184.                    char            *dn,
  1185.                    char            *newrdn,
  1186.                    char            *newparent,
  1187.                    int             deleteoldrdn,
  1188.                    LDAPControl     **serverctrls,
  1189.                    LDAPControl     **clientctrls,
  1190.                    int             *msgidp
  1191.  
  1192.            );
  1193.            int ldap_rename_s(
  1194.                    LDAP            *ld,
  1195.                    char            *dn,
  1196.                    char            *newrdn,
  1197.                    char            *newparent,
  1198.                    int             deleteoldrdn,
  1199.                    LDAPControl     **serverctrls,
  1200.                    LDAPControl     **clientctrls
  1201.            );
  1202.  
  1203.    Use of the following routines is deprecated.
  1204.  
  1205.            int ldap_modrdn(
  1206.                    LDAP    *ld,
  1207.                    char    *dn,
  1208.                    char    *newrdn,
  1209.                    int     deleteoldrdn
  1210.            );
  1211.            int ldap_modrdn_s(
  1212.                    LDAP    *ld,
  1213.                    char    *dn,
  1214.                    char    *newrdn,
  1215.                    int     deleteoldrdn
  1216.            );
  1217.  
  1218. Parameters are:
  1219.  
  1220. ld           The session handle.
  1221.  
  1222. dn           The name of the entry whose DN is to be changed.
  1223.  
  1224. newrdn       The new RDN to give the entry.
  1225.  
  1226. newparent    The new parent, or superior entry.  If this parameter is
  1227.              NULL, only the RDN of the entry is changed.  The root DN
  1228.              may be specified by passing a zero length string, "".  The
  1229.              newparent parameter should always be NULL when using ver-
  1230.              sion 2 of the LDAP protocol; otherwise the server's
  1231.  
  1232.  
  1233.  
  1234. Expires: January 1998                                          [Page 22]
  1235.  
  1236. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  1237.  
  1238.  
  1239.              behavior is undefined.
  1240.  
  1241. deleteoldrdn This parameter only has meaning on the rename routines if
  1242.              newrdn is different than the old RDN. It is a boolean
  1243.              value, if non-zero indicating that the old RDN value(s)
  1244.              should be removed, if zero indicating that the old RDN
  1245.              value(s) should be retained as non-distinguished values of
  1246.              the entry.
  1247.  
  1248. serverctrls  List of LDAP server controls.
  1249.  
  1250. clientctrls  List of client controls.
  1251.  
  1252. msgidp       This result parameter will be set to the message id of the
  1253.              request if the ldap_rename() call succeeds.
  1254.  
  1255. The ldap_rename() function initiates an asynchronous modify DN operation
  1256. and returns the constant LDAP_SUCCESS if the request was successfully
  1257. sent, or another LDAP error code if not.  See the section below on error
  1258. handling for more information about possible errors and how to interpret
  1259. them.  If successful, ldap_rename() places the DN message id of the
  1260. request in *msgidp. A subsequent call to ldap_result(), described below,
  1261. can be used to obtain the result of the rename.
  1262.  
  1263. The synchronous ldap_rename_s() returns the result of the operation,
  1264. either the constant LDAP_SUCCESS if the operation was successful, or
  1265. another LDAP error code if it was not.  See the section below on error
  1266. handling for more information about possible errors and how to interpret
  1267. them.
  1268.  
  1269. The ldap_rename() and ldap_rename_s() functions both support LDAPv3
  1270. server controls and client controls.
  1271.  
  1272.  
  1273. 7.12.  Adding an entry
  1274.  
  1275. The following functions are used to add entries to the LDAP directory.
  1276. There are four variations:
  1277.  
  1278.            int ldap_add_ext(
  1279.                    LDAP            *ld,
  1280.                    char            *dn,
  1281.                    LDAPMod         **attrs,
  1282.                    LDAPControl     **serverctrls,
  1283.                    LDAPControl     **clientctrls,
  1284.                    int             *msgidp
  1285.            );
  1286.  
  1287.  
  1288.  
  1289.  
  1290. Expires: January 1998                                          [Page 23]
  1291.  
  1292. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  1293.  
  1294.  
  1295.            int ldap_add_ext_s(
  1296.                    LDAP            *ld,
  1297.                    char            *dn,
  1298.                    LDAPMod         **attrs,
  1299.                    LDAPControl     **serverctrls,
  1300.                    LDAPControl     **clientctrls
  1301.            );
  1302.  
  1303.            int ldap_add(
  1304.                    LDAP            *ld,
  1305.                    char            *dn,
  1306.                    LDAPMod         **attrs
  1307.            );
  1308.  
  1309.            int ldap_add_s(
  1310.                    LDAP            *ld,
  1311.                    char            *dn,
  1312.                    LDAPMod         **attrs
  1313.            );
  1314.  
  1315. Parameters are:
  1316.  
  1317. ld           The session handle.
  1318.  
  1319. dn           The name of the entry to add.
  1320.  
  1321. attrs        The entry's attributes, specified using the LDAPMod struc-
  1322.              ture defined for ldap_modify(). The mod_type and mod_vals
  1323.              fields should be filled in.  The mod_op field is ignored
  1324.              unless ORed with the constant LDAP_MOD_BVALUES, used to
  1325.              select the mod_bvalues case of the mod_vals union.
  1326.  
  1327. serverctrls  List of LDAP server controls.
  1328.  
  1329. clientctrls  List of client controls.
  1330.  
  1331. msgidp       This result parameter will be set to the message id of the
  1332.              request if the ldap_add_ext() call succeeds.
  1333.  
  1334. Note that the parent of the entry being added must already exist or the
  1335. parent must be empty (i.e., equal to the root DN) for an add to succeed.
  1336.  
  1337. The ldap_add_ext() function initiates an asynchronous add operation and
  1338. returns the constant LDAP_SUCCESS if the request was successfully sent,
  1339. or another LDAP error code if not.  See the section below on error han-
  1340. dling for more information about possible errors and how to interpret
  1341. them.  If successful, ldap_add_ext() places the message id of the
  1342. request in *msgidp. A subsequent call to ldap_result(), described below,
  1343.  
  1344.  
  1345.  
  1346. Expires: January 1998                                          [Page 24]
  1347.  
  1348. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  1349.  
  1350.  
  1351. can be used to obtain the result of the add.
  1352.  
  1353. Similar to ldap_add_ext(), the ldap_add() function initiates an asyn-
  1354. chronous add operation and returns the message id of the operation ini-
  1355. tiated.  As for ldap_add_ext(), a subsequent call to ldap_result(),
  1356. described below, can be used to obtain the result of the add. In case of
  1357. error, ldap_add() will return -1, setting the session error parameters
  1358. in the LDAP structure appropriately.
  1359.  
  1360. The synchronous ldap_add_ext_s() and ldap_add_s() functions both return
  1361. the result of the operation, either the constant LDAP_SUCCESS if the
  1362. operation was successful, or another LDAP error code if it was not.  See
  1363. the section below on error handling for more information about possible
  1364. errors and how to interpret them.
  1365.  
  1366. The ldap_add_ext() and ldap_add_ext_s() functions support LDAPv3 server
  1367. controls and client controls.
  1368.  
  1369.  
  1370.  
  1371. 7.13.  Deleting an entry
  1372.  
  1373. The following functions are used to delete a leaf entry from the LDAP
  1374. directory.  There are four variations:
  1375.  
  1376.            int ldap_delete_ext(
  1377.                    LDAP            *ld,
  1378.                    char            *dn,
  1379.                    LDAPControl     **serverctrls,
  1380.                    LDAPControl     **clientctrls,
  1381.                    int             *msgidp
  1382.            );
  1383.  
  1384.            int ldap_delete_ext_s(
  1385.                    LDAP            *ld,
  1386.                    char            *dn,
  1387.                    LDAPControl     **serverctrls,
  1388.                    LDAPControl     **clientctrls
  1389.            );
  1390.  
  1391.            int ldap_delete(
  1392.                    LDAP            *ld,
  1393.                    char            *dn
  1394.            );
  1395.  
  1396.            int ldap_delete_s(
  1397.                    LDAP            *ld,
  1398.                    char            *dn
  1399.  
  1400.  
  1401.  
  1402. Expires: January 1998                                          [Page 25]
  1403.  
  1404. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  1405.  
  1406.  
  1407.            );
  1408.  
  1409. Parameters are:
  1410.  
  1411. ld           The session handle.
  1412.  
  1413. dn           The name of the entry to delete.
  1414.  
  1415. serverctrls  List of LDAP server controls.
  1416.  
  1417. clientctrls  List of client controls.
  1418.  
  1419. msgidp       This result parameter will be set to the message id of the
  1420.              request if the ldap_delete_ext() call succeeds.
  1421.  
  1422. Note that the entry to delete must be a leaf entry (i.e., it must have
  1423. no children). Deletion of entire subtrees in a single operation is not
  1424. supported by LDAP.
  1425.  
  1426. The ldap_delete_ext() function initiates an asynchronous delete opera-
  1427. tion and returns the constant LDAP_SUCCESS if the request was success-
  1428. fully sent, or another LDAP error code if not.  See the section below on
  1429. error handling for more information about possible errors and how to
  1430. interpret them.  If successful, ldap_delete_ext() places the message id
  1431. of the request in *msgidp. A subsequent call to ldap_result(), described
  1432. below, can be used to obtain the result of the delete.
  1433.  
  1434. Similar to ldap_delete_ext(), the ldap_delete() function initiates an
  1435. asynchronous delete operation and returns the message id of the opera-
  1436. tion initiated.  As for ldap_delete_ext(), a subsequent call to
  1437. ldap_result(), described below, can be used to obtain the result of the
  1438. delete. In case of error, ldap_delete() will return -1, setting the ses-
  1439. sion error parameters in the LDAP structure appropriately.
  1440.  
  1441. The synchronous ldap_delete_ext_s() and ldap_delete_s() functions both
  1442. return the result of the operation, either the constant LDAP_SUCCESS if
  1443. the operation was successful, or another LDAP error code if it was not.
  1444. See the section below on error handling for more information about pos-
  1445. sible errors and how to interpret them.
  1446.  
  1447. The ldap_delete_ext() and ldap_delete_ext_s() functions support LDAPv3
  1448. server controls and client controls.
  1449.  
  1450.  
  1451. 7.14.  Extended Operations
  1452.  
  1453. The ldap_extended_operation() and ldap_extended_operation_s() routines
  1454. allow extended LDAP operations to be passed to the server, providing a
  1455.  
  1456.  
  1457.  
  1458. Expires: January 1998                                          [Page 26]
  1459.  
  1460. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  1461.  
  1462.  
  1463. general protocol extensibility mechanism.
  1464.  
  1465.            int ldap_extended_operation(
  1466.                    LDAP            *ld,
  1467.                    char            *exoid,
  1468.                    struct berval   *exdata,
  1469.                    LDAPControl     **serverctrls,
  1470.                    LDAPControl     **clientctrls,
  1471.                    int             *msgidp
  1472.            );
  1473.  
  1474.            int ldap_extended_operation_s(
  1475.                    LDAP            *ld,
  1476.                    char            *exoid,
  1477.                    struct berval   *exdata,
  1478.                    LDAPControl     **serverctrls,
  1479.                    LDAPControl     **clientctrls,
  1480.                    char            **retoidp,
  1481.                    struct berval   **retdatap
  1482.            );
  1483.  
  1484. Parameters are:
  1485.  
  1486. ld           The session handle.
  1487.  
  1488. requestoid   The dotted-OID text string naming the request.
  1489.  
  1490. requestdata  The arbitrary data required by the operation (if NULL, no
  1491.              data is sent to the server).
  1492.  
  1493. serverctrls  List of LDAP server controls.
  1494.  
  1495. clientctrls  List of client controls.
  1496.  
  1497. msgidp       This result parameter will be set to the message id of the
  1498.              request if the ldap_extended_operation() call succeeds.
  1499.  
  1500. retoidp      Pointer to a character string that will be set to an allo-
  1501.              cated, dotted-OID text string returned by the server.  This
  1502.              string should be disposed of using the ldap_memfree() func-
  1503.              tion.  If no OID was returned, *retoidp is set to NULL.
  1504.  
  1505. retdatap     Pointer to a berval structure pointer that will be set an
  1506.              allocated copy of the data returned by the server.  This
  1507.              struct berval should be disposed of using ber_bvfree().  If
  1508.              no data is returned, *retdatap is set to NULL.
  1509.  
  1510. The ldap_extended_operation() function initiates an asynchronous
  1511.  
  1512.  
  1513.  
  1514. Expires: January 1998                                          [Page 27]
  1515.  
  1516. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  1517.  
  1518.  
  1519. extended operation and returns the constant LDAP_SUCCESS if the request
  1520. was successfully sent, or another LDAP error code if not.  See the sec-
  1521. tion below on error handling for more information about possible errors
  1522. and how to interpret them.  If successful, ldap_extended_operation()
  1523. places the message id of the request in *msgidp. A subsequent call to
  1524. ldap_result(), described below, can be used to obtain the result of the
  1525. extended operation which can be passed to ldap_parse_extended_result()
  1526. to obtain the OID and data contained in the response.
  1527.  
  1528. The synchronous ldap_extended_operation_s() function returns the result
  1529. of the operation, either the constant LDAP_SUCCESS if the operation was
  1530. successful, or another LDAP error code if it was not.  See the section
  1531. below on error handling for more information about possible errors and
  1532. how to interpret them.  The retoid and retdata parameters are filled in
  1533. with the OID and data from the response.  If no OID or data was
  1534. returned, these parameters are set to NULL.
  1535.  
  1536. The ldap_extended_operation() and ldap_extended_operation_s() functions
  1537. both support LDAPv3 server controls and client controls.
  1538.  
  1539.  
  1540. 8.  Abandoning An Operation
  1541.  
  1542. The following calls are used to abandon an operation in progress:
  1543.  
  1544.            int ldap_abandon_ext(
  1545.                    LDAP            *ld,
  1546.                    int             msgid,
  1547.                    LDAPControl     **serverctrls,
  1548.                    LDAPControl     **clientctrls
  1549.            );
  1550.  
  1551.            int ldap_abandon(
  1552.                    LDAP            *ld,
  1553.                    int             msgid
  1554.            );
  1555.  
  1556.  
  1557. ld           The session handle.
  1558.  
  1559. msgid        The message id of the request to be abandoned.
  1560.  
  1561. serverctrls  List of LDAP server controls.
  1562.  
  1563. clientctrls  List of client controls.
  1564.  
  1565. ldap_abandon_ext() abandons the operation with message id msgid and
  1566. returns the constant LDAP_SUCCESS if the abandon was successful or
  1567.  
  1568.  
  1569.  
  1570. Expires: January 1998                                          [Page 28]
  1571.  
  1572. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  1573.  
  1574.  
  1575. another LDAP error code if not.  See the section below on error handling
  1576. for more information about possible errors and how to interpret them.
  1577.  
  1578. ldap_abandon() is identical to ldap_abandon_ext() except that it returns
  1579. zero if the abandon was successful, -1 otherwise and does not support
  1580. LDAPv3 server controls or client controls.
  1581.  
  1582. After a successful call to ldap_abandon() or ldap_abandon_ext(), results
  1583. with the given message id are never returned from a subsequent call to
  1584. ldap_result().  There is no server response to LDAP abandon operations.
  1585.  
  1586.  
  1587. 9.  Obtaining Results and Peeking Inside LDAP Messages
  1588.  
  1589. ldap_result() is used to obtain the result of a previous asynchronously
  1590. initiated operation. Note that depending on how it is called,
  1591. ldap_result() may actually return a list or "chain" of messages.
  1592.  
  1593. ldap_msgfree() frees the results obtained from a previous call to
  1594. ldap_result(), or a synchronous search routine.
  1595.  
  1596. ldap_msgtype() returns the type of an LDAP message.  ldap_msgid()
  1597. returns the message ID of an LDAP message.
  1598.  
  1599.            int ldap_result(
  1600.                    LDAP            *ld,
  1601.                    int             msgid,
  1602.                    int             all,
  1603.                    struct timeval  *timeout,
  1604.                    LDAPMessage     **res
  1605.            );
  1606.  
  1607.            int ldap_msgfree( LDAPMessage *res );
  1608.  
  1609.            int ldap_msgtype( LDAPMessage *res );
  1610.  
  1611.            int ldap_msgid( LDAPMessage *res );
  1612.  
  1613. Parameters are:
  1614.  
  1615. ld       The session handle.
  1616.  
  1617. msgid    The message id of the operation whose results are to be
  1618.          returned, or the constant LDAP_RES_ANY (-1) if any result is
  1619.          desired.
  1620.  
  1621. all      Specifies how many messages will be retrieved in a single call
  1622.          to ldap_result().  This parameter only has meaning for search
  1623.  
  1624.  
  1625.  
  1626. Expires: January 1998                                          [Page 29]
  1627.  
  1628. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  1629.  
  1630.  
  1631.          results.  Pass the constant LDAP_MSG_ONE (0x00) to retrieve one
  1632.          message at a time.  Pass LDAP_MSG_ALL (0x01) to request that
  1633.          all results of a search be received before returning all
  1634.          results in a single chain.  Pass LDAP_MSG_RECEIVED (0x02) to
  1635.          indicate that all results retrieved so far should be returned
  1636.          in the result chain.
  1637.  
  1638. timeout  A timeout specifying how long to wait for results to be
  1639.          returned.  A NULL value causes ldap_result() to block until
  1640.          results are available.  A timeout value of zero seconds speci-
  1641.          fies a polling behavior.
  1642.  
  1643. res      For ldap_result(), a result parameter that will contain the
  1644.          result(s) of the operation. For ldap_msgfree(), the result
  1645.          chain to be freed, obtained from a previous call to
  1646.          ldap_result(), ldap_search_s(), or ldap_search_st().
  1647.  
  1648. Upon successful completion, ldap_result() returns the type of the first
  1649. result returned in the res parameter. This will be one of the following
  1650. constants.
  1651.  
  1652.              LDAP_RES_BIND (0x61)
  1653.              LDAP_RES_SEARCH_ENTRY (0x64)
  1654.              LDAP_RES_SEARCH_REFERENCE (0x73)      -- new in LDAPv3
  1655.              LDAP_RES_SEARCH_RESULT (0x65)
  1656.              LDAP_RES_MODIFY (0x67)
  1657.              LDAP_RES_ADD (0x69)
  1658.              LDAP_RES_DELETE (0x6B)
  1659.              LDAP_RES_MODDN (0x6D)
  1660.              LDAP_RES_COMPARE (0x6F)
  1661.              LDAP_RES_EXTENDED (0x78)              -- new in LDAPv3
  1662.  
  1663. ldap_result() returns 0 if the timeout expired and -1 if an error
  1664. occurs, in which case the error parameters of the LDAP session handle
  1665. will be set accordingly.
  1666.  
  1667. ldap_msgfree() frees the result structure pointed to by res and returns
  1668. the type of the message it freed.
  1669.  
  1670. ldap_msgtype() returns the type of the LDAP message it is passed as a
  1671. parameter. The type will be one of the types listed above, or -1 on
  1672. error.
  1673.  
  1674. ldap_msgid() returns the message ID associated with the LDAP message
  1675. passed as a parameter.
  1676.  
  1677.  
  1678.  
  1679.  
  1680.  
  1681.  
  1682. Expires: January 1998                                          [Page 30]
  1683.  
  1684. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  1685.  
  1686.  
  1687. 10.  Handling Errors and Parsing Results
  1688.  
  1689. The following calls are used to extract information from results and
  1690. handle errors returned by other LDAP API routines.
  1691.  
  1692.            int ldap_parse_result(
  1693.                    LDAP            *ld,
  1694.                    LDAPMessage     *res,
  1695.                    int             *errcodep,
  1696.                    char            **matcheddnp,
  1697.                    char            **errmsgp,
  1698.                    char            ***referralsp,
  1699.                    LDAPControl     ***serverctrlsp,
  1700.                    int             freeit
  1701.            );
  1702.  
  1703.            int ldap_parse_sasl_bind_result(
  1704.                    LDAP            *ld,
  1705.                    LDAPMessage     *res,
  1706.                    struct berval   **servercredp,
  1707.                    int             freeit
  1708.            );
  1709.  
  1710.            int ldap_parse_extended_result(
  1711.                    LDAP            *ld,
  1712.                    LDAPMessage     *res,
  1713.                    char            **resultoidp,
  1714.                    struct berval   **resultdata,
  1715.                    int             freeit
  1716.            );
  1717.  
  1718.            char *ldap_err2string( int err );
  1719.  
  1720.    The use of the following routines is deprecated.
  1721.  
  1722.            int ldap_result2error(
  1723.                    LDAP            *ld,
  1724.                    LDAPMessage     *res,
  1725.                    int             freeit
  1726.            );
  1727.  
  1728.            void ldap_perror( LDAP *ld, char *msg );
  1729.  
  1730. Parameters are:
  1731.  
  1732. ld           The session handle.
  1733.  
  1734. res          The result of an LDAP operation as returned by
  1735.  
  1736.  
  1737.  
  1738. Expires: January 1998                                          [Page 31]
  1739.  
  1740. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  1741.  
  1742.  
  1743.              ldap_result() or one of the synchronous API operation
  1744.              calls.
  1745.  
  1746. errcodep     This result parameter will be filled in with the LDAP error
  1747.              code field from the LDAPResult message.  This is the indi-
  1748.              cation from the server of the outcome of the operation.
  1749.              NULL may be passed to ignore this field.
  1750.  
  1751. matcheddnp   In the case of a return of LDAP_NO_SUCH_OBJECT, this result
  1752.              parameter will be filled in with a DN indicating how much
  1753.              of the name in the request was recognized. NULL may be
  1754.              passed to ignore this field.  The matched DN string should
  1755.              be freed by calling ldap_memfree() which is described later
  1756.              in this document.
  1757.  
  1758. errmsgp      This result parameter will be filled in with the contents
  1759.              of the error message field from the LDAPResult message.
  1760.              The error message string should be freed by calling
  1761.              ldap_memfree() which is described later in this document.
  1762.              NULL may be passed to ignore this field.
  1763.  
  1764. referralsp   This result parameter will be filled in with the contents
  1765.              of the referrals field from the LDAPResult message, indi-
  1766.              cating zero or more alternate LDAP servers where the
  1767.              request should be retried.  The referrals array should be
  1768.              freed by calling ldap_value_free() which is described later
  1769.              in this document.  NULL may be passed to ignore this field.
  1770.  
  1771. serverctrlsp This result parameter will be filled in with an allocated
  1772.              array of controls copied out of the LDAPResult message.
  1773.              The control array should be freed by calling
  1774.              ldap_controls_free() which was described earlier.
  1775.  
  1776. freeit       A boolean that determines whether the res parameter is
  1777.              disposed of or not.  Pass any non-zero value to have these
  1778.              routines free res after extracting the requested informa-
  1779.              tion.  This is provided as a convenience; you can also use
  1780.              ldap_msgfree() to free the result later.
  1781.  
  1782. servercredp  For SASL bind results, this result parameter will be filled
  1783.              in with the credentials passed back by the server for
  1784.              mutual authentication, if given. An allocated berval struc-
  1785.              ture is returned that should be disposed of by calling
  1786.              ldap_ber_free().  NULL may be passed to ignore this field.
  1787.  
  1788. resultoidp   For extended results, this result parameter will be filled
  1789.              in with the dotted-OID text representation of the name of
  1790.              the extended operation response.  This string should be
  1791.  
  1792.  
  1793.  
  1794. Expires: January 1998                                          [Page 32]
  1795.  
  1796. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  1797.  
  1798.  
  1799.              disposed of by calling ldap_memfree().  NULL may be passed
  1800.              to ignore this field.
  1801.  
  1802. resultdatap  For extended results, this result parameter will be filled
  1803.              in with a pointer to a struct berval containing the data in
  1804.              the extended operation response.  It should be disposed of
  1805.              by calling ldap_ber_free(). NULL may be passed to ignore
  1806.              this field.
  1807.  
  1808. err          For ldap_err2string(), an LDAP error code, as returned by
  1809.              ldap_result2error() or another LDAP API call.
  1810.  
  1811. Additional parameters for the deprecated routines are not described.
  1812. Interested readers are referred to RFC 1823.
  1813.  
  1814. All of the ldap_parse_*_result() routines skip over messages of type
  1815. LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_REFERENCE when looking for a
  1816. result message to parse.  They return the constant LDAP_SUCCESS if the
  1817. result was successfully parsed and another LDAP error code if not.  Note
  1818. that the LDAP error code that indicates the outcome of the operation
  1819. performed by the server is placed in the errcodep ldap_parse_result()
  1820. parameter.
  1821.  
  1822. ldap_err2string() is used to convert a numeric LDAP error code, as
  1823. returned by one of the ldap_parse_*_result() routines, or one of the
  1824. synchronous API operation calls, into an informative NULL-terminated
  1825. character string message describing the error.  It returns a pointer to
  1826. static data.
  1827.  
  1828.  
  1829. 11.  Stepping Through a List of Results
  1830.  
  1831. The ldap_first_message() and ldap_next_message() routines are used to
  1832. step through the list of messages in a result chain returned by
  1833. ldap_result().  For search operations, the result chain may actually
  1834. include referral messages, entry messages, and result messages.
  1835. ldap_count_messages() is used to count the number of messages returned.
  1836. The ldap_msgtype() function, described above, can be used to distinguish
  1837. between the different message types.
  1838.  
  1839.            LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *res );
  1840.  
  1841.            LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *msg );
  1842.  
  1843.            int ldap_count_messages( LDAP *ld, LDAPMessage *res );
  1844.  
  1845. Parameters are:
  1846.  
  1847.  
  1848.  
  1849.  
  1850. Expires: January 1998                                          [Page 33]
  1851.  
  1852. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  1853.  
  1854.  
  1855. ld     The session handle.
  1856.  
  1857. res    The result chain, as obtained by a call to one of the synchronous
  1858.        search routines or ldap_result().
  1859.  
  1860. msg    The message returned by a previous call to ldap_first_message()
  1861.        or ldap_next_message().
  1862.  
  1863. ldap_first_message() and ldap_next_message() will return NULL when no
  1864. more messages exist in the result set to be returned.  NULL is also
  1865. returned if an error occurs while stepping through the entries, in which
  1866. case the error parameters in the session handle ld will be set to indi-
  1867. cate the error.
  1868.  
  1869. ldap_count_messages() returns the number of messages contained in a
  1870. chain of results. It can also be used to count the number of messages
  1871. that remain in a chain if called with a message, entry, or reference
  1872. returned by ldap_first_message(), ldap_next_message(),
  1873. ldap_first_entry(), ldap_next_entry(), ldap_first_reference(),
  1874. ldap_next_reference().
  1875.  
  1876.  
  1877. 12.  Parsing Search Results
  1878.  
  1879. The following calls are used to parse the entries and references
  1880. returned by ldap_search() and friends. These results are returned in an
  1881. opaque structure that should only be accessed by calling the routines
  1882. described below. Routines are provided to step through the entries and
  1883. references returned, step through the attributes of an entry, retrieve
  1884. the name of an entry, and retrieve the values associated with a given
  1885. attribute in an entry.
  1886.  
  1887.  
  1888. 12.1.  Stepping Through a List of Entries
  1889.  
  1890. The ldap_first_entry() and ldap_next_entry() routines are used to step
  1891. through and retrieve the list of entries from a search result chain.
  1892. The ldap_first_reference() and ldap_next_reference() routines are used
  1893. to step through and retrieve the list of continuation references from a
  1894. search result chain.  ldap_count_entries() is used to count the number
  1895. of entries returned. ldap_count_references() is used to count the number
  1896. of references returned.
  1897.  
  1898.            LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *res );
  1899.  
  1900.            LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry );
  1901.  
  1902.            LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *res );
  1903.  
  1904.  
  1905.  
  1906. Expires: January 1998                                          [Page 34]
  1907.  
  1908. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  1909.  
  1910.  
  1911.            LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *ref );
  1912.  
  1913.            int ldap_count_entries( LDAP *ld, LDAPMessage *res );
  1914.  
  1915.            int ldap_count_references( LDAP *ld, LDAPMessage *res );
  1916.  
  1917. Parameters are:
  1918.  
  1919. ld     The session handle.
  1920.  
  1921. res    The search result, as obtained by a call to one of the synchro-
  1922.        nous search routines or ldap_result().
  1923.  
  1924. entry  The entry returned by a previous call to ldap_first_entry() or
  1925.        ldap_next_entry().
  1926.  
  1927. ldap_first_entry() and ldap_next_entry() will return NULL when no more
  1928. entries or references exist in the result set to be returned.  NULL is
  1929. also returned if an error occurs while stepping through the entries, in
  1930. which case the error parameters in the session handle ld will be set to
  1931. indicate the error.
  1932.  
  1933. ldap_count_entries() returns the number of entries contained in a chain
  1934. of entries. It can also be used to count the number of entries that
  1935. remain in a chain if called with a message, entry or reference returned
  1936. by ldap_first_message(), ldap_next_message(), ldap_first_entry(),
  1937. ldap_next_entry(), ldap_first_reference(), ldap_next_reference().
  1938.  
  1939. ldap_count_references() returns the number of references contained in a
  1940. chain of search results. It can also be used to count the number of
  1941. references that remain in a chain.
  1942.  
  1943.  
  1944. 12.2.  Stepping Through the Attributes of an Entry
  1945.  
  1946. The ldap_first_attribute() and ldap_next_attribute() calls are used to
  1947. step through the list of attribute types returned with an entry.
  1948.  
  1949.            char *ldap_first_attribute(
  1950.                    LDAP            *ld,
  1951.                    LDAPMessage     *entry,
  1952.                    BerElement      **ptr
  1953.            );
  1954.  
  1955.            char *ldap_next_attribute(
  1956.                    LDAP            *ld,
  1957.                    LDAPMessage     *entry,
  1958.                    BerElement      *ptr
  1959.  
  1960.  
  1961.  
  1962. Expires: January 1998                                          [Page 35]
  1963.  
  1964. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  1965.  
  1966.  
  1967.            );
  1968.  
  1969.            void ldap_memfree( char *mem );
  1970.  
  1971. Parameters are:
  1972.  
  1973. ld     The session handle.
  1974.  
  1975. entry  The entry whose attributes are to be stepped through, as returned
  1976.        by ldap_first_entry() or ldap_next_entry().
  1977.  
  1978. ptr    In ldap_first_attribute(), the address of a pointer used inter-
  1979.        nally to keep track of the current position in the entry. In
  1980.        ldap_next_attribute(), the pointer returned by a previous call to
  1981.        ldap_first_attribute().
  1982.  
  1983. mem    A pointer to memory allocated by the LDAP library, such as the
  1984.        attribute names returned by ldap_first_attribute() and
  1985.        ldap_next_attribute, or the DN returned by ldap_get_dn().
  1986.  
  1987. ldap_first_attribute() and ldap_next_attribute() will return NULL when
  1988. the end of the attributes is reached, or if there is an error, in which
  1989. case the error parameters in the session handle ld will be set to indi-
  1990. cate the error.
  1991.  
  1992. Both routines return a pointer to an allocated buffer containing the
  1993. current attribute name. This should be freed when no longer in use by
  1994. calling ldap_memfree().
  1995.  
  1996. ldap_first_attribute() will allocate and return in ptr a pointer to a
  1997. BerElement used to keep track of the current position. This pointer
  1998. should be passed in subsequent calls to ldap_next_attribute() to step
  1999. through the entry's attributes. After a set of calls to
  2000. ldap_first_attribute() and ldap_next_attibute(), if ptr is non-NULL, it
  2001. should be freed by calling ldap_ber_free( ptr, 0 ). Note that it is very
  2002. important to pass the second parameter as 0 (zero) in this call.
  2003.  
  2004. The attribute names returned are suitable for passing in a call to
  2005. ldap_get_values() and friends to retrieve the associated values.
  2006.  
  2007.  
  2008. 12.3.  Retrieving the Values of an Attribute
  2009.  
  2010. ldap_get_values() and ldap_get_values_len() are used to retrieve the
  2011. values of a given attribute from an entry. ldap_count_values() and
  2012. ldap_count_values_len() are used to count the returned values.
  2013. ldap_value_free() and ldap_value_free_len() are used to free the values.
  2014.  
  2015.  
  2016.  
  2017.  
  2018. Expires: January 1998                                          [Page 36]
  2019.  
  2020. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  2021.  
  2022.  
  2023.            char **ldap_get_values(
  2024.                    LDAP            *ld,
  2025.                    LDAPMessage     *entry,
  2026.                    char            *attr
  2027.            );
  2028.  
  2029.            struct berval **ldap_get_values_len(
  2030.                    LDAP            *ld,
  2031.                    LDAPMessage     *entry,
  2032.                    char            *attr
  2033.            );
  2034.  
  2035.            int ldap_count_values( char **vals );
  2036.  
  2037.            int ldap_count_values_len( struct berval **vals );
  2038.  
  2039.            int ldap_value_free( char **vals );
  2040.  
  2041.            int ldap_value_free_len( struct berval **vals );
  2042.  
  2043. Parameters are:
  2044.  
  2045. ld     The session handle.
  2046.  
  2047. entry  The entry from which to retrieve values, as returned by
  2048.        ldap_first_entry() or ldap_next_entry().
  2049.  
  2050. attr   The attribute whose values are to be retrieved, as returned by
  2051.        ldap_first_attribute() or ldap_next_attribute(), or a caller-
  2052.        supplied string (e.g., "mail").
  2053.  
  2054. vals   The values returned by a previous call to ldap_get_values() or
  2055.        ldap_get_values_len().
  2056.  
  2057. Two forms of the various calls are provided. The first form is only
  2058. suitable for use with non-binary character string data. The second _len
  2059. form is used with any kind of data.
  2060.  
  2061. Note that the values returned are dynamically allocated and should be
  2062. freed by calling either ldap_value_free() or ldap_value_free_len() when
  2063. no longer in use.
  2064.  
  2065.  
  2066. 12.4.  Retrieving the name of an entry
  2067.  
  2068. ldap_get_dn() is used to retrieve the name of an entry.
  2069. ldap_explode_dn() and ldap_explode_rdn() are used to break up a name
  2070. into its component parts. ldap_dn2ufn() is used to convert the name into
  2071.  
  2072.  
  2073.  
  2074. Expires: January 1998                                          [Page 37]
  2075.  
  2076. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  2077.  
  2078.  
  2079. a more "user friendly" format.
  2080.  
  2081.            char *ldap_get_dn( LDAP *ld, LDAPMessage *entry );
  2082.  
  2083.            char **ldap_explode_dn( char *dn, int notypes );
  2084.  
  2085.            char **ldap_explode_rdn( char *rdn, int notypes );
  2086.  
  2087.            char *ldap_dn2ufn( char *dn );
  2088.  
  2089. Parameters are:
  2090.  
  2091. ld      The session handle.
  2092.  
  2093. entry   The entry whose name is to be retrieved, as returned by
  2094.         ldap_first_entry() or ldap_next_entry().
  2095.  
  2096. dn      The dn to explode, such as returned by ldap_get_dn().
  2097.  
  2098. rdn     The rdn to explode, such as returned in the components of the
  2099.         array returned by ldap_explode_dn().
  2100.  
  2101. notypes A boolean parameter, if non-zero indicating that the dn or rdn
  2102.         components should have their type information stripped off
  2103.         (i.e., "cn=Babs" would become "Babs").
  2104.  
  2105. ldap_get_dn() will return NULL if there is some error parsing the dn,
  2106. setting error parameters in the session handle ld to indicate the error.
  2107. It returns a pointer to malloc'ed space that the caller should free by
  2108. calling ldap_memfree() when it is no longer in use.  Note the format of
  2109. the DNs returned is given by [4].
  2110.  
  2111. ldap_explode_dn() returns a NULL-terminated char * array containing the
  2112. RDN components of the DN supplied, with or without types as indicated by
  2113. the notypes parameter. The array returned should be freed when it is no
  2114. longer in use by calling ldap_value_free().
  2115.  
  2116. ldap_explode_rdn() returns a NULL-terminated char * array containing the
  2117. components of the RDN supplied, with or without types as indicated by
  2118. the notypes parameter. The array returned should be freed when it is no
  2119. longer in use by calling ldap_value_free().
  2120.  
  2121. ldap_dn2ufn() converts the DN into the user friendly format described in
  2122. [5]. The UFN returned is malloc'ed space that should be freed by a call
  2123. to ldap_memfree() when no longer in use.
  2124.  
  2125.  
  2126.  
  2127.  
  2128.  
  2129.  
  2130. Expires: January 1998                                          [Page 38]
  2131.  
  2132. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  2133.  
  2134.  
  2135. 13.  Encoded ASN.1 Value Manipulation
  2136.  
  2137. This section describes routines which may be used to encode and decode
  2138. BER-encoded ASN.1 values, which are often used inside of control and
  2139. extension values.
  2140.  
  2141. With the exceptions of two new functions ber_flatten() and ber_init(),
  2142. these functions are compatible with the University of Michigan LDAP 3.3
  2143. implementation of BER.
  2144.  
  2145.  
  2146. 13.1.  General
  2147.  
  2148.            struct berval {
  2149.                    unsigned long   bv_len;
  2150.                    char            *bv_val;
  2151.            };
  2152.  
  2153. A struct berval contains a sequence of bytes and an indication of its
  2154. length.  The bv_val is not null terminated.  bv_len must always be a
  2155. nonnegative number.  Applications may allocate their own berval struc-
  2156. tures.
  2157.  
  2158.            typedef struct berelement {
  2159.                    /* opaque */
  2160.            } BerElement;
  2161.  
  2162. The BerElement structure contains not only a copy of the encoded value,
  2163. but also state information used in encoding or decoding.  Applications
  2164. cannot allocate their own BerElement structures.  The internal state is
  2165. neither thread-specific nor locked, so two threads should not manipulate
  2166. the same BerElement value simultaneously.
  2167.  
  2168. A single BerElement value cannot be used for both encoding and decoding.
  2169.  
  2170.            void ber_bvfree ( struct berval *bv);
  2171.  
  2172. ber_bvfree() frees a berval returned from this API.  Both the bv->bv_val
  2173. string and the berval itself are freed.  Applications should not use
  2174. ber_bvfree() with bervals which the application has allocated.
  2175.  
  2176.            void ber_bvecfree ( struct berval **bv );
  2177.  
  2178. ber_bvecfree() frees an array of bervals returned from this API.  Each
  2179. of the bervals in the array are freed using ber_bvfree(), then the array
  2180. itself is freed.
  2181.  
  2182.            struct berval *ber_bvdup (struct berval *bv );
  2183.  
  2184.  
  2185.  
  2186. Expires: January 1998                                          [Page 39]
  2187.  
  2188. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  2189.  
  2190.  
  2191. ber_bvdup() returns a copy of a berval.  The bv_val field in the
  2192. returned berval points to a different area of memory as the bv_val field
  2193. in the argument berval.  The null pointer is returned on error (e.g. out
  2194. of memory).
  2195.  
  2196.            void ber_free ( BerElement *ber, int fbuf );
  2197.  
  2198. ber_free() frees a BerElement which is returned from the API calls
  2199. ber_alloc_t() or ber_init().  Each BerElement must be freed by the
  2200. caller.  The second argument fbuf should always be set to 1.
  2201.  
  2202.  
  2203. 13.2.  Encoding
  2204.  
  2205.            BerElement *ber_alloc_t(int options);
  2206.  
  2207. ber_alloc_t() constructs and returns BerElement.  The null pointer is
  2208. returned on error.  The options field contains a bitwise-or of options
  2209. which are to be used when generating the encoding of this BerElement.
  2210. One option is defined and must always be supplied:
  2211.  
  2212.            #define LBER_USE_DER 0x01
  2213.  
  2214. When this option is present, lengths will always be encoded in the
  2215. minimum number of octets.  Note that this option does not cause values
  2216. of sets and sequences to be rearranged in tag and byte order, so these
  2217. functions are not suitable for generating DER output as defined in X.509
  2218. and X.680.
  2219.  
  2220. Unrecognized option bits are ignored.
  2221.  
  2222. The BerElement returned by ber_alloc_t() is initially empty.  Calls to
  2223. ber_printf() will append bytes to the end of the ber_alloc_t().
  2224.  
  2225.            int ber_printf(BerElement *ber, char *fmt, ... )
  2226.  
  2227. The ber_printf() routine is used to encode a BER element in much the
  2228. same way that sprintf() works.  One important difference, though, is
  2229. that state information is kept in the ber argument so that multiple
  2230. calls can be made to ber_printf() to append to the end of the BER ele-
  2231. ment. ber must be a pointer to a BerElement returned by ber_alloc_t().
  2232. ber_printf() interprets and formats its arguments according to the for-
  2233. mat string fmt.  ber_printf() returns -1 if there is an error during
  2234. encoding.  As with sprintf(), each character in fmt refers to an argu-
  2235. ment to ber_printf().
  2236.  
  2237. The format string can contain the following format characters:
  2238.  
  2239.  
  2240.  
  2241.  
  2242. Expires: January 1998                                          [Page 40]
  2243.  
  2244. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  2245.  
  2246.  
  2247. 't'     Tag.  The next argument is an int specifying the tag to override
  2248.         the next element to be written to the ber.  This works across
  2249.         calls.  The int value must contain the tag class, constructed
  2250.         bit, and tag value.  The tag value must fit in a single octet
  2251.         (tag value is less than 32).  For example, a tag of "[3]" for a
  2252.         constructed type is 0xA3.
  2253.  
  2254. 'b'     Boolean.  The next argument is an int, containing either 0 for
  2255.         FALSE or 0xff for TRUE.  A boolean element is output.  If this
  2256.         format character is not preceded by the 't' format modifier, the
  2257.         tag 0x01 is used for the element.
  2258.  
  2259. 'i'     Integer.  The next argument is an int, containing the integer in
  2260.         the host's byte order.  An integer element is output. If this
  2261.         format character is not preceded by the 't' format modifier, the
  2262.         tag 0x02 is used for the element.
  2263.  
  2264. 'X'     Bitstring.  The next two arguments are a char * pointer to the
  2265.         start of the bitstring, followed by an int containing the number
  2266.         of bits in the bitstring.  A bitstring element is output, in
  2267.         primitive form.  If this format character is not preceded by the
  2268.         't' format modifier, the tag 0x03 is used for the element.
  2269.  
  2270. 'n'     Null.  No argument is required.  An ASN.1 NULL element is out-
  2271.         put.  If this format character is not preceded by the 't' format
  2272.         modifier, the tag 0x05 is used for the element.
  2273.  
  2274. 'o'     Octet string.  The next two arguments are a char *, followed by
  2275.         an int with the length of the string.  The string may contain
  2276.         null bytes and need not by null-terminated.   An octet string
  2277.         element is output, in primitive form.  If this format character
  2278.         is not preceded by the 't' format modifier, the tag 0x04 is used
  2279.         for the element.
  2280.  
  2281. 's'     Octet string.  The next argument is a char * pointing to a
  2282.         null-terminated string.  An octet string element in primitive
  2283.         form is output, which does not include the trailing ' ' byte. If
  2284.         this format character is not preceded by the 't' format modif-
  2285.         ier, the tag 0x04 is used for the element.
  2286.  
  2287. 'v'     Several octet strings.  The next argument is a char **, an array
  2288.         of char * pointers to null-terminated strings.  The last element
  2289.         in the array must be a null pointer. The octet strings do not
  2290.         include the trailing SEQUENCE OF octet strings.  The 't' format
  2291.         modifier cannot be used with this format character.
  2292.  
  2293. 'V'     Several octet strings.  A null-terminated array of berval *'s is
  2294.         supplied. Note that a construct like '{V}' is required to get an
  2295.  
  2296.  
  2297.  
  2298. Expires: January 1998                                          [Page 41]
  2299.  
  2300. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  2301.  
  2302.  
  2303.         actual SEQUENCE OF octet strings. The 't' format modifier cannot
  2304.         be used with this format character.
  2305.  
  2306. '{'     Begin sequence.  No argument is required.  If this format char-
  2307.         acter is not preceded by the 't' format modifier, the tag 0x30
  2308.         is used.
  2309.  
  2310. '}'     End sequence.  No argument is required.  The 't' format modifier
  2311.         cannot be used with this format character.
  2312.  
  2313. '['     Begin set.  No argument is required.  If this format character
  2314.         is not preceded by the 't' format modifier, the tag 0x31 is
  2315.         used.
  2316.  
  2317. ']'     End set.  No argument is required.  The 't' format modifier can-
  2318.         not be used with this format character.
  2319.  
  2320. Each use of a '{' format character must be matched by a '}' character,
  2321. either later in the format string, or in the format string of a subse-
  2322. quent call to ber_printf() for that BerElement.  The same applies to the
  2323. '[' and
  2324.  
  2325. Sequences and sets nest, and implementations of this API must maintain
  2326. internal state to be able to properly calculate the lengths.
  2327.  
  2328.            int ber_flatten (BerElement *ber, struct berval **bvPtr);
  2329.  
  2330. The ber_flatten routine allocates a struct berval whose contents are a
  2331. BER encoding taken from the ber argument. The bvPtr pointer points to
  2332. the returned berval, which must be freed using ber_bvfree().  This rou-
  2333. tine returns 0 on success and -1 on error.
  2334.  
  2335. The ber_flatten API call is not present in U-M LDAP 3.3.
  2336.  
  2337. The use of ber_flatten on a BerElement in which all '{' and '}' format
  2338. modifiers have not been properly matched can result in a berval whose
  2339. contents are not a valid BER encoding.
  2340.  
  2341.  
  2342. 13.3.  Encoding Example
  2343.  
  2344. The following is an example of encoding the following ASN.1 data type:
  2345.  
  2346.       Example1Request ::= SEQUENCE {
  2347.            s     OCTET STRING, -- must be printable
  2348.            val1  INTEGER,
  2349.            val2  [0] INTEGER DEFAULT 0
  2350.       }
  2351.  
  2352.  
  2353.  
  2354. Expires: January 1998                                          [Page 42]
  2355.  
  2356. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  2357.  
  2358.  
  2359.       int encode_example1(char *s,int val1,int val2,struct berval **bvPtr)
  2360.       {
  2361.            BerElement *ber;
  2362.            int rc;
  2363.  
  2364.            ber = ber_alloc_t(LBER_USE_DER);
  2365.  
  2366.            if (ber == NULL) return -1;
  2367.  
  2368.            if (ber_printf(ber,"{si",s,val1) == -1) {
  2369.                    ber_free(ber,1);
  2370.                    return -1;
  2371.            }
  2372.  
  2373.            if (val2 != 0) {
  2374.                    if (ber_printf(ber,"ti",0x80,val2) == -1) {
  2375.                            ber_free(ber,1);
  2376.                            return -1;
  2377.                    }
  2378.            }
  2379.  
  2380.            if (ber_printf(ber,"}") == -1) {
  2381.                    ber_free(ber,1);
  2382.                    return -1;
  2383.            }
  2384.  
  2385.            rc = ber_flatten(ber,bvPtr);
  2386.            ber_free(ber,1);
  2387.            return -1;
  2388.       }
  2389.  
  2390.  
  2391. 13.4.  Decoding
  2392.  
  2393. The following two symbols are available to applications.
  2394.  
  2395.            #define LBER_ERROR   0xffffffffL
  2396.            #define LBER_DEFAULT 0xffffffffL
  2397.  
  2398.            BerElement *ber_init (struct berval *bv);
  2399.  
  2400. The ber_init functions construct BerElement and returns a new BerElement
  2401. containing a copy of the data in the bv argument.  ber_init returns the
  2402. null pointer on error.
  2403.  
  2404.            unsigned long ber_scanf (BerElement *ber, char *fmt, ... );
  2405.  
  2406. The ber_scanf() routine is used to decode a BER element in much the same
  2407.  
  2408.  
  2409.  
  2410. Expires: January 1998                                          [Page 43]
  2411.  
  2412. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  2413.  
  2414.  
  2415. way that sscanf() works.  One important difference, though, is that some
  2416. state information is kept with the ber argument so that multiple calls
  2417. can be made to ber_scanf() to sequentially read from the BER element.
  2418. The ber argument must be a pointer to a BerElement returned by
  2419. ber_init().  ber_scanf interprets the bytes according to the format
  2420. string fmt, and stores the results in its additional arguments.
  2421. ber_scanf() returns LBER_ERROR on error, and a nonnegative number on
  2422. success.
  2423.  
  2424. The format string contains conversion specifications which are used to
  2425. direct the interpretation of the BER element.  The format string can
  2426. contain the following characters:
  2427.  
  2428. 'a'     Octet string.  A char ** argument should be supplied.  Memory is
  2429.         allocated, filled with the contents of the octet string, null-
  2430.         terminated, and the pointer to the string is stored in the argu-
  2431.         ment.  The returned value must be freed using ldap_memfree.  The
  2432.         tag of the element must indicate the primitive form (constructed
  2433.         strings are not supported) but is otherwise ignored and dis-
  2434.         carded during the decoding.  This format cannot be used with
  2435.         octet strings which could contain null bytes.
  2436.  
  2437. 'O'     Octet string.  A struct berval ** argument should be supplied,
  2438.         which upon return points to a allocated struct berval containing
  2439.         the octet string and its length.  ber_bvfree() must be called to
  2440.         free the allocated memory.  The tag of the element must indicate
  2441.         the primitive form (constructed strings are not supported) but
  2442.         is otherwise ignored during the decoding.
  2443.  
  2444. 'b'     Boolean.  A pointer to an int should be supplied. The int value
  2445.         stored will be 0 for FALSE or nonzero for TRUE.  The tag of the
  2446.         element must indicate the primitive form but is otherwise
  2447.         ignored during the decoding.
  2448.  
  2449. 'i'     Integer.  A pointer to an int should be supplied. The int value
  2450.         stored will be in host byte order.  The tag of the element must
  2451.         indicate the primitive form but is otherwise ignored during the
  2452.         decoding.  ber_scanf() will return an error if the integer can-
  2453.         not be stored in an int.
  2454.  
  2455. 'B'     Bitstring.  A char ** argument should be supplied which will
  2456.         point to the allocated bits, followed by an unsigned long *
  2457.         argument, which will point to the length (in bits) of the bit-
  2458.         string returned.  ldap_memfree must be called to free the bit-
  2459.         string.  The tag of the element must indicate the primitive form
  2460.         (constructed bitstrings are not supported) but is otherwise
  2461.         ignored during the decoding.
  2462.  
  2463.  
  2464.  
  2465.  
  2466. Expires: January 1998                                          [Page 44]
  2467.  
  2468. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  2469.  
  2470.  
  2471. 'n'     Null.  No argument is required.  The element is simply skipped
  2472.         if it is recognized as a zero-length element.  The tag is
  2473.         ignored.
  2474.  
  2475. 'v'     Several octet strings.  A char *** argument should be supplied,
  2476.         which upon return points to a allocated null-terminated array of
  2477.         char *'s containing the octet strings.  NULL is stored if the
  2478.         sequence is empty.  ldap_memfree must be called to free each
  2479.         element of the array and the array itself.  The tag of the
  2480.         sequence and of the octet strings are ignored.
  2481.  
  2482. 'V'     Several octet strings (which could contain null bytes).  A
  2483.         struct berval *** should be supplied, which upon return points
  2484.         to a allocated null-terminated array of struct berval *'s con-
  2485.         taining the octet strings and their lengths.  NULL is stored if
  2486.         the sequence is empty. ber_bvecfree() can be called to free the
  2487.         allocated memory.  The tag of the sequence and of the octet
  2488.         strings are ignored.
  2489.  
  2490. 'x'     Skip element.  The next element is skipped.  No argument is
  2491.         required.
  2492.  
  2493. '{'     Begin sequence.  No argument is required.  The initial sequence
  2494.         tag and length are skipped.
  2495.  
  2496. '}'     End sequence.  No argument is required.
  2497.  
  2498. '['     Begin set.  No argument is required.  The initial set tag and
  2499.         length are skipped.
  2500.  
  2501. ']'     End set.  No argument is required.
  2502.  
  2503.            unsigned long ber_peek_tag (BerElement *ber, unsigned long *lenPtr);
  2504.  
  2505. ber_peek_tag() returns the tag of the next element to be parsed in the
  2506. BerElement argument.  The length of this element is stored in the
  2507. *lenPtr argument.  LBER_DEFAULT is returned if there is no further data
  2508. to be read.  The ber argument is not modified.
  2509.  
  2510.            unsigned long ber_skip_tag (BerElement *ber, unsigned long *lenPtr);
  2511.  
  2512. ber_skip_tag() is similar to ber_peek_tag(), except that the state
  2513. pointer in the BerElement argument is advanced past the first tag and
  2514. length, and is pointed to the value part of the next element.  This rou-
  2515. tine should only be used with constructed types and situations when a
  2516. BER encoding is used as the value of an OCTET STRING.  The length of the
  2517. value is stored in *lenPtr.
  2518.  
  2519.  
  2520.  
  2521.  
  2522. Expires: January 1998                                          [Page 45]
  2523.  
  2524. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  2525.  
  2526.  
  2527.            unsigned long ber_first_element(BerElement *ber,
  2528.                    unsigned long *lenPtr, char **opaquePtr);
  2529.  
  2530.            unsigned long ber_next_element  (BerElement *ber,
  2531.                    unsigned long *lenPtr, char *opaque);
  2532.  
  2533. ber_first_element() and ber_next_element() are used to traverse a SET,
  2534. SET OF, SEQUENCE or SEQUENCE OF data value. ber_first_element() calls
  2535. ber_skip_tag(), stores internal information in *lenPtr and *opaquePtr,
  2536. and calls ber_peek_tag() for the first element inside the constructed
  2537. value. LBER_DEFAULT is returned if the constructed value is empty.
  2538. ber_next_element() positions the state at the start of the next element
  2539. in the constructed type.  LBER_DEFAULT is returned if there are no
  2540. further values.
  2541.  
  2542. The len and opaque values should not be used by applications other than
  2543. as arguments to ber_next_element(), as shown in the example below.
  2544.  
  2545.  
  2546. 13.5.  Decoding Example
  2547.  
  2548. The following is an example of decoding an ASN.1 data type:
  2549.  
  2550.       Example2Request ::= SEQUENCE {
  2551.            dn    OCTET STRING, -- must be printable
  2552.            scope ENUMERATED { b (0), s (1), w (2) },
  2553.            ali   ENUMERATED { n (0), s (1), f (2), a (3) },
  2554.            size  INTEGER,
  2555.            time  INTEGER,
  2556.            tonly BOOLEAN,
  2557.            attrs SEQUENCE OF OCTET STRING, -- must be printable
  2558.            [0] SEQUENCE OF SEQUENCE {
  2559.               type  OCTET STRING -- must be printable,
  2560.               crit  BOOLEAN DEFAULT FALSE,
  2561.               value OCTET STRING
  2562.            } OPTIONAL }
  2563.  
  2564.       #define LDAP_TAG_CONTROL_LIST 0xA0L /* context specific cons 0 */
  2565.  
  2566.       int decode_example2(struct berval *bv)
  2567.       {
  2568.            BerElement *ber;
  2569.            unsigned long len;
  2570.            int scope, ali, size, time, tonly;
  2571.            char *dn = NULL, **attrs = NULL;
  2572.            int res,i,rc = 0;
  2573.  
  2574.            ber = ber_init(bv);
  2575.  
  2576.  
  2577.  
  2578. Expires: January 1998                                          [Page 46]
  2579.  
  2580. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  2581.  
  2582.  
  2583.            if (ber == NULL) {
  2584.                    printf("ERROR ber_init failed0);
  2585.                    return -1;
  2586.            }
  2587.  
  2588.            res = ber_scanf(ber,"{aiiiiib{v}",&dn,&scope,&ali,
  2589.                            &size,&time,&tonly,&attrs);
  2590.  
  2591.            if (res == -1) {
  2592.                    printf("ERROR ber_scanf failed0);
  2593.                    ber_free(ber,1);
  2594.                    return -1;
  2595.            }
  2596.  
  2597.            /* *** use dn */
  2598.            ldap_memfree(dn);
  2599.  
  2600.            for (i = 0; attrs != NULL && attrs[i] != NULL; i++) {
  2601.                    /* *** use attrs[i] */
  2602.                    ldap_memfree(attrs[i]);
  2603.            }
  2604.            ldap_memfree(attrs);
  2605.  
  2606.            if (ber_peek_tag(ber,&len) == LDAP_TAG_CONTROL_LIST) {
  2607.                    char *opaque;
  2608.                    unsigned long tag;
  2609.  
  2610.                    for (tag = ber_first_element(ber,&len,&opaque);
  2611.                         tag != LBER_DEFAULT;
  2612.                         tag = ber_next_element (ber,&len,opaque)) {
  2613.  
  2614.                            unsigned long ttag, tlen;
  2615.                            char *type;
  2616.                            int crit;
  2617.                            struct berval *value;
  2618.  
  2619.                            if (ber_scanf(ber,"{a",&type) == LBER_ERROR) {
  2620.                                    printf("ERROR cannot parse type0);
  2621.                                    break;
  2622.                            }
  2623.                            /* *** use type */
  2624.                            ldap_memfree(type);
  2625.  
  2626.                            ttag = ber_peek_tag(ber,&tlen);
  2627.                            if (ttag == 0x01) {  /* boolean */
  2628.                                    if (ber_scanf(ber,"b",
  2629.                                                  &crit) == LBER_ERROR) {
  2630.                                            printf("ERROR cannot parse crit0);
  2631.  
  2632.  
  2633.  
  2634. Expires: January 1998                                          [Page 47]
  2635.  
  2636. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  2637.  
  2638.  
  2639.                                            rc = -1;
  2640.                                            break;
  2641.                                    }
  2642.                            } else if (ttag == 0x04) { /* octet string */
  2643.                                    crit = 0;
  2644.                            } else {
  2645.                                    printf("ERROR extra field in controls0);
  2646.                                    break;
  2647.                            }
  2648.  
  2649.                            if (ber_scanf(ber,"O}",&value) == LBER_ERROR) {
  2650.                                    printf("ERROR cannot parse value0);
  2651.                                    rc = -1;
  2652.                                    break;
  2653.                            }
  2654.                            /* *** use value */
  2655.                            ldap_bvfree(value);
  2656.                    }
  2657.            }
  2658.  
  2659.            ber_scanf(ber,"}");
  2660.  
  2661.            ber_free(ber,1);
  2662.  
  2663.            return rc;
  2664.        }
  2665.  
  2666.  
  2667.  
  2668. 14.  Security Considerations
  2669.  
  2670. LDAPv2 supports security through protocol-level authentication using
  2671. clear-text passwords.  LDAPv3 adds support for SASL [8] (Simple Authen-
  2672. tication Security Layer) methods.  LDAPv3 also supports operation over a
  2673. secure transport layer using Transport Layer Security TLS [8].  Readers
  2674. are referred to the protocol documents for discussion of related secu-
  2675. rity considerations.
  2676.  
  2677. Implementations of this API should be cautious when handling authentica-
  2678. tion credentials.  In particular, keeping long-lived copies of creden-
  2679. tials without the application's knowledge is discouraged.
  2680.  
  2681.  
  2682. 15.  Acknowledgements
  2683.  
  2684. Many members of the IETF ASID working group as well as members of the
  2685. Internet at large have provided useful comments and suggestions that
  2686. have been incorporated into this revision.
  2687.  
  2688.  
  2689.  
  2690. Expires: January 1998                                          [Page 48]
  2691.  
  2692. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  2693.  
  2694.  
  2695. This original material upon which this revision is based was based upon
  2696. work supported by the National Science Foundation under Grant No.  NCR-
  2697. 9416667.
  2698.  
  2699.  
  2700. 16.  Bibliography
  2701.  
  2702. [1]  The Directory: Selected Attribute Syntaxes.  CCITT, Recommendation
  2703.      X.520.
  2704.  
  2705. [2]  M. Wahl, A. Coulbeck, T. Howes, S. Kille, W. Yeong, C. Robbins,
  2706.      "Lightweight Directory Access Protocol Attribute Syntax Defini-
  2707.      tions", INTERNET-DRAFT <draft-ietf-asid-ldapv3-attributes-06.txt>,
  2708.      11 July 1997.
  2709.  
  2710. [3]  T. Howes, "A String Representation of LDAP Search Filters,"
  2711.      INTERNET-DRAFT <draft-ietf-asid-ldapv3-filter-02.txt>, May 1997.
  2712.  
  2713. [4]  S. Kille, M. Wahl, "A UTF-8 String Representation of Distinguished
  2714.      Names", INTERNET-DRAFT <draft-ietf-asid-ldapv3-dn-03.txt>, 29 April
  2715.      1997.
  2716.  
  2717. [5]  S. Kille, "Using the OSI Directory to Achieve User Friendly Nam-
  2718.      ing," RFC 1781, March 1995.
  2719.  
  2720. [6]  M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
  2721.      (v3)", INTERNET-DRAFT <draft-ietf-asid-ldapv3-protocol-06.txt>, 11
  2722.      July 1997.
  2723.  
  2724. [7]  A. Herron, T. Howes, M. Wahl, "LDAP Control Extension for Server
  2725.      Side Sorting of Search Result," INTERNET-DRAFT <draft-ietf-asid-
  2726.      ldapv3-sorting-00.txt>, 16 April 1997.
  2727.  
  2728. [8]  J. Meyers, "Simple Authentication and Security Layer", INTERNET-
  2729.      DRAFT <draft-myers-auth-sasl-11.txt>, April 1997.
  2730.  
  2731. [9]  "Lightweight Directory Access Protocol (v3) Extension for Transport
  2732.      Layer Security", INTERNET-DRAFT <draft-ietf-asid-ldapv3-tls-
  2733.      01.txt>, June 1997.
  2734.  
  2735. [10] "UTF-8, a transformation format of Unicode and ISO 10646", RFC
  2736.      2044, October 1996.
  2737.  
  2738. [11] "IP Version 6 Addressing Architecture,", RFC 1884, December 1995.
  2739.  
  2740.  
  2741.  
  2742.  
  2743.  
  2744.  
  2745.  
  2746. Expires: January 1998                                          [Page 49]
  2747.  
  2748. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  2749.  
  2750.  
  2751. 17.  Author's Addresses
  2752.  
  2753.    Tim Howes
  2754.    Netscape Communications Corp.
  2755.    501 E. Middlefield Rd., Mailstop MV068
  2756.    Mountain View, CA 94043
  2757.    USA
  2758.    +1 415 937-3419
  2759.    howes@netscape.com
  2760.  
  2761.  
  2762.    Mark Smith
  2763.    Netscape Communications Corp.
  2764.    501 E. Middlefield Rd., Mailstop MV068
  2765.    Mountain View, CA 94043
  2766.    USA
  2767.    +1 415 937-3477
  2768.    mcs@netscape.com
  2769.  
  2770.    Andy Herron
  2771.    Microsoft Corp.
  2772.    1 Microsoft Way
  2773.    Redmond, WA 98052
  2774.    USA
  2775.    +1 425 882-8080
  2776.    andyhe@microsoft.com
  2777.  
  2778.    Chris Weider
  2779.    Microsoft Corp.
  2780.    1 Microsoft Way
  2781.    Redmond, WA 98052
  2782.    USA
  2783.    +1 425 882-8080
  2784.    cweider@microsoft.com
  2785.  
  2786.    Mark Wahl
  2787.    Critical Angle Inc.
  2788.    4815 W Braker Lane #502-385
  2789.    Austin, TX 78759
  2790.    USA
  2791.    M.Wahl@critical-angle.com
  2792.  
  2793.  
  2794. 18.  Appendix A - Sample LDAP API Code
  2795.  
  2796.    #include <ldap.h>
  2797.  
  2798.    main()
  2799.  
  2800.  
  2801.  
  2802. Expires: January 1998                                          [Page 50]
  2803.  
  2804. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  2805.  
  2806.  
  2807.    {
  2808.            LDAP            *ld;
  2809.            LDAPMessage     *res, *e;
  2810.            int             i;
  2811.            char            *a, *dn;
  2812.            BerElement      *ptr;
  2813.            char            **vals;
  2814.  
  2815.            /* open an LDAP session */
  2816.            if ( (ld = ldap_init( "dotted.host.name", LDAP_PORT )) == NULL )
  2817.                    exit( 1 );
  2818.  
  2819.            /* authenticate as nobody */
  2820.            if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) {
  2821.                    ldap_perror( ld, "ldap_simple_bind_s" );
  2822.                    exit( 1 );
  2823.            }
  2824.  
  2825.            /* search for entries with cn of "Babs Jensen", return all attrs  */
  2826.            if ( ldap_search_s( ld, "o=University of Michigan, c=US",
  2827.                LDAP_SCOPE_SUBTREE, "(cn=Babs Jensen)", NULL, 0, &res )
  2828.                != LDAP_SUCCESS ) {
  2829.                    ldap_perror( ld, "ldap_search_s" );
  2830.                    exit( 1 );
  2831.            }
  2832.  
  2833.            /* step through each entry returned */
  2834.            for ( e = ldap_first_entry( ld, res ); e != NULL;
  2835.                e = ldap_next_entry( ld, e ) ) {
  2836.                    /* print its name */
  2837.                    dn = ldap_get_dn( ld, e );
  2838.                    printf( "dn: %s\n", dn );
  2839.                    ldap_memfree( dn );
  2840.  
  2841.                    /* print each attribute */
  2842.                    for ( a = ldap_first_attribute( ld, e, &ptr ); a != NULL;
  2843.                        a = ldap_next_attribute( ld, e, ptr ) ) {
  2844.                            printf( "attribute: %s\n", a );
  2845.  
  2846.                            /* print each value */
  2847.                            vals = ldap_get_values( ld, e, a );
  2848.                            for ( i = 0; vals[i] != NULL; i++ ) {
  2849.                                    printf( "value: %s\n", vals[i] );
  2850.                            }
  2851.                            ldap_value_free( vals );
  2852.                    }
  2853.                    if ( ptr != NULL ) {
  2854.                            ldap_ber_free( ptr, 0 );
  2855.  
  2856.  
  2857.  
  2858. Expires: January 1998                                          [Page 51]
  2859.  
  2860. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  2861.  
  2862.  
  2863.                    }
  2864.            }
  2865.            /* free the search results */
  2866.            ldap_msgfree( res );
  2867.  
  2868.            /* close and free connection resources */
  2869.            ldap_unbind( ld );
  2870.    }
  2871.  
  2872.  
  2873.  
  2874. 19.  Appendix B - Outstanding Issues
  2875.  
  2876.  
  2877. 19.1.  Support for multithreaded applications
  2878.  
  2879. In order to support multithreaded applications in a platform-independent
  2880. way, some additions to the LDAP API are needed.  Different implementors
  2881. have taken different paths to solve this problem in the past.  A common
  2882. set of thread-related API calls must be defined so that application
  2883. developers are not unduly burdened.  These will be added to a future
  2884. revision of this specification.
  2885.  
  2886.  
  2887. 19.2.  Using Transport Layer Security (TLS)
  2888.  
  2889. The API calls used to support TLS must be specified.  They will be added
  2890. to a future revision of this specification.
  2891.  
  2892.  
  2893. 19.3.  Client control for chasing referrals
  2894.  
  2895. A client control has been defined that can be used to specify on a per-
  2896. operation basis whether references and external referrals are automati-
  2897. cally chased by the client library.  This will be added to a future
  2898. revision of this specification.
  2899.  
  2900.  
  2901. 19.4.  Potential confusion between hostname:port and IPv6 addresses
  2902.  
  2903. String representations of IPv6 network addresses [11] can contain colon
  2904. characters.  The ldap_init() call is specified to take strings of the
  2905. form "hostname:port" or "ipaddress:port".  If IPv6 addresses are used,
  2906. the latter could be ambiguous.  A future revision of this specification
  2907. will resolve this issue.
  2908.  
  2909.  
  2910.  
  2911.  
  2912.  
  2913.  
  2914. Expires: January 1998                                          [Page 52]
  2915.  
  2916. C LDAP API      The C LDAP Application Program Interface    29 July 1997
  2917.  
  2918.  
  2919. 19.5.  Need to track SASL API standardization efforts
  2920.  
  2921. If a standard Simple Authentication and Security Layer API is defined,
  2922. it may be necessary to modify the LDAP API to accommodate it.
  2923.  
  2924.  
  2925. 19.6.  Support for character sets other than UTF-8?
  2926.  
  2927. Some application developers would prefer to pass string data using a
  2928. character set other than UTF-8.  This could be accommodated by adding a
  2929. new option to ldap_set_option() that supports choosing a character set.
  2930. If this feature is added, the number of different character sets sup-
  2931. ported should definitely be minimized.
  2932.  
  2933.  
  2934. 19.7.  Use of UTF-8 with LDAPv2 servers
  2935.  
  2936. Strings are always passed as UTF-8 in this API but LDAP version 2
  2937. servers do not support the full range of UTF-8 characters.  The expected
  2938. behavior of this API when using LDAP version 2 with unsupported charac-
  2939. ters should be specified.
  2940.  
  2941.  
  2942.  
  2943.  
  2944.  
  2945.  
  2946.  
  2947.  
  2948.  
  2949.  
  2950.  
  2951.  
  2952.  
  2953.  
  2954.  
  2955.  
  2956.  
  2957.  
  2958.  
  2959.  
  2960.  
  2961.  
  2962.  
  2963.  
  2964.  
  2965.  
  2966.  
  2967.  
  2968.  
  2969.  
  2970. Expires: January 1998                                          [Page 53]
  2971.  
  2972.  
  2973.  
  2974. 1.     Status of this Memo............................................1
  2975. 2.     Introduction...................................................1
  2976. 3.     Overview of the LDAP Model.....................................2
  2977. 4.     Overview of LDAP API Use.......................................3
  2978. 5.     Common Data Structures.........................................4
  2979. 6.     LDAP Error Codes...............................................5
  2980. 7.     Performing LDAP Operations.....................................6
  2981. 7.1.      Initializing an LDAP Session................................6
  2982. 7.2.      LDAP Session Handle Options.................................7
  2983. 7.3.      Working with controls.......................................10
  2984. 7.4.      Authenticating to the directory.............................11
  2985. 7.5.      Closing the session.........................................13
  2986. 7.6.      Searching...................................................13
  2987. 7.7.      Reading an Entry............................................17
  2988. 7.8.      Listing the Children of an Entry............................17
  2989. 7.9.      Comparing a Value Against an Entry..........................17
  2990. 7.10.     Modifying an entry..........................................19
  2991. 7.11.     Modifying the Name of an Entry..............................21
  2992. 7.12.     Adding an entry.............................................23
  2993. 7.13.     Deleting an entry...........................................25
  2994. 7.14.     Extended Operations.........................................26
  2995. 8.     Abandoning An Operation........................................28
  2996. 9.     Obtaining Results and Peeking Inside LDAP Messages.............29
  2997. 10.    Handling Errors and Parsing Results............................31
  2998. 11.    Stepping Through a List of Results.............................33
  2999. 12.    Parsing Search Results.........................................34
  3000. 12.1.     Stepping Through a List of Entries..........................34
  3001. 12.2.     Stepping Through the Attributes of an Entry.................35
  3002. 12.3.     Retrieving the Values of an Attribute.......................36
  3003. 12.4.     Retrieving the name of an entry.............................37
  3004. 13.    Encoded ASN.1 Value Manipulation...............................39
  3005. 13.1.     General.....................................................39
  3006. 13.2.     Encoding....................................................40
  3007. 13.3.     Encoding Example............................................42
  3008. 13.4.     Decoding....................................................43
  3009. 13.5.     Decoding Example............................................46
  3010. 14.    Security Considerations........................................48
  3011. 15.    Acknowledgements...............................................48
  3012. 16.    Bibliography...................................................49
  3013. 17.    Author's Addresses.............................................50
  3014. 18.    Appendix A - Sample LDAP API Code..............................50
  3015. 19.    Appendix B - Outstanding Issues................................52
  3016. 19.1.     Support for multithreaded applications......................52
  3017. 19.2.     Using Transport Layer Security (TLS)........................52
  3018. 19.3.     Client control for chasing referrals........................52
  3019. 19.4.     Potential confusion between hostname:port and IPv6 addresses52
  3020. 19.5.     Need to track SASL API standardization efforts..............53
  3021. 19.6.     Support for character sets other than UTF-8?................53
  3022. 19.7.     Use of UTF-8 with LDAPv2 servers............................53
  3023.  
  3024.  
  3025.  
  3026.  
  3027.  
  3028.  
  3029.  
  3030.  
  3031.