1 Network Working Group M. Smith, Editor
2 INTERNET-DRAFT Netscape Communications Corp.
3 Intended Category: Standards Track T. Howes
4 Obsoletes: RFC 1823 Netscape Communications Corp.
5 Expires: 2 December 1999 A. Herron
8 Innosoft International, Inc.
15 The C LDAP Application Program Interface
16 <draft-ietf-ldapext-ldap-c-api-03.txt>
19 1. Status of this Memo
21 This document is an Internet-Draft and is in full conformance with all
22 provisions of Section 10 of RFC2026. Internet-Drafts are working docu-
23 ments of the Internet Engineering Task Force (IETF), its areas, and its
24 working groups. Note that other groups may also distribute working
25 documents as Internet-Drafts.
27 Internet-Drafts are draft documents valid for a maximum of six months
28 and may be updated, replaced, or obsoleted by other documents at any
29 time. It is inappropriate to use Internet-Drafts as reference material
30 or to cite them other than as "work in progress."
32 The list of current Internet-Drafts can be accessed at
33 http://www.ietf.org/ietf/1id-abstracts.txt.
35 The list of Internet-Draft Shadow Directories can be accessed at
36 http://www.ietf.org/shadow.html.
38 This draft document will be submitted to the RFC Editor as a Standards
39 Track document. Distribution of this memo is unlimited. Technical dis-
40 cussion of this document will take place on the IETF LDAP Extension
41 Working Group mailing list <ietf-ldapext@netscape.com>. Please send
42 editorial comments directly to the authors.
44 Copyright (C) The Internet Society (1997-1999). All Rights Reserved.
46 Please see the Copyright section near the end of this document for more
52 Expires: 2 December 1999 [Page 1]
55 C LDAP API C LDAP Application Program Interface 2 June 1999
60 This document defines a C language application program interface (API)
61 to the Lightweight Directory Access Protocol (LDAP). This document
62 replaces the previous definition of this API, defined in RFC 1823,
63 updating it to include support for features found in version 3 of the
64 LDAP protocol. New extended operation functions were added to support
65 LDAPv3 features such as controls. In addition, other LDAP API changes
66 were made to support information hiding and thread safety.
68 The C LDAP API is designed to be powerful, yet simple to use. It defines
69 compatible synchronous and asynchronous interfaces to LDAP to suit a
70 wide variety of applications. This document gives a brief overview of
71 the LDAP model, then an overview of how the API is used by an applica-
72 tion program to obtain LDAP information. The API calls are described in
73 detail, followed by appendices that provide example code demonstrating
74 use of the API, the namespace consumed by the API, a summary of require-
75 ments for API extensions, known incompatibilities with RFC 1823, and a
76 list of changes made since the last revision of this document.
81 1. Status of this Memo............................................1
82 2. Introduction...................................................2
83 3. Table of Contents..............................................2
84 4. Overview of the LDAP Model.....................................4
85 5. Overview of LDAP API Use.......................................4
86 6. Header File Requirements.......................................6
87 7. Common Data Structures.........................................7
88 8. Retrieving Information About the API Implementation............8
89 8.1. Retrieving Information at Compile Time......................9
90 8.2. Retrieving Information During Execution.....................10
91 9. LDAP Error Codes...............................................13
92 10. Performing LDAP Operations.....................................14
93 10.1. Initializing an LDAP Session................................14
94 10.2. LDAP Session Handle Options.................................15
95 10.3. Working With Controls.......................................20
96 10.3.1. A Client Control That Governs Referral Processing........22
97 10.4. Authenticating to the directory.............................22
98 10.5. Closing the session.........................................25
99 10.6. Searching...................................................26
100 10.7. Reading an Entry............................................29
101 10.8. Listing the Children of an Entry............................30
102 10.9. Comparing a Value Against an Entry..........................30
103 10.10. Modifying an entry..........................................32
104 10.11. Modifying the Name of an Entry..............................34
105 10.12. Adding an entry.............................................36
109 Expires: 2 December 1999 [Page 2]
112 C LDAP API C LDAP Application Program Interface 2 June 1999
115 10.13. Deleting an entry...........................................38
116 10.14. Extended Operations.........................................39
117 11. Abandoning An Operation........................................41
118 12. Obtaining Results and Peeking Inside LDAP Messages.............42
119 13. Handling Errors and Parsing Results............................44
120 14. Stepping Through a List of Results.............................46
121 15. Parsing Search Results.........................................47
122 15.1. Stepping Through a List of Entries or References............48
123 15.2. Stepping Through the Attributes of an Entry.................49
124 15.3. Retrieving the Values of an Attribute.......................50
125 15.4. Retrieving the name of an entry.............................51
126 15.5. Retrieving controls from an entry...........................52
127 15.6. Parsing References..........................................53
128 16. Encoded ASN.1 Value Manipulation...............................54
129 16.1. General.....................................................54
130 16.2. Encoding....................................................55
131 16.3. Encoding Example............................................58
132 16.4. Decoding....................................................59
133 16.5. Decoding Example............................................61
134 17. Security Considerations........................................64
135 18. Acknowledgements...............................................64
136 19. Copyright......................................................64
137 20. Bibliography...................................................65
138 21. Authors' Addresses.............................................66
139 22. Appendix A - Sample C LDAP API Code............................66
140 23. Appendix B - Namespace Consumed By This Specification..........68
141 24. Appendix C - Summary of Requirements for API Extensions........68
142 24.1. Compatibility...............................................69
143 24.2. Style.......................................................69
144 24.3. Dependence on Externally Defined Types......................69
145 24.4. Compile Time Information....................................69
146 24.5. Runtime Information.........................................69
147 24.6. Values Used for Session Handle Options......................70
148 25. Appendix D - Known Incompatibilities with RFC 1823.............70
149 25.1. Opaque LDAP Structure.......................................70
150 25.2. Additional Error Codes......................................70
151 25.3. Freeing of String Data with ldap_memfree()..................71
152 25.4. Changes to ldap_result()....................................71
153 25.5. Changes to ldap_first_attribute() and ldap_next_attribute...71
154 25.6. Changes to ldap_modrdn() and ldap_modrdn_s() Functions......71
155 25.7. Changes to the berval structure.............................71
156 25.8. API Specification Clarified.................................72
157 25.9. Deprecated Functions........................................72
158 26. Appendix E - Data Types and Legacy Implementations.............72
159 27. Appendix F - Changes Made Since Last Document Revision.........73
160 27.1. API Changes.................................................73
161 27.2. Editorial Changes...........................................74
162 28. Appendix G - Changes Made Since draft-ietf-ldapext-ldap-c-api-.74
163 28.1. API Changes.................................................74
164 28.2. Editorial changes...........................................75
166 Expires: 2 December 1999 [Page 3]
169 C LDAP API C LDAP Application Program Interface 2 June 1999
172 4. Overview of the LDAP Model
174 LDAP is the lightweight directory access protocol, described in [2] and
175 [6]. It can provide a lightweight frontend to the X.500 directory [1],
176 or a stand-alone service. In either mode, LDAP is based on a client-
177 server model in which a client makes a TCP connection to an LDAP server,
178 over which it sends requests and receives responses.
180 The LDAP information model is based on the entry, which contains infor-
181 mation about some object (e.g., a person). Entries are composed of
182 attributes, which have a type and one or more values. Each attribute has
183 a syntax that determines what kinds of values are allowed in the attri-
184 bute (e.g., ASCII characters, a jpeg photograph, etc.) and how those
185 values behave during directory operations (e.g., is case significant
188 Entries may be organized in a tree structure, usually based on politi-
189 cal, geographical, and organizational boundaries. Each entry is uniquely
190 named relative to its sibling entries by its relative distinguished name
191 (RDN) consisting of one or more distinguished attribute values from the
192 entry. At most one value from each attribute may be used in the RDN.
193 For example, the entry for the person Babs Jensen might be named with
194 the "Barbara Jensen" value from the commonName attribute.
196 A globally unique name for an entry, called a distinguished name or DN,
197 is constructed by concatenating the sequence of RDNs from the entry up
198 to the root of the tree. For example, if Babs worked for the University
199 of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen,
200 o=University of Michigan, c=US". The DN format used by LDAP is defined
203 Operations are provided to authenticate, search for and retrieve infor-
204 mation, modify information, and add and delete entries from the tree.
205 The next sections give an overview of how the API is used and detailed
206 descriptions of the LDAP API calls that implement all of these func-
210 5. Overview of LDAP API Use
212 An application generally uses the C LDAP API in four simple steps.
214 1. Initialize an LDAP session with a primary LDAP server. The
215 ldap_init() function returns a handle to the session, allowing
216 multiple connections to be open at once.
218 2. Authenticate to the LDAP server. The ldap_sasl_bind() function
219 and friends support a variety of authentication methods.
223 Expires: 2 December 1999 [Page 4]
226 C LDAP API C LDAP Application Program Interface 2 June 1999
229 3. Perform some LDAP operations and obtain some results.
230 ldap_search() and friends return results which can be parsed by
231 ldap_parse_result(), ldap_first_entry(), ldap_next_entry(), etc.
233 4. Close the session. The ldap_unbind() function closes the connec-
236 Operations can be performed either synchronously or asynchronously. The
237 names of the synchronous functions end in _s. For example, a synchronous
238 search can be completed by calling ldap_search_s(). An asynchronous
239 search can be initiated by calling ldap_search(). All synchronous rou-
240 tines return an indication of the outcome of the operation (e.g, the
241 constant LDAP_SUCCESS or some other error code). The asynchronous rou-
242 tines make available to the caller the message id of the operation ini-
243 tiated. This id can be used in subsequent calls to ldap_result() to
244 obtain the result(s) of the operation. An asynchronous operation can be
245 abandoned by calling ldap_abandon() or ldap_abandon_ext().
247 Results and errors are returned in an opaque structure called LDAPMes-
248 sage. Routines are provided to parse this structure, step through
249 entries and attributes returned, etc. Routines are also provided to
250 interpret errors. Later sections of this document describe these rou-
251 tines in more detail.
253 LDAP version 3 servers may return referrals and references to other
254 servers. By default, implementations of this API will attempt to follow
255 referrals automatically for the application. This behavior can be dis-
256 abled globally (using the ldap_set_option() call) or on a per-request
257 basis through the use of a client control.
259 All DN and string attribute values passed into or produced by this C
260 LDAP API are represented using the character set of the underlying LDAP
261 protocol version in use. When this API is used with LDAPv3, DN and
262 string values are represented as UTF-8[10] characters. When this API is
263 used with LDAPv2, the US-ASCII[12] or T.61[12] character set are used.
264 Future documents may specific additional APIs supporting other character
267 For compatibility with existing applications, implementations of this
268 API will by default use version 2 of the LDAP protocol. Applications
269 that intend to take advantage of LDAP version 3 features will need to
270 use the ldap_set_option() call with a LDAP_OPT_PROTOCOL_VERSION to
273 Note that this API is designed for use in environments where the 'int'
274 type is at least 32 bits in size.
280 Expires: 2 December 1999 [Page 5]
283 C LDAP API C LDAP Application Program Interface 2 June 1999
286 6. Header File Requirements
288 To promote portability of applications, implementations of this C LDAP
289 API must conform to the following requirements of the header files used
290 by applications to access the services of this API:
293 Applications are only required to include a single header file
294 named ldap.h to access all of the API services described in this
295 document. Therefore, the following C source program must com-
306 Note that it is permissible for the ldap.h header file to
307 include other implementation-specific header files.
309 Implementations SHOULD also provide a header file named lber.h to faci-
310 late development of applications desiring compatibility with older LDAP
311 implementations. The lber.h header file may be empty.
315 All header files should be idempotent; that is, if they are
316 included more than once the effect is as if they had only been
319 Must Be Included Before API Is Used
320 An application must include the ldap.h header file before
321 referencing any of the function or type definitions described in
322 this API specification.
325 If possible, header files should be mutually independent with
326 minimal dependence on system or any other header files.
328 Use of the 'const' Keyword
329 This API specification is defined in terms of ISO C[13]. It
330 makes use of function prototypes and the 'const' keyword. The
331 use of 'const' in this specification is limited to simple, non-
332 array function parameters to avoid forcing applications to
333 declare parameters and variables that accept return values from
337 Expires: 2 December 1999 [Page 6]
340 C LDAP API C LDAP Application Program Interface 2 June 1999
343 LDAP API functions as 'const.' Implementations specifically
344 designed to be used with non-ISO C translators may provide func-
345 tion declarations without prototypes or function prototypes
346 without specification of 'const' arguments.
348 Definition of 'struct timeval'
349 This API specification uses the 'struct timeval' type. Imple-
350 mentations of this API should ensure that the struct timeval
351 type is by default defined as a consequence of including the
352 ldap.h header file. Because struct timeval is usually defined
353 in one or more system header files, it is possible for header
354 file conflicts to occur if ldap.h also defines it or arranges
355 for it to be defined by including another header file. There-
356 fore, applications may want to arrange for struct timeval to be
357 defined before they include ldap.h. To support this, the ldap.h
358 header file must not itself define struct timeval if the prepro-
359 cessor symbol LDAP_TYPE_TIMEVAL_DEFINED is defined before ldap.h
363 7. Common Data Structures
365 Some data structures that are common to several LDAP API functions are
368 typedef struct ldap LDAP;
370 typedef struct ldapmsg LDAPMessage;
372 typedef struct berelement BerElement;
374 typedef ber_len_t; /* actual definition is implementation-specific */
376 typedef ber_tag_t; /* actual definition is implementation-specific */
388 The LDAP structure is an opaque data type that represents an LDAP ses-
389 sion Typically this corresponds to a connection to a single server, but
390 it may encompass several server connections in the face of LDAPv3
394 Expires: 2 December 1999 [Page 7]
397 C LDAP API C LDAP Application Program Interface 2 June 1999
402 The LDAPMessage structure is an opaque data type that is used to return
403 entry, reference, result, and error information. An LDAPMessage struc-
404 ture may represent the beginning of a list, or chain of messages that
405 consists of a series of entries, references, and result messages as
406 returned by LDAP operations such as search. LDAP API functions such as
407 ldap_parse_result() that operate on message chains that may contain more
408 than one result message always operate on the first result message in
409 the chain. See the "Obtaining Results and Peeking Inside LDAP Messages"
410 section of this document for more information.
412 The BerElement structure is an opaque data type that is used to hold
413 data and state information about encoded data. It is described in more
414 detail in the section "Encoded ASN.1 Value Manipulation" later in this
417 The ber_len_t type is an unsigned integral data type that is large
418 enough to contain the length of the largest piece of data supported by
419 the API implementation. Similarly, the ber_tag_t type is an unsigned
420 integral data type that is large enough to hold the largest BER tag sup-
421 ported by the API implementation. Both of these types should be at
422 least 32 bits in size. See the appendix "Data Types and Legacy Imple-
423 mentations" for additional considerations.
425 The berval structure is used to represent arbitrary binary data and its
426 fields have the following meanings:
428 bv_len Length of data in bytes.
430 bv_val A pointer to the data itself.
433 The timeval structure is used to represent an interval of time and its
434 fields have the following meanings:
436 tv_sec Seconds component of time interval.
438 tv_usec Microseconds component of time interval.
440 See the earlier section "Header File Requirements" for more information
444 8. Retrieving Information About the API Implementation
446 Applications developed to this specification need to be able to deter-
447 mine information about the particular API implementation they are using
451 Expires: 2 December 1999 [Page 8]
454 C LDAP API C LDAP Application Program Interface 2 June 1999
457 both at compile time and during execution.
460 8.1. Retrieving Information at Compile Time
462 All conformant implementations MUST include the following five defini-
463 tions in a header file so compile time tests can be done by LDAP
466 #define LDAP_API_VERSION level
467 #define LDAP_VERSION_MIN min-version
468 #define LDAP_VERSION_MAX max-version
469 #define LDAP_VENDOR_NAME "vend-name"
470 #define LDAP_VENDOR_VERSION vend-version
474 "level" is replaced with the RFC number given to this C LDAP API
475 specification when it is published as a standards track RFC.
477 min-version is replaced with the lowest LDAP protocol version sup-
478 ported by the implementation.
480 max-version is replaced with the highest LDAP protocol version sup-
481 ported by the implementation. This should be 3.
483 "vend-name" is replaced with a text string that identifies the
484 party that supplies the API implementation.
486 "vend-version" is a supplier-specific version number multiplied
489 Note that the LDAP_VENDOR_NAME macro may be defined as "" if no vendor
490 name is available and the LDAP_VENDOR_VERSION macro may be defined as 0
491 if no vendor-specific version information is available.
493 For example, if this specification is published as RFC 88888, Netscape
494 Communication's version 4.0 implementation that supports LDAPv2 and v3
495 might include macro definitions like these:
497 #define LDAP_API_VERSION 88888 /* RFC 88888 compliant */
498 #define LDAP_VERSION_MIN 2
499 #define LDAP_VERSION_MAX 3
500 #define LDAP_VENDOR_NAME "Netscape Communications Corp."
501 #define LDAP_VENDOR_VERSION 400 /* version 4.0 */
503 and application code can test the C LDAP API version level using a
504 construct such as this one:
508 Expires: 2 December 1999 [Page 9]
511 C LDAP API C LDAP Application Program Interface 2 June 1999
514 #if (LDAP_API_VERSION >= 88888)
515 /* use features supported in RFC 88888 or later */
518 Until such time as this document is published as an RFC, implementations
519 should use the value 2000 plus the revision number of this draft for
520 LDAP_API_VERSION. For example, the correct value for LDAP_API_VERSION
521 for revision 03 of this draft is 2003.
523 Documents that extend this specification SHOULD define a macro of the
526 #define LDAP_API_FEATURE_x level
528 where "x" is replaced with a name (textual identifier) for the feature
529 and "level" is replaced with the number of the RFC that specifies the
530 API extension. The name SHOULD NOT begin with the string "X_".
532 For example, if C LDAP API extensions for Transport Layer Security [9]
533 were published in RFC 99999, that RFC might require conformant implemen-
534 tations to define a macro like this:
536 #define LDAP_API_FEATURE_TLS 99999
539 Private or experimental API extensions may be indicated by defining a
540 macro of this same form where "x" (the extension's name) begins with the
541 string "X_" and "level" is replaced with a integer number that is
542 specific to the extension.
545 8.2. Retrieving Information During Execution
547 The ldap_get_option() call (described in greater detail later in this
548 document) can be used during execution in conjunction with an option
549 parameter value of LDAP_OPT_API_INFO (0x00) to retrieve some basic
550 information about the API and about the specific implementation being
551 used. The ld parameter to ldap_get_option() can be either NULL or a
552 valid LDAP session handle which was obtained by calling ldap_init().
553 The optdata parameter to ldap_get_option() MUST be the address of an
554 LDAPAPIInfo structure which is defined as follows:
556 typedef struct ldapapiinfo {
557 int ldapai_info_version; /* version of this struct (1) */
558 int ldapai_api_version; /* revision of API supported */
559 int ldapai_protocol_version; /* highest LDAP version supported */
560 char **ldapai_extensions; /* names of API extensions */
561 char *ldapai_vendor_name; /* name of supplier */
565 Expires: 2 December 1999 [Page 10]
568 C LDAP API C LDAP Application Program Interface 2 June 1999
571 int ldapai_vendor_version; /* supplier-specific version times 100 */
574 In addition, API implementations MUST include the following macro defin-
577 #define LDAP_API_INFO_VERSION 1
579 Note that the ldapai_info_version field of the LDAPAPIInfo structure
580 should be set to the value LDAP_API_INFO_VERSION (1) before calling
581 ldap_get_option() so that it can be checked for consistency. All other
582 fields are set by the ldap_get_option() function.
584 The members of the LDAPAPIInfo structure are:
587 A number that identifies the version of the LDAPAPIInfo struc-
588 ture. This should be set to the value LDAP_API_INFO_VERSION
589 (1) before calling ldap_get_option(). If the value received
590 is not recognized by the API implementation, the
591 ldap_get_option() function sets ldapai_info_version to a valid
592 value that would be recognized, sets the ldapai_api_version to
593 the correct value, and returns an error without filling in any
594 of the other fields in the LDAPAPIInfo structure.
597 A number that matches that assigned to the C LDAP API RFC sup-
598 ported by the API implementation. This should match the value
599 of the LDAP_API_VERSION macro defined earlier.
601 ldapai_protocol_version
602 The highest LDAP protocol version supported by the implementa-
603 tion. For example, if LDAPv3 is the highest version supported
604 then this field will be set to 3.
607 A NULL-terminated array of character strings that lists the
608 names of the API extensions supported by the LDAP API imple-
609 mentation. These names will typically match the textual iden-
610 tifiers that appear in the "x" portion of the
611 LDAP_API_FEATURE_x macros described above, although the pre-
612 cise value MUST be defined by documents that specify C LDAP
613 API extensions. If no API extensions are supported, this
614 field will be set to NULL. The caller is responsible for
615 disposing of the memory occupied by this array by passing it
616 to ldap_value_free() which is described later in this docu-
617 ment. To retrieve more information about a particular exten-
618 sion, the ldap_get_option() call can be used with an option
622 Expires: 2 December 1999 [Page 11]
625 C LDAP API C LDAP Application Program Interface 2 June 1999
628 parameter value of LDAP_OPT_API_FEATURE_INFO (0x15). The opt-
629 data parameter to the ldap_get_option() MUST be the address of
630 an LDAPAPIFeatureInfo structure which is defined as follows:
632 typedef struct ldap_apifeature_info {
633 int ldapaif_info_version; /* version of this struct (1) */
634 char *ldapaif_name; /* name of supported feature */
635 int ldapaif_version; /* revision of supported feature */
636 } LDAPAPIFeatureInfo;
638 In addition, API implementations MUST include the following
641 #define LDAP_FEATURE_INFO_VERSION 1
643 Note that the ldapaif_info_version field of the LDAPAPI-
644 FeatureInfo structure should be set to the value
645 LDAP_FEATURE_INFO_VERSION (1) and the ldapaif_name field
646 should be set to the extension name string as described below
647 before ldap_get_option() is called. The call will fill in the
648 ldapaif_version field of the LDAPAPIFeatureInfo structure.
650 The members of the LDAPAPIFeatureInfo structure are:
653 A number that identifies the version of the LDAPAPI-
654 FeatureInfo structure. This should be set to the value
655 LDAP_FEATURE_INFO_VERSION (1) before calling
656 ldap_get_option(). If the value received is not recognized
657 by the API implementation, the ldap_get_option() function
658 sets ldapaif_info_version to a valid value that would be
659 recognized and returns an error without filling in the
660 ldapaif_version field in the LDAPAPIFeatureInfo structure.
663 The name of an extension, as returned in the
664 ldapai_extensions array of the LDAPAPIInfo structure and as
665 specified in the document that describes the extension.
668 This field will be set as a result of calling
669 ldap_get_option(). It is a number that matches that
670 assigned to the C LDAP API extension RFC supported for this
671 extension. For private or experimental API extensions, the
672 value is extension-specific. In either case, the value of
673 ldapaxi_ext_version should be identical to the value of the
674 LDAP_API_FEATURE_x macro defined for the extension
679 Expires: 2 December 1999 [Page 12]
682 C LDAP API C LDAP Application Program Interface 2 June 1999
687 Many of the LDAP API routines return LDAP error codes, some of which
688 indicate local errors and some of which may be returned by servers. All
689 of the LDAP error codes returned will be positive integers. Supported
690 error codes are (hexadecimal values are given in parentheses after the
694 LDAP_OPERATIONS_ERROR (0x01)
695 LDAP_PROTOCOL_ERROR (0x02)
696 LDAP_TIMELIMIT_EXCEEDED (0x03)
697 LDAP_SIZELIMIT_EXCEEDED (0x04)
698 LDAP_COMPARE_FALSE (0x05)
699 LDAP_COMPARE_TRUE (0x06)
700 LDAP_STRONG_AUTH_NOT_SUPPORTED (0x07)
701 LDAP_STRONG_AUTH_REQUIRED (0x08)
702 LDAP_REFERRAL (0x0a) -- new in LDAPv3
703 LDAP_ADMINLIMIT_EXCEEDED (0x0b) -- new in LDAPv3
704 LDAP_UNAVAILABLE_CRITICAL_EXTENSION (0x0c) -- new in LDAPv3
705 LDAP_CONFIDENTIALITY_REQUIRED (0x0d) -- new in LDAPv3
706 LDAP_SASL_BIND_IN_PROGRESS (0x0e) -- new in LDAPv3
707 LDAP_NO_SUCH_ATTRIBUTE (0x10)
708 LDAP_UNDEFINED_TYPE (0x11)
709 LDAP_INAPPROPRIATE_MATCHING (0x12)
710 LDAP_CONSTRAINT_VIOLATION (0x13)
711 LDAP_TYPE_OR_VALUE_EXISTS (0x14)
712 LDAP_INVALID_SYNTAX (0x15)
713 LDAP_NO_SUCH_OBJECT (0x20)
714 LDAP_ALIAS_PROBLEM (0x21)
715 LDAP_INVALID_DN_SYNTAX (0x22)
716 LDAP_IS_LEAF (0x23) -- not used in LDAPv3
717 LDAP_ALIAS_DEREF_PROBLEM (0x24)
718 LDAP_INAPPROPRIATE_AUTH (0x30)
719 LDAP_INVALID_CREDENTIALS (0x31)
720 LDAP_INSUFFICIENT_ACCESS (0x32)
722 LDAP_UNAVAILABLE (0x34)
723 LDAP_UNWILLING_TO_PERFORM (0x35)
724 LDAP_LOOP_DETECT (0x36)
725 LDAP_NAMING_VIOLATION (0x40)
726 LDAP_OBJECT_CLASS_VIOLATION (0x41)
727 LDAP_NOT_ALLOWED_ON_NONLEAF (0x42)
728 LDAP_NOT_ALLOWED_ON_RDN (0x43)
729 LDAP_ALREADY_EXISTS (0x44)
730 LDAP_NO_OBJECT_CLASS_MODS (0x45)
731 LDAP_RESULTS_TOO_LARGE (0x46) -- reserved for CLDAP
732 LDAP_AFFECTS_MULTIPLE_DSAS (0x47) -- new in LDAPv3
736 Expires: 2 December 1999 [Page 13]
739 C LDAP API C LDAP Application Program Interface 2 June 1999
743 LDAP_SERVER_DOWN (0x51)
744 LDAP_LOCAL_ERROR (0x52)
745 LDAP_ENCODING_ERROR (0x53)
746 LDAP_DECODING_ERROR (0x54)
748 LDAP_AUTH_UNKNOWN (0x56)
749 LDAP_FILTER_ERROR (0x57)
750 LDAP_USER_CANCELLED (0x58)
751 LDAP_PARAM_ERROR (0x59)
752 LDAP_NO_MEMORY (0x5a)
753 LDAP_CONNECT_ERROR (0x5b)
754 LDAP_NOT_SUPPORTED (0x5c)
755 LDAP_CONTROL_NOT_FOUND (0x5d)
756 LDAP_NO_RESULTS_RETURNED (0x5e)
757 LDAP_MORE_RESULTS_TO_RETURN (0x5f)
758 LDAP_CLIENT_LOOP (0x60)
759 LDAP_REFERRAL_LIMIT_EXCEEDED (0x61)
762 10. Performing LDAP Operations
764 This section describes each LDAP operation API call in detail. All func-
765 tions take a "session handle," a pointer to an LDAP structure containing
766 per-connection information. Many routines return results in an LDAPMes-
767 sage structure. These structures and others are described as needed
771 10.1. Initializing an LDAP Session
773 ldap_init() initializes a session with an LDAP server. The server is not
774 actually contacted until an operation is performed that requires it,
775 allowing various options to be set after initialization.
778 const char *hostname,
782 Use of the following routine is deprecated:
785 const char *hostname,
788 Unlike ldap_init(), ldap_open() attempts to make a server connection
789 before returning to the caller.
793 Expires: 2 December 1999 [Page 14]
796 C LDAP API C LDAP Application Program Interface 2 June 1999
801 hostname Contains a space-separated list of hostnames or dotted strings
802 representing the IP address of hosts running an LDAP server to
803 connect to. Each hostname in the list can include an optional
804 port number which is separated from the host itself with a
805 colon (:) character. The hosts will be tried in the order
806 listed, stopping with the first one to which a successful con-
809 Note: A suitable representation for including a literal IPv6[11]
810 address in the hostname parameter is desired, but has not yet been
811 determined or implemented in practice.
813 portno Contains the TCP port number to connect to. The default LDAP
814 port of 389 can be obtained by supplying the constant
815 LDAP_PORT. If a host includes a port number then this parame-
818 ldap_init() and ldap_open() both return a "session handle," a pointer to
819 an opaque structure that should be passed to subsequent calls pertaining
820 to the session. These routines return NULL if the session cannot be ini-
821 tialized in which case the operating system error reporting mechanism
822 can be checked to see why the call failed.
824 Note that if you connect to an LDAPv2 server, one of the LDAP bind calls
825 described below must be completed before other operations can be per-
826 formed on the session. LDAPv3 does not require that a bind operation be
827 completed before other operations can be performed.
829 The calling program can set various attributes of the session by calling
830 the routines described in the next section.
833 10.2. LDAP Session Handle Options
835 The LDAP session handle returned by ldap_init() is a pointer to an
836 opaque data type representing an LDAP session. In RFC 1823 this data
837 type was a structure exposed to the caller, and various fields in the
838 structure could be set to control aspects of the session, such as size
839 and time limits on searches.
841 In the interest of insulating callers from inevitable changes to this
842 structure, these aspects of the session are now accessed through a pair
843 of accessor functions, described below.
845 ldap_get_option() is used to access the current value of various
846 session-wide parameters. ldap_set_option() is used to set the value of
850 Expires: 2 December 1999 [Page 15]
853 C LDAP API C LDAP Application Program Interface 2 June 1999
856 these parameters. Note that some options are READ-ONLY and cannot be
857 set; it is an error to call ldap_set_option() and attempt to set a
860 Note that if automatic referral following is enabled (the default), any
861 connections created during the course of following referrals will
862 inherit the options associated with the session that sent the original
863 request that caused the referrals to be returned.
877 #define LDAP_OPT_ON ((void *)1)
878 #define LDAP_OPT_OFF ((void *)0)
883 ld The session handle. If this is NULL, a set of global defaults is
884 accessed. New LDAP session handles created with ldap_init() or
885 ldap_open() inherit their characteristics from these global
888 option The name of the option being accessed or set. This parameter
889 should be one of the following constants, which have the indi-
890 cated meanings. After the constant the actual hexadecimal value
891 of the constant is listed in parentheses.
894 LDAP_OPT_API_INFO (0x00)
895 Type for invalue parameter: not applicable (option is READ-ONLY)
897 Type for outvalue parameter: LDAPAPIInfo *
900 Used to retrieve some basic information about the LDAP API
901 implementation at execution time. See the section "Retriev-
902 ing Information About the API Implementation" above for more
903 information. This option is READ-ONLY and cannot be set.
907 Expires: 2 December 1999 [Page 16]
910 C LDAP API C LDAP Application Program Interface 2 June 1999
914 Type for invalue parameter: not applicable (option is READ-
917 Type for outvalue parameter: int *
920 The underlying socket descriptor corresponding to the pri-
921 mary LDAP connection. This option is READ-ONLY and cannot
924 LDAP_OPT_DEREF (0x02)
925 Type for invalue parameter: int *
927 Type for outvalue parameter: int *
930 Determines how aliases are handled during search. It can
931 have one of the following values: LDAP_DEREF_NEVER (0x00),
932 LDAP_DEREF_SEARCHING (0x01), LDAP_DEREF_FINDING (0x02), or
933 LDAP_DEREF_ALWAYS (0x03). The LDAP_DEREF_SEARCHING value
934 means aliases should be dereferenced during the search but
935 not when locating the base object of the search. The
936 LDAP_DEREF_FINDING value means aliases should be derefer-
937 enced when locating the base object but not during the
940 LDAP_OPT_SIZELIMIT (0x03)
941 Type for invalue parameter: int *
943 Type for outvalue parameter: int *
946 A limit on the number of entries to return from a search.
947 A value of LDAP_NO_LIMIT (0) means no limit.
949 LDAP_OPT_TIMELIMIT (0x04)
950 Type for invalue parameter: int *
952 Type for outvalue parameter: int *
955 A limit on the number of seconds to spend on a search. A
956 value of LDAP_NO_LIMIT (0) means no limit. This value is
957 passed to the server in the search request only; it does
958 not affect how long the C LDAP API implementation itself
959 will wait locally for search results. The timeout parame-
960 ter passed to ldap_search_ext_s() or ldap_result() -- both
964 Expires: 2 December 1999 [Page 17]
967 C LDAP API C LDAP Application Program Interface 2 June 1999
970 of which are described later in this document -- can be
971 used to specify both a local and server side time limit.
973 LDAP_OPT_REFERRALS (0x08)
974 Type for invalue parameter: void * (LDAP_OPT_ON or
977 Type for outvalue parameter: int *
980 Determines whether the LDAP library automatically follows
981 referrals returned by LDAP servers or not. It can be set
982 to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF; any
983 non-NULL pointer value passed to ldap_set_option() enables
984 this option. When reading the current setting using
985 ldap_get_option(), a zero value means off and any non-zero
988 LDAP_OPT_RESTART (0x09)
989 Type for invalue parameter: void * (LDAP_OPT_ON or
992 Type for outvalue parameter: int *
995 Determines whether LDAP I/O operations should automati-
996 cally be restarted if they abort prematurely. It should be
997 set to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF;
998 any non-NULL pointer value passed to ldap_set_option()
999 enables this option. When reading the current setting
1000 using ldap_get_option(), a zero value means off and any
1001 non-zero value means on. This option is useful if an LDAP
1002 I/O operation may be interrupted prematurely, for example
1003 by a timer going off, or other interrupt.
1005 LDAP_OPT_PROTOCOL_VERSION (0x11)
1006 Type for invalue parameter: int *
1008 Type for outvalue parameter: int *
1011 This option indicates the version of the LDAP protocol
1012 used when communicating with the primary LDAP server. It
1013 must be one of the constants LDAP_VERSION2 (2) or
1014 LDAP_VERSION3 (3). If no version is set the default is
1017 LDAP_OPT_SERVER_CONTROLS (0x12)
1021 Expires: 2 December 1999 [Page 18]
1024 C LDAP API C LDAP Application Program Interface 2 June 1999
1027 Type for invalue parameter: LDAPControl **
1029 Type for outvalue parameter: LDAPControl ***
1032 A default list of LDAP server controls to be sent with
1033 each request. See the Working With Controls section
1036 LDAP_OPT_CLIENT_CONTROLS (0x13)
1037 Type for invalue parameter: LDAPControl **
1039 Type for outvalue parameter: LDAPControl ***
1042 A default list of client controls that affect the LDAP
1043 session. See the Working With Controls section below.
1045 LDAP_OPT_API_FEATURE_INFO (0x15)
1046 Type for invalue parameter: not applicable (option is READ-
1049 Type for outvalue parameter: LDAPAPIFeatureInfo *
1052 Used to retrieve version information about LDAP API
1053 extended features at execution time. See the section
1054 "Retrieving Information About the API Implementation"
1055 above for more information. This option is READ-ONLY and
1058 LDAP_OPT_HOST_NAME (0x30)
1059 Type for invalue parameter: char *
1061 Type for outvalue parameter: char **
1064 The host name (or list of hosts) for the primary LDAP
1065 server. See the definition of the hostname parameter to
1066 ldap_init() for the allowed syntax.
1068 LDAP_OPT_ERROR_NUMBER (0x31)
1069 Type for invalue parameter: int *
1071 Type for outvalue parameter: int *
1074 The code of the most recent LDAP error that occurred for
1078 Expires: 2 December 1999 [Page 19]
1081 C LDAP API C LDAP Application Program Interface 2 June 1999
1086 LDAP_OPT_ERROR_STRING (0x32)
1087 Type for invalue parameter: char *
1089 Type for outvalue parameter: char **
1092 The message returned with the most recent LDAP error that
1093 occurred for this session.
1096 outvalue The address of a place to put the value of the option. The
1097 actual type of this parameter depends on the setting of the
1098 option parameter. For outvalues of type char ** and LDAP-
1099 Control **, a copy of the data that is associated with the
1100 LDAP session ld is returned; callers should dispose of the
1101 memory by calling ldap_memfree() or ldap_controls_free().
1103 invalue A pointer to the value the option is to be given. The actual
1104 type of this parameter depends on the setting of the option
1105 parameter. The data associated with invalue is copied by the
1106 API implementation to allow callers of the API to dispose of
1107 or otherwise change their copy of the data after a success-
1108 ful call to ldap_set_option(). If a value passed for
1109 invalue is invalid or cannot be accepted by the implementa-
1110 tion, ldap_set_option() should return -1 to indicate an
1113 Both ldap_get_option() and ldap_set_option() return 0 if successful and
1114 -1 if an error occurs.
1116 Standards track documents that extend this specification and specify new
1117 options MUST use values for option macros that are between 0x1000 and
1118 0x3FFF inclusive. Private and experimental extensions MUST use values
1119 for the option macros that are between 0x4000 and 0x7FFF inclusive. All
1120 values below 0x1000 and above 0x7FFF that are not defined in this docu-
1121 ment are reserved and MUST NOT be used.
1124 10.3. Working With Controls
1126 LDAPv3 operations can be extended through the use of controls. Controls
1127 may be sent to a server or returned to the client with any LDAP message.
1128 These controls are referred to as server controls.
1130 The LDAP API also supports a client-side extension mechanism through the
1131 use of client controls. These controls affect the behavior of the LDAP
1135 Expires: 2 December 1999 [Page 20]
1138 C LDAP API C LDAP Application Program Interface 2 June 1999
1141 API only and are never sent to a server. A common data structure is
1142 used to represent both types of controls:
1144 typedef struct ldapcontrol {
1146 struct berval ldctl_value;
1147 char ldctl_iscritical;
1148 } LDAPControl, *PLDAPControl;
1150 The fields in the ldapcontrol structure have the following meanings:
1152 ldctl_oid The control type, represented as a string.
1154 ldctl_value The data associated with the control (if any). To
1155 specify a zero-length value, set ldctl_value.bv_len to
1156 zero and ldctl_value.bv_val to a zero-length string.
1157 To indicate that no data is associated with the con-
1158 trol, set ldctl_value.bv_val to NULL.
1160 ldctl_iscritical Indicates whether the control is critical of not. If
1161 this field is non-zero, the operation will only be car-
1162 ried out if the control is recognized by the server
1163 and/or client. Note that the LDAP unbind and abandon
1164 operations have no server response, so clients SHOULD
1165 NOT mark server controls critical when used with these
1168 Some LDAP API calls allocate an ldapcontrol structure or a NULL-
1169 terminated array of ldapcontrol structures. The following routines can
1170 be used to dispose of a single control or an array of controls:
1172 void ldap_control_free( LDAPControl *ctrl );
1173 void ldap_controls_free( LDAPControl **ctrls );
1175 A set of controls that affect the entire session can be set using the
1176 ldap_set_option() function (see above). A list of controls can also be
1177 passed directly to some LDAP API calls such as ldap_search_ext(), in
1178 which case any controls set for the session through the use of
1179 ldap_set_option() are ignored. Control lists are represented as a NULL-
1180 terminated array of pointers to ldapcontrol structures.
1182 Server controls are defined by LDAPv3 protocol extension documents; for
1183 example, a control has been proposed to support server-side sorting of
1186 One client control is defined in this document (described in the follow-
1187 ing section). Other client controls may be defined in future revisions
1188 of this document or in documents that extend this API.
1192 Expires: 2 December 1999 [Page 21]
1195 C LDAP API C LDAP Application Program Interface 2 June 1999
1198 10.3.1. A Client Control That Governs Referral Processing
1200 As described previously in the section "LDAP Session Handle Options,"
1201 applications can enable and disable automatic chasing of referrals on a
1202 session-wide basic by using the ldap_set_option() function with the
1203 LDAP_OPT_REFERRALS option. It is also useful to govern automatic refer-
1204 ral chasing on per-request basis. A client control with an OID of
1205 1.2.840.113556.1.4.616 exists to provide this functionality.
1207 /* OID for referrals client control */
1208 #define LDAP_CONTROL_REFERRALS "1.2.840.113556.1.4.616"
1210 /* Flags for referrals client control value */
1211 #define LDAP_CHASE_SUBORDINATE_REFERRALS 0x00000020
1212 #define LDAP_CHASE_EXTERNAL_REFERRALS 0x00000040
1214 To create a referrals client control, the ldctl_oid field of an LDAPCon-
1215 trol structure should be set to LDAP_CONTROL_REFERRALS
1216 ("1.2.840.113556.1.4.616") and the ldctl_value field should be set to a
1217 4-octet value that contains a set of flags. The ldctl_value.bv_len
1218 field should always be set to 4. The ldctl_value.bv_val field should
1219 point to a 4-octet integer flags value. This flags value can be set to
1220 zero to disable automatic chasing of referrals and LDAPv3 references
1221 altogether. Alternatively, the flags value can be set to the value
1222 LDAP_CHASE_SUBORDINATE_REFERRALS (0x00000020) to indicate that only
1223 LDAPv3 search continuation references should be automatically chased by
1224 the API implementation, to the value LDAP_CHASE_EXTERNAL_REFERRALS
1225 (0x00000040) to indicate that only LDAPv3 referrals should be automati-
1226 cally chased, or the logical OR of the two flag values (0x00000060) to
1227 indicate that both referrals and references should be automatically
1231 10.4. Authenticating to the directory
1233 The following functions are used to authenticate an LDAP client to an
1234 LDAP directory server.
1236 The ldap_sasl_bind() and ldap_sasl_bind_s() functions can be used to do
1237 general and extensible authentication over LDAP through the use of the
1238 Simple Authentication Security Layer [8]. The routines both take the dn
1239 to bind as, the method to use, as a dotted-string representation of an
1240 OID identifying the method, and a struct berval holding the credentials.
1241 The special constant value LDAP_SASL_SIMPLE (NULL) can be passed to
1242 request simple authentication, or the simplified routines
1243 ldap_simple_bind() or ldap_simple_bind_s() can be used.
1249 Expires: 2 December 1999 [Page 22]
1252 C LDAP API C LDAP Application Program Interface 2 June 1999
1257 const char *mechanism,
1258 const struct berval *cred,
1259 LDAPControl **serverctrls,
1260 LDAPControl **clientctrls,
1264 int ldap_sasl_bind_s(
1267 const char *mechanism,
1268 const struct berval *cred,
1269 LDAPControl **serverctrls,
1270 LDAPControl **clientctrls,
1271 struct berval **servercredp
1274 int ldap_simple_bind(
1280 int ldap_simple_bind_s(
1286 The use of the following routines is deprecated:
1288 int ldap_bind( LDAP *ld, const char *dn, const char *cred,
1291 int ldap_bind_s( LDAP *ld, const char *dn, const char *cred,
1294 int ldap_kerberos_bind( LDAP *ld, const char *dn );
1296 int ldap_kerberos_bind_s( LDAP *ld, const char *dn );
1300 ld The session handle.
1302 dn The name of the entry to bind as.
1306 Expires: 2 December 1999 [Page 23]
1309 C LDAP API C LDAP Application Program Interface 2 June 1999
1312 mechanism Either LDAP_SASL_SIMPLE (NULL) to get simple authentica-
1313 tion, or a text string identifying the SASL method.
1315 cred The credentials with which to authenticate. Arbitrary
1316 credentials can be passed using this parameter. The format
1317 and content of the credentials depends on the setting of
1318 the mechanism parameter.
1320 passwd For ldap_simple_bind(), the password to compare to the
1321 entry's userPassword attribute.
1323 serverctrls List of LDAP server controls.
1325 clientctrls List of client controls.
1327 msgidp This result parameter will be set to the message id of the
1328 request if the ldap_sasl_bind() call succeeds.
1330 servercredp This result parameter will be filled in with the creden-
1331 tials passed back by the server for mutual authentication,
1332 if given. An allocated berval structure is returned that
1333 should be disposed of by calling ber_bvfree(). NULL may be
1334 passed to ignore this field.
1336 Additional parameters for the deprecated routines are not described.
1337 Interested readers are referred to RFC 1823.
1339 The ldap_sasl_bind() function initiates an asynchronous bind operation
1340 and returns the constant LDAP_SUCCESS if the request was successfully
1341 sent, or another LDAP error code if not. See the section below on error
1342 handling for more information about possible errors and how to interpret
1343 them. If successful, ldap_sasl_bind() places the message id of the
1344 request in *msgidp. A subsequent call to ldap_result(), described below,
1345 can be used to obtain the result of the bind.
1347 The ldap_simple_bind() function initiates a simple asynchronous bind
1348 operation and returns the message id of the operation initiated. A sub-
1349 sequent call to ldap_result(), described below, can be used to obtain
1350 the result of the bind. In case of error, ldap_simple_bind() will return
1351 -1, setting the session error parameters in the LDAP structure appropri-
1354 The synchronous ldap_sasl_bind_s() and ldap_simple_bind_s() functions
1355 both return the result of the operation, either the constant
1356 LDAP_SUCCESS if the operation was successful, or another LDAP error code
1357 if it was not. See the section below on error handling for more informa-
1358 tion about possible errors and how to interpret them.
1363 Expires: 2 December 1999 [Page 24]
1366 C LDAP API C LDAP Application Program Interface 2 June 1999
1369 Note that if an LDAPv2 server is contacted, no other operations over the
1370 connection should be attempted before a bind call has successfully com-
1373 Subsequent bind calls can be used to re-authenticate over the same con-
1374 nection, and multistep SASL sequences can be accomplished through a
1375 sequence of calls to ldap_sasl_bind() or ldap_sasl_bind_s().
1378 10.5. Closing the session
1380 The following functions are used to unbind from the directory, close
1381 open connections, and dispose of the session handle.
1383 int ldap_unbind_ext( LDAP *ld, LDAPControl **serverctrls,
1384 LDAPControl **clientctrls );
1386 int ldap_unbind( LDAP *ld );
1388 int ldap_unbind_s( LDAP *ld );
1392 ld The session handle.
1394 serverctrls List of LDAP server controls.
1396 clientctrls List of client controls.
1398 The ldap_unbind_ext(), ldap_unbind() and ldap_unbind_s() all work syn-
1399 chronously in the sense that they send an unbind request to the server,
1400 close all open connections associated with the LDAP session handle, and
1401 dispose of all resources associated with the session handle before
1402 returning. Note, however, that there is no server response to an LDAP
1403 unbind operation. All three of the unbind functions return LDAP_SUCCESS
1404 (or another LDAP error code if the request cannot be sent to the LDAP
1405 server). After a call to one of the unbind functions, the session han-
1406 dle ld is invalid and it is illegal to make any further LDAP API calls
1409 The ldap_unbind() and ldap_unbind_s() functions behave identically. The
1410 ldap_unbind_ext() function allows server and client controls to be
1411 included explicitly, but note that since there is no server response to
1412 an unbind request there is no way to receive a response to a server con-
1413 trol sent with an unbind request.
1420 Expires: 2 December 1999 [Page 25]
1423 C LDAP API C LDAP Application Program Interface 2 June 1999
1428 The following functions are used to search the LDAP directory, returning
1429 a requested set of attributes for each entry matched. There are five
1432 int ldap_search_ext(
1439 LDAPControl **serverctrls,
1440 LDAPControl **clientctrls,
1441 struct timeval *timeout,
1446 int ldap_search_ext_s(
1453 LDAPControl **serverctrls,
1454 LDAPControl **clientctrls,
1455 struct timeval *timeout,
1477 Expires: 2 December 1999 [Page 26]
1480 C LDAP API C LDAP Application Program Interface 2 June 1999
1495 struct timeval *timeout,
1501 ld The session handle.
1503 base The dn of the entry at which to start the search.
1505 scope One of LDAP_SCOPE_BASE (0x00), LDAP_SCOPE_ONELEVEL (0x01),
1506 or LDAP_SCOPE_SUBTREE (0x02), indicating the scope of the
1509 filter A character string as described in [3], representing the
1510 search filter. The value NULL can be passed to indicate
1511 that the filter "(objectclass=*)" which matches all entries
1512 should be used. Note that if the caller of the API is
1513 using LDAPv2, only a subset of the filter functionality
1514 described in [3] can be successfully used.
1516 attrs A NULL-terminated array of strings indicating which attri-
1517 butes to return for each matching entry. Passing NULL for
1518 this parameter causes all available user attributes to be
1519 retrieved. The special constant string LDAP_NO_ATTRS
1520 ("1.1") can be used as the only string in the array to
1521 indicate that no attribute types should be returned by the
1522 server. The special constant string LDAP_ALL_USER_ATTRS
1523 ("*") can be used in the attrs array along with the names
1524 of some operational attributes to indicate that all user
1525 attributes plus the listed operational attributes should be
1528 attrsonly A boolean value that should be zero if both attribute types
1529 and values are to be returned, non-zero if only types are
1534 Expires: 2 December 1999 [Page 27]
1537 C LDAP API C LDAP Application Program Interface 2 June 1999
1540 timeout For the ldap_search_st() function, this specifies the local
1541 search timeout value (if it is NULL, the timeout is infin-
1542 ite). For the ldap_search_ext() and ldap_search_ext_s()
1543 functions, this specifies both the local search timeout
1544 value and the operation time limit that is sent to the
1545 server within the search request. For the
1546 ldap_search_ext() and ldap_search_ext_s() functions, pass-
1547 ing a NULL value for timeout causes the global default
1548 timeout stored in the LDAP session handle (set by using
1549 ldap_set_option() with the LDAP_OPT_TIMELIMIT parameter) to
1550 be sent to the server with the request but an infinite
1551 local search timeout to be used.
1553 sizelimit For the ldap_search_ext() and ldap_search_ext_s() calls,
1554 this is a limit on the number of entries to return from the
1555 search. A value of LDAP_NO_LIMIT (0) means no limit.
1557 res For the synchronous calls, this is a result parameter which
1558 will contain the results of the search upon completion of
1559 the call. If no results are returned, *res is set to NULL.
1561 serverctrls List of LDAP server controls.
1563 clientctrls List of client controls.
1565 msgidp This result parameter will be set to the message id of the
1566 request if the ldap_search_ext() call succeeds.
1568 There are three options in the session handle ld which potentially
1569 affect how the search is performed. They are:
1572 A limit on the number of entries to return from the search.
1573 A value of LDAP_NO_LIMIT (0) means no limit. Note that the
1574 value from the session handle is ignored when using the
1575 ldap_search_ext() or ldap_search_ext_s() functions.
1578 A limit on the number of seconds to spend on the search. A
1579 value of LDAP_NO_LIMIT (0) means no limit. Note that the
1580 value from the session handle is ignored when using the
1581 ldap_search_ext() or ldap_search_ext_s() functions.
1584 One of LDAP_DEREF_NEVER (0x00), LDAP_DEREF_SEARCHING
1585 (0x01), LDAP_DEREF_FINDING (0x02), or LDAP_DEREF_ALWAYS
1586 (0x03), specifying how aliases should be handled during the
1587 search. The LDAP_DEREF_SEARCHING value means aliases should
1591 Expires: 2 December 1999 [Page 28]
1594 C LDAP API C LDAP Application Program Interface 2 June 1999
1597 be dereferenced during the search but not when locating the
1598 base object of the search. The LDAP_DEREF_FINDING value
1599 means aliases should be dereferenced when locating the base
1600 object but not during the search.
1602 The ldap_search_ext() function initiates an asynchronous search opera-
1603 tion and returns the constant LDAP_SUCCESS if the request was success-
1604 fully sent, or another LDAP error code if not. See the section below on
1605 error handling for more information about possible errors and how to
1606 interpret them. If successful, ldap_search_ext() places the message id
1607 of the request in *msgidp. A subsequent call to ldap_result(), described
1608 below, can be used to obtain the results from the search. These results
1609 can be parsed using the result parsing routines described in detail
1612 Similar to ldap_search_ext(), the ldap_search() function initiates an
1613 asynchronous search operation and returns the message id of the opera-
1614 tion initiated. As for ldap_search_ext(), a subsequent call to
1615 ldap_result(), described below, can be used to obtain the result of the
1616 bind. In case of error, ldap_search() will return -1, setting the ses-
1617 sion error parameters in the LDAP structure appropriately.
1619 The synchronous ldap_search_ext_s(), ldap_search_s(), and
1620 ldap_search_st() functions all return the result of the operation,
1621 either the constant LDAP_SUCCESS if the operation was successful, or
1622 another LDAP error code if it was not. See the section below on error
1623 handling for more information about possible errors and how to interpret
1624 them. Entries returned from the search (if any) are contained in the
1625 res parameter. This parameter is opaque to the caller. Entries, attri-
1626 butes, values, etc., should be extracted by calling the parsing routines
1627 described below. The results contained in res should be freed when no
1628 longer in use by calling ldap_msgfree(), described later.
1630 The ldap_search_ext() and ldap_search_ext_s() functions support LDAPv3
1631 server controls, client controls, and allow varying size and time limits
1632 to be easily specified for each search operation. The ldap_search_st()
1633 function is identical to ldap_search_s() except that it takes an addi-
1634 tional parameter specifying a local timeout for the search. The local
1635 search timeout is used to limit the amount of time the API implementa-
1636 tion will wait for a search to complete. After the local search timeout
1637 expires, the API implementation will send an abandon operation to abort
1638 the search operation.
1640 10.7. Reading an Entry
1642 LDAP does not support a read operation directly. Instead, this operation
1643 is emulated by a search with base set to the DN of the entry to read,
1644 scope set to LDAP_SCOPE_BASE, and filter set to "(objectclass=*)" or
1648 Expires: 2 December 1999 [Page 29]
1651 C LDAP API C LDAP Application Program Interface 2 June 1999
1654 NULL. attrs contains the list of attributes to return.
1657 10.8. Listing the Children of an Entry
1659 LDAP does not support a list operation directly. Instead, this operation
1660 is emulated by a search with base set to the DN of the entry to list,
1661 scope set to LDAP_SCOPE_ONELEVEL, and filter set to "(objectclass=*)" or
1662 NULL. attrs contains the list of attributes to return for each child
1665 10.9. Comparing a Value Against an Entry
1667 The following routines are used to compare a given attribute value
1668 assertion against an LDAP entry. There are four variations:
1670 int ldap_compare_ext(
1674 struct berval *bvalue
1675 LDAPControl **serverctrls,
1676 LDAPControl **clientctrls,
1680 int ldap_compare_ext_s(
1684 struct berval *bvalue,
1685 LDAPControl **serverctrls,
1686 LDAPControl **clientctrls
1705 Expires: 2 December 1999 [Page 30]
1708 C LDAP API C LDAP Application Program Interface 2 June 1999
1713 ld The session handle.
1715 dn The name of the entry to compare against.
1717 attr The attribute to compare against.
1719 bvalue The attribute value to compare against those found in the
1720 given entry. This parameter is used in the extended rou-
1721 tines and is a pointer to a struct berval so it is possible
1722 to compare binary values.
1724 value A string attribute value to compare against, used by the
1725 ldap_compare() and ldap_compare_s() functions. Use
1726 ldap_compare_ext() or ldap_compare_ext_s() if you need to
1727 compare binary values.
1729 serverctrls List of LDAP server controls.
1731 clientctrls List of client controls.
1733 msgidp This result parameter will be set to the message id of the
1734 request if the ldap_compare_ext() call succeeds.
1736 The ldap_compare_ext() function initiates an asynchronous compare opera-
1737 tion and returns the constant LDAP_SUCCESS if the request was success-
1738 fully sent, or another LDAP error code if not. See the section below on
1739 error handling for more information about possible errors and how to
1740 interpret them. If successful, ldap_compare_ext() places the message id
1741 of the request in *msgidp. A subsequent call to ldap_result(), described
1742 below, can be used to obtain the result of the compare.
1744 Similar to ldap_compare_ext(), the ldap_compare() function initiates an
1745 asynchronous compare operation and returns the message id of the opera-
1746 tion initiated. As for ldap_compare_ext(), a subsequent call to
1747 ldap_result(), described below, can be used to obtain the result of the
1748 bind. In case of error, ldap_compare() will return -1, setting the ses-
1749 sion error parameters in the LDAP structure appropriately.
1751 The synchronous ldap_compare_ext_s() and ldap_compare_s() functions both
1752 return the result of the operation, either the constant LDAP_SUCCESS if
1753 the operation was successful, or another LDAP error code if it was not.
1754 See the section below on error handling for more information about pos-
1755 sible errors and how to interpret them.
1757 The ldap_compare_ext() and ldap_compare_ext_s() functions support LDAPv3
1758 server controls and client controls.
1762 Expires: 2 December 1999 [Page 31]
1765 C LDAP API C LDAP Application Program Interface 2 June 1999
1768 10.10. Modifying an entry
1770 The following routines are used to modify an existing LDAP entry. There
1771 are four variations:
1773 typedef struct ldapmod {
1777 char **modv_strvals;
1778 struct berval **modv_bvals;
1781 #define mod_values mod_vals.modv_strvals
1782 #define mod_bvalues mod_vals.modv_bvals
1784 int ldap_modify_ext(
1788 LDAPControl **serverctrls,
1789 LDAPControl **clientctrls,
1793 int ldap_modify_ext_s(
1797 LDAPControl **serverctrls,
1798 LDAPControl **clientctrls
1815 ld The session handle.
1819 Expires: 2 December 1999 [Page 32]
1822 C LDAP API C LDAP Application Program Interface 2 June 1999
1825 dn The name of the entry to modify.
1827 mods A NULL-terminated array of modifications to make to the
1830 serverctrls List of LDAP server controls.
1832 clientctrls List of client controls.
1834 msgidp This result parameter will be set to the message id of the
1835 request if the ldap_modify_ext() call succeeds.
1837 The fields in the LDAPMod structure have the following meanings:
1839 mod_op The modification operation to perform. It should be one of
1840 LDAP_MOD_ADD (0x00), LDAP_MOD_DELETE (0x01), or
1841 LDAP_MOD_REPLACE (0x02). This field also indicates the
1842 type of values included in the mod_vals union. It is logi-
1843 cally ORed with LDAP_MOD_BVALUES (0x80) to select the
1844 mod_bvalues form. Otherwise, the mod_values form is used.
1846 mod_type The type of the attribute to modify.
1848 mod_vals The values (if any) to add, delete, or replace. Only one of
1849 the mod_values or mod_bvalues variants should be used,
1850 selected by ORing the mod_op field with the constant
1851 LDAP_MOD_BVALUES. mod_values is a NULL-terminated array of
1852 zero-terminated strings and mod_bvalues is a NULL-
1853 terminated array of berval structures that can be used to
1854 pass binary values such as images.
1856 For LDAP_MOD_ADD modifications, the given values are added to the
1857 entry, creating the attribute if necessary.
1859 For LDAP_MOD_DELETE modifications, the given values are deleted from the
1860 entry, removing the attribute if no values remain. If the entire attri-
1861 bute is to be deleted, the mod_vals field should be set to NULL.
1863 For LDAP_MOD_REPLACE modifications, the attribute will have the listed
1864 values after the modification, having been created if necessary, or
1865 removed if the mod_vals field is NULL. All modifications are performed
1866 in the order in which they are listed.
1868 The ldap_modify_ext() function initiates an asynchronous modify opera-
1869 tion and returns the constant LDAP_SUCCESS if the request was success-
1870 fully sent, or another LDAP error code if not. See the section below on
1871 error handling for more information about possible errors and how to
1872 interpret them. If successful, ldap_modify_ext() places the message id
1876 Expires: 2 December 1999 [Page 33]
1879 C LDAP API C LDAP Application Program Interface 2 June 1999
1882 of the request in *msgidp. A subsequent call to ldap_result(), described
1883 below, can be used to obtain the result of the modify.
1885 Similar to ldap_modify_ext(), the ldap_modify() function initiates an
1886 asynchronous modify operation and returns the message id of the opera-
1887 tion initiated. As for ldap_modify_ext(), a subsequent call to
1888 ldap_result(), described below, can be used to obtain the result of the
1889 modify. In case of error, ldap_modify() will return -1, setting the ses-
1890 sion error parameters in the LDAP structure appropriately.
1892 The synchronous ldap_modify_ext_s() and ldap_modify_s() functions both
1893 return the result of the operation, either the constant LDAP_SUCCESS if
1894 the operation was successful, or another LDAP error code if it was not.
1895 See the section below on error handling for more information about pos-
1896 sible errors and how to interpret them.
1898 The ldap_modify_ext() and ldap_modify_ext_s() functions support LDAPv3
1899 server controls and client controls.
1902 10.11. Modifying the Name of an Entry
1904 In LDAPv2, the ldap_modrdn(), ldap_modrdn_s(), ldap_modrdn2(), and
1905 ldap_modrdn2_s() routines were used to change the name of an LDAP entry.
1906 They could only be used to change the least significant component of a
1907 name (the RDN or relative distinguished name). LDAPv3 provides the
1908 Modify DN protocol operation that allows more general name change
1909 access. The ldap_rename() and ldap_rename_s() routines are used to
1910 change the name of an entry, and the use of the ldap_modrdn(),
1911 ldap_modrdn_s(), ldap_modrdn2(), and ldap_modrdn2_s() routines is depre-
1918 const char *newparent,
1920 LDAPControl **serverctrls,
1921 LDAPControl **clientctrls,
1929 const char *newparent,
1933 Expires: 2 December 1999 [Page 34]
1936 C LDAP API C LDAP Application Program Interface 2 June 1999
1940 LDAPControl **serverctrls,
1941 LDAPControl **clientctrls
1944 Use of the following routines is deprecated.
1971 ld The session handle.
1973 dn The name of the entry whose DN is to be changed.
1975 newrdn The new RDN to give the entry.
1977 newparent The new parent, or superior entry. If this parameter is
1978 NULL, only the RDN of the entry is changed. The root DN
1979 may be specified by passing a zero length string, "". The
1980 newparent parameter should always be NULL when using ver-
1981 sion 2 of the LDAP protocol; otherwise the server's
1982 behavior is undefined.
1984 deleteoldrdn This parameter only has meaning on the rename routines if
1985 newrdn is different than the old RDN. It is a boolean
1986 value, if non-zero indicating that the old RDN value(s)
1990 Expires: 2 December 1999 [Page 35]
1993 C LDAP API C LDAP Application Program Interface 2 June 1999
1996 should be removed, if zero indicating that the old RDN
1997 value(s) should be retained as non-distinguished values of
2000 serverctrls List of LDAP server controls.
2002 clientctrls List of client controls.
2004 msgidp This result parameter will be set to the message id of the
2005 request if the ldap_rename() call succeeds.
2007 The ldap_rename() function initiates an asynchronous modify DN operation
2008 and returns the constant LDAP_SUCCESS if the request was successfully
2009 sent, or another LDAP error code if not. See the section below on error
2010 handling for more information about possible errors and how to interpret
2011 them. If successful, ldap_rename() places the DN message id of the
2012 request in *msgidp. A subsequent call to ldap_result(), described below,
2013 can be used to obtain the result of the rename.
2015 The synchronous ldap_rename_s() returns the result of the operation,
2016 either the constant LDAP_SUCCESS if the operation was successful, or
2017 another LDAP error code if it was not. See the section below on error
2018 handling for more information about possible errors and how to interpret
2021 The ldap_rename() and ldap_rename_s() functions both support LDAPv3
2022 server controls and client controls.
2025 10.12. Adding an entry
2027 The following functions are used to add entries to the LDAP directory.
2028 There are four variations:
2034 LDAPControl **serverctrls,
2035 LDAPControl **clientctrls,
2043 LDAPControl **serverctrls,
2047 Expires: 2 December 1999 [Page 36]
2050 C LDAP API C LDAP Application Program Interface 2 June 1999
2053 LDAPControl **clientctrls
2070 ld The session handle.
2072 dn The name of the entry to add.
2074 attrs The entry's attributes, specified using the LDAPMod struc-
2075 ture defined for ldap_modify(). The mod_type and mod_vals
2076 fields should be filled in. The mod_op field is ignored
2077 unless ORed with the constant LDAP_MOD_BVALUES, used to
2078 select the mod_bvalues case of the mod_vals union.
2080 serverctrls List of LDAP server controls.
2082 clientctrls List of client controls.
2084 msgidp This result parameter will be set to the message id of the
2085 request if the ldap_add_ext() call succeeds.
2087 Note that the parent of the entry being added must already exist or the
2088 parent must be empty (i.e., equal to the root DN) for an add to succeed.
2090 The ldap_add_ext() function initiates an asynchronous add operation and
2091 returns the constant LDAP_SUCCESS if the request was successfully sent,
2092 or another LDAP error code if not. See the section below on error han-
2093 dling for more information about possible errors and how to interpret
2094 them. If successful, ldap_add_ext() places the message id of the
2095 request in *msgidp. A subsequent call to ldap_result(), described below,
2096 can be used to obtain the result of the add.
2098 Similar to ldap_add_ext(), the ldap_add() function initiates an asyn-
2099 chronous add operation and returns the message id of the operation ini-
2100 tiated. As for ldap_add_ext(), a subsequent call to ldap_result(),
2104 Expires: 2 December 1999 [Page 37]
2107 C LDAP API C LDAP Application Program Interface 2 June 1999
2110 described below, can be used to obtain the result of the add. In case of
2111 error, ldap_add() will return -1, setting the session error parameters
2112 in the LDAP structure appropriately.
2114 The synchronous ldap_add_ext_s() and ldap_add_s() functions both return
2115 the result of the operation, either the constant LDAP_SUCCESS if the
2116 operation was successful, or another LDAP error code if it was not. See
2117 the section below on error handling for more information about possible
2118 errors and how to interpret them.
2120 The ldap_add_ext() and ldap_add_ext_s() functions support LDAPv3 server
2121 controls and client controls.
2125 10.13. Deleting an entry
2127 The following functions are used to delete a leaf entry from the LDAP
2128 directory. There are four variations:
2130 int ldap_delete_ext(
2133 LDAPControl **serverctrls,
2134 LDAPControl **clientctrls,
2138 int ldap_delete_ext_s(
2141 LDAPControl **serverctrls,
2142 LDAPControl **clientctrls
2157 ld The session handle.
2161 Expires: 2 December 1999 [Page 38]
2164 C LDAP API C LDAP Application Program Interface 2 June 1999
2167 dn The name of the entry to delete.
2169 serverctrls List of LDAP server controls.
2171 clientctrls List of client controls.
2173 msgidp This result parameter will be set to the message id of the
2174 request if the ldap_delete_ext() call succeeds.
2176 Note that the entry to delete must be a leaf entry (i.e., it must have
2177 no children). Deletion of entire subtrees in a single operation is not
2180 The ldap_delete_ext() function initiates an asynchronous delete opera-
2181 tion and returns the constant LDAP_SUCCESS if the request was success-
2182 fully sent, or another LDAP error code if not. See the section below on
2183 error handling for more information about possible errors and how to
2184 interpret them. If successful, ldap_delete_ext() places the message id
2185 of the request in *msgidp. A subsequent call to ldap_result(), described
2186 below, can be used to obtain the result of the delete.
2188 Similar to ldap_delete_ext(), the ldap_delete() function initiates an
2189 asynchronous delete operation and returns the message id of the opera-
2190 tion initiated. As for ldap_delete_ext(), a subsequent call to
2191 ldap_result(), described below, can be used to obtain the result of the
2192 delete. In case of error, ldap_delete() will return -1, setting the ses-
2193 sion error parameters in the LDAP structure appropriately.
2195 The synchronous ldap_delete_ext_s() and ldap_delete_s() functions both
2196 return the result of the operation, either the constant LDAP_SUCCESS if
2197 the operation was successful, or another LDAP error code if it was not.
2198 See the section below on error handling for more information about pos-
2199 sible errors and how to interpret them.
2201 The ldap_delete_ext() and ldap_delete_ext_s() functions support LDAPv3
2202 server controls and client controls.
2205 10.14. Extended Operations
2207 The ldap_extended_operation() and ldap_extended_operation_s() routines
2208 allow extended LDAP operations to be passed to the server, providing a
2209 general protocol extensibility mechanism.
2211 int ldap_extended_operation(
2213 const char *requestoid,
2214 struct berval *requestdata,
2218 Expires: 2 December 1999 [Page 39]
2221 C LDAP API C LDAP Application Program Interface 2 June 1999
2224 LDAPControl **serverctrls,
2225 LDAPControl **clientctrls,
2229 int ldap_extended_operation_s(
2231 const char *requestoid,
2232 struct berval *requestdata,
2233 LDAPControl **serverctrls,
2234 LDAPControl **clientctrls,
2236 struct berval **retdatap
2241 ld The session handle.
2243 requestoid The dotted-OID text string naming the request.
2245 requestdata The arbitrary data required by the operation (if NULL, no
2246 data is sent to the server).
2248 serverctrls List of LDAP server controls.
2250 clientctrls List of client controls.
2252 msgidp This result parameter will be set to the message id of the
2253 request if the ldap_extended_operation() call succeeds.
2255 retoidp Pointer to a character string that will be set to an allo-
2256 cated, dotted-OID text string returned by the server. This
2257 string should be disposed of using the ldap_memfree() func-
2258 tion. If no OID was returned, *retoidp is set to NULL.
2260 retdatap Pointer to a berval structure pointer that will be set an
2261 allocated copy of the data returned by the server. This
2262 struct berval should be disposed of using ber_bvfree(). If
2263 no data is returned, *retdatap is set to NULL.
2265 The ldap_extended_operation() function initiates an asynchronous
2266 extended operation and returns the constant LDAP_SUCCESS if the request
2267 was successfully sent, or another LDAP error code if not. See the sec-
2268 tion below on error handling for more information about possible errors
2269 and how to interpret them. If successful, ldap_extended_operation()
2270 places the message id of the request in *msgidp. A subsequent call to
2271 ldap_result(), described below, can be used to obtain the result of the
2275 Expires: 2 December 1999 [Page 40]
2278 C LDAP API C LDAP Application Program Interface 2 June 1999
2281 extended operation which can be passed to ldap_parse_extended_result()
2282 to obtain the OID and data contained in the response.
2284 The synchronous ldap_extended_operation_s() function returns the result
2285 of the operation, either the constant LDAP_SUCCESS if the operation was
2286 successful, or another LDAP error code if it was not. See the section
2287 below on error handling for more information about possible errors and
2288 how to interpret them. The retoid and retdata parameters are filled in
2289 with the OID and data from the response. If no OID or data was
2290 returned, these parameters are set to NULL.
2292 The ldap_extended_operation() and ldap_extended_operation_s() functions
2293 both support LDAPv3 server controls and client controls.
2296 11. Abandoning An Operation
2298 The following calls are used to abandon an operation in progress:
2300 int ldap_abandon_ext(
2303 LDAPControl **serverctrls,
2304 LDAPControl **clientctrls
2313 ld The session handle.
2315 msgid The message id of the request to be abandoned.
2317 serverctrls List of LDAP server controls.
2319 clientctrls List of client controls.
2321 ldap_abandon_ext() abandons the operation with message id msgid and
2322 returns the constant LDAP_SUCCESS if the abandon was successful or
2323 another LDAP error code if not. See the section below on error handling
2324 for more information about possible errors and how to interpret them.
2326 ldap_abandon() is identical to ldap_abandon_ext() except that it does
2327 not accept client or server controls and it returns zero if the abandon
2328 was successful, -1 otherwise.
2332 Expires: 2 December 1999 [Page 41]
2335 C LDAP API C LDAP Application Program Interface 2 June 1999
2338 After a successful call to ldap_abandon() or ldap_abandon_ext(), results
2339 with the given message id are never returned from a subsequent call to
2340 ldap_result(). There is no server response to LDAP abandon operations.
2343 12. Obtaining Results and Peeking Inside LDAP Messages
2345 ldap_result() is used to obtain the result of a previous asynchronously
2346 initiated operation. Note that depending on how it is called,
2347 ldap_result() may actually return a list or "chain" of result messages.
2348 The ldap_result() function only returns messages for a single request,
2349 so for all LDAP operations other than search only one result message is
2350 expected; that is, the only time the "result chain" may contain more
2351 than one message is if results from a search operation are returned.
2352 Once a chain of messages has been returned to the caller, it is no
2353 longer tied in any caller-visible way to the LDAP request that produced
2354 it. Therefore, a chain of messages returned by calling ldap_result() or
2355 by calling a synchronous search routine will never be affected by subse-
2356 quent LDAP API calls (except for ldap_msgfree() which is used to dispose
2357 of a chain of messages).
2359 ldap_msgfree() frees the result messages (possibly an entire chain of
2360 messages) obtained from a previous call to ldap_result() or from a call
2361 to a synchronous search routine.
2363 ldap_msgtype() returns the type of an LDAP message. ldap_msgid()
2364 returns the message ID of an LDAP message.
2370 struct timeval *timeout,
2374 int ldap_msgfree( LDAPMessage *res );
2376 int ldap_msgtype( LDAPMessage *res );
2378 int ldap_msgid( LDAPMessage *res );
2382 ld The session handle.
2384 msgid The message id of the operation whose results are to be
2385 returned, or the constant LDAP_RES_ANY (-1) if any result is
2389 Expires: 2 December 1999 [Page 42]
2392 C LDAP API C LDAP Application Program Interface 2 June 1999
2397 all Specifies how many messages will be retrieved in a single call
2398 to ldap_result(). This parameter only has meaning for search
2399 results. Pass the constant LDAP_MSG_ONE (0x00) to retrieve one
2400 message at a time. Pass LDAP_MSG_ALL (0x01) to request that
2401 all results of a search be received before returning all
2402 results in a single chain. Pass LDAP_MSG_RECEIVED (0x02) to
2403 indicate that all messages retrieved so far should be returned
2404 in the result chain.
2406 timeout A timeout specifying how long to wait for results to be
2407 returned. A NULL value causes ldap_result() to block until
2408 results are available. A timeout value of zero seconds speci-
2409 fies a polling behavior.
2411 res For ldap_result(), a result parameter that will contain the
2412 result(s) of the operation. If no results are returned, *res is
2413 set to NULL. For ldap_msgfree(), the result chain to be freed,
2414 obtained from a previous call to ldap_result(),
2415 ldap_search_s(), or ldap_search_st(). If res is NULL, nothing
2416 is done and ldap_msgfree() returns zero.
2418 Upon successful completion, ldap_result() returns the type of the first
2419 result returned in the res parameter. This will be one of the following
2422 LDAP_RES_BIND (0x61)
2423 LDAP_RES_SEARCH_ENTRY (0x64)
2424 LDAP_RES_SEARCH_REFERENCE (0x73) -- new in LDAPv3
2425 LDAP_RES_SEARCH_RESULT (0x65)
2426 LDAP_RES_MODIFY (0x67)
2428 LDAP_RES_DELETE (0x6B)
2429 LDAP_RES_MODDN (0x6D)
2430 LDAP_RES_COMPARE (0x6F)
2431 LDAP_RES_EXTENDED (0x78) -- new in LDAPv3
2433 ldap_result() returns 0 if the timeout expired and -1 if an error
2434 occurs, in which case the error parameters of the LDAP session handle
2435 will be set accordingly.
2437 ldap_msgfree() frees the result structure pointed to by res and returns
2438 the type of the message it freed. If res is NULL, nothing is done and
2439 the value zero is returned.
2441 ldap_msgtype() returns the type of the LDAP message it is passed as a
2442 parameter. The type will be one of the types listed above, or -1 on
2446 Expires: 2 December 1999 [Page 43]
2449 C LDAP API C LDAP Application Program Interface 2 June 1999
2454 ldap_msgid() returns the message ID associated with the LDAP message
2455 passed as a parameter.
2458 13. Handling Errors and Parsing Results
2460 The following calls are used to extract information from results and
2461 handle errors returned by other LDAP API routines. Note that
2462 ldap_parse_sasl_bind_result() and ldap_parse_extended_result() must typ-
2463 ically be used in addition to ldap_parse_result() to retrieve all the
2464 result information from SASL Bind and Extended Operations respectively.
2466 int ldap_parse_result(
2473 LDAPControl ***serverctrlsp,
2477 int ldap_parse_sasl_bind_result(
2480 struct berval **servercredp,
2484 int ldap_parse_extended_result(
2488 struct berval **retdatap,
2492 char *ldap_err2string( int err );
2494 The use of the following routines is deprecated.
2496 int ldap_result2error(
2503 Expires: 2 December 1999 [Page 44]
2506 C LDAP API C LDAP Application Program Interface 2 June 1999
2511 void ldap_perror( LDAP *ld, const char *msg );
2515 ld The session handle.
2517 res The result of an LDAP operation as returned by
2518 ldap_result() or one of the synchronous API operation
2521 errcodep This result parameter will be filled in with the LDAP error
2522 code field from the LDAPMessage message. This is the indi-
2523 cation from the server of the outcome of the operation.
2524 NULL may be passed to ignore this field.
2526 matcheddnp In the case of a return of LDAP_NO_SUCH_OBJECT, this result
2527 parameter will be filled in with a DN indicating how much
2528 of the name in the request was recognized. NULL may be
2529 passed to ignore this field. The matched DN string should
2530 be freed by calling ldap_memfree() which is described later
2533 errmsgp This result parameter will be filled in with the contents
2534 of the error message field from the LDAPMessage message.
2535 The error message string should be freed by calling
2536 ldap_memfree() which is described later in this document.
2537 NULL may be passed to ignore this field.
2539 referralsp This result parameter will be filled in with the contents
2540 of the referrals field from the LDAPMessage message, indi-
2541 cating zero or more alternate LDAP servers where the
2542 request should be retried. The referrals array should be
2543 freed by calling ldap_value_free() which is described later
2544 in this document. NULL may be passed to ignore this field.
2546 serverctrlsp This result parameter will be filled in with an allocated
2547 array of controls copied out of the LDAPMessage message.
2548 The control array should be freed by calling
2549 ldap_controls_free() which was described earlier.
2551 freeit A boolean that determines whether the res parameter is
2552 disposed of or not. Pass any non-zero value to have these
2553 routines free res after extracting the requested informa-
2554 tion. This is provided as a convenience; you can also use
2555 ldap_msgfree() to free the result later. If freeit is
2556 non-zero, the entire chain of messages represented by res
2560 Expires: 2 December 1999 [Page 45]
2563 C LDAP API C LDAP Application Program Interface 2 June 1999
2568 servercredp For SASL bind results, this result parameter will be filled
2569 in with the credentials passed back by the server for
2570 mutual authentication, if given. An allocated berval struc-
2571 ture is returned that should be disposed of by calling
2572 ber_bvfree(). NULL may be passed to ignore this field.
2574 retoidp For extended results, this result parameter will be filled
2575 in with the dotted-OID text representation of the name of
2576 the extended operation response. This string should be
2577 disposed of by calling ldap_memfree(). NULL may be passed
2578 to ignore this field.
2580 retdatap For extended results, this result parameter will be filled
2581 in with a pointer to a struct berval containing the data in
2582 the extended operation response. It should be disposed of
2583 by calling ber_bvfree(). NULL may be passed to ignore this
2586 err For ldap_err2string(), an LDAP error code, as returned by
2587 ldap_parse_result() or another LDAP API call.
2589 Additional parameters for the deprecated routines are not described.
2590 Interested readers are referred to RFC 1823.
2592 All three of the ldap_parse_*_result() routines skip over messages of
2593 type LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_REFERENCE when looking
2594 for a result message to parse. They return the constant LDAP_SUCCESS if
2595 the result was successfully parsed and another LDAP error code if not.
2596 Note that the LDAP error code that indicates the outcome of the opera-
2597 tion performed by the server is placed in the errcodep
2598 ldap_parse_result() parameter. If a chain of messages that contains
2599 more than one result message is passed to these routines they always
2600 operate on the first result in the chain.
2602 ldap_err2string() is used to convert a numeric LDAP error code, as
2603 returned by one of the three ldap_parse_*_result() routines, or one of
2604 the synchronous API operation calls, into an informative zero-terminated
2605 character string message describing the error. It returns a pointer to
2609 14. Stepping Through a List of Results
2611 The ldap_first_message() and ldap_next_message() routines are used to
2612 step through the list of messages in a result chain returned by
2613 ldap_result(). For search operations, the result chain may actually
2617 Expires: 2 December 1999 [Page 46]
2620 C LDAP API C LDAP Application Program Interface 2 June 1999
2623 include referral messages, entry messages, and result messages.
2624 ldap_count_messages() is used to count the number of messages returned.
2625 The ldap_msgtype() function, described above, can be used to distinguish
2626 between the different message types.
2628 LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *res );
2630 LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *msg );
2632 int ldap_count_messages( LDAP *ld, LDAPMessage *res );
2636 ld The session handle.
2638 res The result chain, as obtained by a call to one of the synchronous
2639 search routines or ldap_result().
2641 msg The message returned by a previous call to ldap_first_message()
2642 or ldap_next_message().
2644 ldap_first_message() and ldap_next_message() will return NULL when no
2645 more messages exist in the result set to be returned. NULL is also
2646 returned if an error occurs while stepping through the entries, in which
2647 case the error parameters in the session handle ld will be set to indi-
2650 ldap_count_messages() returns the number of messages contained in a
2651 chain of results. It can also be used to count the number of messages
2652 that remain in a chain if called with a message, entry, or reference
2653 returned by ldap_first_message(), ldap_next_message(),
2654 ldap_first_entry(), ldap_next_entry(), ldap_first_reference(),
2655 ldap_next_reference().
2658 15. Parsing Search Results
2660 The following calls are used to parse the entries and references
2661 returned by ldap_search() and friends. These results are returned in an
2662 opaque structure that should only be accessed by calling the routines
2663 described below. Routines are provided to step through the entries and
2664 references returned, step through the attributes of an entry, retrieve
2665 the name of an entry, and retrieve the values associated with a given
2666 attribute in an entry.
2674 Expires: 2 December 1999 [Page 47]
2677 C LDAP API C LDAP Application Program Interface 2 June 1999
2680 15.1. Stepping Through a List of Entries or References
2682 The ldap_first_entry() and ldap_next_entry() routines are used to step
2683 through and retrieve the list of entries from a search result chain.
2684 The ldap_first_reference() and ldap_next_reference() routines are used
2685 to step through and retrieve the list of continuation references from a
2686 search result chain. ldap_count_entries() is used to count the number
2687 of entries returned. ldap_count_references() is used to count the number
2688 of references returned.
2690 LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *res );
2692 LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry );
2694 LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *res );
2696 LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *ref );
2698 int ldap_count_entries( LDAP *ld, LDAPMessage *res );
2700 int ldap_count_references( LDAP *ld, LDAPMessage *res );
2704 ld The session handle.
2706 res The search result, as obtained by a call to one of the synchro-
2707 nous search routines or ldap_result().
2709 entry The entry returned by a previous call to ldap_first_entry() or
2712 ref The reference returned by a previous call to
2713 ldap_first_reference() or ldap_next_reference().
2715 ldap_first_entry(), ldap_next_entry(), ldap_first_reference() and
2716 ldap_next_reference() all return NULL when no more entries or references
2717 exist in the result set to be returned. NULL is also returned if an
2718 error occurs while stepping through the entries or references, in which
2719 case the error parameters in the session handle ld will be set to indi-
2722 ldap_count_entries() returns the number of entries contained in a chain
2723 of entries. It can also be used to count the number of entries that
2724 remain in a chain if called with a message, entry or reference returned
2725 by ldap_first_message(), ldap_next_message(), ldap_first_entry(),
2726 ldap_next_entry(), ldap_first_reference(), ldap_next_reference().
2731 Expires: 2 December 1999 [Page 48]
2734 C LDAP API C LDAP Application Program Interface 2 June 1999
2737 ldap_count_references() returns the number of references contained in a
2738 chain of search results. It can also be used to count the number of
2739 references that remain in a chain.
2742 15.2. Stepping Through the Attributes of an Entry
2744 The ldap_first_attribute() and ldap_next_attribute() calls are used to
2745 step through the list of attribute types returned with an entry.
2747 char *ldap_first_attribute(
2753 char *ldap_next_attribute(
2759 void ldap_memfree( char *mem );
2763 ld The session handle.
2765 entry The entry whose attributes are to be stepped through, as returned
2766 by ldap_first_entry() or ldap_next_entry().
2768 ptr In ldap_first_attribute(), the address of a pointer used inter-
2769 nally to keep track of the current position in the entry. In
2770 ldap_next_attribute(), the pointer returned by a previous call to
2771 ldap_first_attribute(). The BerElement type itself is an opaque
2772 structure that is described in more detail later in this document
2773 in the section "Encoded ASN.1 Value Manipulation".
2775 mem A pointer to memory allocated by the LDAP library, such as the
2776 attribute type names returned by ldap_first_attribute() and
2777 ldap_next_attribute, or the DN returned by ldap_get_dn(). If mem
2778 is NULL, nothing is done.
2780 ldap_first_attribute() and ldap_next_attribute() will return NULL when
2781 the end of the attributes is reached, or if there is an error, in which
2782 case the error parameters in the session handle ld will be set to indi-
2788 Expires: 2 December 1999 [Page 49]
2791 C LDAP API C LDAP Application Program Interface 2 June 1999
2794 Both routines return a pointer to an allocated buffer containing the
2795 current attribute name. This should be freed when no longer in use by
2796 calling ldap_memfree().
2798 ldap_first_attribute() will allocate and return in ptr a pointer to a
2799 BerElement used to keep track of the current position. This pointer
2800 should be passed in subsequent calls to ldap_next_attribute() to step
2801 through the entry's attributes. After a set of calls to
2802 ldap_first_attribute() and ldap_next_attribute(), if ptr is non-NULL, it
2803 should be freed by calling ber_free( ptr, 0 ). Note that it is very
2804 important to pass the second parameter as 0 (zero) in this call, since
2805 the buffer associated with the BerElement does not point to separately
2808 The attribute type names returned are suitable for passing in a call to
2809 ldap_get_values() and friends to retrieve the associated values.
2812 15.3. Retrieving the Values of an Attribute
2814 ldap_get_values() and ldap_get_values_len() are used to retrieve the
2815 values of a given attribute from an entry. ldap_count_values() and
2816 ldap_count_values_len() are used to count the returned values.
2817 ldap_value_free() and ldap_value_free_len() are used to free the values.
2819 char **ldap_get_values(
2825 struct berval **ldap_get_values_len(
2831 int ldap_count_values( char **vals );
2833 int ldap_count_values_len( struct berval **vals );
2835 void ldap_value_free( char **vals );
2837 void ldap_value_free_len( struct berval **vals );
2841 ld The session handle.
2845 Expires: 2 December 1999 [Page 50]
2848 C LDAP API C LDAP Application Program Interface 2 June 1999
2851 entry The entry from which to retrieve values, as returned by
2852 ldap_first_entry() or ldap_next_entry().
2854 attr The attribute whose values are to be retrieved, as returned by
2855 ldap_first_attribute() or ldap_next_attribute(), or a caller-
2856 supplied string (e.g., "mail").
2858 vals The values returned by a previous call to ldap_get_values() or
2859 ldap_get_values_len().
2861 Two forms of the various calls are provided. The first form is only
2862 suitable for use with non-binary character string data. The second _len
2863 form is used with any kind of data.
2865 ldap_get_values() and ldap_get_values_len() return NULL if no values are
2866 found for attr or if an error occurs.
2868 ldap_count_values() and ldap_count_values_len() return -1 if an error
2869 occurs such as the vals parameter being invalid.
2871 Note that the values returned are dynamically allocated and should be
2872 freed by calling either ldap_value_free() or ldap_value_free_len() when
2876 15.4. Retrieving the name of an entry
2878 ldap_get_dn() is used to retrieve the name of an entry.
2879 ldap_explode_dn() and ldap_explode_rdn() are used to break up a name
2880 into its component parts. ldap_dn2ufn() is used to convert the name into
2881 a more "user friendly" format.
2883 char *ldap_get_dn( LDAP *ld, LDAPMessage *entry );
2885 char **ldap_explode_dn( const char *dn, int notypes );
2887 char **ldap_explode_rdn( const char *rdn, int notypes );
2889 char *ldap_dn2ufn( const char *dn );
2893 ld The session handle.
2895 entry The entry whose name is to be retrieved, as returned by
2896 ldap_first_entry() or ldap_next_entry().
2898 dn The dn to explode, such as returned by ldap_get_dn().
2902 Expires: 2 December 1999 [Page 51]
2905 C LDAP API C LDAP Application Program Interface 2 June 1999
2908 rdn The rdn to explode, such as returned in the components of the
2909 array returned by ldap_explode_dn().
2911 notypes A boolean parameter, if non-zero indicating that the dn or rdn
2912 components should have their type information stripped off
2913 (i.e., "cn=Babs" would become "Babs").
2915 ldap_get_dn() will return NULL if there is some error parsing the dn,
2916 setting error parameters in the session handle ld to indicate the error.
2917 It returns a pointer to newly allocated space that the caller should
2918 free by calling ldap_memfree() when it is no longer in use. Note the
2919 format of the DNs returned is given by [4].
2921 ldap_explode_dn() returns a NULL-terminated char * array containing the
2922 RDN components of the DN supplied, with or without types as indicated by
2923 the notypes parameter. The components are returned in the order they
2924 appear in the dn. The array returned should be freed when it is no
2925 longer in use by calling ldap_value_free().
2927 ldap_explode_rdn() returns a NULL-terminated char * array containing the
2928 components of the RDN supplied, with or without types as indicated by
2929 the notypes parameter. The components are returned in the order they
2930 appear in the rdn. The array returned should be freed when it is no
2931 longer in use by calling ldap_value_free().
2933 ldap_dn2ufn() converts the DN into the user friendly format described in
2934 [5]. The UFN returned is newly allocated space that should be freed by a
2935 call to ldap_memfree() when no longer in use.
2938 15.5. Retrieving controls from an entry
2940 ldap_get_entry_controls() is used to extract LDAP controls from an
2944 int ldap_get_entry_controls(
2947 LDAPControl ***serverctrlsp
2952 ld The session handle.
2954 entry The entry to extract controls from, as returned by
2955 ldap_first_entry() or ldap_next_entry().
2959 Expires: 2 December 1999 [Page 52]
2962 C LDAP API C LDAP Application Program Interface 2 June 1999
2965 serverctrlsp This result parameter will be filled in with an allocated
2966 array of controls copied out of entry. The control array
2967 should be freed by calling ldap_controls_free(). If ser-
2968 verctrlsp is NULL, no controls are returned.
2970 ldap_get_entry_controls() returns an LDAP error code that indicates
2971 whether the reference could be successfully parsed (LDAP_SUCCESS if all
2976 15.6. Parsing References
2978 ldap_parse_reference() is used to extract referrals and controls from a
2979 SearchResultReference message.
2982 int ldap_parse_reference(
2986 LDAPControl ***serverctrlsp,
2992 ld The session handle.
2994 ref The reference to parse, as returned by ldap_result(),
2995 ldap_first_reference(), or ldap_next_reference().
2997 referralsp This result parameter will be filled in with an allocated
2998 array of character strings. The elements of the array are
2999 the referrals (typically LDAP URLs) contained in ref. The
3000 array should be freed when no longer in used by calling
3001 ldap_value_free(). If referralsp is NULL, the referral
3002 URLs are not returned.
3004 serverctrlsp This result parameter will be filled in with an allocated
3005 array of controls copied out of ref. The control array
3006 should be freed by calling ldap_controls_free(). If ser-
3007 verctrlsp is NULL, no controls are returned.
3009 freeit A boolean that determines whether the ref parameter is
3010 disposed of or not. Pass any non-zero value to have this
3011 routine free ref after extracting the requested informa-
3012 tion. This is provided as a convenience; you can also use
3016 Expires: 2 December 1999 [Page 53]
3019 C LDAP API C LDAP Application Program Interface 2 June 1999
3022 ldap_msgfree() to free the result later.
3024 ldap_parse_reference() returns an LDAP error code that indicates whether
3025 the reference could be successfully parsed (LDAP_SUCCESS if all goes
3029 16. Encoded ASN.1 Value Manipulation
3031 This section describes routines which may be used to encode and decode
3032 BER-encoded ASN.1 values, which are often used inside of control and
3035 With the exceptions of two new functions ber_flatten() and ber_init(),
3036 these functions are compatible with the University of Michigan LDAP 3.3
3037 implementation of BER.
3047 As defined earlier in the section "Common Data Structures", a struct
3048 berval contains an arbitrary sequence of bytes and an indication of its
3049 length. The bv_len element is an unsigned integer. The bv_val is not
3050 necessarily zero-terminated. Applications may allocate their own berval
3053 As defined earlier in the section "Common Data Structures", the BerEle-
3054 ment structure is an opaque structure:
3056 typedef struct berelement BerElement;
3058 It contains not only a copy of the encoded value, but also state infor-
3059 mation used in encoding or decoding. Applications cannot allocate their
3060 own BerElement structures. The internal state is neither thread-
3061 specific nor locked, so two threads should not manipulate the same
3062 BerElement value simultaneously.
3064 A single BerElement value cannot be used for both encoding and decoding.
3066 void ber_bvfree( struct berval *bv );
3068 ber_bvfree() frees a berval returned from this API. Both the bv->bv_val
3069 string and the berval itself are freed. Applications should not use
3073 Expires: 2 December 1999 [Page 54]
3076 C LDAP API C LDAP Application Program Interface 2 June 1999
3079 ber_bvfree() with bervals which the application has allocated.
3081 void ber_bvecfree( struct berval **bv );
3083 ber_bvecfree() frees an array of bervals returned from this API. Each
3084 of the bervals in the array are freed using ber_bvfree(), then the array
3087 struct berval *ber_bvdup( const struct berval *bv );
3089 ber_bvdup() returns a copy of a berval. The bv_val field in the
3090 returned berval points to a different area of memory than the bv_val
3091 field in the argument berval. The NULL pointer is returned on error
3092 (e.g. out of memory).
3094 void ber_free( BerElement *ber, int fbuf );
3096 ber_free() frees a BerElement which is returned from the API calls
3097 ber_alloc_t() or ber_init(). Each BerElement must be freed by the
3098 caller. The second argument fbuf should always be set to 1 to ensure
3099 that the internal buffer used by the BER functions is freed as well as
3100 the BerElement container itself.
3105 BerElement *ber_alloc_t( int options );
3107 ber_alloc_t() constructs and returns BerElement. The NULL pointer is
3108 returned on error. The options field contains a bitwise-or of options
3109 which are to be used when generating the encoding of this BerElement.
3110 One option is defined and must always be supplied:
3112 #define LBER_USE_DER 0x01
3114 When this option is present, lengths will always be encoded in the
3115 minimum number of octets. Note that this option does not cause values
3116 of sets to be rearranged in tag and byte order or default values to be
3117 removed, so these functions are not sufficient for generating DER output
3118 as defined in X.509 and X.680. If the caller takes responsibility for
3119 ordering values of sets correctly and removing default values, DER out-
3120 put as defined in X.509 and X.680 can be produced.
3122 Unrecognized option bits are ignored.
3124 The BerElement returned by ber_alloc_t() is initially empty. Calls to
3125 ber_printf() will append bytes to the end of the ber_alloc_t().
3130 Expires: 2 December 1999 [Page 55]
3133 C LDAP API C LDAP Application Program Interface 2 June 1999
3136 int ber_printf( BerElement *ber, const char *fmt, ... )
3138 The ber_printf() routine is used to encode a BER element in much the
3139 same way that sprintf() works. One important difference, though, is
3140 that state information is kept in the ber argument so that multiple
3141 calls can be made to ber_printf() to append to the end of the BER ele-
3142 ment. ber must be a pointer to a BerElement returned by ber_alloc_t().
3143 ber_printf() interprets and formats its arguments according to the for-
3144 mat string fmt. ber_printf() returns -1 if there is an error during
3145 encoding and a positive number if successful. As with sprintf(), each
3146 character in fmt refers to an argument to ber_printf().
3148 The format string can contain the following format characters:
3150 't' Tag. The next argument is a ber_tag_t specifying the tag to
3151 override the next element to be written to the ber. This works
3152 across calls. The integer tag value must contain the tag class,
3153 constructed bit, and tag value. For example, a tag of "[3]" for
3154 a constructed type is 0xA3. All implementations must support
3155 tags that fit in a single octet (i.e., where the tag value is
3156 less than 32) and they may support larger tags.
3158 'b' Boolean. The next argument is an int, containing either 0 for
3159 FALSE or 0xff for TRUE. A boolean element is output. If this
3160 format character is not preceded by the 't' format modifier, the
3161 tag 0x01 is used for the element.
3163 'i' Integer. The next argument is an int, containing the integer in
3164 the host's byte order. An integer element is output. If this
3165 format character is not preceded by the 't' format modifier, the
3166 tag 0x02 is used for the element.
3168 'X' Bitstring. The next two arguments are a char * pointer to the
3169 start of the bitstring, followed by an int containing the number
3170 of bits in the bitstring. A bitstring element is output, in
3171 primitive form. If this format character is not preceded by the
3172 't' format modifier, the tag 0x03 is used for the element.
3174 'n' Null. No argument is required. An ASN.1 NULL element is out-
3175 put. If this format character is not preceded by the 't' format
3176 modifier, the tag 0x05 is used for the element.
3178 'o' Octet string. The next two arguments are a char *, followed by
3179 an int with the length of the string. The string may contain
3180 null bytes and need not be zero-terminated. An octet string
3181 element is output, in primitive form. If this format character
3182 is not preceded by the 't' format modifier, the tag 0x04 is used
3187 Expires: 2 December 1999 [Page 56]
3190 C LDAP API C LDAP Application Program Interface 2 June 1999
3193 's' Octet string. The next argument is a char * pointing to a
3194 zero-terminated string. An octet string element in primitive
3195 form is output, which does not include the trailing '\0' (null)
3196 byte. If this format character is not preceded by the 't' format
3197 modifier, the tag 0x04 is used for the element.
3199 'v' Several octet strings. The next argument is a char **, an array
3200 of char * pointers to zero-terminated strings. The last element
3201 in the array must be a NULL pointer. The octet strings do not
3202 include the trailing '\0' (null) byte. Note that a construct
3203 like '{v}' is required to get an actual SEQUENCE OF octet
3204 strings. The 't' format modifier cannot be used with this for-
3207 'V' Several octet strings. A NULL-terminated array of berval *'s is
3208 supplied. Note that a construct like '{V}' is required to get an
3209 actual SEQUENCE OF octet strings. The 't' format modifier cannot
3210 be used with this format character.
3212 '{' Begin sequence. No argument is required. If this format char-
3213 acter is not preceded by the 't' format modifier, the tag 0x30
3216 '}' End sequence. No argument is required. The 't' format modifier
3217 cannot be used with this format character.
3219 '[' Begin set. No argument is required. If this format character
3220 is not preceded by the 't' format modifier, the tag 0x31 is
3223 ']' End set. No argument is required. The 't' format modifier can-
3224 not be used with this format character.
3226 Each use of a '{' format character must be matched by a '}' character,
3227 either later in the format string, or in the format string of a subse-
3228 quent call to ber_printf() for that BerElement. The same applies to the
3229 '[' and ']' format characters.
3231 Sequences and sets nest, and implementations of this API must maintain
3232 internal state to be able to properly calculate the lengths.
3234 int ber_flatten( const BerElement *ber, struct berval **bvPtr );
3236 The ber_flatten routine allocates a struct berval whose contents are a
3237 BER encoding taken from the ber argument. The bvPtr pointer points to
3238 the returned berval, which must be freed using ber_bvfree(). This rou-
3239 tine returns 0 on success and -1 on error.
3244 Expires: 2 December 1999 [Page 57]
3247 C LDAP API C LDAP Application Program Interface 2 June 1999
3250 The ber_flatten API call is not present in U-M LDAP 3.3.
3252 The use of ber_flatten on a BerElement in which all '{' and '}' format
3253 modifiers have not been properly matched is an error (i.e., -1 will be
3254 returned by ber_flatten() if this situation is exists).
3257 16.3. Encoding Example
3259 The following is an example of encoding the following ASN.1 data type:
3261 Example1Request ::= SEQUENCE {
3262 s OCTET STRING, -- must be printable
3264 val2 [0] INTEGER DEFAULT 0
3268 int encode_example1(const char *s,int val1,int val2,struct berval **bvPtr)
3273 ber = ber_alloc_t(LBER_USE_DER);
3275 if (ber == NULL) return -1;
3277 if (ber_printf(ber,"{si",s,val1) == -1) {
3282 if (ber_printf(ber,"ti",0x80,val2) == -1) {
3287 if (ber_printf(ber,"}") == -1) {
3291 rc = ber_flatten(ber,bvPtr);
3301 Expires: 2 December 1999 [Page 58]
3304 C LDAP API C LDAP Application Program Interface 2 June 1999
3309 The following two symbols are available to applications.
3311 #define LBER_ERROR (ber_tag_t)0xffffffff
3312 #define LBER_DEFAULT (ber_tag_t)0xffffffff
3314 BerElement *ber_init( const struct berval *bv );
3316 The ber_init function constructs a BerElement and returns a new BerEle-
3317 ment containing a copy of the data in the bv argument. ber_init returns
3318 the NULL pointer on error.
3320 ber_tag_t ber_scanf( BerElement *ber, const char *fmt, ... );
3322 The ber_scanf() routine is used to decode a BER element in much the same
3323 way that sscanf() works. One important difference, though, is that some
3324 state information is kept with the ber argument so that multiple calls
3325 can be made to ber_scanf() to sequentially read from the BER element.
3326 The ber argument must be a pointer to a BerElement returned by
3327 ber_init(). ber_scanf interprets the bytes according to the format
3328 string fmt, and stores the results in its additional arguments.
3329 ber_scanf() returns LBER_ERROR on error, and a different value on suc-
3332 The format string contains conversion specifications which are used to
3333 direct the interpretation of the BER element. The format string can
3334 contain the following characters:
3336 'a' Octet string. A char ** argument should be supplied. Memory is
3337 allocated, filled with the contents of the octet string, zero-
3338 terminated, and the pointer to the string is stored in the argu-
3339 ment. The returned value must be freed using ldap_memfree. The
3340 tag of the element must indicate the primitive form (constructed
3341 strings are not supported) but is otherwise ignored and dis-
3342 carded during the decoding. This format cannot be used with
3343 octet strings which could contain null bytes.
3345 'O' Octet string. A struct berval ** argument should be supplied,
3346 which upon return points to an allocated struct berval contain-
3347 ing the octet string and its length. ber_bvfree() must be
3348 called to free the allocated memory. The tag of the element
3349 must indicate the primitive form (constructed strings are not
3350 supported) but is otherwise ignored during the decoding.
3352 'b' Boolean. A pointer to an int should be supplied. The int value
3353 stored will be 0 for FALSE or nonzero for TRUE. The tag of the
3354 element must indicate the primitive form but is otherwise
3358 Expires: 2 December 1999 [Page 59]
3361 C LDAP API C LDAP Application Program Interface 2 June 1999
3364 ignored during the decoding.
3366 'i' Integer. A pointer to an int should be supplied. The int value
3367 stored will be in host byte order. The tag of the element must
3368 indicate the primitive form but is otherwise ignored during the
3369 decoding. ber_scanf() will return an error if the integer can-
3370 not be stored in an int.
3372 'B' Bitstring. A char ** argument should be supplied which will
3373 point to the allocated bits, followed by a ber_len_t * argument,
3374 which will point to the length (in bits) of the bitstring
3375 returned. ldap_memfree must be called to free the bitstring.
3376 The tag of the element must indicate the primitive form (con-
3377 structed bitstrings are not supported) but is otherwise ignored
3378 during the decoding.
3380 'n' Null. No argument is required. The element is verified to have
3381 a zero-length value and is skipped. The tag is ignored.
3383 'v' Several octet strings. A char *** argument should be supplied,
3384 which upon return points to an allocated NULL-terminated array
3385 of char *'s containing the octet strings. NULL is stored if the
3386 sequence is empty. ldap_memfree must be called to free each
3387 element of the array and the array itself. The tag of the
3388 sequence and of the octet strings are ignored.
3390 'V' Several octet strings (which could contain null bytes). A
3391 struct berval *** should be supplied, which upon return points
3392 to a allocated NULL-terminated array of struct berval *'s con-
3393 taining the octet strings and their lengths. NULL is stored if
3394 the sequence is empty. ber_bvecfree() can be called to free the
3395 allocated memory. The tag of the sequence and of the octet
3396 strings are ignored.
3398 'x' Skip element. The next element is skipped. No argument is
3401 '{' Begin sequence. No argument is required. The initial sequence
3402 tag and length are skipped.
3404 '}' End sequence. No argument is required.
3406 '[' Begin set. No argument is required. The initial set tag and
3409 ']' End set. No argument is required.
3411 ber_tag_t ber_peek_tag( const BerElement *ber,
3415 Expires: 2 December 1999 [Page 60]
3418 C LDAP API C LDAP Application Program Interface 2 June 1999
3421 ber_len_t *lenPtr );
3423 ber_peek_tag() returns the tag of the next element to be parsed in the
3424 BerElement argument. The length of this element is stored in the
3425 *lenPtr argument. LBER_DEFAULT is returned if there is no further data
3426 to be read. The ber argument is not modified.
3428 ber_tag_t ber_skip_tag( BerElement *ber, ber_len_t *lenPtr );
3430 ber_skip_tag() is similar to ber_peek_tag(), except that the state
3431 pointer in the BerElement argument is advanced past the first tag and
3432 length, and is pointed to the value part of the next element. This rou-
3433 tine should only be used with constructed types and situations when a
3434 BER encoding is used as the value of an OCTET STRING. The length of the
3435 value is stored in *lenPtr.
3437 ber_tag_t ber_first_element( BerElement *ber,
3438 ber_len_t *lenPtr, char **opaquePtr );
3440 ber_tag_t ber_next_element( BerElement *ber,
3441 ber_len_t *lenPtr, char *opaque );
3443 ber_first_element() and ber_next_element() are used to traverse a SET,
3444 SET OF, SEQUENCE or SEQUENCE OF data value. ber_first_element() calls
3445 ber_skip_tag(), stores internal information in *lenPtr and *opaquePtr,
3446 and calls ber_peek_tag() for the first element inside the constructed
3447 value. LBER_DEFAULT is returned if the constructed value is empty.
3448 ber_next_element() positions the state at the start of the next element
3449 in the constructed type. LBER_DEFAULT is returned if there are no
3452 The len and opaque values should not be used by applications other than
3453 as arguments to ber_next_element(), as shown in the example below.
3456 16.5. Decoding Example
3458 The following is an example of decoding an ASN.1 data type:
3460 Example2Request ::= SEQUENCE {
3461 dn OCTET STRING, -- must be printable
3462 scope ENUMERATED { b (0), s (1), w (2) },
3463 ali ENUMERATED { n (0), s (1), f (2), a (3) },
3467 attrs SEQUENCE OF OCTET STRING, -- must be printable
3468 [0] SEQUENCE OF SEQUENCE {
3472 Expires: 2 December 1999 [Page 61]
3475 C LDAP API C LDAP Application Program Interface 2 June 1999
3478 type OCTET STRING -- must be printable,
3479 crit BOOLEAN DEFAULT FALSE,
3483 #define TAG_CONTROL_LIST 0xA0L /* context specific cons 0 */
3485 int decode_example2(struct berval *bv)
3490 int scope, ali, size, time, tonly;
3491 char *dn = NULL, **attrs = NULL;
3496 fputs("ERROR ber_init failed\n", stderr);
3500 res = ber_scanf(ber,"{aiiiib{v}",&dn,&scope,&ali,
3501 &size,&time,&tonly,&attrs);
3503 if (res == LBER_ERROR) {
3504 fputs("ERROR ber_scanf failed\n", stderr);
3512 for (i = 0; attrs != NULL && attrs[i] != NULL; i++) {
3513 /* *** use attrs[i] */
3514 ldap_memfree(attrs[i]);
3516 ldap_memfree(attrs);
3518 if (ber_peek_tag(ber,&len) == TAG_CONTROL_LIST) {
3522 for (tag = ber_first_element(ber,&len,&opaque);
3523 tag != LBER_DEFAULT;
3524 tag = ber_next_element (ber,&len,opaque)) {
3529 Expires: 2 December 1999 [Page 62]
3532 C LDAP API C LDAP Application Program Interface 2 June 1999
3539 struct berval *value;
3541 if (ber_scanf(ber,"{a",&type) == LBER_ERROR) {
3542 fputs("ERROR cannot parse type\n", stderr);
3548 ttag = ber_peek_tag(ber,&tlen);
3549 if (ttag == 0x01) { /* boolean */
3550 if (ber_scanf(ber,"b",
3551 &crit) == LBER_ERROR) {
3552 fputs("ERROR cannot parse crit\n",
3557 } else if (ttag == 0x04) { /* octet string */
3560 fputs("ERROR extra field in controls\n",
3565 if (ber_scanf(ber,"O}",&value) == LBER_ERROR) {
3566 fputs("ERROR cannot parse value\n", stderr);
3586 Expires: 2 December 1999 [Page 63]
3589 C LDAP API C LDAP Application Program Interface 2 June 1999
3592 17. Security Considerations
3594 LDAPv2 supports security through protocol-level authentication using
3595 clear-text passwords. LDAPv3 adds support for SASL [8] (Simple Authen-
3596 tication Security Layer) methods. LDAPv3 also supports operation over a
3597 secure transport layer using Transport Layer Security TLS [9]. Readers
3598 are referred to the protocol documents for discussion of related secu-
3599 rity considerations.
3601 Implementations of this API should be cautious when handling authentica-
3602 tion credentials. In particular, keeping long-lived copies of creden-
3603 tials without the application's knowledge is discouraged.
3606 18. Acknowledgements
3608 Many members of the IETF ASID and LDAPEXT working groups as well as
3609 members of the Internet at large have provided useful comments and
3610 suggestions that have been incorporated into this document. Chris
3611 Weider deserves special mention for his contributions as co-author of
3612 earlier revisions of this document.
3614 The original material upon which this specification is based was sup-
3615 ported by the National Science Foundation under Grant No. NCR-9416667.
3620 Copyright (C) The Internet Society (1997-1999). All Rights Reserved.
3622 This document and translations of it may be copied and furnished to oth-
3623 ers, and derivative works that comment on or otherwise explain it or
3624 assist in its implementation may be prepared, copied, published and dis-
3625 tributed, in whole or in part, without restriction of any kind, provided
3626 that the above copyright notice and this paragraph are included on all
3627 such copies and derivative works. However, this document itself may not
3628 be modified in any way, such as by removing the copyright notice or
3629 references to the Internet Society or other Internet organizations,
3630 except as needed for the purpose of developing Internet standards in
3631 which case the procedures for copyrights defined in the Internet Stan-
3632 dards process must be followed, or as required to translate it into
3633 languages other than English.
3635 The limited permissions granted above are perpetual and will not be
3636 revoked by the Internet Society or its successors or assigns.
3638 This document and the information contained herein is provided on an "AS
3639 IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK
3643 Expires: 2 December 1999 [Page 64]
3646 C LDAP API C LDAP Application Program Interface 2 June 1999
3649 FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT
3650 LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT
3651 INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FIT-
3652 NESS FOR A PARTICULAR PURPOSE.
3657 [1] The Directory: Selected Attribute Syntaxes. CCITT, Recommendation
3660 [2] M. Wahl, A. Coulbeck, T. Howes, S. Kille, W. Yeong, C. Robbins,
3661 "Lightweight Directory Access Protocol (v3): Attribute Syntax
3662 Definitions", RFC 2252, December 1997.
3664 [3] T. Howes, "The String Representation of LDAP Search Filters," RFC
3665 2254, December 1997.
3667 [4] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol
3668 (v3): A UTF-8 String Representation of Distinguished Names", RFC
3669 2253, December 1997.
3671 [5] S. Kille, "Using the OSI Directory to Achieve User Friendly Nam-
3672 ing," RFC 1781, March 1995.
3674 [6] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
3675 (v3)", RFC 2251, December 1997.
3677 [7] A. Herron, T. Howes, M. Wahl, C. Weider, A. Anantha, "LDAP Control
3678 Extension for Server Side Sorting of Search Results", INTERNET-
3679 DRAFT <draft-ietf-ldapext-sorting-01.txt>, 7 August 1998.
3681 [8] J. Meyers, "Simple Authentication and Security Layer (SASL)", RFC
3684 [9] "Lightweight Directory Access Protocol (v3): Extension for Tran-
3685 sport Layer Security", INTERNET-DRAFT <draft-ietf-ldapext-ldapv3-
3686 tls-04.txt>, November 1998.
3688 [10] "UTF-8, a transformation format of Unicode and ISO 10646", RFC
3691 [11] "IP Version 6 Addressing Architecture,", RFC 1884, December 1995.
3693 [12] "Character Mnemonics and Character Sets," RFC 1345, June 1992.
3695 [13] "Programming Languages - C", ANSI/ISO Standard 9899, revised 1997.
3700 Expires: 2 December 1999 [Page 65]
3703 C LDAP API C LDAP Application Program Interface 2 June 1999
3706 21. Authors' Addresses
3708 Mark Smith (document editor)
3709 Netscape Communications Corp.
3710 501 E. Middlefield Rd., Mailstop MV068
3711 Mountain View, CA 94043
3717 Netscape Communications Corp.
3718 501 E. Middlefield Rd., Mailstop MV068
3719 Mountain View, CA 94043
3730 andyhe@microsoft.com
3733 Innosoft International, Inc.
3734 8911 Capital of Texas Hwy, Suite 4140
3738 Mark.Wahl@innosoft.com
3746 anoopa@microsoft.com
3749 22. Appendix A - Sample C LDAP API Code
3757 Expires: 2 December 1999 [Page 66]
3760 C LDAP API C LDAP Application Program Interface 2 June 1999
3766 LDAPMessage *res, *e;
3772 /* open an LDAP session */
3773 if ( (ld = ldap_init( "dotted.host.name", LDAP_PORT )) == NULL )
3776 /* authenticate as nobody */
3777 if (( rc = ldap_simple_bind_s( ld, NULL, NULL )) != LDAP_SUCCESS ) {
3778 fprintf( stderr, "ldap_simple_bind_s: %s\n",
3779 ldap_err2string( rc ));
3784 /* search for entries with cn of "Babs Jensen", return all attrs */
3785 if (( rc = ldap_search_s( ld, "o=University of Michigan, c=US",
3786 LDAP_SCOPE_SUBTREE, "(cn=Babs Jensen)", NULL, 0, &res ))
3788 fprintf( stderr, "ldap_search_s: %s\n",
3789 ldap_err2string( rc ));
3790 if ( res == NULL ) {
3796 /* step through each entry returned */
3797 for ( e = ldap_first_entry( ld, res ); e != NULL;
3798 e = ldap_next_entry( ld, e ) ) {
3799 /* print its name */
3800 dn = ldap_get_dn( ld, e );
3801 printf( "dn: %s\n", dn );
3804 /* print each attribute */
3805 for ( a = ldap_first_attribute( ld, e, &ptr ); a != NULL;
3806 a = ldap_next_attribute( ld, e, ptr ) ) {
3807 printf( "\tattribute: %s\n", a );
3809 /* print each value */
3810 vals = ldap_get_values( ld, e, a );
3814 Expires: 2 December 1999 [Page 67]
3817 C LDAP API C LDAP Application Program Interface 2 June 1999
3820 for ( i = 0; vals[i] != NULL; i++ ) {
3821 printf( "\t\tvalue: %s\n", vals[i] );
3823 ldap_value_free( vals );
3826 if ( ptr != NULL ) {
3830 /* free the search results */
3831 ldap_msgfree( res );
3833 /* close and free connection resources */
3840 23. Appendix B - Namespace Consumed By This Specification
3842 The following 2 prefixes are used in this specification to name func-
3847 The following 6 prefixes are used in this specification to name struc-
3848 tures, unions, and typedefs:
3856 The following 3 prefixes are used in this specification to name #defined
3863 24. Appendix C - Summary of Requirements for API Extensions
3865 As the LDAP protocol is extended, this C LDAP API will need to be
3866 extended as well. For example, an LDAPv3 control extension has already
3867 been defined for server-side sorting of search results [7]. This
3871 Expires: 2 December 1999 [Page 68]
3874 C LDAP API C LDAP Application Program Interface 2 June 1999
3877 appendix summarizes the requirements for extending this API.
3881 Extensions to this document should not, by default, alter the behavior
3882 of any of the APIs specified in this document. If an extension option-
3883 ally changes the behavior of any existing C LDAP API function calls, the
3884 behavior change must be well documented.
3888 Extensions to this API should follow the general style and naming con-
3889 ventions used in this document. For example, function names should
3890 start with "ldap_" or "ber_" and consist entirely of lowercase letters,
3891 digits, and underscore ('_') characters. More information can be found
3892 in the preceding appendix called "Namespace Consumed By This Specifica-
3895 24.3. Dependence on Externally Defined Types
3897 Extensions to this API should minimize dependencies on types and macros
3898 that are defined in system header files and generally use only intrinsic
3899 types that are part of the C language, types defined in this specifica-
3900 tion, or types defined in the extension document itself.
3902 24.4. Compile Time Information
3904 Extensions to this API should conform to the requirements contained in
3905 the "Retrieving Information at Compile Time" section of this document.
3906 That is, extensions should define a macro of the form:
3908 #define LDAP_API_FEATURE_x level
3910 so that applications can detect the presence or absence of the extension
3911 at compile time and also test the version or level of the extension pro-
3912 vided by an API implementation.
3914 24.5. Runtime Information
3916 Extensions to this API should conform to the requirements contained in
3917 the "Retrieving Information During Execution" section of this document.
3918 That is, each extension should be given a character string name and that
3919 name should appear in the ldapai_extensions array field of the LDAPAPI-
3920 Info structure following a successful call to ldap_get_option() with an
3921 option parameter value of LDAP_OPT_API_INFO. In addition, information
3922 about the extension should be available via a call to ldap_get_option()
3923 with an option parameter value of LDAP_OPT_API_FEATURE_INFO.
3928 Expires: 2 December 1999 [Page 69]
3931 C LDAP API C LDAP Application Program Interface 2 June 1999
3934 24.6. Values Used for Session Handle Options
3936 Extensions to this API that add new session options (for use with the
3937 ldap_get_option() and ldap_set_option() functions) should meet the
3938 requirements contained in the last paragraph of the "LDAP Session Handle
3939 Options" section of this document. Specifically, standards track docu-
3940 ments MUST use values for option macros that are between 0x1000 and
3941 0x3FFF inclusive and private and experimental extensions MUST use values
3942 for the option macros that are between 0x4000 and 0x7FFF inclusive.
3945 25. Appendix D - Known Incompatibilities with RFC 1823
3947 This appendix lists known incompatibilities between this API specifica-
3948 tion and the one contained in RFC 1823, beyond the additional API func-
3949 tions added in support of LDAPv3.
3952 25.1. Opaque LDAP Structure
3954 In RFC 1823, some fields in the LDAP structure were exposed to applica-
3955 tion programmers. To provide a cleaner interface and to make it easier
3956 for implementations to evolve over time without sacrificing binary com-
3957 patibility with older applications, the LDAP structure is now entirely
3958 opaque. The new ldap_set_option() and ldap_get_option() calls can be
3959 used to manipulate per-session and global options.
3962 25.2. Additional Error Codes
3964 The following new error code macros were introduced to support LDAPv3:
3966 LDAP_ADMINLIMIT_EXCEEDED
3967 LDAP_UNAVAILABLE_CRITICAL_EXTENSION
3968 LDAP_CONFIDENTIALITY_REQUIRED
3969 LDAP_SASL_BIND_IN_PROGRESS
3970 LDAP_AFFECTS_MULTIPLE_DSAS
3973 LDAP_CONTROL_NOT_FOUND
3974 LDAP_NO_RESULTS_RETURNED
3975 LDAP_MORE_RESULTS_TO_RETURN
3977 LDAP_REFERRAL_LIMIT_EXCEEDED
3985 Expires: 2 December 1999 [Page 70]
3988 C LDAP API C LDAP Application Program Interface 2 June 1999
3991 25.3. Freeing of String Data with ldap_memfree()
3993 All strings received from the API (e.g., those returned by the
3994 ldap_get_dn() or ldap_dn2ufn() functions) should be freed by calling
3995 ldap_memfree() not free(). RFC 1823 did not define an ldap_memfree()
3999 25.4. Changes to ldap_result()
4001 The meaning of the all parameter to ldap_result has changed slightly.
4002 Nonzero values from RFC 1823 correspond to LDAP_MSG_ALL (0x01). There
4003 is also a new possible value, LDAP_MSG_RECEIVED (0x02).
4005 The result type LDAP_RES_MODDN is now returned where RFC 1823 returned
4006 LDAP_RES_MODRDN. The actual value for these two macros is the same
4010 25.5. Changes to ldap_first_attribute() and ldap_next_attribute
4012 Each non-NULL return value should be freed by calling ldap_memfree()
4013 after use. In RFC 1823, these two functions returned a pointer to a
4014 per-session buffer, which was not very thread-friendly.
4016 After the last call to ldap_first_attribute() or ldap_next_attribute(),
4017 the value set in the ptr parameter should be freed by calling ber_free(
4018 ptr, 0 ). RFC 1823 did not mention that the ptr value should be freed.
4020 The type of the ptr parameter was changed from void * to BerElement *.
4023 25.6. Changes to ldap_modrdn() and ldap_modrdn_s() Functions
4025 In RFC 1823, the ldap_modrdn() and ldap_modrdn_s() functions include a
4026 parameter called deleteoldrdn. This does not match the great majority
4027 of implementations, so in this specification the deleteoldrdn parameter
4028 was removed from ldap_modrdn() and ldap_modrdn_s(). Two additional
4029 functions that support deleteoldrdn and are widely implemented as well
4030 were added to this specification: ldap_modrdn2() and ldap_modrdn2_s().
4033 25.7. Changes to the berval structure
4035 In RFC 1823, the bv_len element of the berval structure was defined as
4036 an unsigned long. In this specification, the type is implementation-
4037 specific, although it must be an unsigned integral type that is at least
4038 32 bits in size. See the appendix "Data Types and Legacy
4042 Expires: 2 December 1999 [Page 71]
4045 C LDAP API C LDAP Application Program Interface 2 June 1999
4048 Implementations" for additional considerations.
4051 25.8. API Specification Clarified
4053 RFC 1823 left many things unspecified, including behavior of various
4054 memory disposal functions when a NULL pointer is presented, requirements
4055 for header files, values of many macros, and so on. This specification
4056 is more complete and generally tighter than the one in RFC 1823.
4059 25.9. Deprecated Functions
4061 A number of functions that are in RFC 1823 are labeled as "deprecated"
4062 in this specification. In most cases, a replacement that provides
4063 equivalent functionality has been defined. The deprecated functions
4067 Use ldap_simple_bind() or ldap_sasl_bind() instead.
4070 Use ldap_simple_bind_s() or ldap_sasl_bind_s() instead.
4072 ldap_kerberos_bind() and ldap_kerberos_bind_s()
4073 No equivalent functions are provided.
4075 ldap_modrdn() and ldap_modrdn2()
4076 Use ldap_rename() instead.
4078 ldap_modrdn_s() and ldap_modrdn2_s()
4079 Use ldap_rename_s() instead.
4082 Use ldap_init() instead.
4085 Use ldap_err2string() instead.
4088 Use ldap_parse_result() instead.
4091 26. Appendix E - Data Types and Legacy Implementations
4093 The data types associated with the length of a ber value (ber_len_t) and
4094 the tag (ber_tag_t) have been defined in this specification as unsigned
4095 integral types of implementation-specific size. This was done so that
4099 Expires: 2 December 1999 [Page 72]
4102 C LDAP API C LDAP Application Program Interface 2 June 1999
4105 source and binary compatibility of the C LDAP API can be maintained
4106 across ILP32 environments (where int, long, and pointers are all 32 bits
4107 in size) and LP64 environments (where ints remain 32 bits but longs and
4108 pointers grow to 64 bits).
4110 In older implementations of the C LDAP API, such as those based on RFC
4111 1823, implementors may have chosen to use an unsigned long for these
4112 types. If a long data type was used, a port of an application to a 64-
4113 bit operating system using the LP64 data model would find the size of
4114 the BER length and tag types used by the C LDAP API to increase. Also,
4115 if the legacy implementation had chosen to implement the types as an
4116 unsigned int, adoption of a specification that mandated use of unsigned
4117 longs would cause a source incompatibility in an LP64 application. By
4118 using an implementation-specific data type, the C LDAP API implementa-
4119 tion is free to choose the correct data type and the ability to maintain
4120 source compatibility.
4122 For example, suppose a legacy implementation chose to define the return
4123 value of ber_skip_tag() as an unsigned long but wishes to have the
4124 library return a 32-bit quantity in both ILP32 and LP64 data models.
4125 The following typedefs for ber_tag_t will provide a fixed sized data
4126 structure while preserving existing ILP32 source -- all without generat-
4127 ing compiler warnings:
4129 typedef unsigned int ber_tag_t;
4131 typedef unsigned long ber_tag_t;
4133 The above assumes that the the preprocessor symbol _LP64 is defined if
4134 and only if the code is being compiled in an LP64 environment. Similar
4135 code can be used to define an appropriate ber_len_t type.
4138 27. Appendix F - Changes Made Since Last Document Revision
4140 The previous version of this document was draft-ietf-ldapext-ldap-c-
4141 api-02.txt, dated 23 February, 1999. This appendix lists all of the
4142 changes made to that document to produce this one.
4146 Types: added the ber_len_t and ber_tag_t implementation-specific
4147 unsigned integral data types to support source and binary compatibil-
4148 ity between ILP32 and LP64 environments. Changes were made to the
4149 "Common Data Structures" and "Encoded ASN.1 Value Manipulation" sec-
4150 tions of this document.
4156 Expires: 2 December 1999 [Page 73]
4159 C LDAP API C LDAP Application Program Interface 2 June 1999
4162 27.2. Editorial Changes
4164 General: Added Appendix E - Data Types and Legacy Implementations;
4165 moved list of recent document changes to Appendices F and G.
4167 "Retrieving Information During Execution" section: removed misplaced
4168 ldapai_vendor_name and ldapai_vendor_version from the LDAPAPI-
4169 FeatureInfo structure description.
4171 "Extended Operations" section: changed the names of the "requestoid"
4172 and "requestdata" parameters in the function prototypes to match the
4173 parameter descriptions. The old names were "exoid" and "exdata."
4175 Appendix D - "Appendix D - Known Incompatibilities with RFC 1823 ":
4176 Added note about changes to the berval structure.
4179 28. Appendix G - Changes Made Since draft-ietf-ldapext-ldap-c-api-
4182 The version of this document that preceded draft-ietf-ldapext-ldap-c-
4183 api-02.txt was draft-ietf-ldapext-ldap-c-api-01.txt, dated 7 August
4184 1998. This appendix lists all of the changes made to that document to
4185 produce draft-ietf-ldapext-ldap-c-api-02.txt.
4190 General: added the 'const' keyword to function prototypes where
4193 Added two new sections that specify additional features and require-
4194 ments for API implementors:
4195 "Header File Requirements"
4196 "A Client Control That Governs Referral Processing"
4199 LDAP_VERSION_MAX, LDAP_VENDOR_NAME, and LDAP_VENDOR_VERSION macros.
4200 Corrected LDAP_API_VERSION example code to use >= instead of >.
4201 Added note about what value to use for LDAP_API_VERSION prior to pub-
4202 lication of this draft as an RFC (2000 + draft revision number).
4204 "Retrieving Information During Execution" section: added
4205 LDAP_API_INFO_VERSION macro and clarified the text to explain the
4206 behavior when there is a mismatch between LDAPAPIInfo structure ver-
4207 sions. Added LDAP_OPT_API_FEATURE_INFO to allow applications to
4208 retrieve version information about API extended features.
4213 Expires: 2 December 1999 [Page 74]
4216 C LDAP API C LDAP Application Program Interface 2 June 1999
4219 "LDAP Session Handle Options" section: Added macro definitions for
4220 LDAP_OPT_ON and LDAP_OPT_OFF and changed the "invalue" type for
4221 Boolean options from "int" to "void *". For consistency, we now
4222 require that applications dispose of "char *" and "LDAPControl *"
4223 values that are returned. Added note about which option value ranges
4224 are to be used for various purposes.
4226 "Closing the session" section: added new function ldap_unbind_ext()
4227 to allow controls to be used with unbind operations.
4229 "Searching" section: added requirement that *res be set to NULL by
4230 synchronous calls that fail to return any results.
4232 "Modifying the Name of an Entry" section: added function prototypes
4233 for ldap_modrdn2() and ldap_modrdn2_s() and corrected the ones for
4234 ldap_modrdn() and ldap_modrdn_s() to match the most widely imple-
4237 "Obtaining Results and Peeking Inside LDAP Messages" section: added
4238 requirement that "*res" be set to NULL when ldap_result() fails to
4239 return any results. Added requirement that ldap_msgfree() accept a
4240 NULL "res" parameter.
4242 "Stepping Through the Attributes of an Entry" section: added
4243 requirement that ldap_memfree() accept a NULL "mem" parameter.
4245 "Encoded ASN.1 Value Manipulation - Encoding" section: added note
4246 that implementations may support tags with a value larger than 32
4247 (but this is not required).
4249 "Encoded ASN.1 Value Manipulation - Decoding" section: changed the
4250 LBER_ERROR and LBER_DEFAULT macros to end in "UL" instead of "L"
4251 since all the functions that return these two values return an
4252 "unsigned long" value.
4255 28.2. Editorial changes
4258 Removed section: "Appendix - Outstanding Issues."
4260 Added two new editorial sections:
4261 "Appendix - Summary of Requirements for API Extensions"
4262 "Appendix - Known Incompatibilities with RFC 1823".
4264 General: replaced all occurrences of "LDAP C API" with "C LDAP API"
4270 Expires: 2 December 1999 [Page 75]
4273 C LDAP API C LDAP Application Program Interface 2 June 1999
4276 "Status of Memo" section: added a statement that this document is in
4277 full conformance with all provisions of Section 10 of RFC2026. Also
4278 revised the text about the Internet Draft current and shadow direc-
4279 tories to match the latest I-D guidelines.
4281 Document authors: removed Chris Weider from the list of authors (at
4282 his own request) and added an explicit mention of him in the "Ack-
4283 nowledgements" section. Updated Mark Wahl's company affiliation in
4284 document preface. Added "(document editor)" after Mark Smith's name
4285 in the "Authors' Addresses" section.
4287 Copyright: updated the year to 1999.
4289 "Introduction" section: expanded the sentence that mentioned the sam-
4290 ple code appendix to mention all of the appendices.
4292 "Overview of LDAP API Use" section: numbered the four simple steps
4293 for using the API. Added mention of the referrals client control.
4294 Clarified the text on character sets. Replaced mention of
4295 ldap_bind() with ldap_sasl_bind() because the former is deprecated.
4296 Added note that this API is designed for use in environments where
4297 the 'int' type is at least 32 bits in size.
4299 "Common Data Structures" section: added definition of BerElement so
4300 it is defined before it is used. Added reference back to "Header
4301 File Requirements" for "struct timeval" related considerations.
4303 "Initializing an LDAP Session" section: moved note about ldap_open()
4304 attempting to make a server connection closer to the ldap_open()
4305 function prototype. Added note that using literal IPv6 addresses in
4306 the "hostname" parameter is not yet supported.
4308 "LDAP Session Handle Options" section: replaced one instance of
4309 "Formerly" with "In RFC 1823." Added note about inheritance of
4310 options when automatic referral following is enabled. Added
4311 LDAP_OPT_API_INFO and LDAP_OPT_API_FEATURE_INFO for completeness (not
4312 previously included in this section). Replaced erroneous references
4313 to the "Using Controls" section with references to the "Working With
4314 Controls" section. In the text describing the LDAP_OPT_HOST_NAME
4315 option, added a reference to the "hostname" parameter of ldap_init()
4316 for the syntax of the option value. Clarified that ldap_set_option()
4317 makes a copy of the "invalue" data.
4319 "Working With Controls" section: added a note to remind the reader
4320 that server controls that are marked critical should not be used with
4321 unbind and abandon operations since those two operations have no
4327 Expires: 2 December 1999 [Page 76]
4330 C LDAP API C LDAP Application Program Interface 2 June 1999
4333 "Closing the session" section: made it clear that all open connec-
4334 tions associated with a session handle are closed when any of the
4335 unbind API functions are called.
4337 "Searching" section: added note that only a subset of the filter
4338 functionality is available when communicating with an LDAPv2 server.
4339 Clarified text to explain when a local timeout is used and when it is
4342 "Abandoning An Operation" section: removed some redundant text from
4343 the paragraph that explains the differences between ldap_abandon()
4344 and ldap_abandon_ext().
4346 "Obtaining Results and Peeking Inside LDAP Messages" section: clari-
4347 fied that ldap_result() only returns messages for one request at a
4350 "Handling Errors and Parsing Results" section: replace a few
4351 occurrences of LDAPResult with LDAPMessage (there is no type called
4352 LDAPResult). Changed the names of the "resultoidp" and "resultdatap"
4353 parameters to "retoidp" and "retdatap" to avoid confusion with LDAP
4356 "Stepping Through a List of Entries or References" section: added "or
4357 References" to the section name to better reflect its contents.
4358 Added missing description of "ref" parameter. Added mention of
4359 ldap_first_reference() and ldap_next_reference() in sentence about
4360 function return values.
4362 "Stepping Through the Attributes of an Entry" section: added forward
4363 reference for BerElement type.
4365 "Parsing References" section: in the description of the "ref" parame-
4366 ter, changed the phrase "these routines" to the more accurate "this
4369 "Encoded ASN.1 Value Manipulation - General" section: changed text to
4370 make sense given that the definition of BerElement now appears first
4371 in the "Common Data Structures" section.
4373 "Encoded ASN.1 Value Manipulation - Encoding" section: Changed the
4374 style of function prototypes to better match the rest of the docu-
4375 ment. Corrected a typo in the ber_bvdup() description ("as the"
4376 replaced with "than the"). Changed "null" to "NULL" where appropri-
4377 ate to be consistent with use elsewhere in the document. Removed
4378 mention of sequences from the discussion of the LBER_USE_DER option.
4379 Fixed some truncated sentences (by adding some missing '\' characters
4380 to the nroff document source).
4384 Expires: 2 December 1999 [Page 77]
4387 C LDAP API C LDAP Application Program Interface 2 June 1999
4390 "Encoded ASN.1 Value Manipulation - Encoding Example" section: sim-
4391 plified the error handling in the example code through the use of a
4394 "Encoded ASN.1 Value Manipulation - Decoding" section: Changed the
4395 style of function prototypes to better match the rest of the docu-
4396 ment. Changed "null" to "NULL" and "null-terminated" to "zero-
4397 terminated" where appropriate to be consistent with use elsewhere in
4398 the document. Fixed a typo (the text now says "an allocated" instead
4399 of "a allocated."). Clarified the description of the 'n' format
4400 character for ber_scanf().
4402 "Encoded ASN.1 Value Manipulation - Decoding Example" section:
4403 changed code to not define a macro that begins with "LDAP" since that
4404 prefix is reserved for the API. Removed an extra 'i' from the format
4405 string used in the first call to ber_scanf(). Changed error report-
4406 ing code to send messages to stderr instead of stdout. Changed
4407 declaration of "res" local variable from "int" to "unsigned long" and
4408 corrected one test of the ber_scanf() return value to test against
4409 LBER_ERROR instead of -1. Fixed improperly rendered strings (by
4410 adding '\' characters to the nroff source for this document so that
4411 '\t' and '\n' are correctly rendered).
4413 "Acknowledgements" section: added the mention of Chris Weider.
4414 Rephrased the text that gives credit to the National Science Founda-
4415 tion (it now says "The original material upon which this specifica-
4416 tion is based was supported by ..." instead of "This original
4417 material upon which this revision is based was based upon work sup-
4420 In the "Bibliography" section: Added a reference to RFC 1345 and
4421 ANSI/ISO C. Updated the LDAPv3 TLS and Sorting references to point
4422 to the latest revisions of those documents.
4424 "Appendix - Sample C LDAP API Code": added #include <stdio.h> to the
4425 sample code. Changed the code to demonstrate good error handling by
4426 freeing all memory and calling ldap_unbind() before returning.
4427 Replaced calls to exit() with return statements. Fixed improperly
4428 rendered strings (by adding '\' characters to the nroff source for
4429 this document so that '\t' and '\n' are correctly rendered).
4441 Expires: 2 December 1999 [Page 78]