1 Network Working Group M. Smith, Editor
2 INTERNET-DRAFT Netscape Communications Corp.
3 Intended Category: Standards Track T. Howes
5 Expires: 8 April 2000 A. Herron
8 Innosoft International, Inc.
15 The C LDAP Application Program Interface
16 <draft-ietf-ldapext-ldap-c-api-04.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: 8 April 2000 [Page 1]
55 C LDAP API C LDAP Application Program Interface 8 October 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 key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
69 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
70 document are to be interpreted as described in RFC 2119[1].
72 The C LDAP API is designed to be powerful, yet simple to use. It defines
73 compatible synchronous and asynchronous interfaces to LDAP to suit a
74 wide variety of applications. This document gives a brief overview of
75 the LDAP model, then an overview of how the API is used by an applica-
76 tion program to obtain LDAP information. The API calls are described in
77 detail, followed by appendices that provide example code demonstrating
78 use of the API, the namespace consumed by the API, a summary of require-
79 ments for API extensions, known incompatibilities with RFC 1823, and a
80 list of changes made since the last revision of this document.
85 1. Status of this Memo............................................1
86 2. Introduction...................................................2
87 3. Table of Contents..............................................2
88 4. Overview of the LDAP Model.....................................4
89 5. Overview of LDAP API Use and General Requirements..............4
90 6. Header Requirements............................................6
91 7. Common Data Structures and Types...............................7
92 8. Memory Handling Overview.......................................9
93 9. Retrieving Information About the API Implementation............9
94 9.1. Retrieving Information at Compile Time......................9
95 9.2. Retrieving Information During Execution.....................11
96 10. LDAP Error Codes...............................................14
97 11. Performing LDAP Operations.....................................15
98 11.1. Initializing an LDAP Session................................15
99 11.2. LDAP Session Handle Options.................................16
100 11.3. Working With Controls.......................................22
101 11.3.1. A Client Control That Governs Referral Processing........23
102 11.4. Authenticating to the directory.............................24
103 11.5. Closing the session.........................................26
104 11.6. Searching...................................................27
105 11.7. Reading an Entry............................................31
109 Expires: 8 April 2000 [Page 2]
112 C LDAP API C LDAP Application Program Interface 8 October 1999
114 11.8. Listing the Children of an Entry............................31
115 11.9. Comparing a Value Against an Entry..........................31
116 11.10. Modifying an entry..........................................33
117 11.11. Modifying the Name of an Entry..............................36
118 11.12. Adding an entry.............................................38
119 11.13. Deleting an entry...........................................40
120 11.14. Extended Operations.........................................41
121 12. Abandoning An Operation........................................43
122 13. Obtaining Results and Peeking Inside LDAP Messages.............43
123 14. Handling Errors and Parsing Results............................45
124 15. Stepping Through a List of Results.............................48
125 16. Parsing Search Results.........................................49
126 16.1. Stepping Through a List of Entries or References............49
127 16.2. Stepping Through the Attributes of an Entry.................51
128 16.3. Retrieving the Values of an Attribute.......................52
129 16.4. Retrieving the name of an entry.............................53
130 16.5. Retrieving controls from an entry...........................54
131 16.6. Parsing References..........................................55
132 17. Encoded ASN.1 Value Manipulation...............................56
133 17.1. BER Data Structures and Types...............................56
134 17.2. Memory Disposal and Utility Functions.......................57
135 17.3. Encoding....................................................58
136 17.4. Encoding Example............................................61
137 17.5. Decoding....................................................62
138 17.6. Decoding Example............................................65
139 18. Security Considerations........................................67
140 19. Acknowledgements...............................................68
141 20. Copyright......................................................68
142 21. Bibliography...................................................68
143 22. Authors' Addresses.............................................69
144 23. Appendix A - Sample C LDAP API Code............................70
145 24. Appendix B - Namespace Consumed By This Specification..........72
146 25. Appendix C - Summary of Requirements for API Extensions........72
147 25.1. Compatibility...............................................72
148 25.2. Style.......................................................73
149 25.3. Dependence on Externally Defined Types......................73
150 25.4. Compile Time Information....................................73
151 25.5. Runtime Information.........................................73
152 25.6. Values Used for Session Handle Options......................73
153 26. Appendix D - Known Incompatibilities with RFC 1823.............74
154 26.1. Opaque LDAP Structure.......................................74
155 26.2. Additional Error Codes......................................74
156 26.3. Freeing of String Data with ldap_memfree()..................74
157 26.4. Changes to ldap_result()....................................75
158 26.5. Changes to ldap_first_attribute() and ldap_next_attribute...75
159 26.6. Changes to ldap_modrdn() and ldap_modrdn_s() Functions......75
160 26.7. Changes to the berval structure.............................75
161 26.8. API Specification Clarified.................................75
162 26.9. Deprecated Functions........................................76
166 Expires: 8 April 2000 [Page 3]
169 C LDAP API C LDAP Application Program Interface 8 October 1999
171 27. Appendix E - Data Types and Legacy Implementations.............76
172 28. Appendix F - Changes Made Since Last Document Revision.........77
173 28.1. API Changes.................................................77
174 28.2. Editorial Changes...........................................79
178 4. Overview of the LDAP Model
180 LDAP is the lightweight directory access protocol, described in [2] and
181 [3]. It can provide a lightweight frontend to the X.500 directory [4],
182 or a stand-alone service. In either mode, LDAP is based on a client-
183 server model in which a client makes a TCP connection to an LDAP server,
184 over which it sends requests and receives responses.
186 The LDAP information model is based on the entry, which contains infor-
187 mation about some object (e.g., a person). Entries are composed of
188 attributes, which have a type and one or more values. Each attribute has
189 a syntax that determines what kinds of values are allowed in the attri-
190 bute (e.g., ASCII characters, a jpeg photograph, etc.) and how those
191 values behave during directory operations (e.g., is case significant
194 Entries may be organized in a tree structure, usually based on politi-
195 cal, geographical, and organizational boundaries. Each entry is uniquely
196 named relative to its sibling entries by its relative distinguished name
197 (RDN) consisting of one or more distinguished attribute values from the
198 entry. At most one value from each attribute may be used in the RDN.
199 For example, the entry for the person Babs Jensen might be named with
200 the "Barbara Jensen" value from the commonName attribute.
202 A globally unique name for an entry, called a distinguished name or DN,
203 is constructed by concatenating the sequence of RDNs from the entry up
204 to the root of the tree. For example, if Babs worked for the University
205 of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen,
206 o=University of Michigan, c=US". The DN format used by LDAP is defined
209 Operations are provided to authenticate, search for and retrieve infor-
210 mation, modify information, and add and delete entries from the tree.
211 The next sections give an overview of how the API is used and detailed
212 descriptions of the LDAP API calls that implement all of these func-
216 5. Overview of LDAP API Use and General Requirements
218 An application generally uses the C LDAP API in four simple steps.
223 Expires: 8 April 2000 [Page 4]
226 C LDAP API C LDAP Application Program Interface 8 October 1999
229 1. Initialize an LDAP session with a primary LDAP server. The
230 ldap_init() function returns a handle to the session, allowing
231 multiple connections to be open at once.
233 2. Authenticate to the LDAP server. The ldap_sasl_bind() function
234 and friends support a variety of authentication methods.
236 3. Perform some LDAP operations and obtain some results.
237 ldap_search() and friends return results which can be parsed by
238 ldap_parse_result(), ldap_first_entry(), ldap_next_entry(), etc.
240 4. Close the session. The ldap_unbind() function closes the connec-
243 Operations can be performed either synchronously or asynchronously. The
244 names of the synchronous functions end in _s. For example, a synchronous
245 search can be completed by calling ldap_search_s(). An asynchronous
246 search can be initiated by calling ldap_search(). All synchronous rou-
247 tines return an indication of the outcome of the operation (e.g, the
248 constant LDAP_SUCCESS or some other error code). The asynchronous rou-
249 tines make available to the caller the message id of the operation ini-
250 tiated. This id can be used in subsequent calls to ldap_result() to
251 obtain the result(s) of the operation. An asynchronous operation can be
252 abandoned by calling ldap_abandon() or ldap_abandon_ext().
254 Results and errors are returned in an opaque structure called LDAPMes-
255 sage. Routines are provided to parse this structure, step through
256 entries and attributes returned, etc. Routines are also provided to
257 interpret errors. Later sections of this document describe these rou-
258 tines in more detail.
260 LDAP version 3 servers can return referrals and references to other
261 servers. By default, implementations of this API will attempt to follow
262 referrals automatically for the application. This behavior can be dis-
263 abled globally (using the ldap_set_option() call) or on a per-request
264 basis through the use of a client control.
266 All DN and string attribute values passed into or produced by this C
267 LDAP API are represented using the character set of the underlying LDAP
268 protocol version in use. When this API is used with LDAPv3, DN and
269 string values are represented as UTF-8[6] characters. When this API is
270 used with LDAPv2, the US-ASCII[7] or T.61[7] character set are used.
271 Future documents MAY specify additional APIs supporting other character
274 For compatibility with existing applications, implementations of this
275 API will by default use version 2 of the LDAP protocol. Applications
276 that intend to take advantage of LDAP version 3 features will need to
280 Expires: 8 April 2000 [Page 5]
283 C LDAP API C LDAP Application Program Interface 8 October 1999
286 use the ldap_set_option() call with a LDAP_OPT_PROTOCOL_VERSION to
289 Unless otherwise indicated, conformant implementations of this specifi-
290 cation MUST implement all of the C LDAP API functions as described in
291 this document, and they MUST use the function prototypes, macro defini-
292 tions, and types defined in this document.
294 Note that this API is designed for use in environments where the 'int'
295 type is at least 32 bits in size.
298 6. Header Requirements
300 To promote portability of applications, the following requirements are
301 imposed on the headers used by applications to access the services of
305 Applications only need to include a single header named ldap.h
306 to access all of the API services described in this document.
307 Therefore, the following C source program MUST compile without
318 The ldap.h header MAY include other implementation-specific
321 Implementations SHOULD also provide a header named lber.h to facilitate
322 development of applications desiring compatibility with older LDAP
323 implementations. The lber.h header MAY be empty. Old applications that
324 include lber.h in order to use BER facilities will need to include
329 All headers SHOULD be idempotent; that is, if they are included
330 more than once the effect is as if they had only been included
333 Must Be Included Before API Is Used
337 Expires: 8 April 2000 [Page 6]
340 C LDAP API C LDAP Application Program Interface 8 October 1999
343 An application MUST include the ldap.h header before referencing
344 any of the function or type definitions described in this API
348 Headers SHOULD be mutually independent with minimal dependence
349 on system or any other headers.
351 Use of the 'const' Keyword
352 This API specification is defined in terms of ISO C[8]. It
353 makes use of function prototypes and the 'const' keyword. The
354 use of 'const' in this specification is limited to simple, non-
355 array function parameters to avoid forcing applications to
356 declare parameters and variables that accept return values from
357 LDAP API functions as 'const.' Implementations specifically
358 designed to be used with non-ISO C translators SHOULD provide
359 function declarations without prototypes or function prototypes
360 without specification of 'const' arguments.
362 Definition of 'struct timeval'
363 This API specification uses the 'struct timeval' type. Imple-
364 mentations of this API MUST ensure that the struct timeval type
365 is by default defined as a consequence of including the ldap.h
366 header. Because struct timeval is usually defined in one or
367 more system headers, it is possible for header conflicts to
368 occur if ldap.h also defines it or arranges for it to be defined
369 by including another header. Therefore, applications MAY want
370 to arrange for struct timeval to be defined before they include
371 ldap.h. To support this, the ldap.h header MUST NOT itself
372 define struct timeval if the preprocessor symbol
373 LDAP_TYPE_TIMEVAL_DEFINED is defined before ldap.h is included.
376 7. Common Data Structures and Types
378 Data structures and types that are common to several LDAP API functions
381 typedef struct ldap LDAP;
383 typedef struct ldapmsg LDAPMessage;
385 typedef struct berelement BerElement;
387 typedef impl_len_t ber_len_t;
389 typedef struct berval {
394 Expires: 8 April 2000 [Page 7]
397 C LDAP API C LDAP Application Program Interface 8 October 1999
408 The LDAP structure is an opaque data type that represents an LDAP ses-
409 sion Typically this corresponds to a connection to a single server, but
410 it MAY encompass several server connections in the face of LDAPv3 refer-
413 The LDAPMessage structure is an opaque data type that is used to return
414 entry, reference, result, and error information. An LDAPMessage struc-
415 ture can represent the beginning of a list, or chain of messages that
416 consists of a series of entries, references, and result messages as
417 returned by LDAP operations such as search. LDAP API functions such as
418 ldap_parse_result() that operate on message chains that can contain more
419 than one result message always operate on the first result message in
420 the chain. See the "Obtaining Results and Peeking Inside LDAP Messages"
421 section of this document for more information.
423 The BerElement structure is an opaque data type that is used to hold
424 data and state information about encoded data. It is described in more
425 detail in the section "Encoded ASN.1 Value Manipulation" later in this
428 The `ber_len_t' type is an unsigned integral data type that is large
429 enough to contain the length of the largest piece of data supported by
430 the API implementation. The `impl_len_t' in the `ber_len_t' typedef
431 MUST be replaced with an appropriate type. The width (number of signi-
432 ficant bits) of `ber_len_t' MUST be at least 32 and no larger than that
433 of `unsigned long'. See the appendix "Data Types and Legacy Implementa-
434 tions" for additional considerations.
436 The BerValue structure is used to represent arbitrary binary data and
437 its fields have the following meanings:
439 bv_len Length of data in bytes.
441 bv_val A pointer to the data itself.
444 The timeval structure is used to represent an interval of time and its
445 fields have the following meanings:
447 tv_sec Seconds component of time interval.
451 Expires: 8 April 2000 [Page 8]
454 C LDAP API C LDAP Application Program Interface 8 October 1999
457 tv_usec Microseconds component of time interval.
459 Note that because the struct timeval definition typically is derived
460 from a system header, the types used for the tv_sec and tv_usec com-
461 ponents are implementation-specific integral types. Therefore,
462 `impl_sec_t' and `impl_usec_t' in the struct timeval definition MUST be
463 replaced with appropriate types. See the earlier section "Header
464 Requirements" for more information on struct timeval.
467 8. Memory Handling Overview
469 All memory that is allocated by a function in this C LDAP API and
470 returned to the caller SHOULD be disposed of by calling the appropriate
471 "free" function provided by this API. The correct "free" function to
472 call is documented in each section of this document where a function
473 that allocates memory is described.
475 Memory that is allocated through means outside of the C LDAP API MUST
476 NOT be disposed of using a function provided by this API.
478 If a pointer value passed to one of the C LDAP API "free" functions is
479 NULL, graceful failure (i.e, ignoring of the NULL pointer) MUST occur.
481 The complete list of "free" functions that are used to dispose of allo-
492 ldap_value_free_len()
495 9. Retrieving Information About the API Implementation
497 Applications developed to this specification need to be able to deter-
498 mine information about the particular API implementation they are using
499 both at compile time and during execution.
502 9.1. Retrieving Information at Compile Time
504 All conformant implementations MUST include the following five
508 Expires: 8 April 2000 [Page 9]
511 C LDAP API C LDAP Application Program Interface 8 October 1999
514 definitions in a header so compile time tests can be done by LDAP
517 #define LDAP_API_VERSION level
518 #define LDAP_VERSION_MIN min-version
519 #define LDAP_VERSION_MAX max-version
520 #define LDAP_VENDOR_NAME "vend-name"
521 #define LDAP_VENDOR_VERSION vend-version
525 "level" is replaced with the RFC number given to this C LDAP API
526 specification when it is published as a standards track RFC.
528 min-version is replaced with the lowest LDAP protocol version sup-
529 ported by the implementation.
531 max-version is replaced with the highest LDAP protocol version sup-
532 ported by the implementation. This SHOULD be 3.
534 "vend-name" is replaced with a text string that identifies the
535 party that supplies the API implementation.
537 "vend-version" is a supplier-specific version number multiplied
540 Note that the LDAP_VENDOR_NAME macro SHOULD be defined as "" if no ven-
541 dor name is available and the LDAP_VENDOR_VERSION macro SHOULD be
542 defined as 0 if no vendor-specific version information is available.
544 For example, if this specification is published as RFC 88888, Netscape
545 Communication's version 4.0 implementation that supports LDAPv2 and v3
546 might include macro definitions like these:
548 #define LDAP_API_VERSION 88888 /* RFC 88888 compliant */
549 #define LDAP_VERSION_MIN 2
550 #define LDAP_VERSION_MAX 3
551 #define LDAP_VENDOR_NAME "Netscape Communications Corp."
552 #define LDAP_VENDOR_VERSION 400 /* version 4.0 */
554 and application code can test the C LDAP API version level using a
555 construct such as this one:
557 #if (LDAP_API_VERSION >= 88888)
558 /* use features supported in RFC 88888 or later */
561 Until such time as this document is published as an RFC, implementations
565 Expires: 8 April 2000 [Page 10]
568 C LDAP API C LDAP Application Program Interface 8 October 1999
571 SHOULD use the value 2000 plus the revision number of this draft for
572 LDAP_API_VERSION. For example, the correct value for LDAP_API_VERSION
573 for revision 04 of this draft is 2004.
575 Documents that extend this specification SHOULD define a macro of the
578 #define LDAP_API_FEATURE_x level
580 where "x" is replaced with a name (textual identifier) for the feature
581 and "level" is replaced with the number of the RFC that specifies the
582 API extension. The name SHOULD NOT begin with the string "X_".
584 For example, if C LDAP API extensions for Transport Layer Security [9]
585 were published in RFC 99999, that RFC might require conformant implemen-
586 tations to define a macro like this:
588 #define LDAP_API_FEATURE_TLS 99999
591 Private or experimental API extensions SHOULD be indicated by defining a
592 macro of this same form where "x" (the extension's name) begins with the
593 string "X_" and "level" is replaced with a integer number that is
594 specific to the extension.
596 It is RECOMMENDED that private or experimental API extensions use only
597 the following prefixes for macros, types, and function names:
602 and that these prefixes not be used by standard extensions.
605 9.2. Retrieving Information During Execution
607 The ldap_get_option() call (described in greater detail later in this
608 document) can be used during execution in conjunction with an option
609 parameter value of LDAP_OPT_API_INFO (0x00) to retrieve some basic
610 information about the API and about the specific implementation being
611 used. The ld parameter to ldap_get_option() can be either NULL or a
612 valid LDAP session handle which was obtained by calling ldap_init().
613 The optdata parameter to ldap_get_option() SHOULD be the address of an
614 LDAPAPIInfo structure which is defined as follows:
616 typedef struct ldapapiinfo {
617 int ldapai_info_version; /* version of this struct (1) */
618 int ldapai_api_version; /* revision of API supported */
622 Expires: 8 April 2000 [Page 11]
625 C LDAP API C LDAP Application Program Interface 8 October 1999
628 int ldapai_protocol_version; /* highest LDAP version supported */
629 char **ldapai_extensions; /* names of API extensions */
630 char *ldapai_vendor_name; /* name of supplier */
631 int ldapai_vendor_version; /* supplier-specific version times 100 */
634 In addition, API implementations MUST include the following macro defin-
637 #define LDAP_API_INFO_VERSION 1
639 Note that the ldapai_info_version field of the LDAPAPIInfo structure
640 SHOULD be set to the value LDAP_API_INFO_VERSION (1) before calling
641 ldap_get_option() so that it can be checked for consistency. All other
642 fields are set by the ldap_get_option() function.
644 The members of the LDAPAPIInfo structure are:
647 A number that identifies the version of the LDAPAPIInfo struc-
648 ture. This SHOULD be set to the value LDAP_API_INFO_VERSION
649 (1) before calling ldap_get_option(). If the value received
650 is not recognized by the API implementation, the
651 ldap_get_option() function sets ldapai_info_version to a valid
652 value that would be recognized, sets the ldapai_api_version to
653 the correct value, and returns an error without filling in any
654 of the other fields in the LDAPAPIInfo structure.
657 A number that matches that assigned to the C LDAP API RFC sup-
658 ported by the API implementation. This SHOULD match the value
659 of the LDAP_API_VERSION macro defined earlier.
661 ldapai_protocol_version
662 The highest LDAP protocol version supported by the implementa-
663 tion. For example, if LDAPv3 is the highest version supported
664 then this field will be set to 3.
667 A NULL-terminated array of character strings that lists the
668 names of the API extensions supported by the LDAP API imple-
669 mentation. These names will typically match the textual iden-
670 tifiers that appear in the "x" portion of the
671 LDAP_API_FEATURE_x macros described above, although the pre-
672 cise value MUST be defined by documents that specify C LDAP
673 API extensions. If no API extensions are supported, this
674 field will be set to NULL. The caller is responsible for
675 disposing of the memory occupied by this array by passing it
679 Expires: 8 April 2000 [Page 12]
682 C LDAP API C LDAP Application Program Interface 8 October 1999
685 to ldap_value_free() which is described later in this docu-
686 ment. To retrieve more information about a particular exten-
687 sion, the ldap_get_option() call can be used with an option
688 parameter value of LDAP_OPT_API_FEATURE_INFO (0x15). The opt-
689 data parameter to the ldap_get_option() SHOULD be the address
690 of an LDAPAPIFeatureInfo structure which is defined as fol-
693 typedef struct ldap_apifeature_info {
694 int ldapaif_info_version; /* version of this struct (1) */
695 char *ldapaif_name; /* name of supported feature */
696 int ldapaif_version; /* revision of supported feature */
697 } LDAPAPIFeatureInfo;
699 In addition, API implementations MUST include the following
702 #define LDAP_FEATURE_INFO_VERSION 1
704 Note that the ldapaif_info_version field of the LDAPAPI-
705 FeatureInfo structure SHOULD be set to the value
706 LDAP_FEATURE_INFO_VERSION (1) and the ldapaif_name field
707 SHOULD be set to the extension name string as described below
708 before ldap_get_option() is called. The call will fill in the
709 ldapaif_version field of the LDAPAPIFeatureInfo structure.
711 The members of the LDAPAPIFeatureInfo structure are:
714 A number that identifies the version of the LDAPAPI-
715 FeatureInfo structure. This SHOULD be set to the value
716 LDAP_FEATURE_INFO_VERSION (1) before calling
717 ldap_get_option(). If the value received is not recognized
718 by the API implementation, the ldap_get_option() function
719 sets ldapaif_info_version to a valid value that would be
720 recognized and returns an error without filling in the
721 ldapaif_version field in the LDAPAPIFeatureInfo structure.
724 The name of an extension, as returned in the
725 ldapai_extensions array of the LDAPAPIInfo structure and as
726 specified in the document that describes the extension.
729 This field will be set as a result of calling
730 ldap_get_option(). It is a number that matches that
731 assigned to the C LDAP API extension RFC supported for this
732 extension. For private or experimental API extensions, the
736 Expires: 8 April 2000 [Page 13]
739 C LDAP API C LDAP Application Program Interface 8 October 1999
742 value is extension-specific. In either case, the value of
743 ldapaxi_ext_version SHOULD be identical to the value of the
744 LDAP_API_FEATURE_x macro defined for the extension
750 Many of the LDAP API routines return LDAP error codes, some of which
751 indicate local errors and some of which are returned by servers. All of
752 the LDAP error codes returned will be non-negative integers. Supported
753 error codes are (hexadecimal values are given in parentheses after the
757 LDAP_OPERATIONS_ERROR (0x01)
758 LDAP_PROTOCOL_ERROR (0x02)
759 LDAP_TIMELIMIT_EXCEEDED (0x03)
760 LDAP_SIZELIMIT_EXCEEDED (0x04)
761 LDAP_COMPARE_FALSE (0x05)
762 LDAP_COMPARE_TRUE (0x06)
763 LDAP_STRONG_AUTH_NOT_SUPPORTED (0x07)
764 LDAP_STRONG_AUTH_REQUIRED (0x08)
765 LDAP_REFERRAL (0x0a) -- new in LDAPv3
766 LDAP_ADMINLIMIT_EXCEEDED (0x0b) -- new in LDAPv3
767 LDAP_UNAVAILABLE_CRITICAL_EXTENSION (0x0c) -- new in LDAPv3
768 LDAP_CONFIDENTIALITY_REQUIRED (0x0d) -- new in LDAPv3
769 LDAP_SASL_BIND_IN_PROGRESS (0x0e) -- new in LDAPv3
770 LDAP_NO_SUCH_ATTRIBUTE (0x10)
771 LDAP_UNDEFINED_TYPE (0x11)
772 LDAP_INAPPROPRIATE_MATCHING (0x12)
773 LDAP_CONSTRAINT_VIOLATION (0x13)
774 LDAP_TYPE_OR_VALUE_EXISTS (0x14)
775 LDAP_INVALID_SYNTAX (0x15)
776 LDAP_NO_SUCH_OBJECT (0x20)
777 LDAP_ALIAS_PROBLEM (0x21)
778 LDAP_INVALID_DN_SYNTAX (0x22)
779 LDAP_IS_LEAF (0x23) -- not used in LDAPv3
780 LDAP_ALIAS_DEREF_PROBLEM (0x24)
781 LDAP_INAPPROPRIATE_AUTH (0x30)
782 LDAP_INVALID_CREDENTIALS (0x31)
783 LDAP_INSUFFICIENT_ACCESS (0x32)
785 LDAP_UNAVAILABLE (0x34)
786 LDAP_UNWILLING_TO_PERFORM (0x35)
787 LDAP_LOOP_DETECT (0x36)
788 LDAP_NAMING_VIOLATION (0x40)
789 LDAP_OBJECT_CLASS_VIOLATION (0x41)
793 Expires: 8 April 2000 [Page 14]
796 C LDAP API C LDAP Application Program Interface 8 October 1999
799 LDAP_NOT_ALLOWED_ON_NONLEAF (0x42)
800 LDAP_NOT_ALLOWED_ON_RDN (0x43)
801 LDAP_ALREADY_EXISTS (0x44)
802 LDAP_NO_OBJECT_CLASS_MODS (0x45)
803 LDAP_RESULTS_TOO_LARGE (0x46) -- reserved for CLDAP
804 LDAP_AFFECTS_MULTIPLE_DSAS (0x47) -- new in LDAPv3
806 LDAP_SERVER_DOWN (0x51)
807 LDAP_LOCAL_ERROR (0x52)
808 LDAP_ENCODING_ERROR (0x53)
809 LDAP_DECODING_ERROR (0x54)
811 LDAP_AUTH_UNKNOWN (0x56)
812 LDAP_FILTER_ERROR (0x57)
813 LDAP_USER_CANCELLED (0x58)
814 LDAP_PARAM_ERROR (0x59)
815 LDAP_NO_MEMORY (0x5a)
816 LDAP_CONNECT_ERROR (0x5b)
817 LDAP_NOT_SUPPORTED (0x5c)
818 LDAP_CONTROL_NOT_FOUND (0x5d)
819 LDAP_NO_RESULTS_RETURNED (0x5e)
820 LDAP_MORE_RESULTS_TO_RETURN (0x5f)
821 LDAP_CLIENT_LOOP (0x60)
822 LDAP_REFERRAL_LIMIT_EXCEEDED (0x61)
825 11. Performing LDAP Operations
827 This section describes each LDAP operation API call in detail. All func-
828 tions take a "session handle," a pointer to an LDAP structure containing
829 per-connection information. Many routines return results in an LDAPMes-
830 sage structure. These structures and others are described as needed
834 11.1. Initializing an LDAP Session
836 ldap_init() initializes a session with an LDAP server. The server is not
837 actually contacted until an operation is performed that requires it,
838 allowing various options to be set after initialization.
841 const char *hostname,
845 Use of the following routine is deprecated:
850 Expires: 8 April 2000 [Page 15]
853 C LDAP API C LDAP Application Program Interface 8 October 1999
857 const char *hostname,
860 Unlike ldap_init(), ldap_open() attempts to make a server connection
861 before returning to the caller. A more complete description can be
866 hostname Contains a space-separated list of hostnames or dotted strings
867 representing the IP address of hosts running an LDAP server to
868 connect to. Each hostname in the list MAY include a port number
869 which is separated from the host itself with a colon (:) char-
870 acter. The hosts will be tried in the order listed, stopping
871 with the first one to which a successful connection is made.
873 Note: A suitable representation for including a literal IPv6[10]
874 address in the hostname parameter is desired, but has not yet been
875 determined or implemented in practice.
877 portno Contains the TCP port number to connect to. The default LDAP
878 port of 389 can be obtained by supplying the constant
879 LDAP_PORT. If a host includes a port number then this parame-
882 ldap_init() and ldap_open() both return a "session handle," a pointer to
883 an opaque structure that MUST be passed to subsequent calls pertaining
884 to the session. These routines return NULL if the session cannot be ini-
885 tialized in which case the operating system error reporting mechanism
886 can be checked to see why the call failed.
888 Note that if you connect to an LDAPv2 server, one of the LDAP bind calls
889 described below SHOULD be completed before other operations can be per-
890 formed on the session. LDAPv3 does not require that a bind operation be
891 completed before other operations can be performed.
893 The calling program can set various attributes of the session by calling
894 the routines described in the next section.
897 11.2. LDAP Session Handle Options
899 The LDAP session handle returned by ldap_init() is a pointer to an
900 opaque data type representing an LDAP session. In RFC 1823 this data
901 type was a structure exposed to the caller, and various fields in the
902 structure could be set to control aspects of the session, such as size
903 and time limits on searches.
907 Expires: 8 April 2000 [Page 16]
910 C LDAP API C LDAP Application Program Interface 8 October 1999
913 In the interest of insulating callers from inevitable changes to this
914 structure, these aspects of the session are now accessed through a pair
915 of accessor functions, described below.
917 ldap_get_option() is used to access the current value of various
918 session-wide parameters. ldap_set_option() is used to set the value of
919 these parameters. Note that some options are READ-ONLY and cannot be
920 set; it is an error to call ldap_set_option() and attempt to set a
923 Note that if automatic referral following is enabled (the default), any
924 connections created during the course of following referrals will
925 inherit the options associated with the session that sent the original
926 request that caused the referrals to be returned.
940 #define LDAP_OPT_ON ((void *)1)
941 #define LDAP_OPT_OFF ((void *)0)
946 ld The session handle. If this is NULL, a set of global defaults is
947 accessed. New LDAP session handles created with ldap_init() or
948 ldap_open() inherit their characteristics from these global
951 option The name of the option being accessed or set. This parameter
952 SHOULD be one of the following constants, which have the indi-
953 cated meanings. After the constant the actual hexadecimal value
954 of the constant is listed in parentheses.
957 LDAP_OPT_API_INFO (0x00)
958 Type for invalue parameter: not applicable (option is READ-ONLY)
960 Type for outvalue parameter: LDAPAPIInfo *
964 Expires: 8 April 2000 [Page 17]
967 C LDAP API C LDAP Application Program Interface 8 October 1999
971 Used to retrieve some basic information about the LDAP API
972 implementation at execution time. See the section "Retriev-
973 ing Information About the API Implementation" above for more
974 information. This option is READ-ONLY and cannot be set.
976 LDAP_OPT_DEREF (0x02)
977 Type for invalue parameter: int *
979 Type for outvalue parameter: int *
982 Determines how aliases are handled during search. It SHOULD
983 have one of the following values: LDAP_DEREF_NEVER (0x00),
984 LDAP_DEREF_SEARCHING (0x01), LDAP_DEREF_FINDING (0x02), or
985 LDAP_DEREF_ALWAYS (0x03). The LDAP_DEREF_SEARCHING value
986 means aliases are dereferenced during the search but not when
987 locating the base object of the search. The
988 LDAP_DEREF_FINDING value means aliases are dereferenced when
989 locating the base object but not during the search. The
990 default value for this option is LDAP_DEREF_NEVER.
992 LDAP_OPT_SIZELIMIT (0x03)
993 Type for invalue parameter: int *
995 Type for outvalue parameter: int *
998 A limit on the number of entries to return from a search. A
999 value of LDAP_NO_LIMIT (0) means no limit. The default value
1000 for this option is LDAP_NO_LIMIT.
1002 LDAP_OPT_TIMELIMIT (0x04)
1003 Type for invalue parameter: int *
1005 Type for outvalue parameter: int *
1008 A limit on the number of seconds to spend on a search. A
1009 value of LDAP_NO_LIMIT (0) means no limit. This value is
1010 passed to the server in the search request only; it does not
1011 affect how long the C LDAP API implementation itself will
1012 wait locally for search results. The timeout parameter
1013 passed to ldap_search_ext_s() or ldap_result() -- both of
1014 which are described later in this document -- can be used to
1015 specify both a local and server side time limit. The default
1016 value for this option is LDAP_NO_LIMIT.
1021 Expires: 8 April 2000 [Page 18]
1024 C LDAP API C LDAP Application Program Interface 8 October 1999
1027 LDAP_OPT_REFERRALS (0x08)
1028 Type for invalue parameter: void * (LDAP_OPT_ON or LDAP_OPT_OFF)
1030 Type for outvalue parameter: int *
1033 Determines whether the LDAP library automatically follows
1034 referrals returned by LDAP servers or not. It MAY be set to
1035 one of the constants LDAP_OPT_ON or LDAP_OPT_OFF; any non-
1036 NULL pointer value passed to ldap_set_option() enables this
1037 option. When reading the current setting using
1038 ldap_get_option(), a zero value means OFF and any non-zero
1039 value means ON. By default, this option is ON.
1041 LDAP_OPT_RESTART (0x09)
1042 Type for invalue parameter: void * (LDAP_OPT_ON or LDAP_OPT_OFF)
1044 Type for outvalue parameter: int *
1047 Determines whether LDAP I/O operations are automatically res-
1048 tarted if they abort prematurely. It MAY be set to one of the
1049 constants LDAP_OPT_ON or LDAP_OPT_OFF; any non-NULL pointer
1050 value passed to ldap_set_option() enables this option. When
1051 reading the current setting using ldap_get_option(), a zero
1052 value means OFF and any non-zero value means ON. This option
1053 is useful if an LDAP I/O operation can be interrupted prema-
1054 turely, for example by a timer going off, or other interrupt.
1055 By default, this option is OFF.
1057 LDAP_OPT_PROTOCOL_VERSION (0x11)
1058 Type for invalue parameter: int *
1060 Type for outvalue parameter: int *
1063 This option indicates the version of the LDAP protocol used
1064 when communicating with the primary LDAP server. It SHOULD be
1065 one of the constants LDAP_VERSION2 (2) or LDAP_VERSION3 (3).
1066 If no version is set the default is LDAP_VERSION2 (2).
1068 LDAP_OPT_SERVER_CONTROLS (0x12)
1069 Type for invalue parameter: LDAPControl **
1071 Type for outvalue parameter: LDAPControl ***
1074 A default list of LDAP server controls to be sent with each
1078 Expires: 8 April 2000 [Page 19]
1081 C LDAP API C LDAP Application Program Interface 8 October 1999
1084 request. See the Working With Controls section below.
1086 LDAP_OPT_CLIENT_CONTROLS (0x13)
1087 Type for invalue parameter: LDAPControl **
1089 Type for outvalue parameter: LDAPControl ***
1092 A default list of client controls that affect the LDAP ses-
1093 sion. See the Working With Controls section below.
1095 LDAP_OPT_API_FEATURE_INFO (0x15)
1096 Type for invalue parameter: not applicable (option is READ-ONLY)
1098 Type for outvalue parameter: LDAPAPIFeatureInfo *
1101 Used to retrieve version information about LDAP API extended
1102 features at execution time. See the section "Retrieving
1103 Information About the API Implementation" above for more
1104 information. This option is READ-ONLY and cannot be set.
1106 LDAP_OPT_HOST_NAME (0x30)
1107 Type for invalue parameter: char *
1109 Type for outvalue parameter: char **
1112 The host name (or list of hosts) for the primary LDAP server.
1113 See the definition of the hostname parameter to ldap_init()
1114 for the allowed syntax.
1116 LDAP_OPT_ERROR_NUMBER (0x31)
1117 Type for invalue parameter: int *
1119 Type for outvalue parameter: int *
1122 The code of the most recent LDAP error that occurred for this
1125 LDAP_OPT_ERROR_STRING (0x32)
1126 Type for invalue parameter: char *
1128 Type for outvalue parameter: char **
1131 The message returned with the most recent LDAP error that
1135 Expires: 8 April 2000 [Page 20]
1138 C LDAP API C LDAP Application Program Interface 8 October 1999
1141 occurred for this session.
1143 LDAP_OPT_MATCHED_DN (0x33)
1144 Type for invalue parameter: char *
1146 Type for outvalue parameter: char **
1149 The matched DN value returned with the most recent LDAP error
1150 that occurred for this session.
1153 outvalue The address of a place to put the value of the option. The
1154 actual type of this parameter depends on the setting of the
1155 option parameter. For outvalues of type char ** and LDAPCon-
1156 trol **, a copy of the data that is associated with the LDAP
1157 session ld is returned; callers should dispose of the memory by
1158 calling ldap_memfree() or ldap_controls_free(), depending on
1159 the type of data returned.
1161 invalue A pointer to the value the option is to be given. The actual
1162 type of this parameter depends on the setting of the option
1163 parameter. The data associated with invalue is copied by the
1164 API implementation to allow callers of the API to dispose of or
1165 otherwise change their copy of the data after a successful call
1166 to ldap_set_option(). If a value passed for invalue is invalid
1167 or cannot be accepted by the implementation, ldap_set_option()
1168 should return -1 to indicate an error.
1170 Both ldap_get_option() and ldap_set_option() return 0 if successful and
1171 -1 if an error occurs. If -1 is returned by either function, a specific
1172 error code MAY be retrieved by calling ldap_get_option() with an option
1173 value of LDAP_OPT_ERROR_NUMBER. Note that there is no way to retrieve a
1174 more specific error code if a call to ldap_get_option() with an option
1175 value of LDAP_OPT_ERROR_NUMBER fails.
1177 When a call to ldap_get_option() succeeds, the API implementation MUST
1178 NOT change the state of the LDAP session handle or the state of the
1179 underlying implementation in a way that affects the behavior of future
1180 LDAP API calls. When a call to ldap_get_option() fails, the only ses-
1181 sion handle change permitted is setting the LDAP error code (as returned
1182 by the LDAP_OPT_ERROR_NUMBER option).
1184 When a call to ldap_set_option() fails, it MUST NOT change the state of
1185 the LDAP session handle or the state of the underlying implementation in
1186 a way that affects the behavior of future LDAP API calls.
1188 Standards track documents that extend this specification and specify new
1192 Expires: 8 April 2000 [Page 21]
1195 C LDAP API C LDAP Application Program Interface 8 October 1999
1198 options SHOULD use values for option macros that are between 0x1000 and
1199 0x3FFF inclusive. Private and experimental extensions SHOULD use values
1200 for the option macros that are between 0x4000 and 0x7FFF inclusive. All
1201 values below 0x1000 and above 0x7FFF that are not defined in this docu-
1202 ment are reserved and SHOULD NOT be used. The following macro MUST be
1203 defined by C LDAP API implementations to aid extension implementors:
1204 #define LDAP_OPT_PRIVATE_EXTENSION_BASE 0x4000 /* to 0x7FFF inclusive */
1208 11.3. Working With Controls
1210 LDAPv3 operations can be extended through the use of controls. Controls
1211 can be sent to a server or returned to the client with any LDAP message.
1212 These controls are referred to as server controls.
1214 The LDAP API also supports a client-side extension mechanism through the
1215 use of client controls. These controls affect the behavior of the LDAP
1216 API only and are never sent to a server. A common data structure is
1217 used to represent both types of controls:
1219 typedef struct ldapcontrol {
1221 struct berval ldctl_value;
1222 char ldctl_iscritical;
1225 The fields in the ldapcontrol structure have the following meanings:
1227 ldctl_oid The control type, represented as a string.
1229 ldctl_value The data associated with the control (if any). To
1230 specify a zero-length value, set ldctl_value.bv_len to
1231 zero and ldctl_value.bv_val to a zero-length string.
1232 To indicate that no data is associated with the con-
1233 trol, set ldctl_value.bv_val to NULL.
1235 ldctl_iscritical Indicates whether the control is critical of not. If
1236 this field is non-zero, the operation will only be car-
1237 ried out if the control is recognized by the server
1238 and/or client. Note that the LDAP unbind and abandon
1239 operations have no server response, so clients SHOULD
1240 NOT mark server controls critical when used with these
1243 Some LDAP API calls allocate an ldapcontrol structure or a NULL-
1244 terminated array of ldapcontrol structures. The following routines can
1245 be used to dispose of a single control or an array of controls:
1249 Expires: 8 April 2000 [Page 22]
1252 C LDAP API C LDAP Application Program Interface 8 October 1999
1255 void ldap_control_free( LDAPControl *ctrl );
1256 void ldap_controls_free( LDAPControl **ctrls );
1257 If the ctrl or ctrls parameter is NULL, these calls do nothing.
1259 A set of controls that affect the entire session can be set using the
1260 ldap_set_option() function (see above). A list of controls can also be
1261 passed directly to some LDAP API calls such as ldap_search_ext(), in
1262 which case any controls set for the session through the use of
1263 ldap_set_option() are ignored. Control lists are represented as a NULL-
1264 terminated array of pointers to ldapcontrol structures.
1266 Server controls are defined by LDAPv3 protocol extension documents; for
1267 example, a control has been proposed to support server-side sorting of
1268 search results [11].
1270 One client control is defined in this document (described in the follow-
1271 ing section). Other client controls MAY be defined in future revisions
1272 of this document or in documents that extend this API.
1275 11.3.1. A Client Control That Governs Referral Processing
1277 As described previously in the section "LDAP Session Handle Options,"
1278 applications can enable and disable automatic chasing of referrals on a
1279 session-wide basic by using the ldap_set_option() function with the
1280 LDAP_OPT_REFERRALS option. It is also useful to govern automatic refer-
1281 ral chasing on per-request basis. A client control with an OID of
1282 1.2.840.113556.1.4.616 exists to provide this functionality.
1284 /* OID for referrals client control */
1285 #define LDAP_CONTROL_REFERRALS "1.2.840.113556.1.4.616"
1287 /* Flags for referrals client control value */
1288 #define LDAP_CHASE_SUBORDINATE_REFERRALS 0x00000020U
1289 #define LDAP_CHASE_EXTERNAL_REFERRALS 0x00000040U
1291 To create a referrals client control, the ldctl_oid field of an LDAPCon-
1292 trol structure MUST be set to LDAP_CONTROL_REFERRALS
1293 ("1.2.840.113556.1.4.616") and the ldctl_value field MUST be set to a
1294 4-octet value that contains a set of flags. The ldctl_value.bv_len
1295 field MUST always be set to 4. The ldctl_value.bv_val field MUST point
1296 to a 4-octet integer flags value. This flags value can be set to zero
1297 to disable automatic chasing of referrals and LDAPv3 references alto-
1298 gether. Alternatively, the flags value can be set to the value
1299 LDAP_CHASE_SUBORDINATE_REFERRALS (0x00000020U) to indicate that only
1300 LDAPv3 search continuation references are to be automatically chased by
1301 the API implementation, to the value LDAP_CHASE_EXTERNAL_REFERRALS
1302 (0x00000040U) to indicate that only LDAPv3 referrals are to be
1306 Expires: 8 April 2000 [Page 23]
1309 C LDAP API C LDAP Application Program Interface 8 October 1999
1312 automatically chased, or the logical OR of the two flag values
1313 (0x00000060U) to indicate that both referrals and references are to be
1314 automatically chased.
1317 11.4. Authenticating to the directory
1319 The following functions are used to authenticate an LDAP client to an
1320 LDAP directory server.
1322 The ldap_sasl_bind() and ldap_sasl_bind_s() functions can be used to do
1323 general and extensible authentication over LDAP through the use of the
1324 Simple Authentication Security Layer [12]. The routines both take the
1325 dn to bind as, the method to use, as a dotted-string representation of
1326 an OID identifying the method, and a struct berval holding the creden-
1327 tials. The special constant value LDAP_SASL_SIMPLE (NULL) can be passed
1328 to request simple authentication, or the simplified routines
1329 ldap_simple_bind() or ldap_simple_bind_s() can be used.
1334 const char *mechanism,
1335 const struct berval *cred,
1336 LDAPControl **serverctrls,
1337 LDAPControl **clientctrls,
1341 int ldap_sasl_bind_s(
1344 const char *mechanism,
1345 const struct berval *cred,
1346 LDAPControl **serverctrls,
1347 LDAPControl **clientctrls,
1348 struct berval **servercredp
1351 int ldap_simple_bind(
1357 int ldap_simple_bind_s(
1363 Expires: 8 April 2000 [Page 24]
1366 C LDAP API C LDAP Application Program Interface 8 October 1999
1372 The use of the following routines is deprecated and more complete
1373 descriptions can be found in RFC 1823:
1375 int ldap_bind( LDAP *ld, const char *dn, const char *cred,
1378 int ldap_bind_s( LDAP *ld, const char *dn, const char *cred,
1381 int ldap_kerberos_bind( LDAP *ld, const char *dn );
1383 int ldap_kerberos_bind_s( LDAP *ld, const char *dn );
1387 ld The session handle.
1389 dn The name of the entry to bind as.
1391 mechanism Either LDAP_SASL_SIMPLE (NULL) to get simple authentica-
1392 tion, or a text string identifying the SASL method.
1394 cred The credentials with which to authenticate. Arbitrary
1395 credentials can be passed using this parameter. The format
1396 and content of the credentials depends on the setting of
1397 the mechanism parameter.
1399 passwd For ldap_simple_bind(), the password to compare to the
1400 entry's userPassword attribute.
1402 serverctrls List of LDAP server controls.
1404 clientctrls List of client controls.
1406 msgidp This result parameter will be set to the message id of the
1407 request if the ldap_sasl_bind() call succeeds.
1409 servercredp This result parameter will be filled in with the creden-
1410 tials passed back by the server for mutual authentication,
1411 if given. An allocated berval structure is returned that
1412 SHOULD be disposed of by calling ber_bvfree(). NULL SHOULD
1413 be passed to ignore this field.
1415 Additional parameters for the deprecated routines are not described.
1416 Interested readers are referred to RFC 1823.
1420 Expires: 8 April 2000 [Page 25]
1423 C LDAP API C LDAP Application Program Interface 8 October 1999
1426 The ldap_sasl_bind() function initiates an asynchronous bind operation
1427 and returns the constant LDAP_SUCCESS if the request was successfully
1428 sent, or another LDAP error code if not. See the section below on error
1429 handling for more information about possible errors and how to interpret
1430 them. If successful, ldap_sasl_bind() places the message id of the
1431 request in *msgidp. A subsequent call to ldap_result(), described below,
1432 can be used to obtain the result of the bind.
1434 The ldap_simple_bind() function initiates a simple asynchronous bind
1435 operation and returns the message id of the operation initiated. A sub-
1436 sequent call to ldap_result(), described below, can be used to obtain
1437 the result of the bind. In case of error, ldap_simple_bind() will return
1438 -1, setting the session error parameters in the LDAP structure appropri-
1441 The synchronous ldap_sasl_bind_s() and ldap_simple_bind_s() functions
1442 both return the result of the operation, either the constant
1443 LDAP_SUCCESS if the operation was successful, or another LDAP error code
1444 if it was not. See the section below on error handling for more informa-
1445 tion about possible errors and how to interpret them.
1447 Note that if an LDAPv2 server is contacted, no other operations over the
1448 connection can be attempted before a bind call has successfully com-
1451 Subsequent bind calls can be used to re-authenticate over the same con-
1452 nection, and multistep SASL sequences can be accomplished through a
1453 sequence of calls to ldap_sasl_bind() or ldap_sasl_bind_s().
1456 11.5. Closing the session
1458 The following functions are used to unbind from the directory, close
1459 open connections, and dispose of the session handle.
1461 int ldap_unbind_ext( LDAP *ld, LDAPControl **serverctrls,
1462 LDAPControl **clientctrls );
1464 int ldap_unbind( LDAP *ld );
1466 int ldap_unbind_s( LDAP *ld );
1470 ld The session handle.
1472 serverctrls List of LDAP server controls.
1477 Expires: 8 April 2000 [Page 26]
1480 C LDAP API C LDAP Application Program Interface 8 October 1999
1483 clientctrls List of client controls.
1485 The ldap_unbind_ext(), ldap_unbind() and ldap_unbind_s() all work syn-
1486 chronously in the sense that they send an unbind request to the server,
1487 close all open connections associated with the LDAP session handle, and
1488 dispose of all resources associated with the session handle before
1489 returning. Note, however, that there is no server response to an LDAP
1490 unbind operation. All three of the unbind functions return LDAP_SUCCESS
1491 (or another LDAP error code if the request cannot be sent to the LDAP
1492 server). After a call to one of the unbind functions, the session han-
1493 dle ld is invalid and it is illegal to make any further LDAP API calls
1496 The ldap_unbind() and ldap_unbind_s() functions behave identically. The
1497 ldap_unbind_ext() function allows server and client controls to be
1498 included explicitly, but note that since there is no server response to
1499 an unbind request there is no way to receive a response to a server con-
1500 trol sent with an unbind request.
1506 The following functions are used to search the LDAP directory, returning
1507 a requested set of attributes for each entry matched. There are five
1510 int ldap_search_ext(
1517 LDAPControl **serverctrls,
1518 LDAPControl **clientctrls,
1519 struct timeval *timeout,
1524 int ldap_search_ext_s(
1534 Expires: 8 April 2000 [Page 27]
1537 C LDAP API C LDAP Application Program Interface 8 October 1999
1540 LDAPControl **serverctrls,
1541 LDAPControl **clientctrls,
1542 struct timeval *timeout,
1573 struct timeval *timeout,
1579 ld The session handle.
1581 base The dn of the entry at which to start the search.
1583 scope One of LDAP_SCOPE_BASE (0x00), LDAP_SCOPE_ONELEVEL (0x01),
1584 or LDAP_SCOPE_SUBTREE (0x02), indicating the scope of the
1587 filter A character string as described in [13], representing the
1591 Expires: 8 April 2000 [Page 28]
1594 C LDAP API C LDAP Application Program Interface 8 October 1999
1597 search filter. The value NULL can be passed to indicate
1598 that the filter "(objectclass=*)" which matches all entries
1599 is to be used. Note that if the caller of the API is using
1600 LDAPv2, only a subset of the filter functionality described
1601 in [13] can be successfully used.
1603 attrs A NULL-terminated array of strings indicating which attri-
1604 butes to return for each matching entry. Passing NULL for
1605 this parameter causes all available user attributes to be
1606 retrieved. The special constant string LDAP_NO_ATTRS
1607 ("1.1") MAY be used as the only string in the array to
1608 indicate that no attribute types are to be returned by the
1609 server. The special constant string LDAP_ALL_USER_ATTRS
1610 ("*") can be used in the attrs array along with the names
1611 of some operational attributes to indicate that all user
1612 attributes plus the listed operational attributes are to be
1615 attrsonly A boolean value that MUST be zero if both attribute types
1616 and values are to be returned, and non-zero if only types
1619 timeout For the ldap_search_st() function, this specifies the local
1620 search timeout value (if it is NULL, the timeout is infin-
1621 ite). If a zero timeout (where tv_sec and tv_usec are both
1622 zero) is passed, API implementations SHOULD return
1625 For the ldap_search_ext() and ldap_search_ext_s() func-
1626 tions, the timeout parameter specifies both the local
1627 search timeout value and the operation time limit that is
1628 sent to the server within the search request. Passing a
1629 NULL value for timeout causes the global default timeout
1630 stored in the LDAP session handle (set by using
1631 ldap_set_option() with the LDAP_OPT_TIMELIMIT parameter) to
1632 be sent to the server with the request but an infinite
1633 local search timeout to be used. If a zero timeout (where
1634 tv_sec and tv_usec are both zero) is passed in, API imple-
1635 mentations SHOULD return LDAP_PARAM_ERROR. If a zero value
1636 for tv_sec is used but tv_usec is non-zero, an operation
1637 time limit of 1 SHOULD be passed to the LDAP server as the
1638 operation time limit. For other values of tv_sec, the
1639 tv_sec value itself SHOULD be passed to the LDAP server.
1641 sizelimit For the ldap_search_ext() and ldap_search_ext_s() calls,
1642 this is a limit on the number of entries to return from the
1643 search. A value of LDAP_NO_LIMIT (0) means no limit.
1648 Expires: 8 April 2000 [Page 29]
1651 C LDAP API C LDAP Application Program Interface 8 October 1999
1654 res For the synchronous calls, this is a result parameter which
1655 will contain the results of the search upon completion of
1656 the call. If no results are returned, *res is set to NULL.
1658 serverctrls List of LDAP server controls.
1660 clientctrls List of client controls.
1662 msgidp This result parameter will be set to the message id of the
1663 request if the ldap_search_ext() call succeeds.
1665 There are three options in the session handle ld which potentially
1666 affect how the search is performed. They are:
1669 A limit on the number of entries to return from the search.
1670 A value of LDAP_NO_LIMIT (0) means no limit. Note that the
1671 value from the session handle is ignored when using the
1672 ldap_search_ext() or ldap_search_ext_s() functions.
1675 A limit on the number of seconds to spend on the search. A
1676 value of LDAP_NO_LIMIT (0) means no limit. Note that the
1677 value from the session handle is ignored when using the
1678 ldap_search_ext() or ldap_search_ext_s() functions.
1681 One of LDAP_DEREF_NEVER (0x00), LDAP_DEREF_SEARCHING
1682 (0x01), LDAP_DEREF_FINDING (0x02), or LDAP_DEREF_ALWAYS
1683 (0x03), specifying how aliases are handled during the
1684 search. The LDAP_DEREF_SEARCHING value means aliases are
1685 dereferenced during the search but not when locating the
1686 base object of the search. The LDAP_DEREF_FINDING value
1687 means aliases are dereferenced when locating the base
1688 object but not during the search.
1690 The ldap_search_ext() function initiates an asynchronous search opera-
1691 tion and returns the constant LDAP_SUCCESS if the request was success-
1692 fully sent, or another LDAP error code if not. See the section below on
1693 error handling for more information about possible errors and how to
1694 interpret them. If successful, ldap_search_ext() places the message id
1695 of the request in *msgidp. A subsequent call to ldap_result(), described
1696 below, can be used to obtain the results from the search. These results
1697 can be parsed using the result parsing routines described in detail
1700 Similar to ldap_search_ext(), the ldap_search() function initiates an
1701 asynchronous search operation and returns the message id of the
1705 Expires: 8 April 2000 [Page 30]
1708 C LDAP API C LDAP Application Program Interface 8 October 1999
1711 operation initiated. As for ldap_search_ext(), a subsequent call to
1712 ldap_result(), described below, can be used to obtain the result of the
1713 bind. In case of error, ldap_search() will return -1, setting the ses-
1714 sion error parameters in the LDAP structure appropriately.
1716 The synchronous ldap_search_ext_s(), ldap_search_s(), and
1717 ldap_search_st() functions all return the result of the operation,
1718 either the constant LDAP_SUCCESS if the operation was successful, or
1719 another LDAP error code if it was not. See the section below on error
1720 handling for more information about possible errors and how to interpret
1721 them. Entries returned from the search (if any) are contained in the
1722 res parameter. This parameter is opaque to the caller. Entries, attri-
1723 butes, values, etc., can be extracted by calling the parsing routines
1724 described below. The results contained in res SHOULD be freed when no
1725 longer in use by calling ldap_msgfree(), described later.
1727 The ldap_search_ext() and ldap_search_ext_s() functions support LDAPv3
1728 server controls, client controls, and allow varying size and time limits
1729 to be easily specified for each search operation. The ldap_search_st()
1730 function is identical to ldap_search_s() except that it takes an addi-
1731 tional parameter specifying a local timeout for the search. The local
1732 search timeout is used to limit the amount of time the API implementa-
1733 tion will wait for a search to complete. After the local search timeout
1734 expires, the API implementation will send an abandon operation to abort
1735 the search operation.
1737 11.7. Reading an Entry
1739 LDAP does not support a read operation directly. Instead, this operation
1740 is emulated by a search with base set to the DN of the entry to read,
1741 scope set to LDAP_SCOPE_BASE, and filter set to "(objectclass=*)" or
1742 NULL. attrs contains the list of attributes to return.
1745 11.8. Listing the Children of an Entry
1747 LDAP does not support a list operation directly. Instead, this operation
1748 is emulated by a search with base set to the DN of the entry to list,
1749 scope set to LDAP_SCOPE_ONELEVEL, and filter set to "(objectclass=*)" or
1750 NULL. attrs contains the list of attributes to return for each child
1753 11.9. Comparing a Value Against an Entry
1755 The following routines are used to compare a given attribute value
1756 assertion against an LDAP entry. There are four variations:
1758 int ldap_compare_ext(
1762 Expires: 8 April 2000 [Page 31]
1765 C LDAP API C LDAP Application Program Interface 8 October 1999
1771 const struct berval *bvalue,
1772 LDAPControl **serverctrls,
1773 LDAPControl **clientctrls,
1777 int ldap_compare_ext_s(
1781 const struct berval *bvalue,
1782 LDAPControl **serverctrls,
1783 LDAPControl **clientctrls
1802 ld The session handle.
1804 dn The name of the entry to compare against.
1806 attr The attribute to compare against.
1808 bvalue The attribute value to compare against those found in the
1809 given entry. This parameter is used in the extended rou-
1810 tines and is a pointer to a struct berval so it is possible
1811 to compare binary values.
1813 value A string attribute value to compare against, used by the
1814 ldap_compare() and ldap_compare_s() functions. Use
1815 ldap_compare_ext() or ldap_compare_ext_s() if you need to
1819 Expires: 8 April 2000 [Page 32]
1822 C LDAP API C LDAP Application Program Interface 8 October 1999
1825 compare binary values.
1827 serverctrls List of LDAP server controls.
1829 clientctrls List of client controls.
1831 msgidp This result parameter will be set to the message id of the
1832 request if the ldap_compare_ext() call succeeds.
1834 The ldap_compare_ext() function initiates an asynchronous compare opera-
1835 tion and returns the constant LDAP_SUCCESS if the request was success-
1836 fully sent, or another LDAP error code if not. See the section below on
1837 error handling for more information about possible errors and how to
1838 interpret them. If successful, ldap_compare_ext() places the message id
1839 of the request in *msgidp. A subsequent call to ldap_result(), described
1840 below, can be used to obtain the result of the compare.
1842 Similar to ldap_compare_ext(), the ldap_compare() function initiates an
1843 asynchronous compare operation and returns the message id of the opera-
1844 tion initiated. As for ldap_compare_ext(), a subsequent call to
1845 ldap_result(), described below, can be used to obtain the result of the
1846 bind. In case of error, ldap_compare() will return -1, setting the ses-
1847 sion error parameters in the LDAP structure appropriately.
1849 The synchronous ldap_compare_ext_s() and ldap_compare_s() functions both
1850 return the result of the operation, either the constant LDAP_SUCCESS if
1851 the operation was successful, or another LDAP error code if it was not.
1852 See the section below on error handling for more information about pos-
1853 sible errors and how to interpret them.
1855 The ldap_compare_ext() and ldap_compare_ext_s() functions support LDAPv3
1856 server controls and client controls.
1859 11.10. Modifying an entry
1861 The following routines are used to modify an existing LDAP entry. There
1862 are four variations:
1864 typedef struct ldapmod {
1868 char **modv_strvals;
1869 struct berval **modv_bvals;
1872 #define mod_values mod_vals.modv_strvals
1876 Expires: 8 April 2000 [Page 33]
1879 C LDAP API C LDAP Application Program Interface 8 October 1999
1882 #define mod_bvalues mod_vals.modv_bvals
1884 int ldap_modify_ext(
1888 LDAPControl **serverctrls,
1889 LDAPControl **clientctrls,
1893 int ldap_modify_ext_s(
1897 LDAPControl **serverctrls,
1898 LDAPControl **clientctrls
1915 ld The session handle.
1917 dn The name of the entry to modify.
1919 mods A NULL-terminated array of modifications to make to the
1922 serverctrls List of LDAP server controls.
1924 clientctrls List of client controls.
1926 msgidp This result parameter will be set to the message id of the
1927 request if the ldap_modify_ext() call succeeds.
1929 The fields in the LDAPMod structure have the following meanings:
1933 Expires: 8 April 2000 [Page 34]
1936 C LDAP API C LDAP Application Program Interface 8 October 1999
1939 mod_op The modification operation to perform. It MUST be one of
1940 LDAP_MOD_ADD (0x00), LDAP_MOD_DELETE (0x01), or
1941 LDAP_MOD_REPLACE (0x02). This field also indicates the
1942 type of values included in the mod_vals union. It is logi-
1943 cally ORed with LDAP_MOD_BVALUES (0x80) to select the
1944 mod_bvalues form. Otherwise, the mod_values form is used.
1946 mod_type The type of the attribute to modify.
1948 mod_vals The values (if any) to add, delete, or replace. Only one of
1949 the mod_values or mod_bvalues variants can be used,
1950 selected by ORing the mod_op field with the constant
1951 LDAP_MOD_BVALUES. mod_values is a NULL-terminated array of
1952 zero-terminated strings and mod_bvalues is a NULL-
1953 terminated array of berval structures that can be used to
1954 pass binary values such as images.
1956 For LDAP_MOD_ADD modifications, the given values are added to the
1957 entry, creating the attribute if necessary.
1959 For LDAP_MOD_DELETE modifications, the given values are deleted from the
1960 entry, removing the attribute if no values remain. If the entire attri-
1961 bute is to be deleted, the mod_vals field can be set to NULL.
1963 For LDAP_MOD_REPLACE modifications, the attribute will have the listed
1964 values after the modification, having been created if necessary, or
1965 removed if the mod_vals field is NULL. All modifications are performed
1966 in the order in which they are listed.
1968 The ldap_modify_ext() function initiates an asynchronous modify opera-
1969 tion and returns the constant LDAP_SUCCESS if the request was success-
1970 fully sent, or another LDAP error code if not. See the section below on
1971 error handling for more information about possible errors and how to
1972 interpret them. If successful, ldap_modify_ext() places the message id
1973 of the request in *msgidp. A subsequent call to ldap_result(), described
1974 below, can be used to obtain the result of the modify.
1976 Similar to ldap_modify_ext(), the ldap_modify() function initiates an
1977 asynchronous modify operation and returns the message id of the opera-
1978 tion initiated. As for ldap_modify_ext(), a subsequent call to
1979 ldap_result(), described below, can be used to obtain the result of the
1980 modify. In case of error, ldap_modify() will return -1, setting the ses-
1981 sion error parameters in the LDAP structure appropriately.
1983 The synchronous ldap_modify_ext_s() and ldap_modify_s() functions both
1984 return the result of the operation, either the constant LDAP_SUCCESS if
1985 the operation was successful, or another LDAP error code if it was not.
1986 See the section below on error handling for more information about
1990 Expires: 8 April 2000 [Page 35]
1993 C LDAP API C LDAP Application Program Interface 8 October 1999
1996 possible errors and how to interpret them.
1998 The ldap_modify_ext() and ldap_modify_ext_s() functions support LDAPv3
1999 server controls and client controls.
2002 11.11. Modifying the Name of an Entry
2004 In LDAPv2, the ldap_modrdn(), ldap_modrdn_s(), ldap_modrdn2(), and
2005 ldap_modrdn2_s() routines were used to change the name of an LDAP entry.
2006 They could only be used to change the least significant component of a
2007 name (the RDN or relative distinguished name). LDAPv3 provides the
2008 Modify DN protocol operation that allows more general name change
2009 access. The ldap_rename() and ldap_rename_s() routines are used to
2010 change the name of an entry, and the use of the ldap_modrdn(),
2011 ldap_modrdn_s(), ldap_modrdn2(), and ldap_modrdn2_s() routines is depre-
2018 const char *newparent,
2020 LDAPControl **serverctrls,
2021 LDAPControl **clientctrls,
2029 const char *newparent,
2031 LDAPControl **serverctrls,
2032 LDAPControl **clientctrls
2035 The use of the following routines is deprecated and more complete
2036 descriptions can be found in RFC 1823:
2047 Expires: 8 April 2000 [Page 36]
2050 C LDAP API C LDAP Application Program Interface 8 October 1999
2072 ld The session handle.
2074 dn The name of the entry whose DN is to be changed.
2076 newrdn The new RDN to give the entry.
2078 newparent The new parent, or superior entry. If this parameter is
2079 NULL, only the RDN of the entry is changed. The root DN
2080 SHOULD be specified by passing a zero length string, "".
2081 The newparent parameter SHOULD always be NULL when using
2082 version 2 of the LDAP protocol; otherwise the server's
2083 behavior is undefined.
2085 deleteoldrdn This parameter only has meaning on the rename routines if
2086 newrdn is different than the old RDN. It is a boolean
2087 value, if non-zero indicating that the old RDN value(s) is
2088 to be removed, if zero indicating that the old RDN value(s)
2089 is to be retained as non-distinguished values of the entry.
2091 serverctrls List of LDAP server controls.
2093 clientctrls List of client controls.
2095 msgidp This result parameter will be set to the message id of the
2096 request if the ldap_rename() call succeeds.
2098 The ldap_rename() function initiates an asynchronous modify DN operation
2099 and returns the constant LDAP_SUCCESS if the request was successfully
2100 sent, or another LDAP error code if not. See the section below on error
2104 Expires: 8 April 2000 [Page 37]
2107 C LDAP API C LDAP Application Program Interface 8 October 1999
2110 handling for more information about possible errors and how to interpret
2111 them. If successful, ldap_rename() places the DN message id of the
2112 request in *msgidp. A subsequent call to ldap_result(), described below,
2113 can be used to obtain the result of the rename.
2115 The synchronous ldap_rename_s() returns the result of the operation,
2116 either the constant LDAP_SUCCESS if the operation was successful, or
2117 another LDAP error code if it was not. See the section below on error
2118 handling for more information about possible errors and how to interpret
2121 The ldap_rename() and ldap_rename_s() functions both support LDAPv3
2122 server controls and client controls.
2125 11.12. Adding an entry
2127 The following functions are used to add entries to the LDAP directory.
2128 There are four variations:
2134 LDAPControl **serverctrls,
2135 LDAPControl **clientctrls,
2143 LDAPControl **serverctrls,
2144 LDAPControl **clientctrls
2161 Expires: 8 April 2000 [Page 38]
2164 C LDAP API C LDAP Application Program Interface 8 October 1999
2169 ld The session handle.
2171 dn The name of the entry to add.
2173 attrs The entry's attributes, specified using the LDAPMod struc-
2174 ture defined for ldap_modify(). The mod_type and mod_vals
2175 fields MUST be filled in. The mod_op field is ignored
2176 unless ORed with the constant LDAP_MOD_BVALUES, used to
2177 select the mod_bvalues case of the mod_vals union.
2179 serverctrls List of LDAP server controls.
2181 clientctrls List of client controls.
2183 msgidp This result parameter will be set to the message id of the
2184 request if the ldap_add_ext() call succeeds.
2186 Note that the parent of the entry being added must already exist or the
2187 parent must be empty (i.e., equal to the root DN) for an add to succeed.
2189 The ldap_add_ext() function initiates an asynchronous add operation and
2190 returns the constant LDAP_SUCCESS if the request was successfully sent,
2191 or another LDAP error code if not. See the section below on error han-
2192 dling for more information about possible errors and how to interpret
2193 them. If successful, ldap_add_ext() places the message id of the
2194 request in *msgidp. A subsequent call to ldap_result(), described below,
2195 can be used to obtain the result of the add.
2197 Similar to ldap_add_ext(), the ldap_add() function initiates an asyn-
2198 chronous add operation and returns the message id of the operation ini-
2199 tiated. As for ldap_add_ext(), a subsequent call to ldap_result(),
2200 described below, can be used to obtain the result of the add. In case of
2201 error, ldap_add() will return -1, setting the session error parameters
2202 in the LDAP structure appropriately.
2204 The synchronous ldap_add_ext_s() and ldap_add_s() functions both return
2205 the result of the operation, either the constant LDAP_SUCCESS if the
2206 operation was successful, or another LDAP error code if it was not. See
2207 the section below on error handling for more information about possible
2208 errors and how to interpret them.
2210 The ldap_add_ext() and ldap_add_ext_s() functions support LDAPv3 server
2211 controls and client controls.
2218 Expires: 8 April 2000 [Page 39]
2221 C LDAP API C LDAP Application Program Interface 8 October 1999
2224 11.13. Deleting an entry
2226 The following functions are used to delete a leaf entry from the LDAP
2227 directory. There are four variations:
2229 int ldap_delete_ext(
2232 LDAPControl **serverctrls,
2233 LDAPControl **clientctrls,
2237 int ldap_delete_ext_s(
2240 LDAPControl **serverctrls,
2241 LDAPControl **clientctrls
2256 ld The session handle.
2258 dn The name of the entry to delete.
2260 serverctrls List of LDAP server controls.
2262 clientctrls List of client controls.
2264 msgidp This result parameter will be set to the message id of the
2265 request if the ldap_delete_ext() call succeeds.
2267 Note that the entry to delete must be a leaf entry (i.e., it must have
2268 no children). Deletion of entire subtrees in a single operation is not
2271 The ldap_delete_ext() function initiates an asynchronous delete
2275 Expires: 8 April 2000 [Page 40]
2278 C LDAP API C LDAP Application Program Interface 8 October 1999
2281 operation and returns the constant LDAP_SUCCESS if the request was suc-
2282 cessfully sent, or another LDAP error code if not. See the section
2283 below on error handling for more information about possible errors and
2284 how to interpret them. If successful, ldap_delete_ext() places the mes-
2285 sage id of the request in *msgidp. A subsequent call to ldap_result(),
2286 described below, can be used to obtain the result of the delete.
2288 Similar to ldap_delete_ext(), the ldap_delete() function initiates an
2289 asynchronous delete operation and returns the message id of the opera-
2290 tion initiated. As for ldap_delete_ext(), a subsequent call to
2291 ldap_result(), described below, can be used to obtain the result of the
2292 delete. In case of error, ldap_delete() will return -1, setting the ses-
2293 sion error parameters in the LDAP structure appropriately.
2295 The synchronous ldap_delete_ext_s() and ldap_delete_s() functions both
2296 return the result of the operation, either the constant LDAP_SUCCESS if
2297 the operation was successful, or another LDAP error code if it was not.
2298 See the section below on error handling for more information about pos-
2299 sible errors and how to interpret them.
2301 The ldap_delete_ext() and ldap_delete_ext_s() functions support LDAPv3
2302 server controls and client controls.
2305 11.14. Extended Operations
2307 The ldap_extended_operation() and ldap_extended_operation_s() routines
2308 allow extended LDAP operations to be passed to the server, providing a
2309 general protocol extensibility mechanism.
2311 int ldap_extended_operation(
2313 const char *requestoid,
2314 const struct berval *requestdata,
2315 LDAPControl **serverctrls,
2316 LDAPControl **clientctrls,
2320 int ldap_extended_operation_s(
2322 const char *requestoid,
2323 const struct berval *requestdata,
2324 LDAPControl **serverctrls,
2325 LDAPControl **clientctrls,
2327 struct berval **retdatap
2332 Expires: 8 April 2000 [Page 41]
2335 C LDAP API C LDAP Application Program Interface 8 October 1999
2340 ld The session handle.
2342 requestoid The dotted-OID text string naming the request.
2344 requestdata The arbitrary data needed by the operation (if NULL, no
2345 data is sent to the server).
2347 serverctrls List of LDAP server controls.
2349 clientctrls List of client controls.
2351 msgidp This result parameter will be set to the message id of the
2352 request if the ldap_extended_operation() call succeeds.
2354 retoidp Pointer to a character string that will be set to an allo-
2355 cated, dotted-OID text string returned by the server. This
2356 string SHOULD be disposed of using the ldap_memfree() func-
2357 tion. If no OID was returned, *retoidp is set to NULL.
2359 retdatap Pointer to a berval structure pointer that will be set an
2360 allocated copy of the data returned by the server. This
2361 struct berval SHOULD be disposed of using ber_bvfree(). If
2362 no data is returned, *retdatap is set to NULL.
2364 The ldap_extended_operation() function initiates an asynchronous
2365 extended operation and returns the constant LDAP_SUCCESS if the request
2366 was successfully sent, or another LDAP error code if not. See the sec-
2367 tion below on error handling for more information about possible errors
2368 and how to interpret them. If successful, ldap_extended_operation()
2369 places the message id of the request in *msgidp. A subsequent call to
2370 ldap_result(), described below, can be used to obtain the result of the
2371 extended operation which can be passed to ldap_parse_extended_result()
2372 to obtain the OID and data contained in the response.
2374 The synchronous ldap_extended_operation_s() function returns the result
2375 of the operation, either the constant LDAP_SUCCESS if the operation was
2376 successful, or another LDAP error code if it was not. See the section
2377 below on error handling for more information about possible errors and
2378 how to interpret them. The retoid and retdata parameters are filled in
2379 with the OID and data from the response. If no OID or data was
2380 returned, these parameters are set to NULL.
2382 The ldap_extended_operation() and ldap_extended_operation_s() functions
2383 both support LDAPv3 server controls and client controls.
2389 Expires: 8 April 2000 [Page 42]
2392 C LDAP API C LDAP Application Program Interface 8 October 1999
2395 12. Abandoning An Operation
2397 The following calls are used to abandon an operation in progress:
2399 int ldap_abandon_ext(
2402 LDAPControl **serverctrls,
2403 LDAPControl **clientctrls
2412 ld The session handle.
2414 msgid The message id of the request to be abandoned.
2416 serverctrls List of LDAP server controls.
2418 clientctrls List of client controls.
2420 ldap_abandon_ext() abandons the operation with message id msgid and
2421 returns the constant LDAP_SUCCESS if the abandon was successful or
2422 another LDAP error code if not. See the section below on error handling
2423 for more information about possible errors and how to interpret them.
2425 ldap_abandon() is identical to ldap_abandon_ext() except that it does
2426 not accept client or server controls and it returns zero if the abandon
2427 was successful, -1 otherwise.
2429 After a successful call to ldap_abandon() or ldap_abandon_ext(), results
2430 with the given message id are never returned from a subsequent call to
2431 ldap_result(). There is no server response to LDAP abandon operations.
2434 13. Obtaining Results and Peeking Inside LDAP Messages
2436 ldap_result() is used to obtain the result of a previous asynchronously
2437 initiated operation. Note that depending on how it is called,
2438 ldap_result() can actually return a list or "chain" of result messages.
2439 The ldap_result() function only returns messages for a single request,
2440 so for all LDAP operations other than search only one result message is
2441 expected; that is, the only time the "result chain" can contain more
2442 than one message is if results from a search operation are returned.
2446 Expires: 8 April 2000 [Page 43]
2449 C LDAP API C LDAP Application Program Interface 8 October 1999
2452 Once a chain of messages has been returned to the caller, it is no
2453 longer tied in any caller-visible way to the LDAP request that produced
2454 it. Therefore, a chain of messages returned by calling ldap_result() or
2455 by calling a synchronous search routine will never be affected by subse-
2456 quent LDAP API calls (except for ldap_msgfree() which is used to dispose
2457 of a chain of messages).
2459 ldap_msgfree() frees the result messages (possibly an entire chain of
2460 messages) obtained from a previous call to ldap_result() or from a call
2461 to a synchronous search routine.
2463 ldap_msgtype() returns the type of an LDAP message. ldap_msgid()
2464 returns the message ID of an LDAP message.
2470 struct timeval *timeout,
2474 int ldap_msgfree( LDAPMessage *res );
2476 int ldap_msgtype( LDAPMessage *res );
2478 int ldap_msgid( LDAPMessage *res );
2482 ld The session handle.
2484 msgid The message id of the operation whose results are to be
2485 returned, the constant LDAP_RES_UNSOLICITED (0) if an unsoli-
2486 cited result is desired, or or the constant LDAP_RES_ANY (-1)
2487 if any result is desired.
2489 all Specifies how many messages will be retrieved in a single call
2490 to ldap_result(). This parameter only has meaning for search
2491 results. Pass the constant LDAP_MSG_ONE (0x00) to retrieve one
2492 message at a time. Pass LDAP_MSG_ALL (0x01) to request that
2493 all results of a search be received before returning all
2494 results in a single chain. Pass LDAP_MSG_RECEIVED (0x02) to
2495 indicate that all messages retrieved so far are to be returned
2496 in the result chain.
2498 timeout A timeout specifying how long to wait for results to be
2499 returned. A NULL value causes ldap_result() to block until
2503 Expires: 8 April 2000 [Page 44]
2506 C LDAP API C LDAP Application Program Interface 8 October 1999
2509 results are available. A timeout value of zero seconds speci-
2510 fies a polling behavior.
2512 res For ldap_result(), a result parameter that will contain the
2513 result(s) of the operation. If no results are returned, *res is
2514 set to NULL. For ldap_msgfree(), the result chain to be freed,
2515 obtained from a previous call to ldap_result(),
2516 ldap_search_s(), or ldap_search_st(). If res is NULL, nothing
2517 is done and ldap_msgfree() returns zero.
2519 Upon successful completion, ldap_result() returns the type of the first
2520 result returned in the res parameter. This will be one of the following
2523 LDAP_RES_BIND (0x61)
2524 LDAP_RES_SEARCH_ENTRY (0x64)
2525 LDAP_RES_SEARCH_REFERENCE (0x73) -- new in LDAPv3
2526 LDAP_RES_SEARCH_RESULT (0x65)
2527 LDAP_RES_MODIFY (0x67)
2529 LDAP_RES_DELETE (0x6B)
2530 LDAP_RES_MODDN (0x6D)
2531 LDAP_RES_COMPARE (0x6F)
2532 LDAP_RES_EXTENDED (0x78) -- new in LDAPv3
2534 ldap_result() returns 0 if the timeout expired and -1 if an error
2535 occurs, in which case the error parameters of the LDAP session handle
2536 will be set accordingly.
2538 ldap_msgfree() frees each message in the result chain pointed to by res
2539 and returns the type of the last message in the chain. If res is NULL,
2540 nothing is done and the value zero is returned.
2542 ldap_msgtype() returns the type of the LDAP message it is passed as a
2543 parameter. The type will be one of the types listed above, or -1 on
2546 ldap_msgid() returns the message ID associated with the LDAP message
2547 passed as a parameter, or -1 on error.
2550 14. Handling Errors and Parsing Results
2552 The following calls are used to extract information from results and
2553 handle errors returned by other LDAP API routines. Note that
2554 ldap_parse_sasl_bind_result() and ldap_parse_extended_result() must typ-
2555 ically be used in addition to ldap_parse_result() to retrieve all the
2556 result information from SASL Bind and Extended Operations respectively.
2560 Expires: 8 April 2000 [Page 45]
2563 C LDAP API C LDAP Application Program Interface 8 October 1999
2566 int ldap_parse_result(
2573 LDAPControl ***serverctrlsp,
2577 int ldap_parse_sasl_bind_result(
2580 struct berval **servercredp,
2584 int ldap_parse_extended_result(
2588 struct berval **retdatap,
2592 #define LDAP_NOTICE_OF_DISCONNECTION "1.3.6.1.4.1.1466.20036"
2594 char *ldap_err2string( int err );
2596 The use of the following routines is deprecated and more complete
2597 descriptions can be found in RFC 1823:
2599 int ldap_result2error(
2605 void ldap_perror( LDAP *ld, const char *msg );
2609 ld The session handle.
2611 res The result of an LDAP operation as returned by
2612 ldap_result() or one of the synchronous API operation
2617 Expires: 8 April 2000 [Page 46]
2620 C LDAP API C LDAP Application Program Interface 8 October 1999
2623 errcodep This result parameter will be filled in with the LDAP error
2624 code field from the LDAPMessage message. This is the indi-
2625 cation from the server of the outcome of the operation.
2626 NULL SHOULD be passed to ignore this field.
2628 matcheddnp In the case of a return of LDAP_NO_SUCH_OBJECT, this result
2629 parameter will be filled in with a DN indicating how much
2630 of the name in the request was recognized. NULL SHOULD be
2631 passed to ignore this field. The matched DN string SHOULD
2632 be freed by calling ldap_memfree() which is described later
2635 errmsgp This result parameter will be filled in with the contents
2636 of the error message field from the LDAPMessage message.
2637 The error message string SHOULD be freed by calling
2638 ldap_memfree() which is described later in this document.
2639 NULL SHOULD be passed to ignore this field.
2641 referralsp This result parameter will be filled in with the contents
2642 of the referrals field from the LDAPMessage message, indi-
2643 cating zero or more alternate LDAP servers where the
2644 request is to be retried. The referrals array SHOULD be
2645 freed by calling ldap_value_free() which is described later
2646 in this document. NULL SHOULD be passed to ignore this
2649 serverctrlsp This result parameter will be filled in with an allocated
2650 array of controls copied out of the LDAPMessage message.
2651 The control array SHOULD be freed by calling
2652 ldap_controls_free() which was described earlier.
2654 freeit A boolean that determines whether the res parameter is
2655 disposed of or not. Pass any non-zero value to have these
2656 routines free res after extracting the requested informa-
2657 tion. This is provided as a convenience; you can also use
2658 ldap_msgfree() to free the result later. If freeit is
2659 non-zero, the entire chain of messages represented by res
2662 servercredp For SASL bind results, this result parameter will be filled
2663 in with the credentials passed back by the server for
2664 mutual authentication, if given. An allocated berval struc-
2665 ture is returned that SHOULD be disposed of by calling
2666 ber_bvfree(). NULL SHOULD be passed to ignore this field.
2668 retoidp For extended results, this result parameter will be filled
2669 in with the dotted-OID text representation of the name of
2670 the extended operation response. This string SHOULD be
2674 Expires: 8 April 2000 [Page 47]
2677 C LDAP API C LDAP Application Program Interface 8 October 1999
2680 disposed of by calling ldap_memfree(). NULL SHOULD be
2681 passed to ignore this field. The
2682 LDAP_NOTICE_OF_DISCONNECTION macro is defined as a conveni-
2683 ence for clients that wish to check an OID to see if it
2684 matches the one used for the unsolicited Notice of Discon-
2685 nection (defined in RFC 2251[2] section 4.4.1).
2687 retdatap For extended results, this result parameter will be filled
2688 in with a pointer to a struct berval containing the data in
2689 the extended operation response. It SHOULD be disposed of
2690 by calling ber_bvfree(). NULL SHOULD be passed to ignore
2693 err For ldap_err2string(), an LDAP error code, as returned by
2694 ldap_parse_result() or another LDAP API call.
2696 Additional parameters for the deprecated routines are not described.
2697 Interested readers are referred to RFC 1823.
2699 The ldap_parse_result(), ldap_parse_sasl_bind_result(), and
2700 ldap_parse_extended_result() functions all skip over messages of type
2701 LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_REFERENCE when looking for a
2702 result message to parse. They return the constant LDAP_SUCCESS if the
2703 result was successfully parsed and another LDAP error code if not. Note
2704 that the LDAP error code that indicates the outcome of the operation
2705 performed by the server is placed in the errcodep ldap_parse_result()
2706 parameter. If a chain of messages that contains more than one result
2707 message is passed to these routines they always operate on the first
2708 result in the chain.
2710 ldap_err2string() is used to convert a numeric LDAP error code, as
2711 returned by ldap_parse_result(), ldap_parse_sasl_bind_result(),
2712 ldap_parse_extended_result() or one of the synchronous API operation
2713 calls, into an informative zero-terminated character string message
2714 describing the error. It returns a pointer to static data.
2717 15. Stepping Through a List of Results
2719 The ldap_first_message() and ldap_next_message() routines are used to
2720 step through the list of messages in a result chain returned by
2721 ldap_result(). For search operations, the result chain can actually
2722 include referral messages, entry messages, and result messages.
2723 ldap_count_messages() is used to count the number of messages returned.
2724 The ldap_msgtype() function, described above, can be used to distinguish
2725 between the different message types.
2727 LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *res );
2731 Expires: 8 April 2000 [Page 48]
2734 C LDAP API C LDAP Application Program Interface 8 October 1999
2737 LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *msg );
2739 int ldap_count_messages( LDAP *ld, LDAPMessage *res );
2743 ld The session handle.
2745 res The result chain, as obtained by a call to one of the synchronous
2746 search routines or ldap_result().
2748 msg The message returned by a previous call to ldap_first_message()
2749 or ldap_next_message().
2751 ldap_first_message() and ldap_next_message() will return NULL when no
2752 more messages exist in the result set to be returned. NULL is also
2753 returned if an error occurs while stepping through the entries, in which
2754 case the error parameters in the session handle ld will be set to indi-
2757 If successful, ldap_count_messages() returns the number of messages con-
2758 tained in a chain of results; if an error occurs such as the res parame-
2759 ter being invalid, -1 is returned. The ldap_count_messages() call can
2760 also be used to count the number of messages that remain in a chain if
2761 called with a message, entry, or reference returned by
2762 ldap_first_message(), ldap_next_message(), ldap_first_entry(),
2763 ldap_next_entry(), ldap_first_reference(), ldap_next_reference().
2766 16. Parsing Search Results
2768 The following calls are used to parse the entries and references
2769 returned by ldap_search() and friends. These results are returned in an
2770 opaque structure that MAY be accessed by calling the routines described
2771 below. Routines are provided to step through the entries and references
2772 returned, step through the attributes of an entry, retrieve the name of
2773 an entry, and retrieve the values associated with a given attribute in
2777 16.1. Stepping Through a List of Entries or References
2779 The ldap_first_entry() and ldap_next_entry() routines are used to step
2780 through and retrieve the list of entries from a search result chain.
2781 The ldap_first_reference() and ldap_next_reference() routines are used
2782 to step through and retrieve the list of continuation references from a
2783 search result chain. ldap_count_entries() is used to count the number
2784 of entries returned. ldap_count_references() is used to count the number
2788 Expires: 8 April 2000 [Page 49]
2791 C LDAP API C LDAP Application Program Interface 8 October 1999
2794 of references returned.
2796 LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *res );
2798 LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry );
2800 LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *res );
2802 LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *ref );
2804 int ldap_count_entries( LDAP *ld, LDAPMessage *res );
2806 int ldap_count_references( LDAP *ld, LDAPMessage *res );
2810 ld The session handle.
2812 res The search result, as obtained by a call to one of the synchro-
2813 nous search routines or ldap_result().
2815 entry The entry returned by a previous call to ldap_first_entry() or
2818 ref The reference returned by a previous call to
2819 ldap_first_reference() or ldap_next_reference().
2821 ldap_first_entry(), ldap_next_entry(), ldap_first_reference() and
2822 ldap_next_reference() all return NULL when no more entries or references
2823 exist in the result set to be returned. NULL is also returned if an
2824 error occurs while stepping through the entries or references, in which
2825 case the error parameters in the session handle ld will be set to indi-
2828 ldap_count_entries() returns the number of entries contained in a chain
2829 of entries; if an error occurs such as the res parameter being invalid,
2830 -1 is returned. The ldap_count_entries() call can also be used to count
2831 the number of entries that remain in a chain if called with a message,
2832 entry or reference returned by ldap_first_message(),
2833 ldap_next_message(), ldap_first_entry(), ldap_next_entry(),
2834 ldap_first_reference(), ldap_next_reference().
2836 ldap_count_references() returns the number of references contained in a
2837 chain of search results; if an error occurs such as the res parameter
2838 being invalid, -1 is returned. The ldap_count_references() call can
2839 also be used to count the number of references that remain in a chain.
2845 Expires: 8 April 2000 [Page 50]
2848 C LDAP API C LDAP Application Program Interface 8 October 1999
2851 16.2. Stepping Through the Attributes of an Entry
2853 The ldap_first_attribute() and ldap_next_attribute() calls are used to
2854 step through the list of attribute types returned with an entry.
2856 char *ldap_first_attribute(
2862 char *ldap_next_attribute(
2868 void ldap_memfree( char *mem );
2872 ld The session handle.
2874 entry The entry whose attributes are to be stepped through, as returned
2875 by ldap_first_entry() or ldap_next_entry().
2877 ptr In ldap_first_attribute(), the address of a pointer used inter-
2878 nally to keep track of the current position in the entry. In
2879 ldap_next_attribute(), the pointer returned by a previous call to
2880 ldap_first_attribute(). The BerElement type itself is an opaque
2881 structure that is described in more detail later in this document
2882 in the section "Encoded ASN.1 Value Manipulation".
2884 mem A pointer to memory allocated by the LDAP library, such as the
2885 attribute type names returned by ldap_first_attribute() and
2886 ldap_next_attribute, or the DN returned by ldap_get_dn(). If mem
2887 is NULL, the ldap_memfree() call does nothing.
2889 ldap_first_attribute() and ldap_next_attribute() will return NULL when
2890 the end of the attributes is reached, or if there is an error, in which
2891 case the error parameters in the session handle ld will be set to indi-
2894 Both routines return a pointer to an allocated buffer containing the
2895 current attribute name. This SHOULD be freed when no longer in use by
2896 calling ldap_memfree().
2898 ldap_first_attribute() will allocate and return in ptr a pointer to a
2902 Expires: 8 April 2000 [Page 51]
2905 C LDAP API C LDAP Application Program Interface 8 October 1999
2908 BerElement used to keep track of the current position. This pointer MAY
2909 be passed in subsequent calls to ldap_next_attribute() to step through
2910 the entry's attributes. After a set of calls to ldap_first_attribute()
2911 and ldap_next_attribute(), if ptr is non-NULL, it SHOULD be freed by
2912 calling ber_free( ptr, 0 ). Note that it is very important to pass the
2913 second parameter as 0 (zero) in this call, since the buffer associated
2914 with the BerElement does not point to separately allocated memory.
2916 The attribute type names returned are suitable for passing in a call to
2917 ldap_get_values() and friends to retrieve the associated values.
2920 16.3. Retrieving the Values of an Attribute
2922 ldap_get_values() and ldap_get_values_len() are used to retrieve the
2923 values of a given attribute from an entry. ldap_count_values() and
2924 ldap_count_values_len() are used to count the returned values.
2925 ldap_value_free() and ldap_value_free_len() are used to free the values.
2927 char **ldap_get_values(
2933 struct berval **ldap_get_values_len(
2939 int ldap_count_values( char **vals );
2941 int ldap_count_values_len( struct berval **vals );
2943 void ldap_value_free( char **vals );
2945 void ldap_value_free_len( struct berval **vals );
2949 ld The session handle.
2951 entry The entry from which to retrieve values, as returned by
2952 ldap_first_entry() or ldap_next_entry().
2954 attr The attribute whose values are to be retrieved, as returned by
2955 ldap_first_attribute() or ldap_next_attribute(), or a caller-
2959 Expires: 8 April 2000 [Page 52]
2962 C LDAP API C LDAP Application Program Interface 8 October 1999
2965 supplied string (e.g., "mail").
2967 vals The values returned by a previous call to ldap_get_values() or
2968 ldap_get_values_len().
2970 Two forms of the various calls are provided. The first form is only
2971 suitable for use with non-binary character string data. The second _len
2972 form is used with any kind of data.
2974 ldap_get_values() and ldap_get_values_len() return NULL if no values are
2975 found for attr or if an error occurs.
2977 ldap_count_values() and ldap_count_values_len() return -1 if an error
2978 occurs such as the vals parameter being invalid.
2980 If a NULL vals parameter is passed to ldap_value_free() or
2981 ldap_value_free_len(), nothing is done.
2983 Note that the values returned are dynamically allocated and SHOULD be
2984 freed by calling either ldap_value_free() or ldap_value_free_len() when
2988 16.4. Retrieving the name of an entry
2990 ldap_get_dn() is used to retrieve the name of an entry.
2991 ldap_explode_dn() and ldap_explode_rdn() are used to break up a name
2992 into its component parts. ldap_dn2ufn() is used to convert the name into
2993 a more "user friendly" format.
2995 char *ldap_get_dn( LDAP *ld, LDAPMessage *entry );
2997 char **ldap_explode_dn( const char *dn, int notypes );
2999 char **ldap_explode_rdn( const char *rdn, int notypes );
3001 char *ldap_dn2ufn( const char *dn );
3005 ld The session handle.
3007 entry The entry whose name is to be retrieved, as returned by
3008 ldap_first_entry() or ldap_next_entry().
3010 dn The dn to explode, such as returned by ldap_get_dn().
3012 rdn The rdn to explode, such as returned in the components of the
3016 Expires: 8 April 2000 [Page 53]
3019 C LDAP API C LDAP Application Program Interface 8 October 1999
3022 array returned by ldap_explode_dn().
3024 notypes A boolean parameter, if non-zero indicating that the dn or rdn
3025 components are to have their type information stripped off
3026 (i.e., "cn=Babs" would become "Babs").
3028 ldap_get_dn() will return NULL if there is some error parsing the dn,
3029 setting error parameters in the session handle ld to indicate the error.
3030 It returns a pointer to newly allocated space that the caller SHOULD
3031 free by calling ldap_memfree() when it is no longer in use. Note the
3032 format of the DNs returned is given by [5].
3034 ldap_explode_dn() returns a NULL-terminated char * array containing the
3035 RDN components of the DN supplied, with or without types as indicated by
3036 the notypes parameter. The components are returned in the order they
3037 appear in the dn. The array returned SHOULD be freed when it is no
3038 longer in use by calling ldap_value_free().
3040 ldap_explode_rdn() returns a NULL-terminated char * array containing the
3041 components of the RDN supplied, with or without types as indicated by
3042 the notypes parameter. The components are returned in the order they
3043 appear in the rdn. The array returned SHOULD be freed when it is no
3044 longer in use by calling ldap_value_free().
3046 ldap_dn2ufn() converts the DN into the user friendly format described in
3047 [14]. The UFN returned is newly allocated space that SHOULD be freed by
3048 a call to ldap_memfree() when no longer in use.
3051 16.5. Retrieving controls from an entry
3053 ldap_get_entry_controls() is used to extract LDAP controls from an
3057 int ldap_get_entry_controls(
3060 LDAPControl ***serverctrlsp
3065 ld The session handle.
3067 entry The entry to extract controls from, as returned by
3068 ldap_first_entry() or ldap_next_entry().
3073 Expires: 8 April 2000 [Page 54]
3076 C LDAP API C LDAP Application Program Interface 8 October 1999
3079 serverctrlsp This result parameter will be filled in with an allocated
3080 array of controls copied out of entry. The control array
3081 SHOULD be freed by calling ldap_controls_free(). If ser-
3082 verctrlsp is NULL, no controls are returned.
3084 ldap_get_entry_controls() returns an LDAP error code that indicates
3085 whether the reference could be successfully parsed (LDAP_SUCCESS if all
3090 16.6. Parsing References
3092 ldap_parse_reference() is used to extract referrals and controls from a
3093 SearchResultReference message.
3096 int ldap_parse_reference(
3100 LDAPControl ***serverctrlsp,
3106 ld The session handle.
3108 ref The reference to parse, as returned by ldap_result(),
3109 ldap_first_reference(), or ldap_next_reference().
3111 referralsp This result parameter will be filled in with an allocated
3112 array of character strings. The elements of the array are
3113 the referrals (typically LDAP URLs) contained in ref. The
3114 array SHOULD be freed when no longer in used by calling
3115 ldap_value_free(). If referralsp is NULL, the referral
3116 URLs are not returned.
3118 serverctrlsp This result parameter will be filled in with an allocated
3119 array of controls copied out of ref. The control array
3120 SHOULD be freed by calling ldap_controls_free(). If ser-
3121 verctrlsp is NULL, no controls are returned.
3123 freeit A boolean that determines whether the ref parameter is
3124 disposed of or not. Pass any non-zero value to have this
3125 routine free ref after extracting the requested informa-
3126 tion. This is provided as a convenience; you can also use
3130 Expires: 8 April 2000 [Page 55]
3133 C LDAP API C LDAP Application Program Interface 8 October 1999
3136 ldap_msgfree() to free the result later.
3138 ldap_parse_reference() returns an LDAP error code that indicates whether
3139 the reference could be successfully parsed (LDAP_SUCCESS if all goes
3143 17. Encoded ASN.1 Value Manipulation
3145 This section describes routines which MAY be used to encode and decode
3146 BER-encoded ASN.1 values, which are often used inside of control and
3149 With the exceptions of two new functions ber_flatten() and ber_init(),
3150 these functions are compatible with the University of Michigan LDAP 3.3
3151 implementation of BER.
3153 Note that the functions defined in this section all provide a method for
3154 determining success or failure but generally do not provide access to
3155 specific error codes. Therefore, applications that require precise
3156 error information when encoding or decoding ASN.1 values SHOULD NOT use
3160 17.1. BER Data Structures and Types
3162 The following additional integral types are defined for use in manipula-
3163 tion of BER encoded ASN.1 values:
3164 typedef impl_tag_t ber_tag_t; /* for BER tags */
3166 typedef impl_int_t ber_int_t; /* for BER ints, enums, and Booleans */
3168 typedef impl_unit_t ber_uint_t; /* unsigned equivalent of ber_int_t */
3170 typedef impl_slen_t ber_slen_t; /* signed equivalent of ber_len_t */
3172 Note that the actual definition for these four integral types is imple-
3173 mentation specific; that is, `impl_tag_t', `impl_int_t', `impl_uint_t',
3174 and `impl_slen_t' MUST each be replaced with an appropriate
3175 implementation-specific type.
3177 The `ber_tag_t' type is an unsigned integral data type that is large
3178 enough to hold the largest BER tag supported by the API implementation.
3179 The width (number of significant bits) of `ber_tag_t' MUST be at least
3180 32, greater than or equal to that of `unsigned int' (so that integer
3181 promotions won't promote it to `int'), and no wider than that of
3187 Expires: 8 April 2000 [Page 56]
3190 C LDAP API C LDAP Application Program Interface 8 October 1999
3193 The `ber_int_t' and `ber_uint_t' types are the signed and unsigned vari-
3194 ants of an integral type that is large enough to hold integers for pur-
3195 poses of BER encoding and decoding. The width of `ber_int_t' MUST be at
3196 least 32 and no larger than that of `long'. The width (number of signi-
3197 ficant bits) of `ber_uint_t' MUST be at least 32 and no larger than that
3198 of `unsigned long'. Note that the `ber_uint_t' type is not used
3199 directly in the C LDAP API but is provided for the convenience of appli-
3200 cation developers and for use by extensions to the API.
3202 The `ber_slen_t' type is the signed variant of the `ber_len_t' integral
3203 type that is large enough to contain the length of the largest piece of
3204 data supported by the API implementation. The `impl_slen_t' in the
3205 `ber_len_t' typedef MUST be replaced with an appropriate type. The
3206 width of `ber_slen_t' MUST be at least 32 and no larger than that of
3207 `unsigned long'. Note that `ber_slen_t' is not used directly in the C
3208 LDAP API but is provided for the convenience of application developers
3209 and for use by extensions to the API.
3211 typedef struct berval {
3216 As defined earlier in the section "Common Data Structures", a berval
3217 structure contains an arbitrary sequence of bytes and an indication of
3218 its length. The bv_len element is an unsigned integer. The bv_val is
3219 not necessarily zero-terminated. Applications MAY allocate their own
3222 As defined earlier in the section "Common Data Structures", the BerEle-
3223 ment structure is an opaque structure:
3225 typedef struct berelement BerElement;
3227 It contains not only a copy of the encoded value, but also state infor-
3228 mation used in encoding or decoding. Applications cannot allocate their
3229 own BerElement structures. The internal state is neither thread-
3230 specific nor locked, so two threads SHOULD NOT manipulate the same
3231 BerElement value simultaneously.
3233 A single BerElement value cannot be used for both encoding and decoding.
3235 17.2. Memory Disposal and Utility Functions
3237 void ber_bvfree( struct berval *bv );
3239 ber_bvfree() frees a berval structure returned from this API. Both the
3240 bv->bv_val string and the berval structure itself are freed. If bv is
3244 Expires: 8 April 2000 [Page 57]
3247 C LDAP API C LDAP Application Program Interface 8 October 1999
3250 NULL, this call does nothing.
3252 void ber_bvecfree( struct berval **bv );
3254 ber_bvecfree() frees an array of berval structures returned from this
3255 API. Each of the berval structures in the array are freed using
3256 ber_bvfree(), then the array itself is freed. If bv is NULL, this call
3259 struct berval *ber_bvdup( const struct berval *bv );
3261 ber_bvdup() returns a copy of a berval structure. The bv_val field in
3262 the returned berval structure points to a different area of memory than
3263 the bv_val field in the bv argument. The NULL pointer is returned on
3264 error (e.g. out of memory).
3266 void ber_free( BerElement *ber, int fbuf );
3268 ber_free() frees a BerElement which is returned from the API calls
3269 ber_alloc_t() or ber_init(). Each BerElement SHOULD be freed by the
3270 caller. The second argument fbuf SHOULD always be set to 1 to ensure
3271 that the internal buffer used by the BER functions is freed as well as
3272 the BerElement container itself. If ber is NULL, this call does noth-
3278 BerElement *ber_alloc_t( int options );
3280 ber_alloc_t() constructs and returns BerElement. The NULL pointer is
3281 returned on error. The options field contains a bitwise-or of options
3282 which are to be used when generating the encoding of this BerElement.
3283 One option is defined and SHOULD always be supplied:
3285 #define LBER_USE_DER 0x01
3287 When this option is present, lengths will always be encoded in the
3288 minimum number of octets. Note that this option does not cause values
3289 of sets to be rearranged in tag and byte order or default values to be
3290 removed, so these functions are not sufficient for generating DER output
3291 as defined in X.509 and X.680. If the caller takes responsibility for
3292 ordering values of sets correctly and removing default values, DER out-
3293 put as defined in X.509 and X.680 can be produced.
3295 Unrecognized option bits are ignored.
3297 The BerElement returned by ber_alloc_t() is initially empty. Calls to
3301 Expires: 8 April 2000 [Page 58]
3304 C LDAP API C LDAP Application Program Interface 8 October 1999
3307 ber_printf() will append bytes to the end of the ber_alloc_t().
3309 int ber_printf( BerElement *ber, const char *fmt, ... )
3311 The ber_printf() routine is used to encode a BER element in much the
3312 same way that sprintf() works. One important difference, though, is
3313 that state information is kept in the ber argument so that multiple
3314 calls can be made to ber_printf() to append to the end of the BER ele-
3315 ment. ber MUST be a pointer to a BerElement returned by ber_alloc_t().
3316 ber_printf() interprets and formats its arguments according to the for-
3317 mat string fmt. ber_printf() returns -1 if there is an error during
3318 encoding and a non-negative number if successful. As with sprintf(),
3319 each character in fmt refers to an argument to ber_printf().
3321 The format string can contain the following format characters:
3323 't' Tag. The next argument is a ber_tag_t specifying the tag to
3324 override the next element to be written to the ber. This works
3325 across calls. The integer tag value SHOULD contain the tag
3326 class, constructed bit, and tag value. For example, a tag of
3327 "[3]" for a constructed type is 0xA3U. All implementations MUST
3328 support tags that fit in a single octet (i.e., where the tag
3329 value is less than 32) and they MAY support larger tags.
3331 'b' Boolean. The next argument is an ber_int_t, containing either 0
3332 for FALSE or 0xff for TRUE. A boolean element is output. If
3333 this format character is not preceded by the 't' format modif-
3334 ier, the tag 0x01U is used for the element.
3336 'e' Enumerated. The next argument is a ber_int_t, containing the
3337 enumerated value in the host's byte order. An enumerated ele-
3338 ment is output. If this format character is not preceded by the
3339 't' format modifier, the tag 0x0AU is used for the element.
3341 'i' Integer. The next argument is a ber_int_t, containing the
3342 integer in the host's byte order. An integer element is output.
3343 If this format character is not preceded by the 't' format
3344 modifier, the tag 0x02U is used for the element.
3346 'B' Bitstring. The next two arguments are a char * pointer to the
3347 start of the bitstring, followed by a ber_len_t containing the
3348 number of bits in the bitstring. A bitstring element is output,
3349 in primitive form. If this format character is not preceded by
3350 the 't' format modifier, the tag 0x03U is used for the element.
3352 'n' Null. No argument is needed. An ASN.1 NULL element is output.
3353 If this format character is not preceded by the 't' format
3354 modifier, the tag 0x05U is used for the element.
3358 Expires: 8 April 2000 [Page 59]
3361 C LDAP API C LDAP Application Program Interface 8 October 1999
3364 'o' Octet string. The next two arguments are a char *, followed by
3365 a ber_len_t with the length of the string. The string MAY con-
3366 tain null bytes and are do not have to be zero-terminated. An
3367 octet string element is output, in primitive form. If this for-
3368 mat character is not preceded by the 't' format modifier, the
3369 tag 0x04U is used for the element.
3371 's' Octet string. The next argument is a char * pointing to a
3372 zero-terminated string. An octet string element in primitive
3373 form is output, which does not include the trailing '\0' (null)
3374 byte. If this format character is not preceded by the 't' format
3375 modifier, the tag 0x04U is used for the element.
3377 'v' Several octet strings. The next argument is a char **, an array
3378 of char * pointers to zero-terminated strings. The last element
3379 in the array MUST be a NULL pointer. The octet strings do not
3380 include the trailing '\0' (null) byte. Note that a construct
3381 like '{v}' is used to get an actual SEQUENCE OF octet strings.
3382 The 't' format modifier cannot be used with this format charac-
3385 'V' Several octet strings. A NULL-terminated array of struct berval
3386 *'s is supplied. Note that a construct like '{V}' is used to
3387 get an actual SEQUENCE OF octet strings. The 't' format modifier
3388 cannot be used with this format character.
3390 '{' Begin sequence. No argument is needed. If this format charac-
3391 ter is not preceded by the 't' format modifier, the tag 0x30U is
3394 '}' End sequence. No argument is needed. The 't' format modifier
3395 cannot be used with this format character.
3397 '[' Begin set. No argument is needed. If this format character is
3398 not preceded by the 't' format modifier, the tag 0x31U is used.
3400 ']' End set. No argument is needed. The 't' format modifier cannot
3401 be used with this format character.
3403 Each use of a '{' format character SHOULD be matched by a '}' character,
3404 either later in the format string, or in the format string of a subse-
3405 quent call to ber_printf() for that BerElement. The same applies to the
3406 '[' and ']' format characters.
3408 Sequences and sets nest, and implementations of this API MUST maintain
3409 internal state to be able to properly calculate the lengths.
3411 int ber_flatten( BerElement *ber, struct berval **bvPtr );
3415 Expires: 8 April 2000 [Page 60]
3418 C LDAP API C LDAP Application Program Interface 8 October 1999
3421 The ber_flatten routine allocates a struct berval whose contents are a
3422 BER encoding taken from the ber argument. The bvPtr pointer points to
3423 the returned berval structure, which SHOULD be freed using ber_bvfree().
3424 This routine returns 0 on success and -1 on error.
3426 The ber_flatten API call is not present in U-M LDAP 3.3.
3428 The use of ber_flatten on a BerElement in which all '{' and '}' format
3429 modifiers have not been properly matched is an error (i.e., -1 will be
3430 returned by ber_flatten() if this situation is exists).
3433 17.4. Encoding Example
3435 The following is an example of encoding the following ASN.1 data type:
3437 Example1Request ::= SEQUENCE {
3438 s OCTET STRING, -- must be printable
3440 val2 [0] INTEGER DEFAULT 0
3444 int encode_example1(const char *s, ber_int_t val1, ber_int_t val2,
3445 struct berval **bvPtr)
3450 ber = ber_alloc_t(LBER_USE_DER);
3452 if (ber == NULL) return -1;
3454 if (ber_printf(ber,"{si",s,val1) == -1) {
3459 if (ber_printf(ber,"ti",(ber_tag_t)0x80,val2) == -1) {
3464 if (ber_printf(ber,"}") == -1) {
3468 rc = ber_flatten(ber,bvPtr);
3472 Expires: 8 April 2000 [Page 61]
3475 C LDAP API C LDAP Application Program Interface 8 October 1999
3486 The following two macros are available to applications: LBER_ERROR and
3487 LBER_DEFAULT. Both of these macros MUST be #define'd as integer con-
3488 stants that are both compatible with the ber_tag_t type and for which
3489 all bits have the value one. For example, ISO C guarantees that these
3490 definitions will work:
3492 #define LBER_ERROR ((ber_tag_t)-1)
3493 #define LBER_DEFAULT ((ber_tag_t)-1)
3495 The intent is that LBER_ERROR and LBER_DEFAULT are both defined as the
3496 integer value that has all bits set to 1, as such a value is not a valid
3499 BerElement *ber_init( const struct berval *bv );
3501 The ber_init function constructs a BerElement and returns a new BerEle-
3502 ment containing a copy of the data in the bv argument. ber_init returns
3503 the NULL pointer on error.
3505 ber_tag_t ber_scanf( BerElement *ber, const char *fmt, ... );
3507 The ber_scanf() routine is used to decode a BER element in much the same
3508 way that sscanf() works. One important difference, though, is that some
3509 state information is kept with the ber argument so that multiple calls
3510 can be made to ber_scanf() to sequentially read from the BER element.
3511 The ber argument SHOULD be a pointer to a BerElement returned by
3512 ber_init(). ber_scanf interprets the bytes according to the format
3513 string fmt, and stores the results in its additional arguments.
3514 ber_scanf() returns LBER_ERROR on error, and a different value on suc-
3517 The format string contains conversion specifications which are used to
3518 direct the interpretation of the BER element. The format string can
3519 contain the following characters:
3521 'a' Octet string. A char ** argument MUST be supplied. Memory is
3522 allocated, filled with the contents of the octet string, zero-
3523 terminated, and the pointer to the string is stored in the argu-
3524 ment. The returned value SHOULD be freed using ldap_memfree.
3525 The tag of the element MUST indicate the primitive form
3529 Expires: 8 April 2000 [Page 62]
3532 C LDAP API C LDAP Application Program Interface 8 October 1999
3535 (constructed strings are not supported) but is otherwise ignored
3536 and discarded during the decoding. This format cannot be used
3537 with octet strings which could contain null bytes.
3539 'O' Octet string. A struct berval ** argument MUST be supplied,
3540 which upon return points to an allocated struct berval contain-
3541 ing the octet string and its length. ber_bvfree() SHOULD be
3542 called to free the allocated memory. The tag of the element
3543 MUST indicate the primitive form (constructed strings are not
3544 supported) but is otherwise ignored during the decoding.
3546 'b' Boolean. A pointer to a ber_int_t MUST be supplied. The
3547 ber_int_t value stored will be 0 for FALSE or nonzero for TRUE.
3548 The tag of the element MUST indicate the primitive form but is
3549 otherwise ignored during the decoding.
3551 'e' Enumerated. A pointer to a ber_int_t MUST be supplied. The
3552 enumerated value stored will be in host byte order. The tag of
3553 the element MUST indicate the primitive form but is otherwise
3554 ignored during the decoding. ber_scanf() will return an error
3555 if the value of the enumerated value cannot be stored in a
3558 'i' Integer. A pointer to a ber_int_t MUST be supplied. The
3559 ber_int_t value stored will be in host byte order. The tag of
3560 the element MUST indicate the primitive form but is otherwise
3561 ignored during the decoding. ber_scanf() will return an error
3562 if the integer cannot be stored in a ber_int_t.
3564 'B' Bitstring. A char ** argument MUST be supplied which will point
3565 to the allocated bits, followed by a ber_len_t * argument, which
3566 will point to the length (in bits) of the bitstring returned.
3567 ldap_memfree SHOULD be called to free the bitstring. The tag of
3568 the element MUST indicate the primitive form (constructed bit-
3569 strings are not supported) but is otherwise ignored during the
3572 'n' Null. No argument is needed. The element is verified to have a
3573 zero-length value and is skipped. The tag is ignored.
3575 't' Tag. A pointer to a ber_tag_t MUST be supplied. The ber_tag_t
3576 value stored will be the tag of the next element in the BerEle-
3577 ment ber, represented so it can be written using the 't' format
3578 of ber_printf(). The decoding position within the ber argument
3579 is unchanged by this; that is, the fact that the tag has been
3580 retrieved does not affect future use of ber.
3582 'v' Several octet strings. A char *** argument MUST be supplied,
3586 Expires: 8 April 2000 [Page 63]
3589 C LDAP API C LDAP Application Program Interface 8 October 1999
3592 which upon return points to an allocated NULL-terminated array
3593 of char *'s containing the octet strings. NULL is stored if the
3594 sequence is empty. ldap_memfree SHOULD be called to free each
3595 element of the array and the array itself. The tag of the
3596 sequence and of the octet strings are ignored.
3598 'V' Several octet strings (which could contain null bytes). A
3599 struct berval *** MUST be supplied, which upon return points to
3600 a allocated NULL-terminated array of struct berval *'s contain-
3601 ing the octet strings and their lengths. NULL is stored if the
3602 sequence is empty. ber_bvecfree() can be called to free the
3603 allocated memory. The tag of the sequence and of the octet
3604 strings are ignored.
3606 'x' Skip element. The next element is skipped. No argument is
3609 '{' Begin sequence. No argument is needed. The initial sequence
3610 tag and length are skipped.
3612 '}' End sequence. No argument is needed.
3614 '[' Begin set. No argument is needed. The initial set tag and
3617 ']' End set. No argument is needed.
3619 ber_tag_t ber_peek_tag( BerElement *ber,
3620 ber_len_t *lenPtr );
3622 ber_peek_tag() returns the tag of the next element to be parsed in the
3623 BerElement argument. The length of this element is stored in the
3624 *lenPtr argument. LBER_DEFAULT is returned if there is no further data
3625 to be read. The decoding position within the ber argument is unchanged
3626 by this call; that is, the fact that ber_peek_tag() has been called does
3627 not affect future use of ber.
3629 ber_tag_t ber_skip_tag( BerElement *ber, ber_len_t *lenPtr );
3631 ber_skip_tag() is similar to ber_peek_tag(), except that the state
3632 pointer in the BerElement argument is advanced past the first tag and
3633 length, and is pointed to the value part of the next element. This rou-
3634 tine SHOULD only be used with constructed types and situations when a
3635 BER encoding is used as the value of an OCTET STRING. The length of the
3636 value is stored in *lenPtr.
3638 ber_tag_t ber_first_element( BerElement *ber,
3639 ber_len_t *lenPtr, char **opaquePtr );
3643 Expires: 8 April 2000 [Page 64]
3646 C LDAP API C LDAP Application Program Interface 8 October 1999
3649 ber_tag_t ber_next_element( BerElement *ber,
3650 ber_len_t *lenPtr, char *opaque );
3652 ber_first_element() and ber_next_element() are used to traverse a SET,
3653 SET OF, SEQUENCE or SEQUENCE OF data value. ber_first_element() calls
3654 ber_skip_tag(), stores internal information in *lenPtr and *opaquePtr,
3655 and calls ber_peek_tag() for the first element inside the constructed
3656 value. LBER_DEFAULT is returned if the constructed value is empty.
3657 ber_next_element() positions the state at the start of the next element
3658 in the constructed type. LBER_DEFAULT is returned if there are no
3661 The len and opaque values SHOULD NOT be used by applications other than
3662 as arguments to ber_next_element(), as shown in the example below.
3665 17.6. Decoding Example
3667 The following is an example of decoding an ASN.1 data type:
3669 Example2Request ::= SEQUENCE {
3670 dn OCTET STRING, -- must be printable
3671 scope ENUMERATED { b (0), s (1), w (2) },
3672 ali ENUMERATED { n (0), s (1), f (2), a (3) },
3676 attrs SEQUENCE OF OCTET STRING, -- must be printable
3677 [0] SEQUENCE OF SEQUENCE {
3678 type OCTET STRING -- must be printable,
3679 crit BOOLEAN DEFAULT FALSE,
3683 #define TAG_CONTROL_LIST 0xA0U /* context specific cons 0 */
3685 int decode_example2(struct berval *bv)
3690 ber_int_t scope, ali, size, time, tonly;
3691 char *dn = NULL, **attrs = NULL;
3696 fputs("ERROR ber_init failed\n", stderr);
3700 Expires: 8 April 2000 [Page 65]
3703 C LDAP API C LDAP Application Program Interface 8 October 1999
3709 res = ber_scanf(ber,"{aiiiib{v}",&dn,&scope,&ali,
3710 &size,&time,&tonly,&attrs);
3712 if (res == LBER_ERROR) {
3713 fputs("ERROR ber_scanf failed\n", stderr);
3721 for (i = 0; attrs != NULL && attrs[i] != NULL; i++) {
3722 /* *** use attrs[i] */
3723 ldap_memfree(attrs[i]);
3725 ldap_memfree(attrs);
3727 if (ber_peek_tag(ber,&len) == TAG_CONTROL_LIST) {
3731 for (tag = ber_first_element(ber,&len,&opaque);
3732 tag != LBER_DEFAULT;
3733 tag = ber_next_element (ber,&len,opaque)) {
3739 struct berval *value;
3741 if (ber_scanf(ber,"{a",&type) == LBER_ERROR) {
3742 fputs("ERROR cannot parse type\n", stderr);
3748 ttag = ber_peek_tag(ber,&tlen);
3749 if (ttag == 0x01U) { /* boolean */
3750 if (ber_scanf(ber,"b",
3751 &crit) == LBER_ERROR) {
3752 fputs("ERROR cannot parse crit\n",
3757 Expires: 8 April 2000 [Page 66]
3760 C LDAP API C LDAP Application Program Interface 8 October 1999
3766 } else if (ttag == 0x04U) { /* octet string */
3769 fputs("ERROR extra field in controls\n",
3774 if (ber_scanf(ber,"O}",&value) == LBER_ERROR) {
3775 fputs("ERROR cannot parse value\n", stderr);
3784 if ( rc == 0 ) { /* no errors so far */
3785 if (ber_scanf(ber,"}") == LBER_ERROR) {
3797 18. Security Considerations
3799 LDAPv2 supports security through protocol-level authentication using
3800 clear-text passwords. LDAPv3 adds support for SASL [12] (Simple Authen-
3801 tication Security Layer) methods. LDAPv3 also supports operation over a
3802 secure transport layer using Transport Layer Security TLS [9]. Readers
3803 are referred to the protocol documents for discussion of related secu-
3804 rity considerations.
3806 Implementations of this API SHOULD be cautious when handling authentica-
3807 tion credentials. In particular, keeping long-lived copies of creden-
3808 tials without the application's knowledge is discouraged.
3814 Expires: 8 April 2000 [Page 67]
3817 C LDAP API C LDAP Application Program Interface 8 October 1999
3820 19. Acknowledgements
3822 Many members of the IETF ASID and LDAPEXT working groups as well as
3823 members of the Internet at large have provided useful comments and
3824 suggestions that have been incorporated into this document. Chris
3825 Weider deserves special mention for his contributions as co-author of
3826 earlier revisions of this document.
3828 The original material upon which this specification is based was sup-
3829 ported by the National Science Foundation under Grant No. NCR-9416667.
3834 Copyright (C) The Internet Society (1997-1999). All Rights Reserved.
3836 This document and translations of it may be copied and furnished to oth-
3837 ers, and derivative works that comment on or otherwise explain it or
3838 assist in its implementation may be prepared, copied, published and dis-
3839 tributed, in whole or in part, without restriction of any kind, provided
3840 that the above copyright notice and this paragraph are included on all
3841 such copies and derivative works. However, this document itself may not
3842 be modified in any way, such as by removing the copyright notice or
3843 references to the Internet Society or other Internet organizations,
3844 except as needed for the purpose of developing Internet standards in
3845 which case the procedures for copyrights defined in the Internet Stan-
3846 dards process must be followed, or as required to translate it into
3847 languages other than English.
3849 The limited permissions granted above are perpetual and will not be
3850 revoked by the Internet Society or its successors or assigns.
3852 This document and the information contained herein is provided on an "AS
3853 IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK
3854 FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT
3855 LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT
3856 INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FIT-
3857 NESS FOR A PARTICULAR PURPOSE.
3862 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
3863 Levels", RFC 2119, March 1997.
3865 [2] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
3866 (v3)", RFC 2251, December 1997.
3871 Expires: 8 April 2000 [Page 68]
3874 C LDAP API C LDAP Application Program Interface 8 October 1999
3877 [3] M. Wahl, A. Coulbeck, T. Howes, S. Kille, W. Yeong, C. Robbins,
3878 "Lightweight Directory Access Protocol (v3): Attribute Syntax
3879 Definitions", RFC 2252, December 1997.
3881 [4] The Directory: Selected Attribute Syntaxes. CCITT, Recommendation
3884 [5] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol
3885 (v3): A UTF-8 String Representation of Distinguished Names", RFC
3886 2253, December 1997.
3888 [6] F. Yergeau, "UTF-8, a transformation format of Unicode and ISO
3889 10646", RFC 2044, October 1996.
3891 [7] K. Simonsen, "Character Mnemonics and Character Sets," RFC 1345,
3894 [8] "Programming Languages - C", ANSI/ISO Standard 9899, revised 1997.
3896 [9] J. Hodges, R. Morgan, M. Wahl, "Lightweight Directory Access Proto-
3897 col (v3): Extension for Transport Layer Security", INTERNET-DRAFT
3898 (work in progress) <draft-ietf-ldapext-ldapv3-tls-05.txt>, June
3901 [10] R. Hinden, S. Deering, "IP Version 6 Addressing Architecture," RFC
3902 1884, December 1995.
3904 [11] A. Herron, T. Howes, M. Wahl, A. Anantha, "LDAP Control Extension
3905 for Server Side Sorting of Search Results", INTERNET-DRAFT (work in
3906 progress) <draft-ietf-ldapext-sorting-02.txt>, 5 April 1999.
3908 [12] J. Meyers, "Simple Authentication and Security Layer (SASL)", RFC
3911 [13] T. Howes, "The String Representation of LDAP Search Filters," RFC
3912 2254, December 1997.
3914 [14] S. Kille, "Using the OSI Directory to Achieve User Friendly Nam-
3915 ing," RFC 1781, March 1995.
3918 22. Authors' Addresses
3920 Mark Smith (document editor)
3921 Netscape Communications Corp.
3922 501 E. Middlefield Rd., Mailstop MV068
3923 Mountain View, CA 94043
3928 Expires: 8 April 2000 [Page 69]
3931 C LDAP API C LDAP Application Program Interface 8 October 1999
3949 andyhe@microsoft.com
3952 Innosoft International, Inc.
3953 8911 Capital of Texas Hwy, Suite 4140
3957 Mark.Wahl@innosoft.com
3965 anoopa@microsoft.com
3968 23. Appendix A - Sample C LDAP API Code
3976 LDAPMessage *res, *e;
3985 Expires: 8 April 2000 [Page 70]
3988 C LDAP API C LDAP Application Program Interface 8 October 1999
3991 /* open an LDAP session */
3992 if ( (ld = ldap_init( "dotted.host.name", LDAP_PORT )) == NULL )
3995 /* authenticate as nobody */
3996 if (( rc = ldap_simple_bind_s( ld, NULL, NULL )) != LDAP_SUCCESS ) {
3997 fprintf( stderr, "ldap_simple_bind_s: %s\n",
3998 ldap_err2string( rc ));
4003 /* search for entries with cn of "Babs Jensen", return all attrs */
4004 if (( rc = ldap_search_s( ld, "o=University of Michigan, c=US",
4005 LDAP_SCOPE_SUBTREE, "(cn=Babs Jensen)", NULL, 0, &res ))
4007 fprintf( stderr, "ldap_search_s: %s\n",
4008 ldap_err2string( rc ));
4009 if ( res == NULL ) {
4015 /* step through each entry returned */
4016 for ( e = ldap_first_entry( ld, res ); e != NULL;
4017 e = ldap_next_entry( ld, e ) ) {
4018 /* print its name */
4019 dn = ldap_get_dn( ld, e );
4020 printf( "dn: %s\n", dn );
4023 /* print each attribute */
4024 for ( a = ldap_first_attribute( ld, e, &ptr ); a != NULL;
4025 a = ldap_next_attribute( ld, e, ptr ) ) {
4026 printf( "\tattribute: %s\n", a );
4028 /* print each value */
4029 vals = ldap_get_values( ld, e, a );
4030 for ( i = 0; vals[i] != NULL; i++ ) {
4031 printf( "\t\tvalue: %s\n", vals[i] );
4033 ldap_value_free( vals );
4036 if ( ptr != NULL ) {
4042 Expires: 8 April 2000 [Page 71]
4045 C LDAP API C LDAP Application Program Interface 8 October 1999
4049 /* free the search results */
4050 ldap_msgfree( res );
4052 /* close and free connection resources */
4059 24. Appendix B - Namespace Consumed By This Specification
4061 The following 2 prefixes are used in this specification to name func-
4066 The following 6 prefixes are used in this specification to name struc-
4067 tures, unions, and typedefs:
4075 The following 3 prefixes are used in this specification to name #defined
4082 25. Appendix C - Summary of Requirements for API Extensions
4084 As the LDAP protocol is extended, this C LDAP API will need to be
4085 extended as well. For example, an LDAPv3 control extension has already
4086 been defined for server-side sorting of search results [7]. This appen-
4087 dix summarizes the requirements for extending this API.
4091 Extensions to this document SHOULD NOT, by default, alter the behavior
4092 of any of the APIs specified in this document. If an extension option-
4093 ally changes the behavior of any existing C LDAP API function calls, the
4094 behavior change MUST be well documented.
4099 Expires: 8 April 2000 [Page 72]
4102 C LDAP API C LDAP Application Program Interface 8 October 1999
4107 Extensions to this API SHOULD follow the general style and naming con-
4108 ventions used in this document. For example, function names SHOULD
4109 start with "ldap_" or "ber_" and consist entirely of lowercase letters,
4110 digits, and underscore ('_') characters. It is RECOMMENDED that private
4111 and experimental extensions use only the following prefixes for macros,
4112 types, and function names:
4117 and that these prefixes not be used by standard extensions.
4119 25.3. Dependence on Externally Defined Types
4121 Extensions to this API SHOULD minimize dependencies on types and macros
4122 that are defined in system headers and generally use only intrinsic
4123 types that are part of the C language, types defined in this specifica-
4124 tion, or types defined in the extension document itself.
4126 25.4. Compile Time Information
4128 Extensions to this API SHOULD conform to the requirements contained in
4129 the "Retrieving Information at Compile Time" section of this document.
4130 That is, extensions SHOULD define a macro of the form:
4132 #define LDAP_API_FEATURE_x level
4134 so that applications can detect the presence or absence of the extension
4135 at compile time and also test the version or level of the extension pro-
4136 vided by an API implementation.
4138 25.5. Runtime Information
4140 Extensions to this API SHOULD conform to the requirements contained in
4141 the "Retrieving Information During Execution" section of this document.
4142 That is, each extension SHOULD be given a character string name and that
4143 name SHOULD appear in the ldapai_extensions array field of the LDAPAPI-
4144 Info structure following a successful call to ldap_get_option() with an
4145 option parameter value of LDAP_OPT_API_INFO. In addition, information
4146 about the extension SHOULD be available via a call to ldap_get_option()
4147 with an option parameter value of LDAP_OPT_API_FEATURE_INFO.
4149 25.6. Values Used for Session Handle Options
4151 Extensions to this API that add new session options (for use with the
4152 ldap_get_option() and ldap_set_option() functions) SHOULD meet the
4156 Expires: 8 April 2000 [Page 73]
4159 C LDAP API C LDAP Application Program Interface 8 October 1999
4162 requirements contained in the last paragraph of the "LDAP Session Handle
4163 Options" section of this document. Specifically, standards track docu-
4164 ments MUST use values for option macros that are between 0x1000 and
4165 0x3FFF inclusive and private and experimental extensions MUST use values
4166 for the option macros that are between 0x4000 and 0x7FFF inclusive.
4169 26. Appendix D - Known Incompatibilities with RFC 1823
4171 This appendix lists known incompatibilities between this API specifica-
4172 tion and the one contained in RFC 1823, beyond the additional API func-
4173 tions added in support of LDAPv3.
4176 26.1. Opaque LDAP Structure
4178 In RFC 1823, some fields in the LDAP structure were exposed to applica-
4179 tion programmers. To provide a cleaner interface and to make it easier
4180 for implementations to evolve over time without sacrificing binary com-
4181 patibility with older applications, the LDAP structure is now entirely
4182 opaque. The new ldap_set_option() and ldap_get_option() calls can be
4183 used to manipulate per-session and global options.
4186 26.2. Additional Error Codes
4188 The following new error code macros were introduced to support LDAPv3:
4190 LDAP_ADMINLIMIT_EXCEEDED
4191 LDAP_UNAVAILABLE_CRITICAL_EXTENSION
4192 LDAP_CONFIDENTIALITY_REQUIRED
4193 LDAP_SASL_BIND_IN_PROGRESS
4194 LDAP_AFFECTS_MULTIPLE_DSAS
4197 LDAP_CONTROL_NOT_FOUND
4198 LDAP_NO_RESULTS_RETURNED
4199 LDAP_MORE_RESULTS_TO_RETURN
4201 LDAP_REFERRAL_LIMIT_EXCEEDED
4204 26.3. Freeing of String Data with ldap_memfree()
4206 All strings received from the API (e.g., those returned by the
4207 ldap_get_dn() or ldap_dn2ufn() functions) SHOULD be freed by calling
4208 ldap_memfree() not free(). RFC 1823 did not define an ldap_memfree()
4213 Expires: 8 April 2000 [Page 74]
4216 C LDAP API C LDAP Application Program Interface 8 October 1999
4219 26.4. Changes to ldap_result()
4221 The meaning of the all parameter to ldap_result has changed slightly.
4222 Nonzero values from RFC 1823 correspond to LDAP_MSG_ALL (0x01). There
4223 is also a new possible value, LDAP_MSG_RECEIVED (0x02).
4225 The result type LDAP_RES_MODDN is now returned where RFC 1823 returned
4226 LDAP_RES_MODRDN. The actual value for these two macros is the same
4230 26.5. Changes to ldap_first_attribute() and ldap_next_attribute
4232 Each non-NULL return value SHOULD be freed by calling ldap_memfree()
4233 after use. In RFC 1823, these two functions returned a pointer to a
4234 per-session buffer, which was not very thread-friendly.
4236 After the last call to ldap_first_attribute() or ldap_next_attribute(),
4237 the value set in the ptr parameter SHOULD be freed by calling ber_free(
4238 ptr, 0 ). RFC 1823 did not mention that the ptr value SHOULD be freed.
4240 The type of the ptr parameter was changed from void * to BerElement *.
4243 26.6. Changes to ldap_modrdn() and ldap_modrdn_s() Functions
4245 In RFC 1823, the ldap_modrdn() and ldap_modrdn_s() functions include a
4246 parameter called deleteoldrdn. This does not match the great majority
4247 of implementations, so in this specification the deleteoldrdn parameter
4248 was removed from ldap_modrdn() and ldap_modrdn_s(). Two additional
4249 functions that support deleteoldrdn and are widely implemented as well
4250 were added to this specification: ldap_modrdn2() and ldap_modrdn2_s().
4253 26.7. Changes to the berval structure
4255 In RFC 1823, the bv_len element of the berval structure was defined as
4256 an `unsigned long'. In this specification, the type is implementation-
4257 specific, although it MUST be an unsigned integral type that is at least
4258 32 bits in size. See the appendix "Data Types and Legacy Implementa-
4259 tions" for additional considerations.
4262 26.8. API Specification Clarified
4264 RFC 1823 left many things unspecified, including behavior of various
4265 memory disposal functions when a NULL pointer is presented, requirements
4266 for headers, values of many macros, and so on. This specification is
4270 Expires: 8 April 2000 [Page 75]
4273 C LDAP API C LDAP Application Program Interface 8 October 1999
4276 more complete and generally tighter than the one in RFC 1823.
4279 26.9. Deprecated Functions
4281 A number of functions that are in RFC 1823 are labeled as "deprecated"
4282 in this specification. In most cases, a replacement that provides
4283 equivalent functionality has been defined. The deprecated functions
4287 Use ldap_simple_bind() or ldap_sasl_bind() instead.
4290 Use ldap_simple_bind_s() or ldap_sasl_bind_s() instead.
4292 ldap_kerberos_bind() and ldap_kerberos_bind_s()
4293 No equivalent functions are provided.
4295 ldap_modrdn() and ldap_modrdn2()
4296 Use ldap_rename() instead.
4298 ldap_modrdn_s() and ldap_modrdn2_s()
4299 Use ldap_rename_s() instead.
4302 Use ldap_init() instead.
4305 Use ldap_err2string() instead.
4308 Use ldap_parse_result() instead.
4311 27. Appendix E - Data Types and Legacy Implementations
4313 The data types associated with the length of a ber value (ber_len_t),
4314 and the tag (ber_tag_t) have been defined in this specification as
4315 unsigned integral types of implementation-specific size. The data type
4316 used for encoding and decoding ber integer, enumerated, and boolean
4317 values has been defined in this specification as a signed integral type
4318 of implementation-specific size. This was done so that source and
4319 binary compatibility of the C LDAP API can be maintained across ILP32
4320 environments (where int, long, and pointers are all 32 bits in size) and
4321 LP64 environments (where ints remain 32 bits but longs and pointers grow
4327 Expires: 8 April 2000 [Page 76]
4330 C LDAP API C LDAP Application Program Interface 8 October 1999
4333 In older implementations of the C LDAP API, such as those based on RFC
4334 1823, implementors may have chosen to use an `unsigned long' for length
4335 and tag values. If a long data type was used for either of these items,
4336 a port of an application to a 64-bit operating system using the LP64
4337 data model would find the size of the types used by the C LDAP API to
4338 increase. Also, if the legacy implementation had chosen to implement
4339 the tag and types as an unsigned int, adoption of a specification that
4340 mandated use of unsigned longs would cause a source incompatibility in
4341 an LP64 application. By using implementation-specific data types, the C
4342 LDAP API implementation is free to choose the correct data type and the
4343 ability to maintain source compatibility.
4345 For example, suppose a legacy implementation chose to define the return
4346 value of ber_skip_tag() as an unsigned long but wishes to have the
4347 library return a 32-bit quantity in both ILP32 and LP64 data models.
4348 The following typedefs for ber_tag_t will provide a fixed sized data
4349 structure while preserving existing ILP32 source -- all without generat-
4350 ing compiler warnings:
4351 #include <limits.h> /* provides UINT_MAX in ISO C */
4352 #if UINT_MAX >= 0xffffffffU
4353 typedef unsigned int ber_tag_t;
4355 typedef unsigned long ber_tag_t;
4358 Similar code can be used to define appropriate ber_len_t and ber_int_t
4362 28. Appendix F - Changes Made Since Last Document Revision
4364 The previous version of this document was draft-ietf-ldapext-ldap-c-
4365 api-03.txt, dated 2 June 1999. This appendix lists all of the changes
4366 made to that document to produce this one.
4370 Types: Added BerValue typedef for struct berval. Clarified width
4371 requirements for integral types. Made it clear that the types for
4372 the fields within struct timeval are implementation-specific.
4374 Namespace: Added recommendation that private and experimental exten-
4375 sions use the LDAP_X_, LBER_X_, ldap_x_, and ber_x_ portions of the
4378 Macro-defined constants: Added missing 'U' suffix to unsigned
4384 Expires: 8 April 2000 [Page 77]
4387 C LDAP API C LDAP Application Program Interface 8 October 1999
4390 "LDAP Error Codes" section: Corrected text to say that LDAP error
4391 codes are non-negative integers (used to say "positive integers"
4392 which excluded LDAP_SUCCESS).
4394 "LDAP Session Handle Option" section: Removed LDAP_OPT_DESC because
4395 the definition was insufficient to allow interoperable use. Added
4396 new option LDAP_OPT_MATCHED_DN. Documented the defaults for options.
4397 Added text to specify required behavior with respect to state in the
4398 session handle when a call to ldap_get_option() or ldap_set_option()
4399 succeeds or fails. Added the LDAP_OPT_PRIVATE_EXTENSION_BASE macro.
4401 "Working With Controls" section: Removed PLDAPControl typedef (was a
4402 pointer to an LDAPControl, but was not used anywhere in the API).
4404 "Searching" section: Added text to describe how the operation timel-
4405 imit that is passed to the LDAP server for an LDAP search operation
4406 is derived from the timeout parameter that is passed to
4407 ldap_search_ext() and ldap_search_ext_s().
4409 "Comparing a Value Against an Entry" section: Added `const' to
4410 declarations of `bvalue' in ldap_compare_ext() and
4411 ldap_compare_ext_s(). Also added missing trailing commas in proto-
4414 "Extended Operations" section: Added `const' to declarations of
4415 `requestdata' in ldap_extended_operation() and
4416 ldap_extended_operation_s() prototypes.
4418 "Obtaining Results and Peeking Inside LDAP Messages" section: Added
4419 LDAP_RES_UNSOLICITED macro for use as the `msgid' parameter to
4420 ldap_result(). Added text to indicate that ldap_msgid() returns -1
4423 "Handling Errors and Parsing Results" section: Added
4424 LDAP_NOTICE_OF_DISCONNECTION macro.
4426 "Stepping Through a List of Results" section: Added text to indicate
4427 that ldap_count_messages(), ldap_count_entries(), and
4428 ldap_count_references() return -1 if an error occurs.
4430 "Encoded ASN.1 Value Manipulation" section: Added ber_int_t,
4431 ber_uint_t, and ber_slen_t integral types. Changed functions to use
4432 ber_int_t where appropriate. Added support for encoding and decoding
4433 enumerated values (format 'e'). Added support for the 't' format to
4434 ber_scanf() (works like ber_peek_tag()). Changed the format specif-
4435 ier for Bitstring in ber_printf() from 'X' to 'B' to match
4436 ber_scanf(). Corrected text to say that ber_printf() returns a non-
4437 negative number if successful (used to say positive, but zero is a
4441 Expires: 8 April 2000 [Page 78]
4444 C LDAP API C LDAP Application Program Interface 8 October 1999
4447 valid return value). Removed `const' qualifier from BerElement
4448 parameters in ber_flatten() and ber_peek_tag() function prototypes
4449 and added note about preserving the state of the underlying BerEle-
4450 ment when ber_peek_tag() is called. Revised LBER_ERROR and
4451 LBER_DEFAULT macros to use more portable definitions. Updated exam-
4452 ples to reflect changes.
4455 28.2. Editorial Changes
4457 General: Changed document to reference RFC 2119 ("Key words for use
4458 in RFCs to Indicate Requirement Levels") and to use the key words
4459 consistently. Reordered references to list them in the order they
4460 appear in the document. Added text for deprecated functions to indi-
4461 cate that more complete descriptions can be found in RFC 1823.
4463 Section names: Renamed "Overview of LDAP API Use" to "Overview of
4464 LDAP API Use and General Requirements." Renamed "Header File
4465 Requirements" to "Header Requirements." Renamed "Common Data Struc-
4466 tures" to "Common Data Structures and Types." Renamed "General" sec-
4467 tion within "Encoded ASN.1 Value Manipulation" section to "BER Data
4468 Structures and Types."
4470 Types: Modified implementation-specific typedefs to use `impl_XXX_t'
4471 convention. Moved definition of `ber_tag_t' from "Common Data Struc-
4472 tures and Types" section to "Encoded ASN.1 Value Manipulation" sec-
4475 "Overview of LDAP API Use and General Requirements" section: added
4476 note that conformant implementations MUST implement all of the func-
4477 tions and so on defined in this specification.
4479 "Header Requirements" section: Removed all references to the term
4480 "header file(s)" and replaced with the simpler and less restrictive
4483 "Memory Handling Overview" section: New section added. Also cleaned
4484 up text throughout the document to consistently state that "free"
4485 routines do nothing when a NULL pointer is passed in.
4487 "LDAP Session Handle Options" section: Clarified text to better indi-
4488 cate whether ldap_memfree() or ldap_controls_free() should be used to
4489 dispose of char * and LDAPControl * values returned by
4492 "Handling Errors and Parsing Results" section: Removed confusing use
4493 of ldap_parse_*_result() pattern (all function names are spelled out
4498 Expires: 8 April 2000 [Page 79]
4501 C LDAP API C LDAP Application Program Interface 8 October 1999
4504 "Encoded ASN.1 Value Manipulation" section: Added note about lack of
4505 specific error codes from BER functions. Cleaned up references to
4506 berval to always say "struct berval" or "berval structure."
4508 "Authors" section: Updated Tim Howes' contact information.
4555 Expires: 8 April 2000 [Page 80]