idnits 2.17.1 draft-ietf-ldapext-ldap-c-api-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Abstract section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There are 34 instances of too long lines in the document, the longest one being 10 characters in excess of 72. == The 'Obsoletes: ' line in the draft header should list only the _numbers_ of the RFCs which will be obsoleted by this document (if approved); it should not include the word 'RFC' in the list. -- The draft header indicates that this document obsoletes RFC1823, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 544 has weird spacing: '... int ldapa...' == Line 545 has weird spacing: '... int ldapa...' == Line 546 has weird spacing: '... int ldapa...' == Line 549 has weird spacing: '... int ldapa...' == Line 623 has weird spacing: '... int ldap...' == (4 more instances...) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (17 November 2000) is 8554 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? '1' on line 3488 looks like a reference -- Missing reference section? '2' on line 3491 looks like a reference -- Missing reference section? '3' on line 3494 looks like a reference -- Missing reference section? '4' on line 3498 looks like a reference -- Missing reference section? '5' on line 3501 looks like a reference -- Missing reference section? '6' on line 3505 looks like a reference -- Missing reference section? '7' on line 3685 looks like a reference -- Missing reference section? '8' on line 3511 looks like a reference -- Missing reference section? '9' on line 3513 looks like a reference -- Missing reference section? '10' on line 3518 looks like a reference -- Missing reference section? '11' on line 3523 looks like a reference -- Missing reference section? '12' on line 3527 looks like a reference -- Missing reference section? '13' on line 3530 looks like a reference -- Missing reference section? '14' on line 3533 looks like a reference -- Missing reference section? '0' on line 3328 looks like a reference Summary: 5 errors (**), 0 flaws (~~), 7 warnings (==), 19 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Smith, Editor 3 INTERNET-DRAFT Netscape Communications Corp. 4 Intended Category: Standards Track T. Howes 5 Obsoletes: RFC 1823 Loudcloud, Inc. 6 Expires: May 2001 A. Herron 7 Microsoft Corp. 8 M. Wahl 9 Sun Microsystems, Inc. 10 A. Anantha 11 Microsoft Corp. 13 17 November 2000 15 The C LDAP Application Program Interface 16 18 1. Status of this Memo 20 This document is an Internet-Draft and is in full conformance with all 21 provisions of Section 10 of RFC2026. Internet-Drafts are working docu- 22 ments of the Internet Engineering Task Force (IETF), its areas, and its 23 working groups. Note that other groups may also distribute working 24 documents as Internet-Drafts. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference material 29 or to cite them other than as "work in progress." 31 The list of current Internet-Drafts can be accessed at 32 http://www.ietf.org/ietf/1id-abstracts.txt. 34 The list of Internet-Draft Shadow Directories can be accessed at 35 http://www.ietf.org/shadow.html. 37 This draft document will be submitted to the RFC Editor as a Standards 38 Track document. Distribution of this memo is unlimited. Technical dis- 39 cussion of this document will take place on the IETF LDAP Extension 40 Working Group mailing list . Please send 41 editorial comments directly to the authors. 43 Copyright (C) The Internet Society (1997-1999). All Rights Reserved. 45 Please see the Copyright section near the end of this document for more 46 information. 48 C LDAP API C LDAP Application Program Interface 17 November 2000 50 2. Introduction 52 This document defines a C language application program interface (API) 53 to the Lightweight Directory Access Protocol (LDAP). This document 54 replaces the previous definition of this API, defined in RFC 1823, 55 updating it to include support for features found in version 3 of the 56 LDAP protocol. New extended operation functions were added to support 57 LDAPv3 features such as controls. In addition, other LDAP API changes 58 were made to support information hiding and thread safety. 60 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 61 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 62 document are to be interpreted as described in RFC 2119[1]. 64 The C LDAP API is designed to be powerful, yet simple to use. It defines 65 compatible synchronous and asynchronous interfaces to LDAP to suit a 66 wide variety of applications. This document gives a brief overview of 67 the LDAP model, then an overview of how the API is used by an applica- 68 tion program to obtain LDAP information. The API calls are described in 69 detail, followed by appendices that provide example code demonstrating 70 use of the API, the namespace consumed by the API, a summary of require- 71 ments for API extensions, known incompatibilities with RFC 1823, and a 72 list of changes made since the last revision of this document. 74 3. Table of Contents 76 1. Status of this Memo............................................1 77 2. Introduction...................................................2 78 3. Table of Contents..............................................2 79 4. Overview of the LDAP Model.....................................4 80 5. Overview of LDAP API Use and General Requirements..............4 81 6. Header Requirements............................................6 82 7. Common Data Structures and Types...............................7 83 8. Memory Handling Overview.......................................9 84 9. Retrieving Information About the API Implementation............9 85 9.1. Retrieving Information at Compile Time......................10 86 9.2. Retrieving Information During Execution.....................11 87 10. Result Codes...................................................14 88 11. Performing LDAP Operations.....................................16 89 11.1. Initializing an LDAP Session................................16 90 11.2. LDAP Session Handle Options.................................17 91 11.3. Working With Controls.......................................23 92 11.3.1. A Client Control That Governs Referral Processing........24 93 11.4. Authenticating to the directory.............................25 94 11.5. Closing the session.........................................27 95 11.6. Searching...................................................28 96 11.7. Reading an Entry............................................32 97 C LDAP API C LDAP Application Program Interface 17 November 2000 99 11.8. Listing the Children of an Entry............................32 100 11.9. Comparing a Value Against an Entry..........................33 101 11.10. Modifying an entry..........................................35 102 11.11. Modifying the Name of an Entry..............................37 103 11.12. Adding an entry.............................................39 104 11.13. Deleting an entry...........................................41 105 11.14. Extended Operations.........................................43 106 12. Abandoning An Operation........................................44 107 13. Obtaining Results and Peeking Inside LDAP Messages.............45 108 14. Handling Errors and Parsing Results............................47 109 15. Stepping Through a List of Results.............................51 110 16. Parsing Search Results.........................................51 111 16.1. Stepping Through a List of Entries or References............52 112 16.2. Stepping Through the Attributes of an Entry.................53 113 16.3. Retrieving the Values of an Attribute.......................54 114 16.4. Retrieving the name of an entry.............................55 115 16.5. Retrieving controls from an entry...........................56 116 16.6. Parsing References..........................................57 117 17. Encoded ASN.1 Value Manipulation...............................58 118 17.1. BER Data Structures and Types...............................58 119 17.2. Memory Disposal and Utility Functions.......................60 120 17.3. Encoding....................................................60 121 17.4. Encoding Example............................................63 122 17.5. Decoding....................................................64 123 17.6. Decoding Example............................................67 124 18. Security Considerations........................................70 125 19. Acknowledgements...............................................70 126 20. Copyright......................................................70 127 21. Bibliography...................................................71 128 22. Authors' Addresses.............................................72 129 23. Appendix A - Sample C LDAP API Code............................73 130 24. Appendix B - Namespace Consumed By This Specification..........74 131 25. Appendix C - Summary of Requirements for API Extensions........75 132 25.1. Compatibility...............................................75 133 25.2. Style.......................................................75 134 25.3. Dependence on Externally Defined Types......................75 135 25.4. Compile Time Information....................................76 136 25.5. Runtime Information.........................................76 137 25.6. Values Used for Session Handle Options......................76 138 26. Appendix D - Known Incompatibilities with RFC 1823.............76 139 26.1. Opaque LDAP Structure.......................................76 140 26.2. Additional Result Codes.....................................77 141 26.3. Freeing of String Data with ldap_memfree()..................77 142 26.4. Changes to ldap_result()....................................77 143 26.5. Changes to ldap_first_attribute() and ldap_next_attribute...77 144 26.6. Changes to ldap_modrdn() and ldap_modrdn_s() Functions......78 145 26.7. Changes to the berval structure.............................78 146 26.8. API Specification Clarified.................................78 147 C LDAP API C LDAP Application Program Interface 17 November 2000 149 26.9. Deprecated Functions........................................78 150 27. Appendix E - Data Types and Legacy Implementations.............79 151 28. Appendix F - Changes Made Since Last Document Revision.........80 152 28.1. API Changes.................................................80 153 28.2. Editorial Changes and Clarifications........................81 155 4. Overview of the LDAP Model 157 LDAP is the lightweight directory access protocol, described in [2] and 158 [3]. It can provide a lightweight frontend to the X.500 directory [4], 159 or a stand-alone service. In either mode, LDAP is based on a client- 160 server model in which a client makes a TCP connection to an LDAP server, 161 over which it sends requests and receives responses. 163 The LDAP information model is based on the entry, which contains infor- 164 mation about some object (e.g., a person). Entries are composed of 165 attributes, which have a type and one or more values. Each attribute has 166 a syntax that determines what kinds of values are allowed in the attri- 167 bute (e.g., ASCII characters, a jpeg photograph, etc.) and how those 168 values behave during directory operations (e.g., is case significant 169 during comparisons). 171 Entries may be organized in a tree structure, usually based on politi- 172 cal, geographical, and organizational boundaries. Each entry is uniquely 173 named relative to its sibling entries by its relative distinguished name 174 (RDN) consisting of one or more distinguished attribute values from the 175 entry. At most one value from each attribute may be used in the RDN. 176 For example, the entry for the person Babs Jensen might be named with 177 the "Barbara Jensen" value from the commonName attribute. 179 A globally unique name for an entry, called a distinguished name or DN, 180 is constructed by concatenating the sequence of RDNs from the entry up 181 to the root of the tree. For example, if Babs worked for the University 182 of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen, 183 o=University of Michigan, c=US". The DN format used by LDAP is defined 184 in [5]. 186 Operations are provided to authenticate, search for and retrieve infor- 187 mation, modify information, and add and delete entries from the tree. 188 The next sections give an overview of how the API is used and detailed 189 descriptions of the LDAP API calls that implement all of these func- 190 tions. 192 5. Overview of LDAP API Use and General Requirements 194 An application generally uses the C LDAP API in four simple steps. 196 C LDAP API C LDAP Application Program Interface 17 November 2000 198 1. Initialize an LDAP session with a primary LDAP server. The 199 ldap_init() function returns a handle to the session, allowing 200 multiple connections to be open at once. 202 2. Authenticate to the LDAP server. The ldap_sasl_bind() function 203 and friends support a variety of authentication methods. 205 3. Perform some LDAP operations and obtain some results. 206 ldap_search() and friends return results which can be parsed by 207 ldap_parse_result(), ldap_first_entry(), ldap_next_entry(), etc. 209 4. Close the session. The ldap_unbind() function closes the connec- 210 tion. 212 Operations can be performed either synchronously or asynchronously. The 213 names of the synchronous functions end in _s. For example, a synchronous 214 search can be completed by calling ldap_search_s(). An asynchronous 215 search can be initiated by calling ldap_search(). All synchronous rou- 216 tines return an indication of the outcome of the operation (e.g, the 217 constant LDAP_SUCCESS or some other result code). The asynchronous rou- 218 tines make available to the caller the message id of the operation ini- 219 tiated. This id can be used in subsequent calls to ldap_result() to 220 obtain the result(s) of the operation. An asynchronous operation can be 221 abandoned by calling ldap_abandon() or ldap_abandon_ext(). Note that 222 there is no requirement that an LDAP API implementation not block when 223 handling asynchronous API functions; the term "asynchronous" as used in 224 this document refers to the fact that the sending of LDAP requests can 225 be separated from the receiving of LDAP responses. 227 Results and errors are returned in an opaque structure called LDAPMes- 228 sage. Routines are provided to parse this structure, step through 229 entries and attributes returned, etc. Routines are also provided to 230 interpret errors. Later sections of this document describe these rou- 231 tines in more detail. 233 LDAP version 3 servers can return referrals and references to other 234 servers. By default, implementations of this API will attempt to follow 235 referrals automatically for the application. This behavior can be dis- 236 abled globally (using the ldap_set_option() call) or on a per-request 237 basis through the use of a client control. 239 All DN and string attribute values passed into or produced by this C 240 LDAP API are represented using the character set of the underlying LDAP 241 protocol version in use. When this API is used with LDAPv3, DN and 242 string values are represented as UTF-8[6] characters. When this API is 243 used with LDAPv2, the US-ASCII[7] or T.61[7] character set are used. 244 Future documents MAY specify additional APIs supporting other character 245 sets. 247 C LDAP API C LDAP Application Program Interface 17 November 2000 249 For compatibility with existing applications, implementations of this 250 API will by default use version 2 of the LDAP protocol. Applications 251 that intend to take advantage of LDAP version 3 features will need to 252 use the ldap_set_option() call with a LDAP_OPT_PROTOCOL_VERSION to 253 switch to version 3. 255 Unless otherwise indicated, conformant implementations of this specifi- 256 cation MUST implement all of the C LDAP API functions as described in 257 this document, and they MUST use the function prototypes, macro defini- 258 tions, and types defined in this document. 260 Note that this API is designed for use in environments where the 'int' 261 type is at least 32 bits in size. 263 6. Header Requirements 265 To promote portability of applications, the following requirements are 266 imposed on the headers used by applications to access the services of 267 this API: 269 Name and Inclusion 270 Applications only need to include a single header named ldap.h 271 to access all of the API services described in this document. 272 Therefore, the following C source program MUST compile and exe- 273 cute without errors: 275 #include 277 int 278 main() 279 { 280 return 0; 281 } 283 The ldap.h header MAY include other implementation-specific 284 headers. 286 Implementations SHOULD also provide a header named lber.h to facilitate 287 development of applications desiring compatibility with older LDAP 288 implementations. The lber.h header MAY be empty. Old applications that 289 include lber.h in order to use BER facilities will need to include 290 ldap.h. 292 Idempotence 293 All headers SHOULD be idempotent; that is, if they are included 294 more than once the effect is as if they had only been included 296 C LDAP API C LDAP Application Program Interface 17 November 2000 298 once. 300 Must Be Included Before API Is Used 301 An application MUST include the ldap.h header before referencing 302 any of the function or type definitions described in this API 303 specification. 305 Mutual Independence 306 Headers SHOULD be mutually independent with minimal dependence 307 on system or any other headers. 309 Use of the 'const' Keyword 310 This API specification is defined in terms of ISO C[8]. It 311 makes use of function prototypes and the 'const' keyword. The 312 use of 'const' in this specification is limited to simple, non- 313 array function parameters to avoid forcing applications to 314 declare parameters and variables that accept return values from 315 LDAP API functions as 'const.' Implementations specifically 316 designed to be used with non-ISO C translators SHOULD provide 317 function declarations without prototypes or function prototypes 318 without specification of 'const' arguments. 320 Definition of 'struct timeval' 321 This API specification uses the 'struct timeval' type. Imple- 322 mentations of this API MUST ensure that the struct timeval type 323 is by default defined as a consequence of including the ldap.h 324 header. Because struct timeval is usually defined in one or 325 more system headers, it is possible for header conflicts to 326 occur if ldap.h also defines it or arranges for it to be defined 327 by including another header. Therefore, applications MAY want 328 to arrange for struct timeval to be defined before they include 329 ldap.h. To support this, the ldap.h header MUST NOT itself 330 define struct timeval if the preprocessor symbol 331 LDAP_TYPE_TIMEVAL_DEFINED is defined before ldap.h is included. 333 7. Common Data Structures and Types 335 Data structures and types that are common to several LDAP API functions 336 are defined here: 338 typedef struct ldap LDAP; 340 typedef struct ldapmsg LDAPMessage; 342 typedef struct berelement BerElement; 344 typedef ber_len_t; 346 C LDAP API C LDAP Application Program Interface 17 November 2000 348 typedef struct berval { 349 ber_len_t bv_len; 350 char *bv_val; 351 } BerValue; 353 struct timeval { 354 tv_sec; 355 tv_usec; 356 }; 358 The LDAP structure is an opaque data type that represents an LDAP ses- 359 sion Typically this corresponds to a connection to a single server, but 360 it MAY encompass several server connections in the face of LDAPv3 refer- 361 rals. 363 The LDAPMessage structure is an opaque data type that is used to return 364 entry, reference, result, and error information. An LDAPMessage struc- 365 ture can represent the beginning of a list, or chain of messages that 366 consists of a series of entries, references, and result messages as 367 returned by LDAP operations such as search. LDAP API functions such as 368 ldap_parse_result() that operate on message chains that can contain more 369 than one result message always operate on the first result message in 370 the chain. See the "Obtaining Results and Peeking Inside LDAP Messages" 371 section of this document for more information. 373 The BerElement structure is an opaque data type that is used to hold 374 data and state information about encoded data. It is described in more 375 detail in the section "Encoded ASN.1 Value Manipulation" later in this 376 document. 378 The `ber_len_t' type is an unsigned integral data type that is large 379 enough to contain the length of the largest piece of data supported by 380 the API implementation. The `' in the `ber_len_t' typedef 381 MUST be replaced with an appropriate type. The width (number of signi- 382 ficant bits) of `ber_len_t' MUST be at least 32 and no larger than that 383 of `unsigned long'. See the appendix "Data Types and Legacy Implementa- 384 tions" for additional considerations. 386 The BerValue structure is used to represent arbitrary binary data and 387 its fields have the following meanings: 389 bv_len Length of data in bytes. 391 bv_val A pointer to the data itself. 393 The timeval structure is used to represent an interval of time and its 394 fields have the following meanings: 396 C LDAP API C LDAP Application Program Interface 17 November 2000 398 tv_sec Seconds component of time interval. 400 tv_usec Microseconds component of time interval. 402 Note that because the struct timeval definition typically is derived 403 from a system header, the types used for the tv_sec and tv_usec com- 404 ponents are implementation-specific integral types. Therefore, 405 `' and `' in the struct timeval definition MUST 406 be replaced with appropriate types. See the earlier section "Header 407 Requirements" for more information on struct timeval. 409 8. Memory Handling Overview 411 All memory that is allocated by a function in this C LDAP API and 412 returned to the caller SHOULD be disposed of by calling the appropriate 413 "free" function provided by this API. The correct "free" function to 414 call is documented in each section of this document where a function 415 that allocates memory is described. 417 Memory that is allocated through means outside of the C LDAP API MUST 418 NOT be disposed of using a function provided by this API. 420 If a pointer value passed to one of the C LDAP API "free" functions is 421 NULL, graceful failure (i.e, ignoring of the NULL pointer) MUST occur. 423 The complete list of "free" functions that are used to dispose of allo- 424 cated memory is: 426 ber_bvecfree() 427 ber_bvfree() 428 ber_free() 429 ldap_control_free() 430 ldap_controls_free() 431 ldap_memfree() 432 ldap_msgfree() 433 ldap_value_free() 434 ldap_value_free_len() 436 9. Retrieving Information About the API Implementation 438 Applications developed to this specification need to be able to deter- 439 mine information about the particular API implementation they are using 440 both at compile time and during execution. 442 C LDAP API C LDAP Application Program Interface 17 November 2000 444 9.1. Retrieving Information at Compile Time 446 All conformant implementations MUST include the following five defini- 447 tions in a header so compile time tests can be done by LDAP software 448 developers: 450 #define LDAP_API_VERSION level 451 #define LDAP_VERSION_MIN min-version 452 #define LDAP_VERSION_MAX max-version 453 #define LDAP_VENDOR_NAME "vend-name" 454 #define LDAP_VENDOR_VERSION vend-version 456 where: 458 "level" is replaced with the RFC number given to this C LDAP API 459 specification when it is published as a standards track RFC. 461 min-version is replaced with the lowest LDAP protocol version sup- 462 ported by the implementation. 464 max-version is replaced with the highest LDAP protocol version sup- 465 ported by the implementation. This SHOULD be 3. 467 "vend-name" is replaced with a text string that identifies the 468 party that supplies the API implementation. 470 "vend-version" is a supplier-specific version number multiplied 471 times 100. 473 Note that the LDAP_VENDOR_NAME macro SHOULD be defined as "" if no ven- 474 dor name is available and the LDAP_VENDOR_VERSION macro SHOULD be 475 defined as 0 if no vendor-specific version information is available. 477 For example, if this specification is published as RFC 88888, Netscape 478 Communication's version 4.0 implementation that supports LDAPv2 and v3 479 might include macro definitions like these: 481 #define LDAP_API_VERSION 88888 /* RFC 88888 compliant */ 482 #define LDAP_VERSION_MIN 2 483 #define LDAP_VERSION_MAX 3 484 #define LDAP_VENDOR_NAME "Netscape Communications Corp." 485 #define LDAP_VENDOR_VERSION 400 /* version 4.0 */ 487 and application code can test the C LDAP API version level using a 488 construct such as this one: 490 #if (LDAP_API_VERSION >= 88888) 491 /* use features supported in RFC 88888 or later */ 493 C LDAP API C LDAP Application Program Interface 17 November 2000 495 #endif 497 Until such time as this document is published as an RFC, implementations 498 SHOULD use the value 2000 plus the revision number of this draft for 499 LDAP_API_VERSION. For example, the correct value for LDAP_API_VERSION 500 for revision 05 of this draft is 2005. 502 Documents that extend this specification SHOULD define a macro of the 503 form: 505 #define LDAP_API_FEATURE_x level 507 where "x" is replaced with a name (textual identifier) for the feature 508 and "level" is replaced with the number of the RFC that specifies the 509 API extension. The name SHOULD NOT begin with the string "X_". 511 For example, if C LDAP API extensions for Transport Layer Security [9] 512 were published in RFC 99999, that RFC might require conformant implemen- 513 tations to define a macro like this: 515 #define LDAP_API_FEATURE_TLS 99999 517 Private or experimental API extensions SHOULD be indicated by defining a 518 macro of this same form where "x" (the extension's name) begins with the 519 string "X_" and "level" is replaced with a integer number that is 520 specific to the extension. 522 It is RECOMMENDED that private or experimental API extensions use only 523 the following prefixes for macros, types, and function names: 524 LDAP_X_ 525 LBER_X_ 526 ldap_x_ 527 ber_x_ 528 and that these prefixes not be used by standard extensions. 530 9.2. Retrieving Information During Execution 532 The ldap_get_option() call (described in greater detail later in this 533 document) can be used during execution in conjunction with an option 534 parameter value of LDAP_OPT_API_INFO (0x00) to retrieve some basic 535 information about the API and about the specific implementation being 536 used. The ld parameter to ldap_get_option() can be either NULL or a 537 valid LDAP session handle which was obtained by calling ldap_init(). 538 The optdata parameter to ldap_get_option() SHOULD be the address of an 539 LDAPAPIInfo structure which is defined as follows: 541 C LDAP API C LDAP Application Program Interface 17 November 2000 543 typedef struct ldapapiinfo { 544 int ldapai_info_version; /* version of this struct (1) */ 545 int ldapai_api_version; /* revision of API supported */ 546 int ldapai_protocol_version; /* highest LDAP version supported */ 547 char **ldapai_extensions; /* names of API extensions */ 548 char *ldapai_vendor_name; /* name of supplier */ 549 int ldapai_vendor_version; /* supplier-specific version times 100 */ 550 } LDAPAPIInfo; 552 In addition, API implementations MUST include the following macro defin- 553 ition: 555 #define LDAP_API_INFO_VERSION 1 557 Note that the ldapai_info_version field of the LDAPAPIInfo structure 558 SHOULD be set to the value LDAP_API_INFO_VERSION (1) before calling 559 ldap_get_option() so that it can be checked for consistency. All other 560 fields are set by the ldap_get_option() function. 562 The members of the LDAPAPIInfo structure are: 564 ldapai_info_version 565 A number that identifies the version of the LDAPAPIInfo struc- 566 ture. This SHOULD be set to the value LDAP_API_INFO_VERSION 567 (1) before calling ldap_get_option(). If the value received 568 is not recognized by the API implementation, the 569 ldap_get_option() function sets ldapai_info_version to a valid 570 value that would be recognized, sets the ldapai_api_version to 571 the correct value, and returns an error without filling in any 572 of the other fields in the LDAPAPIInfo structure. 574 ldapai_api_version 575 A number that matches that assigned to the C LDAP API RFC sup- 576 ported by the API implementation. This SHOULD match the value 577 of the LDAP_API_VERSION macro defined earlier. 579 ldapai_protocol_version 580 The highest LDAP protocol version supported by the implementa- 581 tion. For example, if LDAPv3 is the highest version supported 582 then this field will be set to 3. 584 ldapai_vendor_name 585 A zero-terminated string that contains the name of the party 586 that produced the LDAP API implementation. This field may be 587 set to NULL if no name is available. If non-NULL, the caller 588 is responsible for disposing of the memory occupied by passing 589 this pointer to ldap_memfree() which is described later in 590 this document. This value SHOULD match the value of the 592 C LDAP API C LDAP Application Program Interface 17 November 2000 594 LDAP_VENDOR_NAME macro described earlier in this document. 596 ldapai_vendor_version 597 An implementation-specific version number multiplied by 100. 598 For example, if the implementation version is 4.0 then this 599 field will be set to 400. If no version information is avail- 600 able, this field will be set to 0. This value SHOULD match 601 the value of the LDAP_VENDOR_VERSION macro described earlier 602 in this document. 604 ldapai_extensions 605 A NULL-terminated array of character strings that lists the 606 names of the API extensions supported by the LDAP API imple- 607 mentation. These names will typically match the textual iden- 608 tifiers that appear in the "x" portion of the 609 LDAP_API_FEATURE_x macros described above, although the pre- 610 cise value MUST be defined by documents that specify C LDAP 611 API extensions. If no API extensions are supported, this 612 field will be set to NULL. The caller is responsible for 613 disposing of the memory occupied by this array by passing it 614 to ldap_value_free() which is described later in this docu- 615 ment. To retrieve more information about a particular exten- 616 sion, the ldap_get_option() call can be used with an option 617 parameter value of LDAP_OPT_API_FEATURE_INFO (0x15). The opt- 618 data parameter to the ldap_get_option() SHOULD be the address 619 of an LDAPAPIFeatureInfo structure which is defined as fol- 620 lows: 622 typedef struct ldap_apifeature_info { 623 int ldapaif_info_version; /* version of this struct (1) */ 624 char *ldapaif_name; /* name of supported feature */ 625 int ldapaif_version; /* revision of supported feature */ 626 } LDAPAPIFeatureInfo; 628 In addition, API implementations MUST include the following 629 macro definition: 631 #define LDAP_FEATURE_INFO_VERSION 1 633 Note that the ldapaif_info_version field of the LDAPAPI- 634 FeatureInfo structure SHOULD be set to the value 635 LDAP_FEATURE_INFO_VERSION (1) and the ldapaif_name field 636 SHOULD be set to the extension name string as described below 637 before ldap_get_option() is called. The call will fill in the 638 ldapaif_version field of the LDAPAPIFeatureInfo structure. 640 The members of the LDAPAPIFeatureInfo structure are: 642 C LDAP API C LDAP Application Program Interface 17 November 2000 644 ldapaif_info_version 645 A number that identifies the version of the LDAPAPI- 646 FeatureInfo structure. This SHOULD be set to the value 647 LDAP_FEATURE_INFO_VERSION (1) before calling 648 ldap_get_option(). If the value received is not recognized 649 by the API implementation, the ldap_get_option() function 650 sets ldapaif_info_version to a valid value that would be 651 recognized and returns an error without filling in the 652 ldapaif_version field in the LDAPAPIFeatureInfo structure. 654 ldapaif_name 655 The name of an extension, as returned in the 656 ldapai_extensions array of the LDAPAPIInfo structure and as 657 specified in the document that describes the extension. 659 ldapaif_version 660 This field will be set as a result of calling 661 ldap_get_option(). It is a number that matches that 662 assigned to the C LDAP API extension RFC supported for this 663 extension. For private or experimental API extensions, the 664 value is extension-specific. In either case, the value of 665 ldapaxi_ext_version SHOULD be identical to the value of the 666 LDAP_API_FEATURE_x macro defined for the extension 667 (described above). 669 10. Result Codes 671 Many of the LDAP API routines return result codes, some of which indi- 672 cate local API errors and some of which are LDAP resultCodes that are 673 returned by servers. All of the result codes are non-negative integers. 674 Supported result codes are as follows (hexadecimal values are given in 675 parentheses after the constant): 677 LDAP_SUCCESS (0x00) 678 LDAP_OPERATIONS_ERROR (0x01) 679 LDAP_PROTOCOL_ERROR (0x02) 680 LDAP_TIMELIMIT_EXCEEDED (0x03) 681 LDAP_SIZELIMIT_EXCEEDED (0x04) 682 LDAP_COMPARE_FALSE (0x05) 683 LDAP_COMPARE_TRUE (0x06) 684 LDAP_STRONG_AUTH_NOT_SUPPORTED (0x07) 685 LDAP_STRONG_AUTH_REQUIRED (0x08) 686 LDAP_REFERRAL (0x0a) -- new in LDAPv3 687 LDAP_ADMINLIMIT_EXCEEDED (0x0b) -- new in LDAPv3 688 LDAP_UNAVAILABLE_CRITICAL_EXTENSION (0x0c) -- new in LDAPv3 689 LDAP_CONFIDENTIALITY_REQUIRED (0x0d) -- new in LDAPv3 690 LDAP_SASL_BIND_IN_PROGRESS (0x0e) -- new in LDAPv3 692 C LDAP API C LDAP Application Program Interface 17 November 2000 694 LDAP_NO_SUCH_ATTRIBUTE (0x10) 695 LDAP_UNDEFINED_TYPE (0x11) 696 LDAP_INAPPROPRIATE_MATCHING (0x12) 697 LDAP_CONSTRAINT_VIOLATION (0x13) 698 LDAP_TYPE_OR_VALUE_EXISTS (0x14) 699 LDAP_INVALID_SYNTAX (0x15) 700 LDAP_NO_SUCH_OBJECT (0x20) 701 LDAP_ALIAS_PROBLEM (0x21) 702 LDAP_INVALID_DN_SYNTAX (0x22) 703 LDAP_IS_LEAF (0x23) -- not used in LDAPv3 704 LDAP_ALIAS_DEREF_PROBLEM (0x24) 705 LDAP_INAPPROPRIATE_AUTH (0x30) 706 LDAP_INVALID_CREDENTIALS (0x31) 707 LDAP_INSUFFICIENT_ACCESS (0x32) 708 LDAP_BUSY (0x33) 709 LDAP_UNAVAILABLE (0x34) 710 LDAP_UNWILLING_TO_PERFORM (0x35) 711 LDAP_LOOP_DETECT (0x36) 712 LDAP_NAMING_VIOLATION (0x40) 713 LDAP_OBJECT_CLASS_VIOLATION (0x41) 714 LDAP_NOT_ALLOWED_ON_NONLEAF (0x42) 715 LDAP_NOT_ALLOWED_ON_RDN (0x43) 716 LDAP_ALREADY_EXISTS (0x44) 717 LDAP_NO_OBJECT_CLASS_MODS (0x45) 718 LDAP_RESULTS_TOO_LARGE (0x46) -- reserved for CLDAP 719 LDAP_AFFECTS_MULTIPLE_DSAS (0x47) -- new in LDAPv3 720 LDAP_OTHER (0x50) 721 LDAP_SERVER_DOWN (0x51) 722 LDAP_LOCAL_ERROR (0x52) 723 LDAP_ENCODING_ERROR (0x53) 724 LDAP_DECODING_ERROR (0x54) 725 LDAP_TIMEOUT (0x55) 726 LDAP_AUTH_UNKNOWN (0x56) 727 LDAP_FILTER_ERROR (0x57) 728 LDAP_USER_CANCELLED (0x58) 729 LDAP_PARAM_ERROR (0x59) 730 LDAP_NO_MEMORY (0x5a) 731 LDAP_CONNECT_ERROR (0x5b) 732 LDAP_NOT_SUPPORTED (0x5c) 733 LDAP_CONTROL_NOT_FOUND (0x5d) 734 LDAP_NO_RESULTS_RETURNED (0x5e) 735 LDAP_MORE_RESULTS_TO_RETURN (0x5f) 736 LDAP_CLIENT_LOOP (0x60) 737 LDAP_REFERRAL_LIMIT_EXCEEDED (0x61) 739 C LDAP API C LDAP Application Program Interface 17 November 2000 741 11. Performing LDAP Operations 743 This section describes each LDAP operation API call in detail. Most 744 functions take a "session handle," a pointer to an LDAP structure con- 745 taining per-connection information. Many routines return results in an 746 LDAPMessage structure. These structures and others are described as 747 needed below. 749 11.1. Initializing an LDAP Session 751 ldap_init() initializes a session with an LDAP server. The server is not 752 actually contacted until an operation is performed that requires it, 753 allowing various options to be set after initialization. 755 LDAP *ldap_init( 756 const char *hostname, 757 int portno 758 ); 760 Use of the following routine is deprecated: 762 LDAP *ldap_open( 763 const char *hostname, 764 int portno 765 ); 767 Unlike ldap_init(), ldap_open() attempts to make a server connection 768 before returning to the caller. A more complete description can be 769 found in RFC 1823. 771 Parameters are: 773 hostname Contains a space-separated list of hostnames or dotted strings 774 representing the IP address of hosts running an LDAP server to 775 connect to. Each hostname in the list MAY include a port number 776 which is separated from the host itself with a colon (:) char- 777 acter. The hosts will be tried in the order listed, stopping 778 with the first one to which a successful connection is made. 780 Note: A suitable representation for including a literal IPv6[10] 781 address in the hostname parameter is desired, but has not yet been 782 determined or implemented in practice. 784 portno Contains the TCP port number to connect to. The default LDAP 785 port of 389 can be obtained by supplying the value zero (0) or 786 the macro LDAP_PORT (389). If a host includes a port number 787 then this parameter is ignored. 789 C LDAP API C LDAP Application Program Interface 17 November 2000 791 ldap_init() and ldap_open() both return a "session handle," a pointer to 792 an opaque structure that MUST be passed to subsequent calls pertaining 793 to the session. These routines return NULL if the session cannot be ini- 794 tialized in which case the operating system error reporting mechanism 795 can be checked to see why the call failed. 797 Note that if you connect to an LDAPv2 server, one of the LDAP bind calls 798 described below SHOULD be completed before other operations can be per- 799 formed on the session. LDAPv3 does not require that a bind operation be 800 completed before other operations can be performed. 802 The calling program can set various attributes of the session by calling 803 the routines described in the next section. 805 11.2. LDAP Session Handle Options 807 The LDAP session handle returned by ldap_init() is a pointer to an 808 opaque data type representing an LDAP session. In RFC 1823 this data 809 type was a structure exposed to the caller, and various fields in the 810 structure could be set to control aspects of the session, such as size 811 and time limits on searches. 813 In the interest of insulating callers from inevitable changes to this 814 structure, these aspects of the session are now accessed through a pair 815 of accessor functions, described below. 817 ldap_get_option() is used to access the current value of various 818 session-wide parameters. ldap_set_option() is used to set the value of 819 these parameters. Note that some options are READ-ONLY and cannot be 820 set; it is an error to call ldap_set_option() and attempt to set a 821 READ-ONLY option. 823 Note that if automatic referral following is enabled (the default), any 824 connections created during the course of following referrals will 825 inherit the options associated with the session that sent the original 826 request that caused the referrals to be returned. 828 int ldap_get_option( 829 LDAP *ld, 830 int option, 831 void *outvalue 832 ); 834 int ldap_set_option( 835 LDAP *ld, 836 int option, 837 const void *invalue 839 C LDAP API C LDAP Application Program Interface 17 November 2000 841 ); 843 #define LDAP_OPT_ON () 844 #define LDAP_OPT_OFF ((void *)0) 846 LDAP_OPT_ON MUST be defined as a non-null pointer to void; that is, 847 MUST be replaced with a non-null pointer to 848 void, e.g., one could use: 849 #define LDAP_OPT_ON ((void *)1) 850 if that value is safe to use on the architecture where the API is 851 implemented. 853 Parameters are: 855 ld The session handle. If this is NULL, a set of global defaults is 856 accessed. New LDAP session handles created with ldap_init() or 857 ldap_open() inherit their characteristics from these global 858 defaults. 860 option The name of the option being accessed or set. This parameter 861 SHOULD be one of the following constants, which have the indi- 862 cated meanings. After the constant the actual hexadecimal value 863 of the constant is listed in parentheses. 865 LDAP_OPT_API_INFO (0x00) 866 Type for invalue parameter: not applicable (option is READ-ONLY) 868 Type for outvalue parameter: LDAPAPIInfo * 870 Description: 871 Used to retrieve some basic information about the LDAP API 872 implementation at execution time. See the section "Retriev- 873 ing Information About the API Implementation" above for more 874 information. This option is READ-ONLY and cannot be set. 876 LDAP_OPT_DEREF (0x02) 877 Type for invalue parameter: int * 879 Type for outvalue parameter: int * 881 Description: 882 Determines how aliases are handled during search. It SHOULD 883 have one of the following values: LDAP_DEREF_NEVER (0x00), 884 LDAP_DEREF_SEARCHING (0x01), LDAP_DEREF_FINDING (0x02), or 885 LDAP_DEREF_ALWAYS (0x03). The LDAP_DEREF_SEARCHING value 886 means aliases are dereferenced during the search but not when 887 locating the base object of the search. The 889 C LDAP API C LDAP Application Program Interface 17 November 2000 891 LDAP_DEREF_FINDING value means aliases are dereferenced when 892 locating the base object but not during the search. The 893 default value for this option is LDAP_DEREF_NEVER. 895 LDAP_OPT_SIZELIMIT (0x03) 896 Type for invalue parameter: int * 898 Type for outvalue parameter: int * 900 Description: 901 A limit on the number of entries to return from a search. A 902 value of LDAP_NO_LIMIT (0) means no limit. The default value 903 for this option is LDAP_NO_LIMIT. 905 LDAP_OPT_TIMELIMIT (0x04) 906 Type for invalue parameter: int * 908 Type for outvalue parameter: int * 910 Description: 911 A limit on the number of seconds to spend on a search. A 912 value of LDAP_NO_LIMIT (0) means no limit. The default value 913 for this option is LDAP_NO_LIMIT. This value is passed to 914 the server in the search request only; it does not affect how 915 long the C LDAP API implementation itself will wait locally 916 for search results. Note that the timeout parameter passed 917 to the ldap_search_ext_s() or ldap_result() functions can be 918 used to specify a limit on how long the API implementation 919 will wait for results. 921 LDAP_OPT_REFERRALS (0x08) 922 Type for invalue parameter: void * (LDAP_OPT_ON or LDAP_OPT_OFF) 924 Type for outvalue parameter: int * 926 Description: 927 Determines whether the LDAP library automatically follows 928 referrals returned by LDAP servers or not. It MAY be set to 929 one of the constants LDAP_OPT_ON or LDAP_OPT_OFF; any non- 930 NULL pointer value passed to ldap_set_option() enables this 931 option. When reading the current setting using 932 ldap_get_option(), a zero value means OFF and any non-zero 933 value means ON. By default, this option is ON. 935 LDAP_OPT_RESTART (0x09) 936 Type for invalue parameter: void * (LDAP_OPT_ON or LDAP_OPT_OFF) 938 Type for outvalue parameter: int * 940 C LDAP API C LDAP Application Program Interface 17 November 2000 942 Description: 943 Determines whether LDAP I/O operations are automatically res- 944 tarted if they abort prematurely. It MAY be set to one of the 945 constants LDAP_OPT_ON or LDAP_OPT_OFF; any non-NULL pointer 946 value passed to ldap_set_option() enables this option. When 947 reading the current setting using ldap_get_option(), a zero 948 value means OFF and any non-zero value means ON. This option 949 is useful if an LDAP I/O operation can be interrupted prema- 950 turely, for example by a timer going off, or other interrupt. 951 By default, this option is OFF. 953 LDAP_OPT_PROTOCOL_VERSION (0x11) 954 Type for invalue parameter: int * 956 Type for outvalue parameter: int * 958 Description: 959 This option indicates the version of the LDAP protocol used 960 when communicating with the primary LDAP server. It SHOULD be 961 one of the constants LDAP_VERSION2 (2) or LDAP_VERSION3 (3). 962 If no version is set the default is LDAP_VERSION2 (2). 964 LDAP_OPT_SERVER_CONTROLS (0x12) 965 Type for invalue parameter: LDAPControl ** 967 Type for outvalue parameter: LDAPControl *** 969 Description: 970 A default list of LDAP server controls to be sent with each 971 request. See the Working With Controls section below. 973 LDAP_OPT_CLIENT_CONTROLS (0x13) 974 Type for invalue parameter: LDAPControl ** 976 Type for outvalue parameter: LDAPControl *** 978 Description: 979 A default list of client controls that affect the LDAP ses- 980 sion. See the Working With Controls section below. 982 LDAP_OPT_API_FEATURE_INFO (0x15) 983 Type for invalue parameter: not applicable (option is READ-ONLY) 985 Type for outvalue parameter: LDAPAPIFeatureInfo * 987 Description: 988 Used to retrieve version information about LDAP API extended 989 features at execution time. See the section "Retrieving 991 C LDAP API C LDAP Application Program Interface 17 November 2000 993 Information About the API Implementation" above for more 994 information. This option is READ-ONLY and cannot be set. 996 LDAP_OPT_HOST_NAME (0x30) 997 Type for invalue parameter: char * 999 Type for outvalue parameter: char ** 1001 Description: 1002 The host name (or list of hosts) for the primary LDAP server. 1003 See the definition of the hostname parameter to ldap_init() 1004 for the allowed syntax. Note that if the portno parameter 1005 passed to ldap_init() is a value other than 0 or 389 1006 (LDAP_PORT), this value SHOULD include a string like 1007 ":portno" after each hostname or IP address that did not have 1008 one in the original hostname parameter that was passed to 1009 ldap_init(). For example, if this hostname value was passed 1010 to ldap_init(): 1012 "ldap.example.com:389 ldap2.example.com" 1014 and the portno parameter passed to ldap_init() was 6389, then 1015 the value returned for the LDAP_OPT_HOST_NAME option SHOULD 1016 be: 1018 "ldap.example.com:389 ldap2.example.com:6389" 1020 LDAP_OPT_RESULT_CODE (0x31) 1021 Type for invalue parameter: int * 1023 Type for outvalue parameter: int * 1025 Description: 1026 The most recent local (API generated) or server returned LDAP 1027 result code that occurred for this session. 1029 LDAP_OPT_ERROR_STRING (0x32) 1030 Type for invalue parameter: char * 1032 Type for outvalue parameter: char ** 1034 Description: 1035 The message returned with the most recent LDAP error that 1036 occurred for this session. 1038 LDAP_OPT_MATCHED_DN (0x33) 1039 Type for invalue parameter: char * 1041 C LDAP API C LDAP Application Program Interface 17 November 2000 1043 Type for outvalue parameter: char ** 1045 Description: 1046 The matched DN value returned with the most recent LDAP error 1047 that occurred for this session. 1049 outvalue The address of a place to put the value of the option. The 1050 actual type of this parameter depends on the setting of the 1051 option parameter. For outvalues of type char ** and LDAPCon- 1052 trol **, a copy of the data that is associated with the LDAP 1053 session ld is returned; callers should dispose of the memory by 1054 calling ldap_memfree() or ldap_controls_free(), depending on 1055 the type of data returned. 1057 invalue A pointer to the value the option is to be given. The actual 1058 type of this parameter depends on the setting of the option 1059 parameter. The data associated with invalue is copied by the 1060 API implementation to allow callers of the API to dispose of or 1061 otherwise change their copy of the data after a successful call 1062 to ldap_set_option(). If a value passed for invalue is invalid 1063 or cannot be accepted by the implementation, ldap_set_option() 1064 should return -1 to indicate an error. 1066 Both ldap_get_option() and ldap_set_option() return 0 if successful and 1067 -1 if an error occurs. If -1 is returned by either function, a specific 1068 result code MAY be retrieved by calling ldap_get_option() with an option 1069 value of LDAP_OPT_RESULT_CODE. Note that there is no way to retrieve a 1070 more specific result code if a call to ldap_get_option() with an option 1071 value of LDAP_OPT_RESULT_CODE fails. 1073 When a call to ldap_get_option() succeeds, the API implementation MUST 1074 NOT change the state of the LDAP session handle or the state of the 1075 underlying implementation in a way that affects the behavior of future 1076 LDAP API calls. When a call to ldap_get_option() fails, the only ses- 1077 sion handle change permitted is setting the LDAP result code (as 1078 returned by the LDAP_OPT_RESULT_CODE option). 1080 When a call to ldap_set_option() fails, it MUST NOT change the state of 1081 the LDAP session handle or the state of the underlying implementation in 1082 a way that affects the behavior of future LDAP API calls. 1084 Standards track documents that extend this specification and specify new 1085 options SHOULD use values for option macros that are between 0x1000 and 1086 0x3FFF inclusive. Private and experimental extensions SHOULD use values 1087 for the option macros that are between 0x4000 and 0x7FFF inclusive. All 1088 values below 0x1000 and above 0x7FFF that are not defined in this docu- 1089 ment are reserved and SHOULD NOT be used. The following macro MUST be 1090 C LDAP API C LDAP Application Program Interface 17 November 2000 1092 defined by C LDAP API implementations to aid extension implementors: 1093 #define LDAP_OPT_PRIVATE_EXTENSION_BASE 0x4000 /* to 0x7FFF inclusive */ 1095 11.3. Working With Controls 1097 LDAPv3 operations can be extended through the use of controls. Controls 1098 can be sent to a server or returned to the client with any LDAP message. 1099 These controls are referred to as server controls. 1101 The LDAP API also supports a client-side extension mechanism through the 1102 use of client controls. These controls affect the behavior of the LDAP 1103 API only and are never sent to a server. A common data structure is 1104 used to represent both types of controls: 1106 typedef struct ldapcontrol { 1107 char *ldctl_oid; 1108 struct berval ldctl_value; 1109 char ldctl_iscritical; 1110 } LDAPControl; 1112 The fields in the ldapcontrol structure have the following meanings: 1114 ldctl_oid The control type, represented as a string. 1116 ldctl_value The data associated with the control (if any). To 1117 specify a zero-length value, set ldctl_value.bv_len to 1118 zero and ldctl_value.bv_val to a zero-length string. 1119 To indicate that no data is associated with the con- 1120 trol, set ldctl_value.bv_val to NULL. 1122 ldctl_iscritical Indicates whether the control is critical of not. If 1123 this field is non-zero, the operation will only be car- 1124 ried out if the control is recognized by the server 1125 and/or client. Note that the LDAP unbind and abandon 1126 operations have no server response, so clients SHOULD 1127 NOT mark server controls critical when used with these 1128 two operations. 1130 Some LDAP API calls allocate an ldapcontrol structure or a NULL- 1131 terminated array of ldapcontrol structures. The following routines can 1132 be used to dispose of a single control or an array of controls: 1134 void ldap_control_free( LDAPControl *ctrl ); 1135 void ldap_controls_free( LDAPControl **ctrls ); 1136 If the ctrl or ctrls parameter is NULL, these calls do nothing. 1138 C LDAP API C LDAP Application Program Interface 17 November 2000 1140 A set of controls that affect the entire session can be set using the 1141 ldap_set_option() function (see above). A list of controls can also be 1142 passed directly to some LDAP API calls such as ldap_search_ext(), in 1143 which case any controls set for the session through the use of 1144 ldap_set_option() are ignored. Control lists are represented as a NULL- 1145 terminated array of pointers to ldapcontrol structures. 1147 Server controls are defined by LDAPv3 protocol extension documents; for 1148 example, a control has been proposed to support server-side sorting of 1149 search results [11]. 1151 One client control is defined in this document (described in the follow- 1152 ing section). Other client controls MAY be defined in future revisions 1153 of this document or in documents that extend this API. 1155 11.3.1. A Client Control That Governs Referral Processing 1157 As described previously in the section "LDAP Session Handle Options," 1158 applications can enable and disable automatic chasing of referrals on a 1159 session-wide basic by using the ldap_set_option() function with the 1160 LDAP_OPT_REFERRALS option. It is also useful to govern automatic refer- 1161 ral chasing on per-request basis. A client control with an OID of 1162 1.2.840.113556.1.4.616 exists to provide this functionality. 1164 /* OID for referrals client control */ 1165 #define LDAP_CONTROL_REFERRALS "1.2.840.113556.1.4.616" 1167 /* Flags for referrals client control value */ 1168 #define LDAP_CHASE_SUBORDINATE_REFERRALS 0x00000020U 1169 #define LDAP_CHASE_EXTERNAL_REFERRALS 0x00000040U 1171 To create a referrals client control, the ldctl_oid field of an LDAPCon- 1172 trol structure MUST be set to LDAP_CONTROL_REFERRALS 1173 ("1.2.840.113556.1.4.616") and the ldctl_value field MUST be set to a 1174 value that contains a set of flags. The ldctl_value.bv_len field MUST 1175 be set to sizeof(ber_uint_t), and the ldctl_value.bv_val field MUST 1176 point to a ber_uint_t which contains the flags value." The ber_uint_t 1177 type is define in the section "BER Data Structures and Types" below. 1179 The flags value can be set to zero to disable automatic chasing of 1180 referrals and LDAPv3 references altogether. Alternatively, the flags 1181 value can be set to the value LDAP_CHASE_SUBORDINATE_REFERRALS 1182 (0x00000020U) to indicate that only LDAPv3 search continuation refer- 1183 ences are to be automatically chased by the API implementation, to the 1184 value LDAP_CHASE_EXTERNAL_REFERRALS (0x00000040U) to indicate that only 1185 LDAPv3 referrals are to be automatically chased, or the logical OR of 1186 the two flag values (0x00000060U) to indicate that both referrals and 1187 C LDAP API C LDAP Application Program Interface 17 November 2000 1189 references are to be automatically chased. 1191 11.4. Authenticating to the directory 1193 The following functions are used to authenticate an LDAP client to an 1194 LDAP directory server. 1196 The ldap_sasl_bind() and ldap_sasl_bind_s() functions can be used to do 1197 general and extensible authentication over LDAP through the use of the 1198 Simple Authentication Security Layer [12]. The routines both take the 1199 dn to bind as, the method to use, as a dotted-string representation of 1200 an OID identifying the method, and a struct berval holding the creden- 1201 tials. The special constant value LDAP_SASL_SIMPLE (NULL) can be passed 1202 to request simple authentication, or the simplified routines 1203 ldap_simple_bind() or ldap_simple_bind_s() can be used. 1205 int ldap_sasl_bind( 1206 LDAP *ld, 1207 const char *dn, 1208 const char *mechanism, 1209 const struct berval *cred, 1210 LDAPControl **serverctrls, 1211 LDAPControl **clientctrls, 1212 int *msgidp 1213 ); 1215 int ldap_sasl_bind_s( 1216 LDAP *ld, 1217 const char *dn, 1218 const char *mechanism, 1219 const struct berval *cred, 1220 LDAPControl **serverctrls, 1221 LDAPControl **clientctrls, 1222 struct berval **servercredp 1223 ); 1225 int ldap_simple_bind( 1226 LDAP *ld, 1227 const char *dn, 1228 const char *passwd 1229 ); 1231 int ldap_simple_bind_s( 1232 LDAP *ld, 1233 const char *dn, 1234 const char *passwd 1235 ); 1237 C LDAP API C LDAP Application Program Interface 17 November 2000 1239 The use of the following routines is deprecated and more complete 1240 descriptions can be found in RFC 1823: 1242 int ldap_bind( LDAP *ld, const char *dn, const char *cred, 1243 int method ); 1245 int ldap_bind_s( LDAP *ld, const char *dn, const char *cred, 1246 int method ); 1248 int ldap_kerberos_bind( LDAP *ld, const char *dn ); 1250 int ldap_kerberos_bind_s( LDAP *ld, const char *dn ); 1252 Parameters are: 1254 ld The session handle. 1256 dn The name of the entry to bind as. If NULL, a zero length 1257 DN is sent to the server. 1259 mechanism Either LDAP_SASL_SIMPLE (NULL) to get simple authentica- 1260 tion, or a text string identifying the SASL method. 1262 cred The credentials with which to authenticate. Arbitrary 1263 credentials can be passed using this parameter. The format 1264 and content of the credentials depends on the setting of 1265 the mechanism parameter. If the cred parameter is NULL and 1266 the mechanism is LDAP_SASL_SIMPLE, a zero-length octet 1267 string is sent to the server in the simple credentials 1268 field of the bind request. If the cred parameter is NULL 1269 and the mechanism is anything else, no credentials are sent 1270 to the server in the bind request. 1272 passwd For ldap_simple_bind(), the password that is sent to the 1273 server in the simple credentials field of the bind request. 1274 If NULL, a zero length password is sent to the server. 1276 serverctrls List of LDAP server controls, or NULL if no server controls 1277 are used. 1279 clientctrls List of client controls, or NULL if no client controls are 1280 used. 1282 msgidp This result parameter will be set to the message id of the 1283 request if the ldap_sasl_bind() call succeeds. The value 1284 is undefined if a value other than LDAP_SUCCESS is 1285 returned. 1287 C LDAP API C LDAP Application Program Interface 17 November 2000 1289 servercredp This result parameter will be filled in with the creden- 1290 tials passed back by the server for mutual authentication, 1291 if given. An allocated berval structure is returned that 1292 SHOULD be disposed of by calling ber_bvfree(). NULL SHOULD 1293 be passed to ignore this field. If an API error occurs or 1294 the server did not return any credentials, *servercredp is 1295 set to NULL. 1297 Additional parameters for the deprecated routines are not described. 1298 Interested readers are referred to RFC 1823. 1300 The ldap_sasl_bind() function initiates an asynchronous bind operation 1301 and returns the constant LDAP_SUCCESS if the request was successfully 1302 sent, or another LDAP result code if not. See the section below on 1303 error handling for more information about possible errors and how to 1304 interpret them. If successful, ldap_sasl_bind() places the message id 1305 of the request in *msgidp. A subsequent call to ldap_result(), described 1306 below, can be used to obtain the result of the bind. 1308 The ldap_simple_bind() function initiates a simple asynchronous bind 1309 operation and returns the message id of the operation initiated. A sub- 1310 sequent call to ldap_result(), described below, can be used to obtain 1311 the result of the bind. In case of error, ldap_simple_bind() will return 1312 -1, setting the session error parameters in the LDAP structure appropri- 1313 ately. 1315 The synchronous ldap_sasl_bind_s() and ldap_simple_bind_s() functions 1316 both return the result of the operation, either the constant 1317 LDAP_SUCCESS if the operation was successful, or another LDAP result 1318 code if it was not. See the section below on error handling for more 1319 information about possible errors and how to interpret them. 1321 Note that if an LDAPv2 server is contacted, no other operations over the 1322 connection can be attempted before a bind call has successfully com- 1323 pleted. 1325 Subsequent bind calls can be used to re-authenticate over the same con- 1326 nection, and multistep SASL sequences can be accomplished through a 1327 sequence of calls to ldap_sasl_bind() or ldap_sasl_bind_s(). 1329 11.5. Closing the session 1331 The following functions are used to unbind from the directory, close 1332 open connections, and dispose of the session handle. 1334 int ldap_unbind_ext( LDAP *ld, LDAPControl **serverctrls, 1335 LDAPControl **clientctrls ); 1337 C LDAP API C LDAP Application Program Interface 17 November 2000 1339 int ldap_unbind( LDAP *ld ); 1341 int ldap_unbind_s( LDAP *ld ); 1343 Parameters are: 1345 ld The session handle. 1347 serverctrls List of LDAP server controls, or NULL if no server controls 1348 are to be used. 1350 clientctrls List of client controls, or NULL if no client controls are 1351 to be used. 1353 The ldap_unbind_ext(), ldap_unbind() and ldap_unbind_s() all work syn- 1354 chronously in the sense that they send an unbind request to the server, 1355 close all open connections associated with the LDAP session handle, and 1356 dispose of all resources associated with the session handle before 1357 returning. Note, however, that there is no server response to an LDAP 1358 unbind operation. All three of the unbind functions return LDAP_SUCCESS 1359 (or another LDAP result code if the request cannot be sent to the LDAP 1360 server). After a call to one of the unbind functions, the session han- 1361 dle ld is invalid and it is illegal to make any further LDAP API calls 1362 using ld. 1364 The ldap_unbind() and ldap_unbind_s() functions behave identically. The 1365 ldap_unbind_ext() function allows server and client controls to be 1366 included explicitly, but note that since there is no server response to 1367 an unbind request there is no way to receive a response to a server con- 1368 trol sent with an unbind request. 1370 11.6. Searching 1372 The following functions are used to search the LDAP directory, returning 1373 a requested set of attributes for each entry matched. There are five 1374 variations. 1376 int ldap_search_ext( 1377 LDAP *ld, 1378 const char *base, 1379 int scope, 1380 const char *filter, 1381 char **attrs, 1382 int attrsonly, 1383 LDAPControl **serverctrls, 1384 LDAPControl **clientctrls, 1386 C LDAP API C LDAP Application Program Interface 17 November 2000 1388 struct timeval *timeout, 1389 int sizelimit, 1390 int *msgidp 1391 ); 1393 int ldap_search_ext_s( 1394 LDAP *ld, 1395 const char *base, 1396 int scope, 1397 const char *filter, 1398 char **attrs, 1399 int attrsonly, 1400 LDAPControl **serverctrls, 1401 LDAPControl **clientctrls, 1402 struct timeval *timeout, 1403 int sizelimit, 1404 LDAPMessage **res 1405 ); 1407 int ldap_search( 1408 LDAP *ld, 1409 const char *base, 1410 int scope, 1411 const char *filter, 1412 char **attrs, 1413 int attrsonly 1414 ); 1416 int ldap_search_s( 1417 LDAP *ld, 1418 const char *base, 1419 int scope, 1420 const char *filter, 1421 char **attrs, 1422 int attrsonly, 1423 LDAPMessage **res 1424 ); 1426 int ldap_search_st( 1427 LDAP *ld, 1428 const char *base, 1429 int scope, 1430 const char *filter, 1431 char **attrs, 1432 int attrsonly, 1433 struct timeval *timeout, 1434 LDAPMessage **res 1435 ); 1437 C LDAP API C LDAP Application Program Interface 17 November 2000 1439 Parameters are: 1441 ld The session handle. 1443 base The dn of the entry at which to start the search. If NULL, 1444 a zero length DN is sent to the server. 1446 scope One of LDAP_SCOPE_BASE (0x00), LDAP_SCOPE_ONELEVEL (0x01), 1447 or LDAP_SCOPE_SUBTREE (0x02), indicating the scope of the 1448 search. 1450 filter A character string as described in [13], representing the 1451 search filter. The value NULL can be passed to indicate 1452 that the filter "(objectclass=*)" which matches all entries 1453 is to be used. Note that if the caller of the API is using 1454 LDAPv2, only a subset of the filter functionality described 1455 in [13] can be successfully used. 1457 attrs A NULL-terminated array of strings indicating which attri- 1458 butes to return for each matching entry. Passing NULL for 1459 this parameter causes all available user attributes to be 1460 retrieved. The special constant string LDAP_NO_ATTRS 1461 ("1.1") MAY be used as the only string in the array to 1462 indicate that no attribute types are to be returned by the 1463 server. The special constant string LDAP_ALL_USER_ATTRS 1464 ("*") can be used in the attrs array along with the names 1465 of some operational attributes to indicate that all user 1466 attributes plus the listed operational attributes are to be 1467 returned. 1469 attrsonly A boolean value that MUST be zero if both attribute types 1470 and values are to be returned, and non-zero if only types 1471 are wanted. 1473 timeout For the ldap_search_st() function, this specifies the local 1474 search timeout value (if it is NULL, the timeout is infin- 1475 ite). If a zero timeout (where tv_sec and tv_usec are both 1476 zero) is passed, API implementations SHOULD return 1477 LDAP_PARAM_ERROR. 1479 For the ldap_search_ext() and ldap_search_ext_s() func- 1480 tions, the timeout parameter specifies both the local 1481 search timeout value and the operation time limit that is 1482 sent to the server within the search request. Passing a 1483 NULL value for timeout causes the default timeout stored in 1484 the LDAP session handle (set by using ldap_set_option() 1485 with the LDAP_OPT_TIMELIMIT parameter) to be sent to the 1486 server with the request but an infinite local search 1488 C LDAP API C LDAP Application Program Interface 17 November 2000 1490 timeout to be used. If a zero timeout (where tv_sec and 1491 tv_usec are both zero) is passed in, API implementations 1492 SHOULD return LDAP_PARAM_ERROR. If a zero value for tv_sec 1493 is used but tv_usec is non-zero, an operation time limit of 1494 1 SHOULD be passed to the LDAP server as the operation time 1495 limit. For other values of tv_sec, the tv_sec value itself 1496 SHOULD be passed to the LDAP server. 1498 sizelimit For the ldap_search_ext() and ldap_search_ext_s() calls, 1499 this is a limit on the number of entries to return from the 1500 search. A value of LDAP_NO_LIMIT (0) means no limit. A 1501 value of LDAP_DEFAULT_SIZELIMIT (-1) means use the default 1502 timeout from the LDAP session handle (which is set by cal- 1503 ling ldap_set_option() with the LDAP_OPT_SIZELIMIT parame- 1504 ter). 1506 res For the synchronous calls, this is a result parameter which 1507 will contain the results of the search upon completion of 1508 the call. If an API error occurs or no results are 1509 returned, *res is set to NULL. 1511 serverctrls List of LDAP server controls, or NULL if no server controls 1512 are to be used. 1514 clientctrls List of client controls, or NULL if no client controls are 1515 to be used. 1517 msgidp This result parameter will be set to the message id of the 1518 request if the ldap_search_ext() call succeeds. The value 1519 is undefined if a value other than LDAP_SUCCESS is 1520 returned. 1522 There are three options in the session handle ld which potentially 1523 affect how the search is performed. They are: 1525 LDAP_OPT_SIZELIMIT 1526 LDAP_OPT_TIMELIMIT 1527 LDAP_OPT_DEREF 1529 These options are fully described in the earlier section "LDAP Session 1530 Handle Options." 1532 The ldap_search_ext() function initiates an asynchronous search opera- 1533 tion and returns the constant LDAP_SUCCESS if the request was success- 1534 fully sent, or another LDAP result code if not. See the section below 1535 on error handling for more information about possible errors and how to 1536 interpret them. If successful, ldap_search_ext() places the message id 1537 of the request in *msgidp. A subsequent call to ldap_result(), described 1538 C LDAP API C LDAP Application Program Interface 17 November 2000 1540 below, can be used to obtain the results from the search. These results 1541 can be parsed using the result parsing routines described in detail 1542 later. 1544 Similar to ldap_search_ext(), the ldap_search() function initiates an 1545 asynchronous search operation and returns the message id of the opera- 1546 tion initiated. As for ldap_search_ext(), a subsequent call to 1547 ldap_result(), described below, can be used to obtain the result of the 1548 bind. In case of error, ldap_search() will return -1, setting the ses- 1549 sion error parameters in the LDAP structure appropriately. 1551 The synchronous ldap_search_ext_s(), ldap_search_s(), and 1552 ldap_search_st() functions all return the result of the operation, 1553 either the constant LDAP_SUCCESS if the operation was successful, or 1554 another LDAP result code if it was not. See the section below on error 1555 handling for more information about possible errors and how to interpret 1556 them. Entries returned from the search (if any) are contained in the 1557 res parameter. This parameter is opaque to the caller. Entries, attri- 1558 butes, values, etc., can be extracted by calling the parsing routines 1559 described below. The results contained in res SHOULD be freed when no 1560 longer in use by calling ldap_msgfree(), described later. 1562 The ldap_search_ext() and ldap_search_ext_s() functions support LDAPv3 1563 server controls, client controls, and allow varying size and time limits 1564 to be easily specified for each search operation. The ldap_search_st() 1565 function is identical to ldap_search_s() except that it takes an addi- 1566 tional parameter specifying a local timeout for the search. The local 1567 search timeout is used to limit the amount of time the API implementa- 1568 tion will wait for a search to complete. After the local search timeout 1569 expires, the API implementation will send an abandon operation to abort 1570 the search operation. 1572 11.7. Reading an Entry 1574 LDAP does not support a read operation directly. Instead, this operation 1575 is emulated by a search with base set to the DN of the entry to read, 1576 scope set to LDAP_SCOPE_BASE, and filter set to "(objectclass=*)" or 1577 NULL. attrs contains the list of attributes to return. 1579 11.8. Listing the Children of an Entry 1581 LDAP does not support a list operation directly. Instead, this operation 1582 is emulated by a search with base set to the DN of the entry to list, 1583 scope set to LDAP_SCOPE_ONELEVEL, and filter set to "(objectclass=*)" or 1584 NULL. attrs contains the list of attributes to return for each child 1585 entry. 1587 C LDAP API C LDAP Application Program Interface 17 November 2000 1589 11.9. Comparing a Value Against an Entry 1591 The following routines are used to compare a given attribute value 1592 assertion against an LDAP entry. There are four variations: 1594 int ldap_compare_ext( 1595 LDAP *ld, 1596 const char *dn, 1597 const char *attr, 1598 const struct berval *bvalue, 1599 LDAPControl **serverctrls, 1600 LDAPControl **clientctrls, 1601 int *msgidp 1602 ); 1604 int ldap_compare_ext_s( 1605 LDAP *ld, 1606 const char *dn, 1607 const char *attr, 1608 const struct berval *bvalue, 1609 LDAPControl **serverctrls, 1610 LDAPControl **clientctrls 1611 ); 1613 int ldap_compare( 1614 LDAP *ld, 1615 const char *dn, 1616 const char *attr, 1617 const char *value 1618 ); 1620 int ldap_compare_s( 1621 LDAP *ld, 1622 const char *dn, 1623 const char *attr, 1624 const char *value 1625 ); 1627 Parameters are: 1629 ld The session handle. 1631 dn The name of the entry to compare against. If NULL, a zero 1632 length DN is sent to the server. 1634 attr The attribute to compare against. 1636 bvalue The attribute value to compare against those found in the 1637 C LDAP API C LDAP Application Program Interface 17 November 2000 1639 given entry. This parameter is used in the extended rou- 1640 tines and is a pointer to a struct berval so it is possible 1641 to compare binary values. 1643 value A string attribute value to compare against, used by the 1644 ldap_compare() and ldap_compare_s() functions. Use 1645 ldap_compare_ext() or ldap_compare_ext_s() if you need to 1646 compare binary values. 1648 serverctrls List of LDAP server controls, or NULL if no server controls 1649 are to be used. 1651 clientctrls List of client controls, or NULL if no client controls are 1652 to be used. 1654 msgidp This result parameter will be set to the message id of the 1655 request if the ldap_compare_ext() call succeeds. The value 1656 is undefined if a value other than LDAP_SUCCESS is 1657 returned. 1659 The ldap_compare_ext() function initiates an asynchronous compare opera- 1660 tion and returns the constant LDAP_SUCCESS if the request was success- 1661 fully sent, or another LDAP result code if not. See the section below 1662 on error handling for more information about possible errors and how to 1663 interpret them. If successful, ldap_compare_ext() places the message id 1664 of the request in *msgidp. A subsequent call to ldap_result(), described 1665 below, can be used to obtain the result of the compare. 1667 Similar to ldap_compare_ext(), the ldap_compare() function initiates an 1668 asynchronous compare operation and returns the message id of the opera- 1669 tion initiated. As for ldap_compare_ext(), a subsequent call to 1670 ldap_result(), described below, can be used to obtain the result of the 1671 bind. In case of error, ldap_compare() will return -1, setting the ses- 1672 sion error parameters in the LDAP structure appropriately. 1674 The synchronous ldap_compare_ext_s() and ldap_compare_s() functions both 1675 return the result of the operation: one of the constants 1676 LDAP_COMPARE_TRUE or LDAP_COMPARE_FALSE if the operation was successful, 1677 or another LDAP result code if it was not. See the section below on 1678 error handling for more information about possible errors and how to 1679 interpret them. 1681 The ldap_compare_ext() and ldap_compare_ext_s() functions support LDAPv3 1682 server controls and client controls. 1684 C LDAP API C LDAP Application Program Interface 17 November 2000 1686 11.10. Modifying an entry 1688 The following routines are used to modify an existing LDAP entry. There 1689 are four variations: 1691 typedef union mod_vals_u { 1692 char **modv_strvals; 1693 struct berval **modv_bvals; 1694 } mod_vals_u_t; 1696 typedef struct ldapmod { 1697 int mod_op; 1698 char *mod_type; 1699 mod_vals_u_t mod_vals; 1700 } LDAPMod; 1701 #define mod_values mod_vals.modv_strvals 1702 #define mod_bvalues mod_vals.modv_bvals 1704 int ldap_modify_ext( 1705 LDAP *ld, 1706 const char *dn, 1707 LDAPMod **mods, 1708 LDAPControl **serverctrls, 1709 LDAPControl **clientctrls, 1710 int *msgidp 1711 ); 1713 int ldap_modify_ext_s( 1714 LDAP *ld, 1715 const char *dn, 1716 LDAPMod **mods, 1717 LDAPControl **serverctrls, 1718 LDAPControl **clientctrls 1719 ); 1721 int ldap_modify( 1722 LDAP *ld, 1723 const char *dn, 1724 LDAPMod **mods 1725 ); 1727 int ldap_modify_s( 1728 LDAP *ld, 1729 const char *dn, 1730 LDAPMod **mods 1731 ); 1733 Parameters are: 1735 C LDAP API C LDAP Application Program Interface 17 November 2000 1737 ld The session handle. 1739 dn The name of the entry to modify. If NULL, a zero length DN 1740 is sent to the server. 1742 mods A NULL-terminated array of modifications to make to the 1743 entry. 1745 serverctrls List of LDAP server controls, or NULL if no server controls 1746 are to be used. 1748 clientctrls List of client controls, or NULL if no client controls are 1749 to be used. 1751 msgidp This result parameter will be set to the message id of the 1752 request if the ldap_modify_ext() call succeeds. The value 1753 is undefined if a value other than LDAP_SUCCESS is 1754 returned. 1756 The fields in the LDAPMod structure have the following meanings: 1758 mod_op The modification operation to perform. It MUST be one of 1759 LDAP_MOD_ADD (0x00), LDAP_MOD_DELETE (0x01), or 1760 LDAP_MOD_REPLACE (0x02). This field also indicates the 1761 type of values included in the mod_vals union. It is logi- 1762 cally ORed with LDAP_MOD_BVALUES (0x80) to select the 1763 mod_bvalues form. Otherwise, the mod_values form is used. 1765 mod_type The type of the attribute to modify. 1767 mod_vals The values (if any) to add, delete, or replace. Only one of 1768 the mod_values or mod_bvalues variants can be used, 1769 selected by ORing the mod_op field with the constant 1770 LDAP_MOD_BVALUES. mod_values is a NULL-terminated array of 1771 zero-terminated strings and mod_bvalues is a NULL- 1772 terminated array of berval structures that can be used to 1773 pass binary values such as images. 1775 For LDAP_MOD_ADD modifications, the given values are added to the 1776 entry, creating the attribute if necessary. 1778 For LDAP_MOD_DELETE modifications, the given values are deleted from the 1779 entry, removing the attribute if no values remain. If the entire attri- 1780 bute is to be deleted, the mod_vals field can be set to NULL. 1782 For LDAP_MOD_REPLACE modifications, the attribute will have the listed 1783 values after the modification, having been created if necessary, or 1784 removed if the mod_vals field is NULL. All modifications are performed 1785 C LDAP API C LDAP Application Program Interface 17 November 2000 1787 in the order in which they are listed. 1789 The ldap_modify_ext() function initiates an asynchronous modify opera- 1790 tion and returns the constant LDAP_SUCCESS if the request was success- 1791 fully sent, or another LDAP result code if not. See the section below 1792 on error handling for more information about possible errors and how to 1793 interpret them. If successful, ldap_modify_ext() places the message id 1794 of the request in *msgidp. A subsequent call to ldap_result(), described 1795 below, can be used to obtain the result of the modify. 1797 Similar to ldap_modify_ext(), the ldap_modify() function initiates an 1798 asynchronous modify operation and returns the message id of the opera- 1799 tion initiated. As for ldap_modify_ext(), a subsequent call to 1800 ldap_result(), described below, can be used to obtain the result of the 1801 modify. In case of error, ldap_modify() will return -1, setting the ses- 1802 sion error parameters in the LDAP structure appropriately. 1804 The synchronous ldap_modify_ext_s() and ldap_modify_s() functions both 1805 return the result of the operation, either the constant LDAP_SUCCESS if 1806 the operation was successful, or another LDAP result code if it was not. 1807 See the section below on error handling for more information about pos- 1808 sible errors and how to interpret them. 1810 The ldap_modify_ext() and ldap_modify_ext_s() functions support LDAPv3 1811 server controls and client controls. 1813 11.11. Modifying the Name of an Entry 1815 In LDAPv2, the ldap_modrdn(), ldap_modrdn_s(), ldap_modrdn2(), and 1816 ldap_modrdn2_s() routines were used to change the name of an LDAP entry. 1817 They could only be used to change the least significant component of a 1818 name (the RDN or relative distinguished name). LDAPv3 provides the 1819 Modify DN protocol operation that allows more general name change 1820 access. The ldap_rename() and ldap_rename_s() routines are used to 1821 change the name of an entry, and the use of the ldap_modrdn(), 1822 ldap_modrdn_s(), ldap_modrdn2(), and ldap_modrdn2_s() routines is depre- 1823 cated. 1825 int ldap_rename( 1826 LDAP *ld, 1827 const char *dn, 1828 const char *newrdn, 1829 const char *newparent, 1830 int deleteoldrdn, 1831 LDAPControl **serverctrls, 1832 LDAPControl **clientctrls, 1833 int *msgidp 1835 C LDAP API C LDAP Application Program Interface 17 November 2000 1837 ); 1838 int ldap_rename_s( 1839 LDAP *ld, 1840 const char *dn, 1841 const char *newrdn, 1842 const char *newparent, 1843 int deleteoldrdn, 1844 LDAPControl **serverctrls, 1845 LDAPControl **clientctrls 1846 ); 1848 The use of the following routines is deprecated and more complete 1849 descriptions can be found in RFC 1823: 1851 int ldap_modrdn( 1852 LDAP *ld, 1853 const char *dn, 1854 const char *newrdn 1855 ); 1856 int ldap_modrdn_s( 1857 LDAP *ld, 1858 const char *dn, 1859 const char *newrdn 1860 ); 1861 int ldap_modrdn2( 1862 LDAP *ld, 1863 const char *dn, 1864 const char *newrdn, 1865 int deleteoldrdn 1866 ); 1867 int ldap_modrdn2_s( 1868 LDAP *ld, 1869 const char *dn, 1870 const char *newrdn, 1871 int deleteoldrdn 1872 ); 1874 Parameters are: 1876 ld The session handle. 1878 dn The name of the entry whose DN is to be changed. If NULL, 1879 a zero length DN is sent to the server. 1881 newrdn The new RDN to give the entry. 1883 newparent The new parent, or superior entry. If this parameter is 1884 NULL, only the RDN of the entry is changed. The root DN 1886 C LDAP API C LDAP Application Program Interface 17 November 2000 1888 SHOULD be specified by passing a zero length string, "". 1889 The newparent parameter SHOULD always be NULL when using 1890 version 2 of the LDAP protocol; otherwise the server's 1891 behavior is undefined. 1893 deleteoldrdn This parameter only has meaning on the rename routines if 1894 newrdn is different than the old RDN. It is a boolean 1895 value, if non-zero indicating that the old RDN value(s) is 1896 to be removed, if zero indicating that the old RDN value(s) 1897 is to be retained as non-distinguished values of the entry. 1899 serverctrls List of LDAP server controls, or NULL if no server controls 1900 are to be used. 1902 clientctrls List of client controls, or NULL if no client controls are 1903 to be used. 1905 msgidp This result parameter will be set to the message id of the 1906 request if the ldap_rename() call succeeds. The value is 1907 undefined if a value other than LDAP_SUCCESS is returned. 1909 The ldap_rename() function initiates an asynchronous modify DN operation 1910 and returns the constant LDAP_SUCCESS if the request was successfully 1911 sent, or another LDAP result code if not. See the section below on 1912 error handling for more information about possible errors and how to 1913 interpret them. If successful, ldap_rename() places the DN message id 1914 of the request in *msgidp. A subsequent call to ldap_result(), described 1915 below, can be used to obtain the result of the rename. 1917 The synchronous ldap_rename_s() returns the result of the operation, 1918 either the constant LDAP_SUCCESS if the operation was successful, or 1919 another LDAP result code if it was not. See the section below on error 1920 handling for more information about possible errors and how to interpret 1921 them. 1923 The ldap_rename() and ldap_rename_s() functions both support LDAPv3 1924 server controls and client controls. 1926 11.12. Adding an entry 1928 The following functions are used to add entries to the LDAP directory. 1929 There are four variations: 1931 int ldap_add_ext( 1932 LDAP *ld, 1933 const char *dn, 1934 LDAPMod **attrs, 1936 C LDAP API C LDAP Application Program Interface 17 November 2000 1938 LDAPControl **serverctrls, 1939 LDAPControl **clientctrls, 1940 int *msgidp 1941 ); 1943 int ldap_add_ext_s( 1944 LDAP *ld, 1945 const char *dn, 1946 LDAPMod **attrs, 1947 LDAPControl **serverctrls, 1948 LDAPControl **clientctrls 1949 ); 1951 int ldap_add( 1952 LDAP *ld, 1953 const char *dn, 1954 LDAPMod **attrs 1955 ); 1957 int ldap_add_s( 1958 LDAP *ld, 1959 const char *dn, 1960 LDAPMod **attrs 1961 ); 1963 Parameters are: 1965 ld The session handle. 1967 dn The name of the entry to add. If NULL, a zero length DN is 1968 sent to the server. 1970 attrs The entry's attributes, specified using the LDAPMod struc- 1971 ture defined for ldap_modify(). The mod_type and mod_vals 1972 fields MUST be filled in. The mod_op field is ignored 1973 unless ORed with the constant LDAP_MOD_BVALUES, used to 1974 select the mod_bvalues case of the mod_vals union. 1976 serverctrls List of LDAP server controls, or NULL if no server controls 1977 are to be used. 1979 clientctrls List of client controls, or NULL if no client controls are 1980 to be used. 1982 msgidp This result parameter will be set to the message id of the 1983 request if the ldap_add_ext() call succeeds. The value is 1984 undefined if a value other than LDAP_SUCCESS is returned. 1986 C LDAP API C LDAP Application Program Interface 17 November 2000 1988 Note that the parent of the entry being added must already exist or the 1989 parent must be empty (i.e., equal to the root DN) for an add to succeed. 1991 The ldap_add_ext() function initiates an asynchronous add operation and 1992 returns the constant LDAP_SUCCESS if the request was successfully sent, 1993 or another LDAP result code if not. See the section below on error han- 1994 dling for more information about possible errors and how to interpret 1995 them. If successful, ldap_add_ext() places the message id of the 1996 request in *msgidp. A subsequent call to ldap_result(), described below, 1997 can be used to obtain the result of the add. 1999 Similar to ldap_add_ext(), the ldap_add() function initiates an asyn- 2000 chronous add operation and returns the message id of the operation ini- 2001 tiated. As for ldap_add_ext(), a subsequent call to ldap_result(), 2002 described below, can be used to obtain the result of the add. In case of 2003 error, ldap_add() will return -1, setting the session error parameters 2004 in the LDAP structure appropriately. 2006 The synchronous ldap_add_ext_s() and ldap_add_s() functions both return 2007 the result of the operation, either the constant LDAP_SUCCESS if the 2008 operation was successful, or another LDAP result code if it was not. 2009 See the section below on error handling for more information about pos- 2010 sible errors and how to interpret them. 2012 The ldap_add_ext() and ldap_add_ext_s() functions support LDAPv3 server 2013 controls and client controls. 2015 11.13. Deleting an entry 2017 The following functions are used to delete a leaf entry from the LDAP 2018 directory. There are four variations: 2020 int ldap_delete_ext( 2021 LDAP *ld, 2022 const char *dn, 2023 LDAPControl **serverctrls, 2024 LDAPControl **clientctrls, 2025 int *msgidp 2026 ); 2028 int ldap_delete_ext_s( 2029 LDAP *ld, 2030 const char *dn, 2031 LDAPControl **serverctrls, 2032 LDAPControl **clientctrls 2033 ); 2035 C LDAP API C LDAP Application Program Interface 17 November 2000 2037 int ldap_delete( 2038 LDAP *ld, 2039 const char *dn 2040 ); 2042 int ldap_delete_s( 2043 LDAP *ld, 2044 const char *dn 2045 ); 2047 Parameters are: 2049 ld The session handle. 2051 dn The name of the entry to delete. If NULL, a zero length DN 2052 is sent to the server. 2054 serverctrls List of LDAP server controls, or NULL if no server controls 2055 are to be used. 2057 clientctrls List of client controls, or NULL if no client controls are 2058 to be used. 2060 msgidp This result parameter will be set to the message id of the 2061 request if the ldap_delete_ext() call succeeds. The value 2062 is undefined if a value other than LDAP_SUCCESS is 2063 returned. 2065 Note that the entry to delete must be a leaf entry (i.e., it must have 2066 no children). Deletion of entire subtrees in a single operation is not 2067 supported by LDAP. 2069 The ldap_delete_ext() function initiates an asynchronous delete opera- 2070 tion and returns the constant LDAP_SUCCESS if the request was success- 2071 fully sent, or another LDAP result code if not. See the section below 2072 on error handling for more information about possible errors and how to 2073 interpret them. If successful, ldap_delete_ext() places the message id 2074 of the request in *msgidp. A subsequent call to ldap_result(), described 2075 below, can be used to obtain the result of the delete. 2077 Similar to ldap_delete_ext(), the ldap_delete() function initiates an 2078 asynchronous delete operation and returns the message id of the opera- 2079 tion initiated. As for ldap_delete_ext(), a subsequent call to 2080 ldap_result(), described below, can be used to obtain the result of the 2081 delete. In case of error, ldap_delete() will return -1, setting the ses- 2082 sion error parameters in the LDAP structure appropriately. 2084 C LDAP API C LDAP Application Program Interface 17 November 2000 2086 The synchronous ldap_delete_ext_s() and ldap_delete_s() functions both 2087 return the result of the operation, either the constant LDAP_SUCCESS if 2088 the operation was successful, or another LDAP result code if it was not. 2089 See the section below on error handling for more information about pos- 2090 sible errors and how to interpret them. 2092 The ldap_delete_ext() and ldap_delete_ext_s() functions support LDAPv3 2093 server controls and client controls. 2095 11.14. Extended Operations 2097 The ldap_extended_operation() and ldap_extended_operation_s() routines 2098 allow extended LDAP operations to be passed to the server, providing a 2099 general protocol extensibility mechanism. 2101 int ldap_extended_operation( 2102 LDAP *ld, 2103 const char *requestoid, 2104 const struct berval *requestdata, 2105 LDAPControl **serverctrls, 2106 LDAPControl **clientctrls, 2107 int *msgidp 2108 ); 2110 int ldap_extended_operation_s( 2111 LDAP *ld, 2112 const char *requestoid, 2113 const struct berval *requestdata, 2114 LDAPControl **serverctrls, 2115 LDAPControl **clientctrls, 2116 char **retoidp, 2117 struct berval **retdatap 2118 ); 2120 Parameters are: 2122 ld The session handle. 2124 requestoid The dotted-OID text string naming the request. 2126 requestdata The arbitrary data needed by the operation (if NULL, no 2127 data is sent to the server). 2129 serverctrls List of LDAP server controls, or NULL if no server controls 2130 are to be used. 2132 clientctrls List of client controls, or NULL if no client controls are 2133 C LDAP API C LDAP Application Program Interface 17 November 2000 2135 to be used. 2137 msgidp This result parameter will be set to the message id of the 2138 request if the ldap_extended_operation() call succeeds. The 2139 value is undefined if a value other than LDAP_SUCCESS is 2140 returned. 2142 retoidp Pointer to a character string that will be set to an allo- 2143 cated, dotted-OID text string returned by the server. This 2144 string SHOULD be disposed of using the ldap_memfree() func- 2145 tion. If an API error occurs or no OID is returned by the 2146 server, *retoidp is set to NULL. 2148 retdatap Pointer to a berval structure pointer that will be set an 2149 allocated copy of the data returned by the server. This 2150 struct berval SHOULD be disposed of using ber_bvfree(). If 2151 an API error occurs or no data is returned by the server, 2152 *retdatap is set to NULL. 2154 The ldap_extended_operation() function initiates an asynchronous 2155 extended operation and returns the constant LDAP_SUCCESS if the request 2156 was successfully sent, or another LDAP result code if not. See the sec- 2157 tion below on error handling for more information about possible errors 2158 and how to interpret them. If successful, ldap_extended_operation() 2159 places the message id of the request in *msgidp. A subsequent call to 2160 ldap_result(), described below, can be used to obtain the result of the 2161 extended operation which can be passed to ldap_parse_extended_result() 2162 to obtain the OID and data contained in the response. 2164 The synchronous ldap_extended_operation_s() function returns the result 2165 of the operation, either the constant LDAP_SUCCESS if the operation was 2166 successful, or another LDAP result code if it was not. See the section 2167 below on error handling for more information about possible errors and 2168 how to interpret them. The retoid and retdata parameters are filled in 2169 with the OID and data from the response. 2171 The ldap_extended_operation() and ldap_extended_operation_s() functions 2172 both support LDAPv3 server controls and client controls. 2174 12. Abandoning An Operation 2176 The following calls are used to abandon an operation in progress: 2178 int ldap_abandon_ext( 2179 LDAP *ld, 2180 int msgid, 2181 LDAPControl **serverctrls, 2183 C LDAP API C LDAP Application Program Interface 17 November 2000 2185 LDAPControl **clientctrls 2186 ); 2188 int ldap_abandon( 2189 LDAP *ld, 2190 int msgid 2191 ); 2193 ld The session handle. 2195 msgid The message id of the request to be abandoned. 2197 serverctrls List of LDAP server controls, or NULL if no server controls 2198 are to be used. 2200 clientctrls List of client controls, or NULL if no client controls are 2201 to be used. 2203 ldap_abandon_ext() abandons the operation with message id msgid and 2204 returns the constant LDAP_SUCCESS if the abandon was successful or 2205 another LDAP result code if not. See the section below on error han- 2206 dling for more information about possible errors and how to interpret 2207 them. 2209 ldap_abandon() is identical to ldap_abandon_ext() except that it does 2210 not accept client or server controls and it returns zero if the abandon 2211 was successful, -1 otherwise. 2213 After a successful call to ldap_abandon() or ldap_abandon_ext(), results 2214 with the given message id are never returned from a subsequent call to 2215 ldap_result(). There is no server response to LDAP abandon operations. 2217 13. Obtaining Results and Peeking Inside LDAP Messages 2219 ldap_result() is used to obtain the result of a previous asynchronously 2220 initiated operation. Note that depending on how it is called, 2221 ldap_result() can actually return a list or "chain" of result messages. 2222 The ldap_result() function only returns messages for a single request, 2223 so for all LDAP operations other than search only one result message is 2224 expected; that is, the only time the "result chain" can contain more 2225 than one message is if results from a search operation are returned. 2226 Once a chain of messages has been returned to the caller, it is no 2227 longer tied in any caller-visible way to the LDAP request that produced 2228 it. However, it MAY be tied to the session handle. Therefore, a chain 2229 of messages returned by calling ldap_result() or by calling a synchro- 2230 nous search routine will never be affected by subsequent LDAP API calls 2231 C LDAP API C LDAP Application Program Interface 17 November 2000 2233 except for ldap_msgfree() (which is used to dispose of a chain of mes- 2234 sages) and the unbind calls (which dispose of a session handle): 2235 ldap_unbind(), ldap_unbind_s(), or ldap_unbind_ext(), or functions 2236 defined by extensions of this API. 2238 ldap_msgfree() frees the result messages (possibly an entire chain of 2239 messages) obtained from a previous call to ldap_result() or from a call 2240 to a synchronous search routine. 2242 ldap_msgtype() returns the type of an LDAP message. 2244 ldap_msgid() returns the message ID of an LDAP message. 2246 int ldap_result( 2247 LDAP *ld, 2248 int msgid, 2249 int all, 2250 struct timeval *timeout, 2251 LDAPMessage **res 2252 ); 2254 int ldap_msgfree( LDAPMessage *res ); 2256 int ldap_msgtype( LDAPMessage *res ); 2258 int ldap_msgid( LDAPMessage *res ); 2260 Parameters are: 2262 ld The session handle. 2264 msgid The message id of the operation whose results are to be 2265 returned, the constant LDAP_RES_UNSOLICITED (0) if an unsoli- 2266 cited result is desired, or or the constant LDAP_RES_ANY (-1) 2267 if any result is desired. 2269 all Specifies how many messages will be retrieved in a single call 2270 to ldap_result(). This parameter only has meaning for search 2271 results. Pass the constant LDAP_MSG_ONE (0x00) to retrieve one 2272 message at a time. Pass LDAP_MSG_ALL (0x01) to request that 2273 all results of a search be received before returning all 2274 results in a single chain. Pass LDAP_MSG_RECEIVED (0x02) to 2275 indicate that all messages retrieved so far are to be returned 2276 in the result chain. 2278 timeout A timeout specifying how long to wait for results to be 2279 returned. A NULL value causes ldap_result() to block until 2280 results are available. A timeout value of zero seconds 2282 C LDAP API C LDAP Application Program Interface 17 November 2000 2284 specifies a polling behavior. 2286 res For ldap_result(), a result parameter that will contain the 2287 result(s) of the operation. If an API error occurs or no 2288 results are returned, *res is set to NULL. For ldap_msgfree(), 2289 the result chain to be freed, obtained from a previous call to 2290 ldap_result(), ldap_search_s(), or ldap_search_st(). If res is 2291 NULL, nothing is done and ldap_msgfree() returns zero. 2293 Upon successful completion, ldap_result() returns the type of the first 2294 result returned in the res parameter. This will be one of the following 2295 constants. 2297 LDAP_RES_BIND (0x61) 2298 LDAP_RES_SEARCH_ENTRY (0x64) 2299 LDAP_RES_SEARCH_REFERENCE (0x73) -- new in LDAPv3 2300 LDAP_RES_SEARCH_RESULT (0x65) 2301 LDAP_RES_MODIFY (0x67) 2302 LDAP_RES_ADD (0x69) 2303 LDAP_RES_DELETE (0x6B) 2304 LDAP_RES_MODDN (0x6D) 2305 LDAP_RES_COMPARE (0x6F) 2306 LDAP_RES_EXTENDED (0x78) -- new in LDAPv3 2308 ldap_result() returns 0 if the timeout expired and -1 if an error 2309 occurs, in which case the error parameters of the LDAP session handle 2310 will be set accordingly. 2312 ldap_msgfree() frees each message in the result chain pointed to by res 2313 and returns the type of the last message in the chain. If res is NULL, 2314 nothing is done and the value zero is returned. 2316 ldap_msgtype() returns the type of the LDAP message it is passed as a 2317 parameter. The type will be one of the types listed above, or -1 on 2318 error. 2320 ldap_msgid() returns the message ID associated with the LDAP message 2321 passed as a parameter, or -1 on error. 2323 14. Handling Errors and Parsing Results 2325 The following calls are used to extract information from results and 2326 handle errors returned by other LDAP API routines. Note that 2327 ldap_parse_sasl_bind_result() and ldap_parse_extended_result() must typ- 2328 ically be used in addition to ldap_parse_result() to retrieve all the 2329 result information from SASL Bind and Extended Operations respectively. 2331 C LDAP API C LDAP Application Program Interface 17 November 2000 2333 int ldap_parse_result( 2334 LDAP *ld, 2335 LDAPMessage *res, 2336 int *errcodep, 2337 char **matcheddnp, 2338 char **errmsgp, 2339 char ***referralsp, 2340 LDAPControl ***serverctrlsp, 2341 int freeit 2342 ); 2344 int ldap_parse_sasl_bind_result( 2345 LDAP *ld, 2346 LDAPMessage *res, 2347 struct berval **servercredp, 2348 int freeit 2349 ); 2351 int ldap_parse_extended_result( 2352 LDAP *ld, 2353 LDAPMessage *res, 2354 char **retoidp, 2355 struct berval **retdatap, 2356 int freeit 2357 ); 2359 #define LDAP_NOTICE_OF_DISCONNECTION "1.3.6.1.4.1.1466.20036" 2361 char *ldap_err2string( int err ); 2363 The use of the following routines is deprecated and more complete 2364 descriptions can be found in RFC 1823: 2366 int ldap_result2error( 2367 LDAP *ld, 2368 LDAPMessage *res, 2369 int freeit 2370 ); 2372 void ldap_perror( LDAP *ld, const char *msg ); 2374 Parameters are: 2376 ld The session handle. 2378 res The result of an LDAP operation as returned by 2379 ldap_result() or one of the synchronous API operation 2380 calls. 2382 C LDAP API C LDAP Application Program Interface 17 November 2000 2384 errcodep This result parameter will be filled in with the LDAP 2385 resultCode field from the LDAPMessage message. This is the 2386 indication from the server of the outcome of the operation. 2387 NULL SHOULD be passed to ignore this field. 2389 matcheddnp If the server returned a matchedDN string to indicate how 2390 much of a name passed in a request was recognized, this 2391 result parameter will be filled in with that matchedDN 2392 string. Otherwise, this field will be set to NULL. NULL 2393 SHOULD be passed to ignore this field. The matched DN 2394 string SHOULD be freed by calling ldap_memfree() which is 2395 described later in this document. Note that the server may 2396 return a zero length matchedDN (in which case *matchednp is 2397 set to an allocated copy of "") which is different than not 2398 returning a value at all (in which case *matcheddnp is set 2399 to NULL). 2401 errmsgp This result parameter will be filled in with the contents 2402 of the error message field from the LDAPMessage message. 2403 The error message string SHOULD be freed by calling 2404 ldap_memfree() which is described later in this document. 2405 NULL SHOULD be passed to ignore this field. 2407 referralsp This result parameter will be filled in with the contents 2408 of the referrals field from the LDAPMessage message, indi- 2409 cating zero or more alternate LDAP servers where the 2410 request is to be retried. The referrals array SHOULD be 2411 freed by calling ldap_value_free() which is described later 2412 in this document. NULL SHOULD be passed to ignore this 2413 field. If no referrals were returned, *referralsp is set 2414 to NULL. 2416 serverctrlsp This result parameter will be filled in with an allocated 2417 array of controls copied out of the LDAPMessage message. 2418 If serverctrlsp is NULL, no controls are returned. The 2419 control array SHOULD be freed by calling 2420 ldap_controls_free() which was described earlier. If no 2421 controls were returned, *serverctrlsp is set to NULL. 2423 freeit A boolean that determines whether the res parameter is 2424 disposed of or not. Pass any non-zero value to have these 2425 routines free res after extracting the requested informa- 2426 tion. This is provided as a convenience; you can also use 2427 ldap_msgfree() to free the result later. If freeit is 2428 non-zero, the entire chain of messages represented by res 2429 is disposed of. 2431 servercredp For SASL bind results, this result parameter will be filled 2432 C LDAP API C LDAP Application Program Interface 17 November 2000 2434 in with the credentials passed back by the server for 2435 mutual authentication, if given. An allocated berval struc- 2436 ture is returned that SHOULD be disposed of by calling 2437 ber_bvfree(). NULL SHOULD be passed to ignore this field. 2439 retoidp For extended results, this result parameter will be filled 2440 in with the dotted-OID text representation of the name of 2441 the extended operation response. This string SHOULD be 2442 disposed of by calling ldap_memfree(). NULL SHOULD be 2443 passed to ignore this field. If no OID was returned, 2444 *retoidp is set to NULL. The LDAP_NOTICE_OF_DISCONNECTION 2445 macro is defined as a convenience for clients that wish to 2446 check an OID to see if it matches the one used for the 2447 unsolicited Notice of Disconnection (defined in RFC 2251[2] 2448 section 4.4.1). 2450 retdatap For extended results, this result parameter will be filled 2451 in with a pointer to a struct berval containing the data in 2452 the extended operation response. It SHOULD be disposed of 2453 by calling ber_bvfree(). NULL SHOULD be passed to ignore 2454 this field. If no data is returned, *retdatap is set to 2455 NULL. 2457 err For ldap_err2string(), an LDAP result code, as returned by 2458 ldap_parse_result() or another LDAP API call. 2460 Additional parameters for the deprecated routines are not described. 2461 Interested readers are referred to RFC 1823. 2463 The ldap_parse_result(), ldap_parse_sasl_bind_result(), and 2464 ldap_parse_extended_result() functions all skip over messages of type 2465 LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_REFERENCE when looking for a 2466 result message to parse. They return the constant LDAP_SUCCESS if the 2467 result was successfully parsed and another LDAP API result code if not. 2468 If a value other than LDAP_SUCCESS is returned, the values of all the 2469 result parameters are undefined. Note that the LDAP result code that 2470 indicates the outcome of the operation performed by the server is placed 2471 in the errcodep ldap_parse_result() parameter. If a chain of messages 2472 that contains more than one result message is passed to these routines 2473 they always operate on the first result in the chain. 2475 ldap_err2string() is used to convert a numeric LDAP result code, as 2476 returned by ldap_parse_result(), ldap_parse_sasl_bind_result(), 2477 ldap_parse_extended_result() or one of the synchronous API operation 2478 calls, into an informative zero-terminated character string message 2479 describing the error. It returns a pointer to static data and it MUST 2480 NOT return NULL; the value returned is always a valid null-terminated 2481 "C" string. 2483 C LDAP API C LDAP Application Program Interface 17 November 2000 2485 15. Stepping Through a List of Results 2487 The ldap_first_message() and ldap_next_message() routines are used to 2488 step through the list of messages in a result chain returned by 2489 ldap_result(). For search operations, the result chain can actually 2490 include referral messages, entry messages, and result messages. 2491 ldap_count_messages() is used to count the number of messages returned. 2492 The ldap_msgtype() function, described above, can be used to distinguish 2493 between the different message types. 2495 LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *res ); 2497 LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *msg ); 2499 int ldap_count_messages( LDAP *ld, LDAPMessage *res ); 2501 Parameters are: 2503 ld The session handle. 2505 res The result chain, as obtained by a call to one of the synchronous 2506 search routines or ldap_result(). 2508 msg The message returned by a previous call to ldap_first_message() 2509 or ldap_next_message(). 2511 ldap_first_message() and ldap_next_message() will return NULL when no 2512 more messages exist in the result set to be returned. NULL is also 2513 returned if an error occurs while stepping through the entries, in which 2514 case the error parameters in the session handle ld will be set to indi- 2515 cate the error. 2517 If successful, ldap_count_messages() returns the number of messages con- 2518 tained in a chain of results; if an error occurs such as the res parame- 2519 ter being invalid, -1 is returned. The ldap_count_messages() call can 2520 also be used to count the number of messages that remain in a chain if 2521 called with a message, entry, or reference returned by 2522 ldap_first_message(), ldap_next_message(), ldap_first_entry(), 2523 ldap_next_entry(), ldap_first_reference(), ldap_next_reference(). 2525 16. Parsing Search Results 2527 The following calls are used to parse the entries and references 2528 returned by ldap_search() and friends. These results are returned in an 2529 opaque structure that MAY be accessed by calling the routines described 2530 below. Routines are provided to step through the entries and references 2531 returned, step through the attributes of an entry, retrieve the name of 2532 C LDAP API C LDAP Application Program Interface 17 November 2000 2534 an entry, and retrieve the values associated with a given attribute in 2535 an entry. 2537 16.1. Stepping Through a List of Entries or References 2539 The ldap_first_entry() and ldap_next_entry() routines are used to step 2540 through and retrieve the list of entries from a search result chain. 2541 The ldap_first_reference() and ldap_next_reference() routines are used 2542 to step through and retrieve the list of continuation references from a 2543 search result chain. ldap_count_entries() is used to count the number 2544 of entries returned. ldap_count_references() is used to count the number 2545 of references returned. 2547 LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *res ); 2549 LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry ); 2551 LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *res ); 2553 LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *ref ); 2555 int ldap_count_entries( LDAP *ld, LDAPMessage *res ); 2557 int ldap_count_references( LDAP *ld, LDAPMessage *res ); 2559 Parameters are: 2561 ld The session handle. 2563 res The search result, as obtained by a call to one of the synchro- 2564 nous search routines or ldap_result(). 2566 entry The entry returned by a previous call to ldap_first_entry() or 2567 ldap_next_entry(). 2569 ref The reference returned by a previous call to 2570 ldap_first_reference() or ldap_next_reference(). 2572 ldap_first_entry(), ldap_next_entry(), ldap_first_reference() and 2573 ldap_next_reference() all return NULL when no more entries or references 2574 exist in the result set to be returned. NULL is also returned if an 2575 error occurs while stepping through the entries or references, in which 2576 case the error parameters in the session handle ld will be set to indi- 2577 cate the error. 2579 ldap_count_entries() returns the number of entries contained in a chain 2580 of entries; if an error occurs such as the res parameter being invalid, 2581 C LDAP API C LDAP Application Program Interface 17 November 2000 2583 -1 is returned. The ldap_count_entries() call can also be used to count 2584 the number of entries that remain in a chain if called with a message, 2585 entry or reference returned by ldap_first_message(), 2586 ldap_next_message(), ldap_first_entry(), ldap_next_entry(), 2587 ldap_first_reference(), ldap_next_reference(). 2589 ldap_count_references() returns the number of references contained in a 2590 chain of search results; if an error occurs such as the res parameter 2591 being invalid, -1 is returned. The ldap_count_references() call can 2592 also be used to count the number of references that remain in a chain. 2594 16.2. Stepping Through the Attributes of an Entry 2596 The ldap_first_attribute() and ldap_next_attribute() calls are used to 2597 step through the list of attribute types returned with an entry. 2599 char *ldap_first_attribute( 2600 LDAP *ld, 2601 LDAPMessage *entry, 2602 BerElement **ptr 2603 ); 2605 char *ldap_next_attribute( 2606 LDAP *ld, 2607 LDAPMessage *entry, 2608 BerElement *ptr 2609 ); 2611 void ldap_memfree( char *mem ); 2613 Parameters are: 2615 ld The session handle. 2617 entry The entry whose attributes are to be stepped through, as returned 2618 by ldap_first_entry() or ldap_next_entry(). 2620 ptr In ldap_first_attribute(), the address of a pointer used inter- 2621 nally to keep track of the current position in the entry. In 2622 ldap_next_attribute(), the pointer returned by a previous call to 2623 ldap_first_attribute(). The BerElement type itself is an opaque 2624 structure that is described in more detail later in this document 2625 in the section "Encoded ASN.1 Value Manipulation". 2627 mem A pointer to memory allocated by the LDAP library, such as the 2628 attribute type names returned by ldap_first_attribute() and 2629 ldap_next_attribute, or the DN returned by ldap_get_dn(). If mem 2631 C LDAP API C LDAP Application Program Interface 17 November 2000 2633 is NULL, the ldap_memfree() call does nothing. 2635 ldap_first_attribute() and ldap_next_attribute() will return NULL when 2636 the end of the attributes is reached, or if there is an error, in which 2637 case the error parameters in the session handle ld will be set to indi- 2638 cate the error. 2640 Both routines return a pointer to an allocated buffer containing the 2641 current attribute name. This SHOULD be freed when no longer in use by 2642 calling ldap_memfree(). 2644 ldap_first_attribute() will allocate and return in ptr a pointer to a 2645 BerElement used to keep track of the current position. This pointer MAY 2646 be passed in subsequent calls to ldap_next_attribute() to step through 2647 the entry's attributes. After a set of calls to ldap_first_attribute() 2648 and ldap_next_attribute(), if ptr is non-NULL, it SHOULD be freed by 2649 calling ber_free( ptr, 0 ). Note that it is very important to pass the 2650 second parameter as 0 (zero) in this call, since the buffer associated 2651 with the BerElement does not point to separately allocated memory. 2653 The attribute type names returned are suitable for passing in a call to 2654 ldap_get_values() and friends to retrieve the associated values. 2656 16.3. Retrieving the Values of an Attribute 2658 ldap_get_values() and ldap_get_values_len() are used to retrieve the 2659 values of a given attribute from an entry. ldap_count_values() and 2660 ldap_count_values_len() are used to count the returned values. 2661 ldap_value_free() and ldap_value_free_len() are used to free the values. 2663 char **ldap_get_values( 2664 LDAP *ld, 2665 LDAPMessage *entry, 2666 const char *attr 2667 ); 2669 struct berval **ldap_get_values_len( 2670 LDAP *ld, 2671 LDAPMessage *entry, 2672 const char *attr 2673 ); 2675 int ldap_count_values( char **vals ); 2677 int ldap_count_values_len( struct berval **vals ); 2679 void ldap_value_free( char **vals ); 2681 C LDAP API C LDAP Application Program Interface 17 November 2000 2683 void ldap_value_free_len( struct berval **vals ); 2685 Parameters are: 2687 ld The session handle. 2689 entry The entry from which to retrieve values, as returned by 2690 ldap_first_entry() or ldap_next_entry(). 2692 attr The attribute whose values are to be retrieved, as returned by 2693 ldap_first_attribute() or ldap_next_attribute(), or a caller- 2694 supplied string (e.g., "mail"). 2696 vals The values returned by a previous call to ldap_get_values() or 2697 ldap_get_values_len(). 2699 Two forms of the various calls are provided. The first form is only 2700 suitable for use with non-binary character string data. The second _len 2701 form is used with any kind of data. 2703 ldap_get_values() and ldap_get_values_len() return NULL if no values are 2704 found for attr or if an error occurs. 2706 ldap_count_values() and ldap_count_values_len() return -1 if an error 2707 occurs such as the vals parameter being invalid. 2709 If a NULL vals parameter is passed to ldap_value_free() or 2710 ldap_value_free_len(), nothing is done. 2712 Note that the values returned are dynamically allocated and SHOULD be 2713 freed by calling either ldap_value_free() or ldap_value_free_len() when 2714 no longer in use. 2716 16.4. Retrieving the name of an entry 2718 ldap_get_dn() is used to retrieve the name of an entry. 2719 ldap_explode_dn() and ldap_explode_rdn() are used to break up a name 2720 into its component parts. ldap_dn2ufn() is used to convert the name into 2721 a more "user friendly" format. 2723 char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ); 2725 char **ldap_explode_dn( const char *dn, int notypes ); 2727 char **ldap_explode_rdn( const char *rdn, int notypes ); 2729 char *ldap_dn2ufn( const char *dn ); 2731 C LDAP API C LDAP Application Program Interface 17 November 2000 2733 Parameters are: 2735 ld The session handle. 2737 entry The entry whose name is to be retrieved, as returned by 2738 ldap_first_entry() or ldap_next_entry(). 2740 dn The dn to explode, such as returned by ldap_get_dn(). If NULL, 2741 a zero length DN is used. 2743 rdn The rdn to explode, such as returned in the components of the 2744 array returned by ldap_explode_dn(). If NULL, a zero length DN 2745 is used. 2747 notypes A boolean parameter, if non-zero indicating that the dn or rdn 2748 components are to have their type information stripped off 2749 (i.e., "cn=Babs" would become "Babs"). 2751 ldap_get_dn() will return NULL if there is some error parsing the dn, 2752 setting error parameters in the session handle ld to indicate the error. 2753 It returns a pointer to newly allocated space that the caller SHOULD 2754 free by calling ldap_memfree() when it is no longer in use. Note the 2755 format of the DNs returned is given by [5]. The root DN is returned as 2756 a zero length string (""). 2758 ldap_explode_dn() returns a NULL-terminated char * array containing the 2759 RDN components of the DN supplied, with or without types as indicated by 2760 the notypes parameter. The components are returned in the order they 2761 appear in the dn. The array returned SHOULD be freed when it is no 2762 longer in use by calling ldap_value_free(). 2764 ldap_explode_rdn() returns a NULL-terminated char * array containing the 2765 components of the RDN supplied, with or without types as indicated by 2766 the notypes parameter. The components are returned in the order they 2767 appear in the rdn. The array returned SHOULD be freed when it is no 2768 longer in use by calling ldap_value_free(). 2770 ldap_dn2ufn() converts the DN into the user friendly format described in 2771 [14]. The UFN returned is newly allocated space that SHOULD be freed by 2772 a call to ldap_memfree() when no longer in use. 2774 16.5. Retrieving controls from an entry 2776 ldap_get_entry_controls() is used to extract LDAP controls from an 2777 entry. 2779 C LDAP API C LDAP Application Program Interface 17 November 2000 2781 int ldap_get_entry_controls( 2782 LDAP *ld, 2783 LDAPMessage *entry, 2784 LDAPControl ***serverctrlsp 2785 ); 2787 Parameters are: 2789 ld The session handle. 2791 entry The entry to extract controls from, as returned by 2792 ldap_first_entry() or ldap_next_entry(). 2794 serverctrlsp This result parameter will be filled in with an allocated 2795 array of controls copied out of entry. The control array 2796 SHOULD be freed by calling ldap_controls_free(). If ser- 2797 verctrlsp is NULL, no controls are returned. If no con- 2798 trols were returned, *serverctrlsp is set to NULL. 2800 ldap_get_entry_controls() returns an LDAP result code that indicates 2801 whether the reference could be successfully parsed (LDAP_SUCCESS if all 2802 goes well). If ldap_get_entry_controls() returns a value other than 2803 LDAP_SUCCESS, the value of the serverctrlsp output parameter is unde- 2804 fined. 2806 16.6. Parsing References 2808 ldap_parse_reference() is used to extract referrals and controls from a 2809 SearchResultReference message. 2811 int ldap_parse_reference( 2812 LDAP *ld, 2813 LDAPMessage *ref, 2814 char ***referralsp, 2815 LDAPControl ***serverctrlsp, 2816 int freeit 2817 ); 2819 Parameters are: 2821 ld The session handle. 2823 ref The reference to parse, as returned by ldap_result(), 2824 ldap_first_reference(), or ldap_next_reference(). 2826 C LDAP API C LDAP Application Program Interface 17 November 2000 2828 referralsp This result parameter will be filled in with an allocated 2829 array of character strings. The elements of the array are 2830 the referrals (typically LDAP URLs) contained in ref. The 2831 array SHOULD be freed when no longer in used by calling 2832 ldap_value_free(). If referralsp is NULL, the referral 2833 URLs are not returned. If no referrals were returned, 2834 *referralsp is set to NULL. 2836 serverctrlsp This result parameter will be filled in with an allocated 2837 array of controls copied out of ref. The control array 2838 SHOULD be freed by calling ldap_controls_free(). If ser- 2839 verctrlsp is NULL, no controls are returned. If no con- 2840 trols were returned, *serverctrlsp is set to NULL. 2842 freeit A boolean that determines whether the ref parameter is 2843 disposed of or not. Pass any non-zero value to have this 2844 routine free ref after extracting the requested informa- 2845 tion. This is provided as a convenience; you can also use 2846 ldap_msgfree() to free the result later. 2848 ldap_parse_reference() returns an LDAP result code that indicates 2849 whether the reference could be successfully parsed (LDAP_SUCCESS if all 2850 goes well). If a value other than LDAP_SUCCESS is returned, the value 2851 of the referralsp and serverctrlsp result parameters are undefined. 2853 17. Encoded ASN.1 Value Manipulation 2855 This section describes routines which MAY be used to encode and decode 2856 BER-encoded ASN.1 values, which are often used inside of control and 2857 extension values. 2859 With the exceptions of two new functions ber_flatten() and ber_init(), 2860 these functions are compatible with the University of Michigan LDAP 3.3 2861 implementation of BER. 2863 Note that the functions defined in this section all provide a method for 2864 determining success or failure but generally do not provide access to 2865 specific error codes. Therefore, applications that require precise 2866 error information when encoding or decoding ASN.1 values SHOULD NOT use 2867 these functions. 2869 17.1. BER Data Structures and Types 2871 The following additional integral types are defined for use in manipula- 2872 tion of BER encoded ASN.1 values: 2874 C LDAP API C LDAP Application Program Interface 17 November 2000 2876 typedef ber_tag_t; /* for BER tags */ 2878 typedef ber_int_t; /* for BER ints, enums, and Booleans */ 2880 typedef ber_uint_t; /* unsigned equivalent of ber_uint_t */ 2882 typedef ber_slen_t; /* signed equivalent of ber_len_t */ 2884 Note that the actual definition for these four integral types is imple- 2885 mentation specific; that is, `', `', 2886 `', and `' MUST each be replaced with an 2887 appropriate implementation-specific type. 2889 The `ber_tag_t' type is an unsigned integral data type that is large 2890 enough to hold the largest BER tag supported by the API implementation. 2891 The width (number of significant bits) of `ber_tag_t' MUST be at least 2892 32, greater than or equal to that of `unsigned int' (so that integer 2893 promotions won't promote it to `int'), and no wider than that of 2894 `unsigned long'. 2896 The `ber_int_t' and `ber_uint_t' types are the signed and unsigned vari- 2897 ants of an integral type that is large enough to hold integers for pur- 2898 poses of BER encoding and decoding. The width of `ber_int_t' MUST be at 2899 least 32 and no larger than that of `long'. 2901 The `ber_slen_t' type is the signed variant of the `ber_len_t' integral 2902 type, i.e. if `ber_len_t' is unsigned long, then `ber_slen_t' is signed 2903 long. The `' in the `ber_len_t' typedef MUST be replaced 2904 with an appropriate type. Note that `ber_slen_t' is not used directly 2905 in the C LDAP API but is provided for the convenience of application 2906 developers and for use by extensions to the API. 2908 typedef struct berval { 2909 ber_len_t bv_len; 2910 char *bv_val; 2911 } BerValue; 2913 As defined earlier in the section "Common Data Structures", a berval 2914 structure contains an arbitrary sequence of bytes and an indication of 2915 its length. The bv_len element is an unsigned integer. The bv_val is 2916 not necessarily zero-terminated. Applications MAY allocate their own 2917 berval structures. 2919 As defined earlier in the section "Common Data Structures", the BerEle- 2920 ment structure is an opaque structure: 2922 typedef struct berelement BerElement; 2924 C LDAP API C LDAP Application Program Interface 17 November 2000 2926 It contains not only a copy of the encoded value, but also state infor- 2927 mation used in encoding or decoding. Applications cannot allocate their 2928 own BerElement structures. The internal state is neither thread- 2929 specific nor locked, so two threads SHOULD NOT manipulate the same 2930 BerElement value simultaneously. 2932 A single BerElement value cannot be used for both encoding and decoding. 2934 17.2. Memory Disposal and Utility Functions 2936 void ber_bvfree( struct berval *bv ); 2938 ber_bvfree() frees a berval structure returned from this API. Both the 2939 bv->bv_val string and the berval structure itself are freed. If bv is 2940 NULL, this call does nothing. 2942 void ber_bvecfree( struct berval **bv ); 2944 ber_bvecfree() frees an array of berval structures returned from this 2945 API. Each of the berval structures in the array are freed using 2946 ber_bvfree(), then the array itself is freed. If bv is NULL, this call 2947 does nothing. 2949 struct berval *ber_bvdup( const struct berval *bv ); 2951 ber_bvdup() returns a copy of a berval structure. The bv_val field in 2952 the returned berval structure points to a different area of memory than 2953 the bv_val field in the bv argument. The NULL pointer is returned on 2954 error (e.g. out of memory). 2956 void ber_free( BerElement *ber, int fbuf ); 2958 ber_free() frees a BerElement which is returned from the API calls 2959 ber_alloc_t() or ber_init(). Each BerElement SHOULD be freed by the 2960 caller. The second argument fbuf SHOULD always be set to 1 to ensure 2961 that the internal buffer used by the BER functions is freed as well as 2962 the BerElement container itself. If ber is NULL, this call does noth- 2963 ing. 2965 17.3. Encoding 2967 BerElement *ber_alloc_t( int options ); 2969 ber_alloc_t() constructs and returns BerElement. The NULL pointer is 2970 returned on error. The options field contains a bitwise-or of options 2971 which are to be used when generating the encoding of this BerElement. 2972 One option is defined and SHOULD always be supplied: 2974 C LDAP API C LDAP Application Program Interface 17 November 2000 2976 #define LBER_USE_DER 0x01 2978 When this option is present, lengths will always be encoded in the 2979 minimum number of octets. Note that this option does not cause values 2980 of sets to be rearranged in tag and byte order or default values to be 2981 removed, so these functions are not sufficient for generating DER output 2982 as defined in X.509 and X.680. If the caller takes responsibility for 2983 ordering values of sets correctly and removing default values, DER out- 2984 put as defined in X.509 and X.680 can be produced. 2986 Unrecognized option bits are ignored. 2988 The BerElement returned by ber_alloc_t() is initially empty. Calls to 2989 ber_printf() will append bytes to the end of the ber_alloc_t(). 2991 int ber_printf( BerElement *ber, const char *fmt, ... ); 2993 The ber_printf() routine is used to encode a BER element in much the 2994 same way that sprintf() works. One important difference, though, is 2995 that state information is kept in the ber argument so that multiple 2996 calls can be made to ber_printf() to append to the end of the BER ele- 2997 ment. ber MUST be a pointer to a BerElement returned by ber_alloc_t(). 2998 ber_printf() interprets and formats its arguments according to the for- 2999 mat string fmt. ber_printf() returns -1 if there is an error during 3000 encoding and a non-negative number if successful. As with sprintf(), 3001 each character in fmt refers to an argument to ber_printf(). 3003 The format string can contain the following format characters: 3005 't' Tag. The next argument is a ber_tag_t specifying the tag to 3006 override the next element to be written to the ber. This works 3007 across calls. The integer tag value SHOULD contain the tag 3008 class, constructed bit, and tag value. For example, a tag of 3009 "[3]" for a constructed type is 0xA3U. All implementations MUST 3010 support tags that fit in a single octet (i.e., where the tag 3011 value is less than 32) and they MAY support larger tags. 3013 'b' Boolean. The next argument is an ber_int_t, containing either 0 3014 for FALSE or 0xff for TRUE. A boolean element is output. If 3015 this format character is not preceded by the 't' format modif- 3016 ier, the tag 0x01U is used for the element. 3018 'e' Enumerated. The next argument is a ber_int_t, containing the 3019 enumerated value in the host's byte order. An enumerated ele- 3020 ment is output. If this format character is not preceded by the 3021 't' format modifier, the tag 0x0AU is used for the element. 3023 'i' Integer. The next argument is a ber_int_t, containing the 3024 C LDAP API C LDAP Application Program Interface 17 November 2000 3026 integer in the host's byte order. An integer element is output. 3027 If this format character is not preceded by the 't' format 3028 modifier, the tag 0x02U is used for the element. 3030 'B' Bitstring. The next two arguments are a char * pointer to the 3031 start of the bitstring, followed by a ber_len_t containing the 3032 number of bits in the bitstring. A bitstring element is output, 3033 in primitive form. If this format character is not preceded by 3034 the 't' format modifier, the tag 0x03U is used for the element. 3036 'X' Reserved and not to be used. In older revisions of this specif- 3037 ication, 3039 'n' Null. No argument is needed. An ASN.1 NULL element is output. 3040 If this format character is not preceded by the 't' format 3041 modifier, the tag 0x05U is used for the element. 3043 'o' Octet string. The next two arguments are a char *, followed by 3044 a ber_len_t with the length of the string. The string MAY con- 3045 tain null bytes and are do not have to be zero-terminated. An 3046 octet string element is output, in primitive form. If this for- 3047 mat character is not preceded by the 't' format modifier, the 3048 tag 0x04U is used for the element. 3050 's' Octet string. The next argument is a char * pointing to a 3051 zero-terminated string. An octet string element in primitive 3052 form is output, which does not include the trailing '\0' (null) 3053 byte. If this format character is not preceded by the 't' format 3054 modifier, the tag 0x04U is used for the element. 3056 'v' Several octet strings. The next argument is a char **, an array 3057 of char * pointers to zero-terminated strings. The last element 3058 in the array MUST be a NULL pointer. The octet strings do not 3059 include the trailing '\0' (null) byte. Note that a construct 3060 like '{v}' is used to get an actual SEQUENCE OF octet strings. 3061 The 't' format modifier cannot be used with this format charac- 3062 ter. 3064 'V' Several octet strings. A NULL-terminated array of struct berval 3065 *'s is supplied. Note that a construct like '{V}' is used to 3066 get an actual SEQUENCE OF octet strings. The 't' format modifier 3067 cannot be used with this format character. 3069 '{' Begin sequence. No argument is needed. If this format charac- 3070 ter is not preceded by the 't' format modifier, the tag 0x30U is 3071 used. 3073 '}' End sequence. No argument is needed. The 't' format modifier 3074 C LDAP API C LDAP Application Program Interface 17 November 2000 3076 cannot be used with this format character. 3078 '[' Begin set. No argument is needed. If this format character is 3079 not preceded by the 't' format modifier, the tag 0x31U is used. 3081 ']' End set. No argument is needed. The 't' format modifier cannot 3082 be used with this format character. 3084 Each use of a '{' format character SHOULD be matched by a '}' character, 3085 either later in the format string, or in the format string of a subse- 3086 quent call to ber_printf() for that BerElement. The same applies to the 3087 '[' and ']' format characters. 3089 Sequences and sets nest, and implementations of this API MUST maintain 3090 internal state to be able to properly calculate the lengths. 3092 int ber_flatten( BerElement *ber, struct berval **bvPtr ); 3094 The ber_flatten routine allocates a struct berval whose contents are a 3095 BER encoding taken from the ber argument. The bvPtr pointer points to 3096 the returned berval structure, which SHOULD be freed using ber_bvfree(). 3097 This routine returns 0 on success and -1 on error. 3099 The ber_flatten API call is not present in U-M LDAP 3.3. 3101 The use of ber_flatten on a BerElement in which all '{' and '}' format 3102 modifiers have not been properly matched is an error (i.e., -1 will be 3103 returned by ber_flatten() if this situation is exists). 3105 17.4. Encoding Example 3107 The following is an example of encoding the following ASN.1 data type: 3109 Example1Request ::= SEQUENCE { 3110 s OCTET STRING, -- must be printable 3111 val1 INTEGER, 3112 val2 [0] INTEGER DEFAULT 0 3113 } 3115 int encode_example1(const char *s, ber_int_t val1, ber_int_t val2, 3116 struct berval **bvPtr) 3117 { 3118 BerElement *ber; 3119 int rc = -1; 3121 *bvPtr = NULL; /* in case of error */ 3123 C LDAP API C LDAP Application Program Interface 17 November 2000 3125 ber = ber_alloc_t(LBER_USE_DER); 3127 if (ber == NULL) return -1; 3129 if (ber_printf(ber,"{si",s,val1) == -1) { 3130 goto done; 3131 } 3133 if (val2 != 0) { 3134 if (ber_printf(ber,"ti",(ber_tag_t)0x80,val2) == -1) { 3135 goto done; 3136 } 3137 } 3139 if (ber_printf(ber,"}") == -1) { 3140 goto done; 3141 } 3143 rc = ber_flatten(ber,bvPtr); 3145 done: 3146 ber_free(ber,1); 3147 return rc; 3148 } 3150 17.5. Decoding 3152 The following two macros are available to applications: LBER_ERROR and 3153 LBER_DEFAULT. Both of these macros MUST be #define'd as ber_tag_t 3154 integral values that are treated as invalid tags by the API implementa- 3155 tion. It is RECOMMENDED that the values of LBER_ERROR and LBER_DEFAULT 3156 be the same and that they be defined as values where all octets have the 3157 value 0xFF. ISO C guarantees that these definitions will work: 3159 #define LBER_ERROR ((ber_tag_t)-1) 3160 #define LBER_DEFAULT ((ber_tag_t)-1) 3162 The intent is that LBER_ERROR and LBER_DEFAULT are both defined as the 3163 integer value that has all octets set to 0xFF, as such a value is not a 3164 valid BER tag. 3166 BerElement *ber_init( const struct berval *bv ); 3168 The ber_init function constructs a BerElement and returns a new BerEle- 3169 ment containing a copy of the data in the bv argument. ber_init returns 3170 the NULL pointer on error. 3172 C LDAP API C LDAP Application Program Interface 17 November 2000 3174 ber_tag_t ber_scanf( BerElement *ber, const char *fmt, ... ); 3176 The ber_scanf() routine is used to decode a BER element in much the same 3177 way that sscanf() works. One important difference, though, is that some 3178 state information is kept with the ber argument so that multiple calls 3179 can be made to ber_scanf() to sequentially read from the BER element. 3180 The ber argument SHOULD be a pointer to a BerElement returned by 3181 ber_init(). ber_scanf interprets the bytes according to the format 3182 string fmt, and stores the results in its additional arguments. 3183 ber_scanf() returns LBER_ERROR on error, and a different value on suc- 3184 cess. If an error occurred, the values of all the result parameters are 3185 undefined. 3187 The format string contains conversion specifications which are used to 3188 direct the interpretation of the BER element. The format string can 3189 contain the following characters: 3191 'a' Octet string. A char ** argument MUST be supplied. Memory is 3192 allocated, filled with the contents of the octet string, zero- 3193 terminated, and the pointer to the string is stored in the argu- 3194 ment. The returned value SHOULD be freed using ldap_memfree. 3195 The tag of the element MUST indicate the primitive form (con- 3196 structed strings are not supported) but is otherwise ignored and 3197 discarded during the decoding. This format cannot be used with 3198 octet strings which could contain null bytes. 3200 'O' Octet string. A struct berval ** argument MUST be supplied, 3201 which upon return points to an allocated struct berval contain- 3202 ing the octet string and its length. ber_bvfree() SHOULD be 3203 called to free the allocated memory. The tag of the element 3204 MUST indicate the primitive form (constructed strings are not 3205 supported) but is otherwise ignored during the decoding. 3207 'b' Boolean. A pointer to a ber_int_t MUST be supplied. The 3208 ber_int_t value stored will be 0 for FALSE or nonzero for TRUE. 3209 The tag of the element MUST indicate the primitive form but is 3210 otherwise ignored during the decoding. 3212 'e' Enumerated. A pointer to a ber_int_t MUST be supplied. The 3213 enumerated value stored will be in host byte order. The tag of 3214 the element MUST indicate the primitive form but is otherwise 3215 ignored during the decoding. ber_scanf() will return an error 3216 if the value of the enumerated value cannot be stored in a 3217 ber_int_t. 3219 'i' Integer. A pointer to a ber_int_t MUST be supplied. The 3220 ber_int_t value stored will be in host byte order. The tag of 3221 the element MUST indicate the primitive form but is otherwise 3223 C LDAP API C LDAP Application Program Interface 17 November 2000 3225 ignored during the decoding. ber_scanf() will return an error 3226 if the integer cannot be stored in a ber_int_t. 3228 'B' Bitstring. A char ** argument MUST be supplied which will point 3229 to the allocated bits, followed by a ber_len_t * argument, which 3230 will point to the length (in bits) of the bitstring returned. 3231 ldap_memfree SHOULD be called to free the bitstring. The tag of 3232 the element MUST indicate the primitive form (constructed bit- 3233 strings are not supported) but is otherwise ignored during the 3234 decoding. 3236 'n' Null. No argument is needed. The element is verified to have a 3237 zero-length value and is skipped. The tag is ignored. 3239 't' Tag. A pointer to a ber_tag_t MUST be supplied. The ber_tag_t 3240 value stored will be the tag of the next element in the BerEle- 3241 ment ber, represented so it can be written using the 't' format 3242 of ber_printf(). The decoding position within the ber argument 3243 is unchanged by this; that is, the fact that the tag has been 3244 retrieved does not affect future use of ber. 3246 'v' Several octet strings. A char *** argument MUST be supplied, 3247 which upon return points to an allocated NULL-terminated array 3248 of char *'s containing the octet strings. NULL is stored if the 3249 sequence is empty. ldap_memfree SHOULD be called to free each 3250 element of the array and the array itself. The tag of the 3251 sequence and of the octet strings are ignored. 3253 'V' Several octet strings (which could contain null bytes). A 3254 struct berval *** MUST be supplied, which upon return points to 3255 a allocated NULL-terminated array of struct berval *'s contain- 3256 ing the octet strings and their lengths. NULL is stored if the 3257 sequence is empty. ber_bvecfree() can be called to free the 3258 allocated memory. The tag of the sequence and of the octet 3259 strings are ignored. 3261 'x' Skip element. The next element is skipped. No argument is 3262 needed. 3264 '{' Begin sequence. No argument is needed. The initial sequence 3265 tag and length are skipped. 3267 '}' End sequence. No argument is needed. 3269 '[' Begin set. No argument is needed. The initial set tag and 3270 length are skipped. 3272 ']' End set. No argument is needed. 3274 C LDAP API C LDAP Application Program Interface 17 November 2000 3276 ber_tag_t ber_peek_tag( BerElement *ber, 3277 ber_len_t *lenPtr ); 3279 ber_peek_tag() returns the tag of the next element to be parsed in the 3280 BerElement argument. The length of this element is stored in the 3281 *lenPtr argument. LBER_DEFAULT is returned if there is no further data 3282 to be read. The decoding position within the ber argument is unchanged 3283 by this call; that is, the fact that ber_peek_tag() has been called does 3284 not affect future use of ber. 3286 ber_tag_t ber_skip_tag( BerElement *ber, ber_len_t *lenPtr ); 3288 ber_skip_tag() is similar to ber_peek_tag(), except that the state 3289 pointer in the BerElement argument is advanced past the first tag and 3290 length, and is pointed to the value part of the next element. This rou- 3291 tine SHOULD only be used with constructed types and situations when a 3292 BER encoding is used as the value of an OCTET STRING. The length of the 3293 value is stored in *lenPtr. 3295 ber_tag_t ber_first_element( BerElement *ber, 3296 ber_len_t *lenPtr, char **opaquePtr ); 3298 ber_tag_t ber_next_element( BerElement *ber, 3299 ber_len_t *lenPtr, char *opaque ); 3301 ber_first_element() and ber_next_element() are used to traverse a SET, 3302 SET OF, SEQUENCE or SEQUENCE OF data value. ber_first_element() calls 3303 ber_skip_tag(), stores internal information in *lenPtr and *opaquePtr, 3304 and calls ber_peek_tag() for the first element inside the constructed 3305 value. LBER_DEFAULT is returned if the constructed value is empty. 3306 ber_next_element() positions the state at the start of the next element 3307 in the constructed type. LBER_DEFAULT is returned if there are no 3308 further values. 3310 The len and opaque values SHOULD NOT be used by applications other than 3311 as arguments to ber_next_element(), as shown in the example below. 3313 17.6. Decoding Example 3315 The following is an example of decoding an ASN.1 data type: 3317 Example2Request ::= SEQUENCE { 3318 dn OCTET STRING, -- must be printable 3319 scope ENUMERATED { b (0), s (1), w (2) }, 3320 ali ENUMERATED { n (0), s (1), f (2), a (3) }, 3321 size INTEGER, 3322 time INTEGER, 3324 C LDAP API C LDAP Application Program Interface 17 November 2000 3326 tonly BOOLEAN, 3327 attrs SEQUENCE OF OCTET STRING, -- must be printable 3328 [0] SEQUENCE OF SEQUENCE { 3329 type OCTET STRING -- must be printable, 3330 crit BOOLEAN DEFAULT FALSE, 3331 value OCTET STRING 3332 } OPTIONAL } 3334 #define TAG_CONTROL_LIST 0xA0U /* context specific cons 0 */ 3336 int decode_example2(struct berval *bv) 3337 { 3338 BerElement *ber; 3339 ber_len_t len; 3340 ber_tag_t res; 3341 ber_int_t scope, ali, size, time, tonly; 3342 char *dn = NULL, **attrs = NULL; 3343 int i,rc = 0; 3345 ber = ber_init(bv); 3346 if (ber == NULL) { 3347 fputs("ERROR ber_init failed\n", stderr); 3348 return -1; 3349 } 3351 res = ber_scanf(ber,"{aiiiib{v}",&dn,&scope,&ali, 3352 &size,&time,&tonly,&attrs); 3354 if (res == LBER_ERROR) { 3355 fputs("ERROR ber_scanf failed\n", stderr); 3356 ber_free(ber,1); 3357 return -1; 3358 } 3360 /* *** use dn */ 3361 ldap_memfree(dn); 3363 for (i = 0; attrs != NULL && attrs[i] != NULL; i++) { 3364 /* *** use attrs[i] */ 3365 ldap_memfree(attrs[i]); 3366 } 3367 ldap_memfree((char *)attrs); 3369 if (ber_peek_tag(ber,&len) == TAG_CONTROL_LIST) { 3370 char *opaque; 3371 ber_tag_t tag; 3373 for (tag = ber_first_element(ber,&len,&opaque); 3375 C LDAP API C LDAP Application Program Interface 17 November 2000 3377 tag != LBER_DEFAULT; 3378 tag = ber_next_element (ber,&len,opaque)) { 3380 ber_len_t tlen; 3381 ber_tag_t ttag; 3382 char *type; 3383 ber_int_t crit; 3384 struct berval *value; 3386 if (ber_scanf(ber,"{a",&type) == LBER_ERROR) { 3387 fputs("ERROR cannot parse type\n", stderr); 3388 break; 3389 } 3390 /* *** use type */ 3391 ldap_memfree(type); 3393 ttag = ber_peek_tag(ber,&tlen); 3394 if (ttag == 0x01U) { /* boolean */ 3395 if (ber_scanf(ber,"b", 3396 &crit) == LBER_ERROR) { 3397 fputs("ERROR cannot parse crit\n", 3398 stderr); 3399 rc = -1; 3400 break; 3401 } 3402 } else if (ttag == 0x04U) { /* octet string */ 3403 crit = 0; 3404 } else { 3405 fputs("ERROR extra field in controls\n", 3406 stderr ); 3407 break; 3408 } 3410 if (ber_scanf(ber,"O}",&value) == LBER_ERROR) { 3411 fputs("ERROR cannot parse value\n", stderr); 3412 rc = -1; 3413 break; 3414 } 3415 /* *** use value */ 3416 ber_bvfree(value); 3417 } 3418 } 3420 if ( rc == 0 ) { /* no errors so far */ 3421 if (ber_scanf(ber,"}") == LBER_ERROR) { 3422 rc = -1; 3423 } 3424 } 3426 C LDAP API C LDAP Application Program Interface 17 November 2000 3428 ber_free(ber,1); 3430 return rc; 3431 } 3433 18. Security Considerations 3435 LDAPv2 supports security through protocol-level authentication using 3436 clear-text passwords. LDAPv3 adds support for SASL [12] (Simple Authen- 3437 tication Security Layer) methods. LDAPv3 also supports operation over a 3438 secure transport layer using Transport Layer Security TLS [9]. Readers 3439 are referred to the protocol documents for discussion of related secu- 3440 rity considerations. 3442 Implementations of this API SHOULD be cautious when handling authentica- 3443 tion credentials. In particular, keeping long-lived copies of creden- 3444 tials without the application's knowledge is discouraged. 3446 19. Acknowledgements 3448 Many members of the IETF ASID and LDAPEXT working groups as well as 3449 members of the Internet at large have provided useful comments and 3450 suggestions that have been incorporated into this document. Chris 3451 Weider deserves special mention for his contributions as co-author of 3452 earlier revisions of this document. 3454 The original material upon which this specification is based was sup- 3455 ported by the National Science Foundation under Grant No. NCR-9416667. 3457 20. Copyright 3459 Copyright (C) The Internet Society (1997-2000). All Rights Reserved. 3461 This document and translations of it may be copied and furnished to oth- 3462 ers, and derivative works that comment on or otherwise explain it or 3463 assist in its implementation may be prepared, copied, published and dis- 3464 tributed, in whole or in part, without restriction of any kind, provided 3465 that the above copyright notice and this paragraph are included on all 3466 such copies and derivative works. However, this document itself may not 3467 be modified in any way, such as by removing the copyright notice or 3468 references to the Internet Society or other Internet organizations, 3469 except as needed for the purpose of developing Internet standards in 3470 which case the procedures for copyrights defined in the Internet Stan- 3471 dards process must be followed, or as required to translate it into 3472 C LDAP API C LDAP Application Program Interface 17 November 2000 3474 languages other than English. 3476 The limited permissions granted above are perpetual and will not be 3477 revoked by the Internet Society or its successors or assigns. 3479 This document and the information contained herein is provided on an "AS 3480 IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK 3481 FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT 3482 LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT 3483 INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FIT- 3484 NESS FOR A PARTICULAR PURPOSE. 3486 21. Bibliography 3488 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement 3489 Levels", RFC 2119, March 1997. 3491 [2] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol 3492 (v3)", RFC 2251, December 1997. 3494 [3] M. Wahl, A. Coulbeck, T. Howes, S. Kille, W. Yeong, C. Robbins, 3495 "Lightweight Directory Access Protocol (v3): Attribute Syntax 3496 Definitions", RFC 2252, December 1997. 3498 [4] The Directory: Selected Attribute Syntaxes. CCITT, Recommendation 3499 X.520. 3501 [5] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol 3502 (v3): A UTF-8 String Representation of Distinguished Names", RFC 3503 2253, December 1997. 3505 [6] F. Yergeau, "UTF-8, a transformation format of Unicode and ISO 3506 10646", RFC 2044, October 1996. 3508 [7] K. Simonsen, "Character Mnemonics and Character Sets," RFC 1345, 3509 June 1992. 3511 [8] "Programming Languages - C", ANSI/ISO Standard 9899, revised 1997. 3513 [9] J. Hodges, R. Morgan, M. Wahl, "Lightweight Directory Access Proto- 3514 col (v3): Extension for Transport Layer Security", INTERNET-DRAFT 3515 (work in progress) , June 3516 1999. 3518 [10] R. Hinden, S. Deering, "IP Version 6 Addressing Architecture," RFC 3519 1884, December 1995. 3521 C LDAP API C LDAP Application Program Interface 17 November 2000 3523 [11] A. Herron, T. Howes, M. Wahl, A. Anantha, "LDAP Control Extension 3524 for Server Side Sorting of Search Results", INTERNET-DRAFT (work in 3525 progress) , 5 April 1999. 3527 [12] J. Meyers, "Simple Authentication and Security Layer (SASL)", RFC 3528 2222, October 1997. 3530 [13] T. Howes, "The String Representation of LDAP Search Filters," RFC 3531 2254, December 1997. 3533 [14] S. Kille, "Using the OSI Directory to Achieve User Friendly Nam- 3534 ing," RFC 1781, March 1995. 3536 22. Authors' Addresses 3538 Mark Smith (document editor) 3539 Netscape Communications Corp. 3540 901 San Antonio Rd. 3541 Palo Alto, CA 94303-4900 3542 Mail Stop SCA17 - 201 3543 USA 3544 +1 650 937-3477 3545 mcs@netscape.com 3547 Tim Howes 3548 Loudcloud, Inc. 3549 599 N. Mathilda Avenue 3550 Sunnyvale, CA 94085 3551 USA 3552 +1 408 744-7300 3553 howes@loudcloud.com 3555 Andy Herron 3556 Microsoft Corp. 3557 1 Microsoft Way 3558 Redmond, WA 98052 3559 USA 3560 +1 425 882-8080 3561 andyhe@microsoft.com 3563 Mark Wahl 3564 Sun Microsystems, Inc. 3565 8911 Capital of Texas Hwy, Suite 4140 3566 Austin, TX 78759 3567 USA 3568 +1 626 919 3600 3569 Mark.Wahl@sun.com 3571 C LDAP API C LDAP Application Program Interface 17 November 2000 3573 Anoop Anantha 3574 Microsoft Corp. 3575 1 Microsoft Way 3576 Redmond, WA 98052 3577 USA 3578 +1 425 882-8080 3579 anoopa@microsoft.com 3581 23. Appendix A - Sample C LDAP API Code 3583 #include 3584 #include 3586 main() 3587 { 3588 LDAP *ld; 3589 LDAPMessage *res, *e; 3590 int i, rc; 3591 char *a, *dn; 3592 BerElement *ptr; 3593 char **vals; 3595 /* open an LDAP session */ 3596 if ( (ld = ldap_init( "dotted.host.name", LDAP_PORT )) == NULL ) 3597 return 1; 3599 /* authenticate as nobody */ 3600 if (( rc = ldap_simple_bind_s( ld, NULL, NULL )) != LDAP_SUCCESS ) { 3601 fprintf( stderr, "ldap_simple_bind_s: %s\n", 3602 ldap_err2string( rc )); 3603 ldap_unbind( ld ); 3604 return 1; 3605 } 3607 /* search for entries with cn of "Babs Jensen", return all attrs */ 3608 if (( rc = ldap_search_s( ld, "o=University of Michigan, c=US", 3609 LDAP_SCOPE_SUBTREE, "(cn=Babs Jensen)", NULL, 0, &res )) 3610 != LDAP_SUCCESS ) { 3611 fprintf( stderr, "ldap_search_s: %s\n", 3612 ldap_err2string( rc )); 3613 if ( res == NULL ) { 3614 ldap_unbind( ld ); 3615 return 1; 3616 } 3617 } 3619 /* step through each entry returned */ 3621 C LDAP API C LDAP Application Program Interface 17 November 2000 3623 for ( e = ldap_first_entry( ld, res ); e != NULL; 3624 e = ldap_next_entry( ld, e ) ) { 3625 /* print its name */ 3626 dn = ldap_get_dn( ld, e ); 3627 printf( "dn: %s\n", dn ); 3628 ldap_memfree( dn ); 3630 /* print each attribute */ 3631 for ( a = ldap_first_attribute( ld, e, &ptr ); a != NULL; 3632 a = ldap_next_attribute( ld, e, ptr ) ) { 3633 printf( "\tattribute: %s\n", a ); 3635 /* print each value */ 3636 vals = ldap_get_values( ld, e, a ); 3637 for ( i = 0; vals[i] != NULL; i++ ) { 3638 printf( "\t\tvalue: %s\n", vals[i] ); 3639 } 3640 ldap_value_free( vals ); 3641 ldap_memfree( a ); 3642 } 3643 if ( ptr != NULL ) { 3644 ber_free( ptr, 0 ); 3645 } 3646 } 3647 /* free the search results */ 3648 ldap_msgfree( res ); 3650 /* close and free connection resources */ 3651 ldap_unbind( ld ); 3653 return 0; 3654 } 3656 24. Appendix B - Namespace Consumed By This Specification 3658 The following 2 prefixes are used in this specification to name func- 3659 tions: 3660 ldap_ 3661 ber_ 3663 The following 6 prefixes are used in this specification to name struc- 3664 tures, unions, and typedefs: 3665 ldap 3666 LDAP 3667 mod_vals_u 3668 ber 3669 Ber 3671 C LDAP API C LDAP Application Program Interface 17 November 2000 3673 timeval 3675 The following 3 prefixes are used in this specification to name #defined 3676 macros: 3677 LDAP 3678 LBER_ 3679 mod_ 3681 25. Appendix C - Summary of Requirements for API Extensions 3683 As the LDAP protocol is extended, this C LDAP API will need to be 3684 extended as well. For example, an LDAPv3 control extension has already 3685 been defined for server-side sorting of search results [7]. This appen- 3686 dix summarizes the requirements for extending this API. 3688 25.1. Compatibility 3690 Extensions to this document SHOULD NOT, by default, alter the behavior 3691 of any of the APIs specified in this document. If an extension option- 3692 ally changes the behavior of any existing C LDAP API function calls, the 3693 behavior change MUST be well documented. If an extension that operates 3694 on an LDAP session affects a chain of messages that was previously 3695 obtained by a call to ldap_result() or by calling a synchronous search 3696 routine, this MUST be well documented. 3698 25.2. Style 3700 Extensions to this API SHOULD follow the general style and naming con- 3701 ventions used in this document. For example, function names SHOULD 3702 start with "ldap_" or "ber_" and consist entirely of lowercase letters, 3703 digits, and underscore ('_') characters. It is RECOMMENDED that private 3704 and experimental extensions use only the following prefixes for macros, 3705 types, and function names: 3706 LDAP_X_ 3707 LBER_X_ 3708 ldap_x_ 3709 ber_x_ 3710 and that these prefixes not be used by standard extensions. 3712 25.3. Dependence on Externally Defined Types 3714 Extensions to this API SHOULD minimize dependencies on types and macros 3715 that are defined in system headers and generally use only intrinsic 3716 types that are part of the C language, types defined in this specifica- 3717 tion, or types defined in the extension document itself. 3719 C LDAP API C LDAP Application Program Interface 17 November 2000 3721 25.4. Compile Time Information 3723 Extensions to this API SHOULD conform to the requirements contained in 3724 the "Retrieving Information at Compile Time" section of this document. 3725 That is, extensions SHOULD define a macro of the form: 3727 #define LDAP_API_FEATURE_x level 3729 so that applications can detect the presence or absence of the extension 3730 at compile time and also test the version or level of the extension pro- 3731 vided by an API implementation. 3733 25.5. Runtime Information 3735 Extensions to this API SHOULD conform to the requirements contained in 3736 the "Retrieving Information During Execution" section of this document. 3737 That is, each extension SHOULD be given a character string name and that 3738 name SHOULD appear in the ldapai_extensions array field of the LDAPAPI- 3739 Info structure following a successful call to ldap_get_option() with an 3740 option parameter value of LDAP_OPT_API_INFO. In addition, information 3741 about the extension SHOULD be available via a call to ldap_get_option() 3742 with an option parameter value of LDAP_OPT_API_FEATURE_INFO. 3744 25.6. Values Used for Session Handle Options 3746 Extensions to this API that add new session options (for use with the 3747 ldap_get_option() and ldap_set_option() functions) SHOULD meet the 3748 requirements contained in the last paragraph of the "LDAP Session Handle 3749 Options" section of this document. Specifically, standards track docu- 3750 ments MUST use values for option macros that are between 0x1000 and 3751 0x3FFF inclusive and private and experimental extensions MUST use values 3752 for the option macros that are between 0x4000 and 0x7FFF inclusive. 3754 26. Appendix D - Known Incompatibilities with RFC 1823 3756 This appendix lists known incompatibilities between this API specifica- 3757 tion and the one contained in RFC 1823, beyond the additional API func- 3758 tions added in support of LDAPv3. 3760 26.1. Opaque LDAP Structure 3762 In RFC 1823, some fields in the LDAP structure were exposed to applica- 3763 tion programmers. To provide a cleaner interface and to make it easier 3764 for implementations to evolve over time without sacrificing binary com- 3765 patibility with older applications, the LDAP structure is now entirely 3766 opaque. The new ldap_set_option() and ldap_get_option() calls can be 3767 C LDAP API C LDAP Application Program Interface 17 November 2000 3769 used to manipulate per-session and global options. 3771 26.2. Additional Result Codes 3773 The following new result code macros were introduced to support LDAPv3: 3774 LDAP_REFERRAL 3775 LDAP_ADMINLIMIT_EXCEEDED 3776 LDAP_UNAVAILABLE_CRITICAL_EXTENSION 3777 LDAP_CONFIDENTIALITY_REQUIRED 3778 LDAP_SASL_BIND_IN_PROGRESS 3779 LDAP_AFFECTS_MULTIPLE_DSAS 3780 LDAP_CONNECT_ERROR 3781 LDAP_NOT_SUPPORTED 3782 LDAP_CONTROL_NOT_FOUND 3783 LDAP_NO_RESULTS_RETURNED 3784 LDAP_MORE_RESULTS_TO_RETURN 3785 LDAP_CLIENT_LOOP 3786 LDAP_REFERRAL_LIMIT_EXCEEDED 3788 26.3. Freeing of String Data with ldap_memfree() 3790 All strings received from the API (e.g., those returned by the 3791 ldap_get_dn() or ldap_dn2ufn() functions) SHOULD be freed by calling 3792 ldap_memfree() not free(). RFC 1823 did not define an ldap_memfree() 3793 function. 3795 26.4. Changes to ldap_result() 3797 The meaning of the all parameter to ldap_result has changed slightly. 3798 Nonzero values from RFC 1823 correspond to LDAP_MSG_ALL (0x01). There 3799 is also a new possible value, LDAP_MSG_RECEIVED (0x02). 3801 The result type LDAP_RES_MODDN is now returned where RFC 1823 returned 3802 LDAP_RES_MODRDN. The actual value for these two macros is the same 3803 (0x6D). 3805 26.5. Changes to ldap_first_attribute() and ldap_next_attribute 3807 Each non-NULL return value SHOULD be freed by calling ldap_memfree() 3808 after use. In RFC 1823, these two functions returned a pointer to a 3809 per-session buffer, which was not very thread-friendly. 3811 After the last call to ldap_first_attribute() or ldap_next_attribute(), 3812 the value set in the ptr parameter SHOULD be freed by calling ber_free( 3813 C LDAP API C LDAP Application Program Interface 17 November 2000 3815 ptr, 0 ). RFC 1823 did not mention that the ptr value SHOULD be freed. 3817 The type of the ptr parameter was changed from void * to BerElement *. 3819 26.6. Changes to ldap_modrdn() and ldap_modrdn_s() Functions 3821 In RFC 1823, the ldap_modrdn() and ldap_modrdn_s() functions include a 3822 parameter called deleteoldrdn. This does not match the great majority 3823 of implementations, so in this specification the deleteoldrdn parameter 3824 was removed from ldap_modrdn() and ldap_modrdn_s(). Two additional 3825 functions that support deleteoldrdn and are widely implemented as well 3826 were added to this specification: ldap_modrdn2() and ldap_modrdn2_s(). 3828 26.7. Changes to the berval structure 3830 In RFC 1823, the bv_len element of the berval structure was defined as 3831 an `unsigned long'. In this specification, the type is implementation- 3832 specific, although it MUST be an unsigned integral type that is at least 3833 32 bits in size. See the appendix "Data Types and Legacy Implementa- 3834 tions" for additional considerations. 3836 26.8. API Specification Clarified 3838 RFC 1823 left many things unspecified, including behavior of various 3839 memory disposal functions when a NULL pointer is presented, requirements 3840 for headers, values of many macros, and so on. This specification is 3841 more complete and generally tighter than the one in RFC 1823. 3843 26.9. Deprecated Functions 3845 A number of functions that are in RFC 1823 are labeled as "deprecated" 3846 in this specification. In most cases, a replacement that provides 3847 equivalent functionality has been defined. The deprecated functions 3848 are: 3850 ldap_bind() 3851 Use ldap_simple_bind() or ldap_sasl_bind() instead. 3853 ldap_bind_s() 3854 Use ldap_simple_bind_s() or ldap_sasl_bind_s() instead. 3856 ldap_kerberos_bind() and ldap_kerberos_bind_s() 3857 No equivalent functions are provided. 3859 C LDAP API C LDAP Application Program Interface 17 November 2000 3861 ldap_modrdn() and ldap_modrdn2() 3862 Use ldap_rename() instead. 3864 ldap_modrdn_s() and ldap_modrdn2_s() 3865 Use ldap_rename_s() instead. 3867 ldap_open() 3868 Use ldap_init() instead. 3870 ldap_perror() 3871 Use ldap_get_option( ld, LDAP_OPT_RESULT_CODE, &rc ) followed 3872 by fprintf( stderr, "%s: %s", msg, ldap_err2string( rc )) 3873 instead. 3875 ldap_result2error() 3876 Use ldap_parse_result() instead. 3878 27. Appendix E - Data Types and Legacy Implementations 3880 The data types associated with the length of a ber value (ber_len_t), 3881 and the tag (ber_tag_t) have been defined in this specification as 3882 unsigned integral types of implementation-specific size. The data type 3883 used for encoding and decoding ber integer, enumerated, and boolean 3884 values has been defined in this specification as a signed integral type 3885 of implementation-specific size. This was done so that source and 3886 binary compatibility of the C LDAP API can be maintained across ILP32 3887 environments (where int, long, and pointers are all 32 bits in size) and 3888 LP64 environments (where ints remain 32 bits but longs and pointers grow 3889 to 64 bits). 3891 In older implementations of the C LDAP API, such as those based on RFC 3892 1823, implementors may have chosen to use an `unsigned long' for length 3893 and tag values. If a long data type was used for either of these items, 3894 a port of an application to a 64-bit operating system using the LP64 3895 data model would find the size of the types used by the C LDAP API to 3896 increase. Also, if the legacy implementation had chosen to implement 3897 the tag and types as an unsigned int, adoption of a specification that 3898 mandated use of unsigned longs would cause a source incompatibility in 3899 an LP64 application. By using implementation-specific data types, the C 3900 LDAP API implementation is free to choose the correct data type and the 3901 ability to maintain source compatibility. 3903 For example, suppose a legacy implementation chose to define the return 3904 value of ber_skip_tag() as an unsigned long but wishes to have the 3905 library return a 32-bit quantity in both ILP32 and LP64 data models. 3906 The following typedefs for ber_tag_t will provide a fixed sized data 3907 structure while preserving existing ILP32 source -- all without 3908 C LDAP API C LDAP Application Program Interface 17 November 2000 3910 generating compiler warnings: 3911 #include /* provides UINT_MAX in ISO C */ 3912 #if UINT_MAX >= 0xffffffffU 3913 typedef unsigned int ber_tag_t; 3914 #else 3915 typedef unsigned long ber_tag_t; 3916 #endif 3918 Similar code can be used to define appropriate ber_len_t, ber_int_t, 3919 ber_slen_t and ber_uint_t types. 3921 28. Appendix F - Changes Made Since Last Document Revision 3923 The previous version of this document was draft-ietf-ldapext-ldap-c- 3924 api-04.txt, dated 8 October 1999. This appendix lists all of the 3925 changes made to that document to produce this one. 3927 28.1. API Changes 3929 "Header Requirements" section: added requirement that the simple pro- 3930 gram provided must execute as well as compile without errors. 3932 "LDAP Session Handle Options" section: changed the name of the 3933 LDAP_OPT_ERROR_NUMBER option to LDAP_OPT_RESULT_CODE. Allow 3934 LDAP_OPT_ON to be defined as an implementation specific value (to 3935 avoid problems on architectures where the value ((void *)1) is not 3936 usable). 3938 "Initializing an LDAP Session" section: allow use of the value zero 3939 for the `portno' parameter to mean "use port 389." 3941 "Searching" section: added LDAP_DEFAULT_SIZELIMIT (-1) to allow 3942 application programmers to use the sizelimit from the LDAP session 3943 handle with ldap_search_ext() and ldap_search_ext_s(). 3945 "Modifying an entry" section: moved mod_vals union out of LDAPMod and 3946 added mod_vals_u_t typedef so users of the API can declare variables 3947 using the union type. "Handling Errors and Parsing Results" section: 3948 added text to require that ldap_err2string() MUST NOT return NULL. 3950 "A Client Control That Governs Referral Processing" section: modified 3951 the text to specify that a ber_uint_t value should be used to hold 3952 the flags. 3954 C LDAP API C LDAP Application Program Interface 17 November 2000 3956 28.2. Editorial Changes and Clarifications 3958 "Overview of LDAP API Use and General Requirements" section: added 3959 text to clarify our use of the term "asynchronous." 3961 "Retrieving Information During Execution" section: added text 3962 describing the `ldapai_vendor_name' and `ldapai_vendor_version' 3963 fields (text was accidently deleted during a previous round of 3964 edits). 3966 "LDAP Session Handle Options" section: improved the text that 3967 describes the LDAP_OPT_TIMELIMIT, LDAP_OPT_SIZELIMIT, and 3968 LDAP_OPT_RESULT_CODE options. Provided details and an example of the 3969 correct LDAP_OPT_HOST_NAME string to return when the `portno' passed 3970 to ldap_init() is not zero or 389. 3972 "Result Codes" section: renamed section (was "LDAP Error Codes"). 3974 "Authenticating to the directory" section: clarified that the `dn', 3975 `cred', and `passwd' parameters can be NULL. Added text indicate 3976 that the `servercredp' is set to NULL if an API error occurs. 3978 "Performing LDAP Operations" section: replaced "All functions take a 3979 session handle" with "Most functions...." 3981 "Search" section: removed the detailed discussion of the session han- 3982 dle options (already covered in the "Retrieving Information During 3983 Execution" section). Also removed the word "global" when discussing 3984 the session default value for the `timeout' parameter. Also clari- 3985 fied that a NULL `base' parameter means use a zero-length string for 3986 the base DN. 3988 "Comparing a Value Against an Entry" section: corrected the "success- 3989 ful" return codes for ldap_compare_ext_s() and ldap_compare_s() (was 3990 LDAP_SUCCESS; changed to LDAP_COMPARE_TRUE or LDAP_COMPARE_FALSE). 3992 "Extended Operations" section: added text to indicate that the 3993 `retoidp' and `retdatap' result parameters are set to NULL if an API 3994 error occurs in ldap_extended_operation_s(). 3996 "Handling Errors and Parsing Results" section: added text to say that 3997 the `matcheddnp' result parameter will be set to NULL if the server 3998 does not return a matched DN string. Added text to indicate that 3999 serverctrlsp can be NULL. Added text to indicate that *retoidpp, 4000 *retdatap, *referralsp, and *serverctrlsp will be set to NULL if no 4001 items of that type are returned. Removed specific reference to 4002 LDAP_NO_SUCH_OBJECT result code when discussing the `matcheddnp' 4003 result parameter and added clarifying note about "" vs. NULL. 4005 C LDAP API C LDAP Application Program Interface 17 November 2000 4007 "Parsing References" section: added text to indicate that *refer- 4008 ralsp, and *serverctrlsp will be set to NULL if no items of that type 4009 are returned. 4011 "Obtaining Results and Peeking Inside LDAP Messages" section: added 4012 text to say that LDAPMessage chains MAY be tied to a session handle. 4014 "BER Data Structures and Types" section: removed note about 4015 ber_uint_t not being used in this document (it is now). Changed text 4016 to simplify the description of ber_slen_t. Removed misleading sen- 4017 tence about the width of ber_uint_t. 4019 "Encoded ASN.1 Value Manipulation / Encoding" section: added note 4020 that 'X' is reserved. Also fixed a few small bugs in the example 4021 code. 4023 "Encoded ASN.1 Value Manipulation / Decoding" section: clarified the 4024 requirements for LBER_ERROR and LBER_DEFAULT (expressed using octets 4025 instead of bits). Also fixed a few small bugs in the example code. 4027 Added the following text to all descriptions of the `serverctrls' and 4028 `clientctrls' parameters: ", or NULL if no controls 4029 are to be used." 4031 Added the following text to the description of all `dn' and `rdn' 4032 parameters: "If NULL, a zero length DN is sent to the server." 4034 Replaced many occurrences of the phrase "error code" with "result 4035 code" throughout the document. 4037 Added text to indicate that the value of the `msgidp' result parame- 4038 ter is undefined if an error occurs in the following functions: 4039 ldap_sasl_bind(), ldap_search_ext(), ldap_compare_ext(), 4040 ldap_modify_ext(), ldap_add_ext(), ldap_delete_ext(), 4041 ldap_extended_operation(). 4043 Added text to indicate that the `res' result parameter is set to NULL 4044 if an API error occurs in the following functions: ldap_result(), 4045 ldap_search_s(), ldap_search_st(). 4047 Added text to indicate that all result parameters have undefined 4048 values if an API error is returned by the following functions: 4049 ldap_parse_result(), ldap_parse_sasl_bind_result(), 4050 ldap_parse_extended_result(), ldap_parse_reference(), ber_scanf(). 4052 Added angle brackets around ficticious impl_XXX_t types to make it 4053 more obvious that these are not real "C" types, e.g., typedef 4054 ber_len_t'. 4056 C LDAP API C LDAP Application Program Interface 17 November 2000 4058 Appendix B: Added mod_vals_u and removed PLDAP from the struct, 4059 unions, and typedefs prefix list. 4061 Appendix C: Added note in "Compatibility" section about extensions 4062 possible affecting chains of messages and the fact that that must be 4063 well documented. Appendix D: Improved text for ldap_perror() (what 4064 to use instead). 4066 "Authors" section: updated contact information for Mark Smith, Tim 4067 Howes, and Mark Wahl. 4069 Fixed a few obvious typos, improved indentation, added missing blank 4070 lines, and so on.