1 2 3Network Working Group M. Smith, Editor 4INTERNET-DRAFT Netscape Communications Corp. 5Intended Category: Standards Track T. Howes 6Obsoletes: RFC 1823 Loudcloud, Inc. 7Expires: May 2001 A. Herron 8 Microsoft Corp. 9 M. Wahl 10 Sun Microsystems, Inc. 11 A. Anantha 12 Microsoft Corp. 13 14 15 17 November 2000 16 17 The C LDAP Application Program Interface 18 <draft-ietf-ldapext-ldap-c-api-05.txt> 19 20 211. Status of this Memo 22 23This document is an Internet-Draft and is in full conformance with all 24provisions of Section 10 of RFC2026. Internet-Drafts are working docu- 25ments of the Internet Engineering Task Force (IETF), its areas, and its 26working groups. Note that other groups may also distribute working 27documents as Internet-Drafts. 28 29Internet-Drafts are draft documents valid for a maximum of six months 30and may be updated, replaced, or obsoleted by other documents at any 31time. It is inappropriate to use Internet-Drafts as reference material 32or to cite them other than as "work in progress." 33 34The list of current Internet-Drafts can be accessed at 35http://www.ietf.org/ietf/1id-abstracts.txt. 36 37The list of Internet-Draft Shadow Directories can be accessed at 38http://www.ietf.org/shadow.html. 39 40This draft document will be submitted to the RFC Editor as a Standards 41Track document. Distribution of this memo is unlimited. Technical dis- 42cussion of this document will take place on the IETF LDAP Extension 43Working Group mailing list <ietf-ldapext@netscape.com>. Please send 44editorial comments directly to the authors. 45 46Copyright (C) The Internet Society (1997-1999). All Rights Reserved. 47 48Please see the Copyright section near the end of this document for more 49information. 50 51 52 53 54Expires: May 2001 [Page 1] 55 56C LDAP API C LDAP Application Program Interface 17 November 2000 57 58 592. Introduction 60 61This document defines a C language application program interface (API) 62to the Lightweight Directory Access Protocol (LDAP). This document 63replaces the previous definition of this API, defined in RFC 1823, 64updating it to include support for features found in version 3 of the 65LDAP protocol. New extended operation functions were added to support 66LDAPv3 features such as controls. In addition, other LDAP API changes 67were made to support information hiding and thread safety. 68 69The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 70"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 71document are to be interpreted as described in RFC 2119[1]. 72 73The C LDAP API is designed to be powerful, yet simple to use. It defines 74compatible synchronous and asynchronous interfaces to LDAP to suit a 75wide variety of applications. This document gives a brief overview of 76the LDAP model, then an overview of how the API is used by an applica- 77tion program to obtain LDAP information. The API calls are described in 78detail, followed by appendices that provide example code demonstrating 79use of the API, the namespace consumed by the API, a summary of require- 80ments for API extensions, known incompatibilities with RFC 1823, and a 81list of changes made since the last revision of this document. 82 83 843. Table of Contents 85 861. Status of this Memo............................................1 872. Introduction...................................................2 883. Table of Contents..............................................2 894. Overview of the LDAP Model.....................................4 905. Overview of LDAP API Use and General Requirements..............4 916. Header Requirements............................................6 927. Common Data Structures and Types...............................7 938. Memory Handling Overview.......................................9 949. Retrieving Information About the API Implementation............9 959.1. Retrieving Information at Compile Time......................10 969.2. Retrieving Information During Execution.....................11 9710. Result Codes...................................................14 9811. Performing LDAP Operations.....................................16 9911.1. Initializing an LDAP Session................................16 10011.2. LDAP Session Handle Options.................................17 10111.3. Working With Controls.......................................23 10211.3.1. A Client Control That Governs Referral Processing........24 10311.4. Authenticating to the directory.............................25 10411.5. Closing the session.........................................27 10511.6. Searching...................................................28 10611.7. Reading an Entry............................................32 107 108 109 110Expires: May 2001 [Page 2] 111 112C LDAP API C LDAP Application Program Interface 17 November 2000 113 114 115 11611.8. Listing the Children of an Entry............................32 11711.9. Comparing a Value Against an Entry..........................33 11811.10. Modifying an entry..........................................35 11911.11. Modifying the Name of an Entry..............................37 12011.12. Adding an entry.............................................39 12111.13. Deleting an entry...........................................41 12211.14. Extended Operations.........................................43 12312. Abandoning An Operation........................................44 12413. Obtaining Results and Peeking Inside LDAP Messages.............45 12514. Handling Errors and Parsing Results............................47 12615. Stepping Through a List of Results.............................51 12716. Parsing Search Results.........................................51 12816.1. Stepping Through a List of Entries or References............52 12916.2. Stepping Through the Attributes of an Entry.................53 13016.3. Retrieving the Values of an Attribute.......................54 13116.4. Retrieving the name of an entry.............................55 13216.5. Retrieving controls from an entry...........................56 13316.6. Parsing References..........................................57 13417. Encoded ASN.1 Value Manipulation...............................58 13517.1. BER Data Structures and Types...............................58 13617.2. Memory Disposal and Utility Functions.......................60 13717.3. Encoding....................................................60 13817.4. Encoding Example............................................63 13917.5. Decoding....................................................64 14017.6. Decoding Example............................................67 14118. Security Considerations........................................70 14219. Acknowledgements...............................................70 14320. Copyright......................................................70 14421. Bibliography...................................................71 14522. Authors' Addresses.............................................72 14623. Appendix A - Sample C LDAP API Code............................73 14724. Appendix B - Namespace Consumed By This Specification..........74 14825. Appendix C - Summary of Requirements for API Extensions........75 14925.1. Compatibility...............................................75 15025.2. Style.......................................................75 15125.3. Dependence on Externally Defined Types......................75 15225.4. Compile Time Information....................................76 15325.5. Runtime Information.........................................76 15425.6. Values Used for Session Handle Options......................76 15526. Appendix D - Known Incompatibilities with RFC 1823.............76 15626.1. Opaque LDAP Structure.......................................76 15726.2. Additional Result Codes.....................................77 15826.3. Freeing of String Data with ldap_memfree()..................77 15926.4. Changes to ldap_result()....................................77 16026.5. Changes to ldap_first_attribute() and ldap_next_attribute...77 16126.6. Changes to ldap_modrdn() and ldap_modrdn_s() Functions......78 16226.7. Changes to the berval structure.............................78 16326.8. API Specification Clarified.................................78 164 165 166Expires: May 2001 [Page 3] 167 168C LDAP API C LDAP Application Program Interface 17 November 2000 169 170 17126.9. Deprecated Functions........................................78 17227. Appendix E - Data Types and Legacy Implementations.............79 17328. Appendix F - Changes Made Since Last Document Revision.........80 17428.1. API Changes.................................................80 17528.2. Editorial Changes and Clarifications........................81 176 177 1784. Overview of the LDAP Model 179 180LDAP is the lightweight directory access protocol, described in [2] and 181[3]. It can provide a lightweight frontend to the X.500 directory [4], 182or a stand-alone service. In either mode, LDAP is based on a client- 183server model in which a client makes a TCP connection to an LDAP server, 184over which it sends requests and receives responses. 185 186The LDAP information model is based on the entry, which contains infor- 187mation about some object (e.g., a person). Entries are composed of 188attributes, which have a type and one or more values. Each attribute has 189a syntax that determines what kinds of values are allowed in the attri- 190bute (e.g., ASCII characters, a jpeg photograph, etc.) and how those 191values behave during directory operations (e.g., is case significant 192during comparisons). 193 194Entries may be organized in a tree structure, usually based on politi- 195cal, geographical, and organizational boundaries. Each entry is uniquely 196named relative to its sibling entries by its relative distinguished name 197(RDN) consisting of one or more distinguished attribute values from the 198entry. At most one value from each attribute may be used in the RDN. 199For example, the entry for the person Babs Jensen might be named with 200the "Barbara Jensen" value from the commonName attribute. 201 202A globally unique name for an entry, called a distinguished name or DN, 203is constructed by concatenating the sequence of RDNs from the entry up 204to the root of the tree. For example, if Babs worked for the University 205of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen, 206o=University of Michigan, c=US". The DN format used by LDAP is defined 207in [5]. 208 209Operations are provided to authenticate, search for and retrieve infor- 210mation, modify information, and add and delete entries from the tree. 211The next sections give an overview of how the API is used and detailed 212descriptions of the LDAP API calls that implement all of these func- 213tions. 214 215 2165. Overview of LDAP API Use and General Requirements 217 218An application generally uses the C LDAP API in four simple steps. 219 220 221 222Expires: May 2001 [Page 4] 223 224C LDAP API C LDAP Application Program Interface 17 November 2000 225 226 227 1. Initialize an LDAP session with a primary LDAP server. The 228 ldap_init() function returns a handle to the session, allowing 229 multiple connections to be open at once. 230 231 2. Authenticate to the LDAP server. The ldap_sasl_bind() function 232 and friends support a variety of authentication methods. 233 234 3. Perform some LDAP operations and obtain some results. 235 ldap_search() and friends return results which can be parsed by 236 ldap_parse_result(), ldap_first_entry(), ldap_next_entry(), etc. 237 238 4. Close the session. The ldap_unbind() function closes the connec- 239 tion. 240 241Operations can be performed either synchronously or asynchronously. The 242names of the synchronous functions end in _s. For example, a synchronous 243search can be completed by calling ldap_search_s(). An asynchronous 244search can be initiated by calling ldap_search(). All synchronous rou- 245tines return an indication of the outcome of the operation (e.g, the 246constant LDAP_SUCCESS or some other result code). The asynchronous rou- 247tines make available to the caller the message id of the operation ini- 248tiated. This id can be used in subsequent calls to ldap_result() to 249obtain the result(s) of the operation. An asynchronous operation can be 250abandoned by calling ldap_abandon() or ldap_abandon_ext(). Note that 251there is no requirement that an LDAP API implementation not block when 252handling asynchronous API functions; the term "asynchronous" as used in 253this document refers to the fact that the sending of LDAP requests can 254be separated from the receiving of LDAP responses. 255 256Results and errors are returned in an opaque structure called LDAPMes- 257sage. Routines are provided to parse this structure, step through 258entries and attributes returned, etc. Routines are also provided to 259interpret errors. Later sections of this document describe these rou- 260tines in more detail. 261 262LDAP version 3 servers can return referrals and references to other 263servers. By default, implementations of this API will attempt to follow 264referrals automatically for the application. This behavior can be dis- 265abled globally (using the ldap_set_option() call) or on a per-request 266basis through the use of a client control. 267 268All DN and string attribute values passed into or produced by this C 269LDAP API are represented using the character set of the underlying LDAP 270protocol version in use. When this API is used with LDAPv3, DN and 271string values are represented as UTF-8[6] characters. When this API is 272used with LDAPv2, the US-ASCII[7] or T.61[7] character set are used. 273Future documents MAY specify additional APIs supporting other character 274sets. 275 276 277 278Expires: May 2001 [Page 5] 279 280C LDAP API C LDAP Application Program Interface 17 November 2000 281 282 283For compatibility with existing applications, implementations of this 284API will by default use version 2 of the LDAP protocol. Applications 285that intend to take advantage of LDAP version 3 features will need to 286use the ldap_set_option() call with a LDAP_OPT_PROTOCOL_VERSION to 287switch to version 3. 288 289Unless otherwise indicated, conformant implementations of this specifi- 290cation MUST implement all of the C LDAP API functions as described in 291this document, and they MUST use the function prototypes, macro defini- 292tions, and types defined in this document. 293 294Note that this API is designed for use in environments where the 'int' 295type is at least 32 bits in size. 296 297 2986. Header Requirements 299 300To promote portability of applications, the following requirements are 301imposed on the headers used by applications to access the services of 302this API: 303 304Name and Inclusion 305 Applications only need to include a single header named ldap.h 306 to access all of the API services described in this document. 307 Therefore, the following C source program MUST compile and exe- 308 cute without errors: 309 310 #include <ldap.h> 311 312 int 313 main() 314 { 315 return 0; 316 } 317 318 The ldap.h header MAY include other implementation-specific 319 headers. 320 321Implementations SHOULD also provide a header named lber.h to facilitate 322development of applications desiring compatibility with older LDAP 323implementations. The lber.h header MAY be empty. Old applications that 324include lber.h in order to use BER facilities will need to include 325ldap.h. 326 327 328Idempotence 329 All headers SHOULD be idempotent; that is, if they are included 330 more than once the effect is as if they had only been included 331 332 333 334Expires: May 2001 [Page 6] 335 336C LDAP API C LDAP Application Program Interface 17 November 2000 337 338 339 once. 340 341Must Be Included Before API Is Used 342 An application MUST include the ldap.h header before referencing 343 any of the function or type definitions described in this API 344 specification. 345 346Mutual Independence 347 Headers SHOULD be mutually independent with minimal dependence 348 on system or any other headers. 349 350Use of the 'const' Keyword 351 This API specification is defined in terms of ISO C[8]. It 352 makes use of function prototypes and the 'const' keyword. The 353 use of 'const' in this specification is limited to simple, non- 354 array function parameters to avoid forcing applications to 355 declare parameters and variables that accept return values from 356 LDAP API functions as 'const.' Implementations specifically 357 designed to be used with non-ISO C translators SHOULD provide 358 function declarations without prototypes or function prototypes 359 without specification of 'const' arguments. 360 361Definition of 'struct timeval' 362 This API specification uses the 'struct timeval' type. Imple- 363 mentations of this API MUST ensure that the struct timeval type 364 is by default defined as a consequence of including the ldap.h 365 header. Because struct timeval is usually defined in one or 366 more system headers, it is possible for header conflicts to 367 occur if ldap.h also defines it or arranges for it to be defined 368 by including another header. Therefore, applications MAY want 369 to arrange for struct timeval to be defined before they include 370 ldap.h. To support this, the ldap.h header MUST NOT itself 371 define struct timeval if the preprocessor symbol 372 LDAP_TYPE_TIMEVAL_DEFINED is defined before ldap.h is included. 373 374 3757. Common Data Structures and Types 376 377Data structures and types that are common to several LDAP API functions 378are defined here: 379 380 typedef struct ldap LDAP; 381 382 typedef struct ldapmsg LDAPMessage; 383 384 typedef struct berelement BerElement; 385 386 typedef <impl_len_t> ber_len_t; 387 388 389 390Expires: May 2001 [Page 7] 391 392C LDAP API C LDAP Application Program Interface 17 November 2000 393 394 395 typedef struct berval { 396 ber_len_t bv_len; 397 char *bv_val; 398 } BerValue; 399 400 struct timeval { 401 <impl_sec_t> tv_sec; 402 <impl_usec_t> tv_usec; 403 }; 404 405The LDAP structure is an opaque data type that represents an LDAP ses- 406sion Typically this corresponds to a connection to a single server, but 407it MAY encompass several server connections in the face of LDAPv3 refer- 408rals. 409 410The LDAPMessage structure is an opaque data type that is used to return 411entry, reference, result, and error information. An LDAPMessage struc- 412ture can represent the beginning of a list, or chain of messages that 413consists of a series of entries, references, and result messages as 414returned by LDAP operations such as search. LDAP API functions such as 415ldap_parse_result() that operate on message chains that can contain more 416than one result message always operate on the first result message in 417the chain. See the "Obtaining Results and Peeking Inside LDAP Messages" 418section of this document for more information. 419 420The BerElement structure is an opaque data type that is used to hold 421data and state information about encoded data. It is described in more 422detail in the section "Encoded ASN.1 Value Manipulation" later in this 423document. 424 425The `ber_len_t' type is an unsigned integral data type that is large 426enough to contain the length of the largest piece of data supported by 427the API implementation. The `<impl_len_t>' in the `ber_len_t' typedef 428MUST be replaced with an appropriate type. The width (number of signi- 429ficant bits) of `ber_len_t' MUST be at least 32 and no larger than that 430of `unsigned long'. See the appendix "Data Types and Legacy Implementa- 431tions" for additional considerations. 432 433The BerValue structure is used to represent arbitrary binary data and 434its fields have the following meanings: 435 436bv_len Length of data in bytes. 437 438bv_val A pointer to the data itself. 439 440 441The timeval structure is used to represent an interval of time and its 442fields have the following meanings: 443 444 445 446Expires: May 2001 [Page 8] 447 448C LDAP API C LDAP Application Program Interface 17 November 2000 449 450 451tv_sec Seconds component of time interval. 452 453tv_usec Microseconds component of time interval. 454 455Note that because the struct timeval definition typically is derived 456from a system header, the types used for the tv_sec and tv_usec com- 457ponents are implementation-specific integral types. Therefore, 458`<impl_sec_t>' and `<impl_usec_t>' in the struct timeval definition MUST 459be replaced with appropriate types. See the earlier section "Header 460Requirements" for more information on struct timeval. 461 462 4638. Memory Handling Overview 464 465All memory that is allocated by a function in this C LDAP API and 466returned to the caller SHOULD be disposed of by calling the appropriate 467"free" function provided by this API. The correct "free" function to 468call is documented in each section of this document where a function 469that allocates memory is described. 470 471Memory that is allocated through means outside of the C LDAP API MUST 472NOT be disposed of using a function provided by this API. 473 474If a pointer value passed to one of the C LDAP API "free" functions is 475NULL, graceful failure (i.e, ignoring of the NULL pointer) MUST occur. 476 477The complete list of "free" functions that are used to dispose of allo- 478cated memory is: 479 480 ber_bvecfree() 481 ber_bvfree() 482 ber_free() 483 ldap_control_free() 484 ldap_controls_free() 485 ldap_memfree() 486 ldap_msgfree() 487 ldap_value_free() 488 ldap_value_free_len() 489 490 4919. Retrieving Information About the API Implementation 492 493Applications developed to this specification need to be able to deter- 494mine information about the particular API implementation they are using 495both at compile time and during execution. 496 497 498 499 500 501 502Expires: May 2001 [Page 9] 503 504C LDAP API C LDAP Application Program Interface 17 November 2000 505 506 5079.1. Retrieving Information at Compile Time 508 509All conformant implementations MUST include the following five defini- 510tions in a header so compile time tests can be done by LDAP software 511developers: 512 513 #define LDAP_API_VERSION level 514 #define LDAP_VERSION_MIN min-version 515 #define LDAP_VERSION_MAX max-version 516 #define LDAP_VENDOR_NAME "vend-name" 517 #define LDAP_VENDOR_VERSION vend-version 518 519where: 520 521 "level" is replaced with the RFC number given to this C LDAP API 522 specification when it is published as a standards track RFC. 523 524 min-version is replaced with the lowest LDAP protocol version sup- 525 ported by the implementation. 526 527 max-version is replaced with the highest LDAP protocol version sup- 528 ported by the implementation. This SHOULD be 3. 529 530 "vend-name" is replaced with a text string that identifies the 531 party that supplies the API implementation. 532 533 "vend-version" is a supplier-specific version number multiplied 534 times 100. 535 536Note that the LDAP_VENDOR_NAME macro SHOULD be defined as "" if no ven- 537dor name is available and the LDAP_VENDOR_VERSION macro SHOULD be 538defined as 0 if no vendor-specific version information is available. 539 540For example, if this specification is published as RFC 88888, Netscape 541Communication's version 4.0 implementation that supports LDAPv2 and v3 542might include macro definitions like these: 543 544 #define LDAP_API_VERSION 88888 /* RFC 88888 compliant */ 545 #define LDAP_VERSION_MIN 2 546 #define LDAP_VERSION_MAX 3 547 #define LDAP_VENDOR_NAME "Netscape Communications Corp." 548 #define LDAP_VENDOR_VERSION 400 /* version 4.0 */ 549 550and application code can test the C LDAP API version level using a 551construct such as this one: 552 553 #if (LDAP_API_VERSION >= 88888) 554 /* use features supported in RFC 88888 or later */ 555 556 557 558Expires: May 2001 [Page 10] 559 560C LDAP API C LDAP Application Program Interface 17 November 2000 561 562 563 #endif 564 565Until such time as this document is published as an RFC, implementations 566SHOULD use the value 2000 plus the revision number of this draft for 567LDAP_API_VERSION. For example, the correct value for LDAP_API_VERSION 568for revision 05 of this draft is 2005. 569 570Documents that extend this specification SHOULD define a macro of the 571form: 572 573 #define LDAP_API_FEATURE_x level 574 575where "x" is replaced with a name (textual identifier) for the feature 576and "level" is replaced with the number of the RFC that specifies the 577API extension. The name SHOULD NOT begin with the string "X_". 578 579For example, if C LDAP API extensions for Transport Layer Security [9] 580were published in RFC 99999, that RFC might require conformant implemen- 581tations to define a macro like this: 582 583 #define LDAP_API_FEATURE_TLS 99999 584 585 586Private or experimental API extensions SHOULD be indicated by defining a 587macro of this same form where "x" (the extension's name) begins with the 588string "X_" and "level" is replaced with a integer number that is 589specific to the extension. 590 591It is RECOMMENDED that private or experimental API extensions use only 592the following prefixes for macros, types, and function names: 593 LDAP_X_ 594 LBER_X_ 595 ldap_x_ 596 ber_x_ 597and that these prefixes not be used by standard extensions. 598 599 6009.2. Retrieving Information During Execution 601 602The ldap_get_option() call (described in greater detail later in this 603document) can be used during execution in conjunction with an option 604parameter value of LDAP_OPT_API_INFO (0x00) to retrieve some basic 605information about the API and about the specific implementation being 606used. The ld parameter to ldap_get_option() can be either NULL or a 607valid LDAP session handle which was obtained by calling ldap_init(). 608The optdata parameter to ldap_get_option() SHOULD be the address of an 609LDAPAPIInfo structure which is defined as follows: 610 611 612 613 614Expires: May 2001 [Page 11] 615 616C LDAP API C LDAP Application Program Interface 17 November 2000 617 618 619 typedef struct ldapapiinfo { 620 int ldapai_info_version; /* version of this struct (1) */ 621 int ldapai_api_version; /* revision of API supported */ 622 int ldapai_protocol_version; /* highest LDAP version supported */ 623 char **ldapai_extensions; /* names of API extensions */ 624 char *ldapai_vendor_name; /* name of supplier */ 625 int ldapai_vendor_version; /* supplier-specific version times 100 */ 626 } LDAPAPIInfo; 627 628In addition, API implementations MUST include the following macro defin- 629ition: 630 631 #define LDAP_API_INFO_VERSION 1 632 633Note that the ldapai_info_version field of the LDAPAPIInfo structure 634SHOULD be set to the value LDAP_API_INFO_VERSION (1) before calling 635ldap_get_option() so that it can be checked for consistency. All other 636fields are set by the ldap_get_option() function. 637 638The members of the LDAPAPIInfo structure are: 639 640ldapai_info_version 641 A number that identifies the version of the LDAPAPIInfo struc- 642 ture. This SHOULD be set to the value LDAP_API_INFO_VERSION 643 (1) before calling ldap_get_option(). If the value received 644 is not recognized by the API implementation, the 645 ldap_get_option() function sets ldapai_info_version to a valid 646 value that would be recognized, sets the ldapai_api_version to 647 the correct value, and returns an error without filling in any 648 of the other fields in the LDAPAPIInfo structure. 649 650ldapai_api_version 651 A number that matches that assigned to the C LDAP API RFC sup- 652 ported by the API implementation. This SHOULD match the value 653 of the LDAP_API_VERSION macro defined earlier. 654 655ldapai_protocol_version 656 The highest LDAP protocol version supported by the implementa- 657 tion. For example, if LDAPv3 is the highest version supported 658 then this field will be set to 3. 659 660ldapai_vendor_name 661 A zero-terminated string that contains the name of the party 662 that produced the LDAP API implementation. This field may be 663 set to NULL if no name is available. If non-NULL, the caller 664 is responsible for disposing of the memory occupied by passing 665 this pointer to ldap_memfree() which is described later in 666 this document. This value SHOULD match the value of the 667 668 669 670Expires: May 2001 [Page 12] 671 672C LDAP API C LDAP Application Program Interface 17 November 2000 673 674 675 LDAP_VENDOR_NAME macro described earlier in this document. 676 677ldapai_vendor_version 678 An implementation-specific version number multiplied by 100. 679 For example, if the implementation version is 4.0 then this 680 field will be set to 400. If no version information is avail- 681 able, this field will be set to 0. This value SHOULD match 682 the value of the LDAP_VENDOR_VERSION macro described earlier 683 in this document. 684 685ldapai_extensions 686 A NULL-terminated array of character strings that lists the 687 names of the API extensions supported by the LDAP API imple- 688 mentation. These names will typically match the textual iden- 689 tifiers that appear in the "x" portion of the 690 LDAP_API_FEATURE_x macros described above, although the pre- 691 cise value MUST be defined by documents that specify C LDAP 692 API extensions. If no API extensions are supported, this 693 field will be set to NULL. The caller is responsible for 694 disposing of the memory occupied by this array by passing it 695 to ldap_value_free() which is described later in this docu- 696 ment. To retrieve more information about a particular exten- 697 sion, the ldap_get_option() call can be used with an option 698 parameter value of LDAP_OPT_API_FEATURE_INFO (0x15). The opt- 699 data parameter to the ldap_get_option() SHOULD be the address 700 of an LDAPAPIFeatureInfo structure which is defined as fol- 701 lows: 702 703 typedef struct ldap_apifeature_info { 704 int ldapaif_info_version; /* version of this struct (1) */ 705 char *ldapaif_name; /* name of supported feature */ 706 int ldapaif_version; /* revision of supported feature */ 707 } LDAPAPIFeatureInfo; 708 709 In addition, API implementations MUST include the following 710 macro definition: 711 712 #define LDAP_FEATURE_INFO_VERSION 1 713 714 Note that the ldapaif_info_version field of the LDAPAPI- 715 FeatureInfo structure SHOULD be set to the value 716 LDAP_FEATURE_INFO_VERSION (1) and the ldapaif_name field 717 SHOULD be set to the extension name string as described below 718 before ldap_get_option() is called. The call will fill in the 719 ldapaif_version field of the LDAPAPIFeatureInfo structure. 720 721 The members of the LDAPAPIFeatureInfo structure are: 722 723 724 725 726Expires: May 2001 [Page 13] 727 728C LDAP API C LDAP Application Program Interface 17 November 2000 729 730 731 ldapaif_info_version 732 A number that identifies the version of the LDAPAPI- 733 FeatureInfo structure. This SHOULD be set to the value 734 LDAP_FEATURE_INFO_VERSION (1) before calling 735 ldap_get_option(). If the value received is not recognized 736 by the API implementation, the ldap_get_option() function 737 sets ldapaif_info_version to a valid value that would be 738 recognized and returns an error without filling in the 739 ldapaif_version field in the LDAPAPIFeatureInfo structure. 740 741 ldapaif_name 742 The name of an extension, as returned in the 743 ldapai_extensions array of the LDAPAPIInfo structure and as 744 specified in the document that describes the extension. 745 746 ldapaif_version 747 This field will be set as a result of calling 748 ldap_get_option(). It is a number that matches that 749 assigned to the C LDAP API extension RFC supported for this 750 extension. For private or experimental API extensions, the 751 value is extension-specific. In either case, the value of 752 ldapaxi_ext_version SHOULD be identical to the value of the 753 LDAP_API_FEATURE_x macro defined for the extension 754 (described above). 755 756 75710. Result Codes 758 759Many of the LDAP API routines return result codes, some of which indi- 760cate local API errors and some of which are LDAP resultCodes that are 761returned by servers. All of the result codes are non-negative integers. 762Supported result codes are as follows (hexadecimal values are given in 763parentheses after the constant): 764 765 LDAP_SUCCESS (0x00) 766 LDAP_OPERATIONS_ERROR (0x01) 767 LDAP_PROTOCOL_ERROR (0x02) 768 LDAP_TIMELIMIT_EXCEEDED (0x03) 769 LDAP_SIZELIMIT_EXCEEDED (0x04) 770 LDAP_COMPARE_FALSE (0x05) 771 LDAP_COMPARE_TRUE (0x06) 772 LDAP_STRONG_AUTH_NOT_SUPPORTED (0x07) 773 LDAP_STRONG_AUTH_REQUIRED (0x08) 774 LDAP_REFERRAL (0x0a) -- new in LDAPv3 775 LDAP_ADMINLIMIT_EXCEEDED (0x0b) -- new in LDAPv3 776 LDAP_UNAVAILABLE_CRITICAL_EXTENSION (0x0c) -- new in LDAPv3 777 LDAP_CONFIDENTIALITY_REQUIRED (0x0d) -- new in LDAPv3 778 LDAP_SASL_BIND_IN_PROGRESS (0x0e) -- new in LDAPv3 779 780 781 782Expires: May 2001 [Page 14] 783 784C LDAP API C LDAP Application Program Interface 17 November 2000 785 786 787 LDAP_NO_SUCH_ATTRIBUTE (0x10) 788 LDAP_UNDEFINED_TYPE (0x11) 789 LDAP_INAPPROPRIATE_MATCHING (0x12) 790 LDAP_CONSTRAINT_VIOLATION (0x13) 791 LDAP_TYPE_OR_VALUE_EXISTS (0x14) 792 LDAP_INVALID_SYNTAX (0x15) 793 LDAP_NO_SUCH_OBJECT (0x20) 794 LDAP_ALIAS_PROBLEM (0x21) 795 LDAP_INVALID_DN_SYNTAX (0x22) 796 LDAP_IS_LEAF (0x23) -- not used in LDAPv3 797 LDAP_ALIAS_DEREF_PROBLEM (0x24) 798 LDAP_INAPPROPRIATE_AUTH (0x30) 799 LDAP_INVALID_CREDENTIALS (0x31) 800 LDAP_INSUFFICIENT_ACCESS (0x32) 801 LDAP_BUSY (0x33) 802 LDAP_UNAVAILABLE (0x34) 803 LDAP_UNWILLING_TO_PERFORM (0x35) 804 LDAP_LOOP_DETECT (0x36) 805 LDAP_NAMING_VIOLATION (0x40) 806 LDAP_OBJECT_CLASS_VIOLATION (0x41) 807 LDAP_NOT_ALLOWED_ON_NONLEAF (0x42) 808 LDAP_NOT_ALLOWED_ON_RDN (0x43) 809 LDAP_ALREADY_EXISTS (0x44) 810 LDAP_NO_OBJECT_CLASS_MODS (0x45) 811 LDAP_RESULTS_TOO_LARGE (0x46) -- reserved for CLDAP 812 LDAP_AFFECTS_MULTIPLE_DSAS (0x47) -- new in LDAPv3 813 LDAP_OTHER (0x50) 814 LDAP_SERVER_DOWN (0x51) 815 LDAP_LOCAL_ERROR (0x52) 816 LDAP_ENCODING_ERROR (0x53) 817 LDAP_DECODING_ERROR (0x54) 818 LDAP_TIMEOUT (0x55) 819 LDAP_AUTH_UNKNOWN (0x56) 820 LDAP_FILTER_ERROR (0x57) 821 LDAP_USER_CANCELLED (0x58) 822 LDAP_PARAM_ERROR (0x59) 823 LDAP_NO_MEMORY (0x5a) 824 LDAP_CONNECT_ERROR (0x5b) 825 LDAP_NOT_SUPPORTED (0x5c) 826 LDAP_CONTROL_NOT_FOUND (0x5d) 827 LDAP_NO_RESULTS_RETURNED (0x5e) 828 LDAP_MORE_RESULTS_TO_RETURN (0x5f) 829 LDAP_CLIENT_LOOP (0x60) 830 LDAP_REFERRAL_LIMIT_EXCEEDED (0x61) 831 832 833 834 835 836 837 838Expires: May 2001 [Page 15] 839 840C LDAP API C LDAP Application Program Interface 17 November 2000 841 842 84311. Performing LDAP Operations 844 845This section describes each LDAP operation API call in detail. Most 846functions take a "session handle," a pointer to an LDAP structure con- 847taining per-connection information. Many routines return results in an 848LDAPMessage structure. These structures and others are described as 849needed below. 850 851 85211.1. Initializing an LDAP Session 853 854ldap_init() initializes a session with an LDAP server. The server is not 855actually contacted until an operation is performed that requires it, 856allowing various options to be set after initialization. 857 858 LDAP *ldap_init( 859 const char *hostname, 860 int portno 861 ); 862 863Use of the following routine is deprecated: 864 865 LDAP *ldap_open( 866 const char *hostname, 867 int portno 868 ); 869 870Unlike ldap_init(), ldap_open() attempts to make a server connection 871before returning to the caller. A more complete description can be 872found in RFC 1823. 873 874Parameters are: 875 876hostname Contains a space-separated list of hostnames or dotted strings 877 representing the IP address of hosts running an LDAP server to 878 connect to. Each hostname in the list MAY include a port number 879 which is separated from the host itself with a colon (:) char- 880 acter. The hosts will be tried in the order listed, stopping 881 with the first one to which a successful connection is made. 882 883 Note: A suitable representation for including a literal IPv6[10] 884 address in the hostname parameter is desired, but has not yet been 885 determined or implemented in practice. 886 887portno Contains the TCP port number to connect to. The default LDAP 888 port of 389 can be obtained by supplying the value zero (0) or 889 the macro LDAP_PORT (389). If a host includes a port number 890 then this parameter is ignored. 891 892 893 894Expires: May 2001 [Page 16] 895 896C LDAP API C LDAP Application Program Interface 17 November 2000 897 898 899ldap_init() and ldap_open() both return a "session handle," a pointer to 900an opaque structure that MUST be passed to subsequent calls pertaining 901to the session. These routines return NULL if the session cannot be ini- 902tialized in which case the operating system error reporting mechanism 903can be checked to see why the call failed. 904 905Note that if you connect to an LDAPv2 server, one of the LDAP bind calls 906described below SHOULD be completed before other operations can be per- 907formed on the session. LDAPv3 does not require that a bind operation be 908completed before other operations can be performed. 909 910The calling program can set various attributes of the session by calling 911the routines described in the next section. 912 913 91411.2. LDAP Session Handle Options 915 916The LDAP session handle returned by ldap_init() is a pointer to an 917opaque data type representing an LDAP session. In RFC 1823 this data 918type was a structure exposed to the caller, and various fields in the 919structure could be set to control aspects of the session, such as size 920and time limits on searches. 921 922In the interest of insulating callers from inevitable changes to this 923structure, these aspects of the session are now accessed through a pair 924of accessor functions, described below. 925 926ldap_get_option() is used to access the current value of various 927session-wide parameters. ldap_set_option() is used to set the value of 928these parameters. Note that some options are READ-ONLY and cannot be 929set; it is an error to call ldap_set_option() and attempt to set a 930READ-ONLY option. 931 932Note that if automatic referral following is enabled (the default), any 933connections created during the course of following referrals will 934inherit the options associated with the session that sent the original 935request that caused the referrals to be returned. 936 937 int ldap_get_option( 938 LDAP *ld, 939 int option, 940 void *outvalue 941 ); 942 943 int ldap_set_option( 944 LDAP *ld, 945 int option, 946 const void *invalue 947 948 949 950Expires: May 2001 [Page 17] 951 952C LDAP API C LDAP Application Program Interface 17 November 2000 953 954 955 ); 956 957 #define LDAP_OPT_ON (<impl_void_star_value>) 958 #define LDAP_OPT_OFF ((void *)0) 959 960 LDAP_OPT_ON MUST be defined as a non-null pointer to void; that is, 961 <impl_void_star_value> MUST be replaced with a non-null pointer to 962 void, e.g., one could use: 963 #define LDAP_OPT_ON ((void *)1) 964 if that value is safe to use on the architecture where the API is 965 implemented. 966 967Parameters are: 968 969ld The session handle. If this is NULL, a set of global defaults is 970 accessed. New LDAP session handles created with ldap_init() or 971 ldap_open() inherit their characteristics from these global 972 defaults. 973 974option The name of the option being accessed or set. This parameter 975 SHOULD be one of the following constants, which have the indi- 976 cated meanings. After the constant the actual hexadecimal value 977 of the constant is listed in parentheses. 978 979 980 LDAP_OPT_API_INFO (0x00) 981 Type for invalue parameter: not applicable (option is READ-ONLY) 982 983 Type for outvalue parameter: LDAPAPIInfo * 984 985 Description: 986 Used to retrieve some basic information about the LDAP API 987 implementation at execution time. See the section "Retriev- 988 ing Information About the API Implementation" above for more 989 information. This option is READ-ONLY and cannot be set. 990 991 LDAP_OPT_DEREF (0x02) 992 Type for invalue parameter: int * 993 994 Type for outvalue parameter: int * 995 996 Description: 997 Determines how aliases are handled during search. It SHOULD 998 have one of the following values: LDAP_DEREF_NEVER (0x00), 999 LDAP_DEREF_SEARCHING (0x01), LDAP_DEREF_FINDING (0x02), or 1000 LDAP_DEREF_ALWAYS (0x03). The LDAP_DEREF_SEARCHING value 1001 means aliases are dereferenced during the search but not when 1002 locating the base object of the search. The 1003 1004 1005 1006Expires: May 2001 [Page 18] 1007 1008C LDAP API C LDAP Application Program Interface 17 November 2000 1009 1010 1011 LDAP_DEREF_FINDING value means aliases are dereferenced when 1012 locating the base object but not during the search. The 1013 default value for this option is LDAP_DEREF_NEVER. 1014 1015 LDAP_OPT_SIZELIMIT (0x03) 1016 Type for invalue parameter: int * 1017 1018 Type for outvalue parameter: int * 1019 1020 Description: 1021 A limit on the number of entries to return from a search. A 1022 value of LDAP_NO_LIMIT (0) means no limit. The default value 1023 for this option is LDAP_NO_LIMIT. 1024 1025 LDAP_OPT_TIMELIMIT (0x04) 1026 Type for invalue parameter: int * 1027 1028 Type for outvalue parameter: int * 1029 1030 Description: 1031 A limit on the number of seconds to spend on a search. A 1032 value of LDAP_NO_LIMIT (0) means no limit. The default value 1033 for this option is LDAP_NO_LIMIT. This value is passed to 1034 the server in the search request only; it does not affect how 1035 long the C LDAP API implementation itself will wait locally 1036 for search results. Note that the timeout parameter passed 1037 to the ldap_search_ext_s() or ldap_result() functions can be 1038 used to specify a limit on how long the API implementation 1039 will wait for results. 1040 1041 LDAP_OPT_REFERRALS (0x08) 1042 Type for invalue parameter: void * (LDAP_OPT_ON or LDAP_OPT_OFF) 1043 1044 Type for outvalue parameter: int * 1045 1046 Description: 1047 Determines whether the LDAP library automatically follows 1048 referrals returned by LDAP servers or not. It MAY be set to 1049 one of the constants LDAP_OPT_ON or LDAP_OPT_OFF; any non- 1050 NULL pointer value passed to ldap_set_option() enables this 1051 option. When reading the current setting using 1052 ldap_get_option(), a zero value means OFF and any non-zero 1053 value means ON. By default, this option is ON. 1054 1055 LDAP_OPT_RESTART (0x09) 1056 Type for invalue parameter: void * (LDAP_OPT_ON or LDAP_OPT_OFF) 1057 1058 Type for outvalue parameter: int * 1059 1060 1061 1062Expires: May 2001 [Page 19] 1063 1064C LDAP API C LDAP Application Program Interface 17 November 2000 1065 1066 1067 Description: 1068 Determines whether LDAP I/O operations are automatically res- 1069 tarted if they abort prematurely. It MAY be set to one of the 1070 constants LDAP_OPT_ON or LDAP_OPT_OFF; any non-NULL pointer 1071 value passed to ldap_set_option() enables this option. When 1072 reading the current setting using ldap_get_option(), a zero 1073 value means OFF and any non-zero value means ON. This option 1074 is useful if an LDAP I/O operation can be interrupted prema- 1075 turely, for example by a timer going off, or other interrupt. 1076 By default, this option is OFF. 1077 1078 LDAP_OPT_PROTOCOL_VERSION (0x11) 1079 Type for invalue parameter: int * 1080 1081 Type for outvalue parameter: int * 1082 1083 Description: 1084 This option indicates the version of the LDAP protocol used 1085 when communicating with the primary LDAP server. It SHOULD be 1086 one of the constants LDAP_VERSION2 (2) or LDAP_VERSION3 (3). 1087 If no version is set the default is LDAP_VERSION2 (2). 1088 1089 LDAP_OPT_SERVER_CONTROLS (0x12) 1090 Type for invalue parameter: LDAPControl ** 1091 1092 Type for outvalue parameter: LDAPControl *** 1093 1094 Description: 1095 A default list of LDAP server controls to be sent with each 1096 request. See the Working With Controls section below. 1097 1098 LDAP_OPT_CLIENT_CONTROLS (0x13) 1099 Type for invalue parameter: LDAPControl ** 1100 1101 Type for outvalue parameter: LDAPControl *** 1102 1103 Description: 1104 A default list of client controls that affect the LDAP ses- 1105 sion. See the Working With Controls section below. 1106 1107 LDAP_OPT_API_FEATURE_INFO (0x15) 1108 Type for invalue parameter: not applicable (option is READ-ONLY) 1109 1110 Type for outvalue parameter: LDAPAPIFeatureInfo * 1111 1112 Description: 1113 Used to retrieve version information about LDAP API extended 1114 features at execution time. See the section "Retrieving 1115 1116 1117 1118Expires: May 2001 [Page 20] 1119 1120C LDAP API C LDAP Application Program Interface 17 November 2000 1121 1122 1123 Information About the API Implementation" above for more 1124 information. This option is READ-ONLY and cannot be set. 1125 1126 LDAP_OPT_HOST_NAME (0x30) 1127 Type for invalue parameter: char * 1128 1129 Type for outvalue parameter: char ** 1130 1131 Description: 1132 The host name (or list of hosts) for the primary LDAP server. 1133 See the definition of the hostname parameter to ldap_init() 1134 for the allowed syntax. Note that if the portno parameter 1135 passed to ldap_init() is a value other than 0 or 389 1136 (LDAP_PORT), this value SHOULD include a string like 1137 ":portno" after each hostname or IP address that did not have 1138 one in the original hostname parameter that was passed to 1139 ldap_init(). For example, if this hostname value was passed 1140 to ldap_init(): 1141 1142 "ldap.example.com:389 ldap2.example.com" 1143 1144 and the portno parameter passed to ldap_init() was 6389, then 1145 the value returned for the LDAP_OPT_HOST_NAME option SHOULD 1146 be: 1147 1148 "ldap.example.com:389 ldap2.example.com:6389" 1149 1150 1151 LDAP_OPT_RESULT_CODE (0x31) 1152 Type for invalue parameter: int * 1153 1154 Type for outvalue parameter: int * 1155 1156 Description: 1157 The most recent local (API generated) or server returned LDAP 1158 result code that occurred for this session. 1159 1160 LDAP_OPT_ERROR_STRING (0x32) 1161 Type for invalue parameter: char * 1162 1163 Type for outvalue parameter: char ** 1164 1165 Description: 1166 The message returned with the most recent LDAP error that 1167 occurred for this session. 1168 1169 LDAP_OPT_MATCHED_DN (0x33) 1170 Type for invalue parameter: char * 1171 1172 1173 1174Expires: May 2001 [Page 21] 1175 1176C LDAP API C LDAP Application Program Interface 17 November 2000 1177 1178 1179 Type for outvalue parameter: char ** 1180 1181 Description: 1182 The matched DN value returned with the most recent LDAP error 1183 that occurred for this session. 1184 1185 1186outvalue The address of a place to put the value of the option. The 1187 actual type of this parameter depends on the setting of the 1188 option parameter. For outvalues of type char ** and LDAPCon- 1189 trol **, a copy of the data that is associated with the LDAP 1190 session ld is returned; callers should dispose of the memory by 1191 calling ldap_memfree() or ldap_controls_free(), depending on 1192 the type of data returned. 1193 1194invalue A pointer to the value the option is to be given. The actual 1195 type of this parameter depends on the setting of the option 1196 parameter. The data associated with invalue is copied by the 1197 API implementation to allow callers of the API to dispose of or 1198 otherwise change their copy of the data after a successful call 1199 to ldap_set_option(). If a value passed for invalue is invalid 1200 or cannot be accepted by the implementation, ldap_set_option() 1201 should return -1 to indicate an error. 1202 1203Both ldap_get_option() and ldap_set_option() return 0 if successful and 1204-1 if an error occurs. If -1 is returned by either function, a specific 1205result code MAY be retrieved by calling ldap_get_option() with an option 1206value of LDAP_OPT_RESULT_CODE. Note that there is no way to retrieve a 1207more specific result code if a call to ldap_get_option() with an option 1208value of LDAP_OPT_RESULT_CODE fails. 1209 1210When a call to ldap_get_option() succeeds, the API implementation MUST 1211NOT change the state of the LDAP session handle or the state of the 1212underlying implementation in a way that affects the behavior of future 1213LDAP API calls. When a call to ldap_get_option() fails, the only ses- 1214sion handle change permitted is setting the LDAP result code (as 1215returned by the LDAP_OPT_RESULT_CODE option). 1216 1217When a call to ldap_set_option() fails, it MUST NOT change the state of 1218the LDAP session handle or the state of the underlying implementation in 1219a way that affects the behavior of future LDAP API calls. 1220 1221Standards track documents that extend this specification and specify new 1222options SHOULD use values for option macros that are between 0x1000 and 12230x3FFF inclusive. Private and experimental extensions SHOULD use values 1224for the option macros that are between 0x4000 and 0x7FFF inclusive. All 1225values below 0x1000 and above 0x7FFF that are not defined in this docu- 1226ment are reserved and SHOULD NOT be used. The following macro MUST be 1227 1228 1229 1230Expires: May 2001 [Page 22] 1231 1232C LDAP API C LDAP Application Program Interface 17 November 2000 1233 1234 1235defined by C LDAP API implementations to aid extension implementors: 1236 #define LDAP_OPT_PRIVATE_EXTENSION_BASE 0x4000 /* to 0x7FFF inclusive */ 1237 1238 1239 124011.3. Working With Controls 1241 1242LDAPv3 operations can be extended through the use of controls. Controls 1243can be sent to a server or returned to the client with any LDAP message. 1244These controls are referred to as server controls. 1245 1246The LDAP API also supports a client-side extension mechanism through the 1247use of client controls. These controls affect the behavior of the LDAP 1248API only and are never sent to a server. A common data structure is 1249used to represent both types of controls: 1250 1251 typedef struct ldapcontrol { 1252 char *ldctl_oid; 1253 struct berval ldctl_value; 1254 char ldctl_iscritical; 1255 } LDAPControl; 1256 1257The fields in the ldapcontrol structure have the following meanings: 1258 1259ldctl_oid The control type, represented as a string. 1260 1261ldctl_value The data associated with the control (if any). To 1262 specify a zero-length value, set ldctl_value.bv_len to 1263 zero and ldctl_value.bv_val to a zero-length string. 1264 To indicate that no data is associated with the con- 1265 trol, set ldctl_value.bv_val to NULL. 1266 1267ldctl_iscritical Indicates whether the control is critical of not. If 1268 this field is non-zero, the operation will only be car- 1269 ried out if the control is recognized by the server 1270 and/or client. Note that the LDAP unbind and abandon 1271 operations have no server response, so clients SHOULD 1272 NOT mark server controls critical when used with these 1273 two operations. 1274 1275Some LDAP API calls allocate an ldapcontrol structure or a NULL- 1276terminated array of ldapcontrol structures. The following routines can 1277be used to dispose of a single control or an array of controls: 1278 1279 void ldap_control_free( LDAPControl *ctrl ); 1280 void ldap_controls_free( LDAPControl **ctrls ); 1281If the ctrl or ctrls parameter is NULL, these calls do nothing. 1282 1283 1284 1285 1286Expires: May 2001 [Page 23] 1287 1288C LDAP API C LDAP Application Program Interface 17 November 2000 1289 1290 1291A set of controls that affect the entire session can be set using the 1292ldap_set_option() function (see above). A list of controls can also be 1293passed directly to some LDAP API calls such as ldap_search_ext(), in 1294which case any controls set for the session through the use of 1295ldap_set_option() are ignored. Control lists are represented as a NULL- 1296terminated array of pointers to ldapcontrol structures. 1297 1298Server controls are defined by LDAPv3 protocol extension documents; for 1299example, a control has been proposed to support server-side sorting of 1300search results [11]. 1301 1302One client control is defined in this document (described in the follow- 1303ing section). Other client controls MAY be defined in future revisions 1304of this document or in documents that extend this API. 1305 1306 130711.3.1. A Client Control That Governs Referral Processing 1308 1309As described previously in the section "LDAP Session Handle Options," 1310applications can enable and disable automatic chasing of referrals on a 1311session-wide basic by using the ldap_set_option() function with the 1312LDAP_OPT_REFERRALS option. It is also useful to govern automatic refer- 1313ral chasing on per-request basis. A client control with an OID of 13141.2.840.113556.1.4.616 exists to provide this functionality. 1315 1316 /* OID for referrals client control */ 1317 #define LDAP_CONTROL_REFERRALS "1.2.840.113556.1.4.616" 1318 1319 /* Flags for referrals client control value */ 1320 #define LDAP_CHASE_SUBORDINATE_REFERRALS 0x00000020U 1321 #define LDAP_CHASE_EXTERNAL_REFERRALS 0x00000040U 1322 1323To create a referrals client control, the ldctl_oid field of an LDAPCon- 1324trol structure MUST be set to LDAP_CONTROL_REFERRALS 1325("1.2.840.113556.1.4.616") and the ldctl_value field MUST be set to a 1326value that contains a set of flags. The ldctl_value.bv_len field MUST 1327be set to sizeof(ber_uint_t), and the ldctl_value.bv_val field MUST 1328point to a ber_uint_t which contains the flags value." The ber_uint_t 1329type is define in the section "BER Data Structures and Types" below. 1330 1331The flags value can be set to zero to disable automatic chasing of 1332referrals and LDAPv3 references altogether. Alternatively, the flags 1333value can be set to the value LDAP_CHASE_SUBORDINATE_REFERRALS 1334(0x00000020U) to indicate that only LDAPv3 search continuation refer- 1335ences are to be automatically chased by the API implementation, to the 1336value LDAP_CHASE_EXTERNAL_REFERRALS (0x00000040U) to indicate that only 1337LDAPv3 referrals are to be automatically chased, or the logical OR of 1338the two flag values (0x00000060U) to indicate that both referrals and 1339 1340 1341 1342Expires: May 2001 [Page 24] 1343 1344C LDAP API C LDAP Application Program Interface 17 November 2000 1345 1346 1347references are to be automatically chased. 1348 1349 135011.4. Authenticating to the directory 1351 1352The following functions are used to authenticate an LDAP client to an 1353LDAP directory server. 1354 1355The ldap_sasl_bind() and ldap_sasl_bind_s() functions can be used to do 1356general and extensible authentication over LDAP through the use of the 1357Simple Authentication Security Layer [12]. The routines both take the 1358dn to bind as, the method to use, as a dotted-string representation of 1359an OID identifying the method, and a struct berval holding the creden- 1360tials. The special constant value LDAP_SASL_SIMPLE (NULL) can be passed 1361to request simple authentication, or the simplified routines 1362ldap_simple_bind() or ldap_simple_bind_s() can be used. 1363 1364 int ldap_sasl_bind( 1365 LDAP *ld, 1366 const char *dn, 1367 const char *mechanism, 1368 const struct berval *cred, 1369 LDAPControl **serverctrls, 1370 LDAPControl **clientctrls, 1371 int *msgidp 1372 ); 1373 1374 int ldap_sasl_bind_s( 1375 LDAP *ld, 1376 const char *dn, 1377 const char *mechanism, 1378 const struct berval *cred, 1379 LDAPControl **serverctrls, 1380 LDAPControl **clientctrls, 1381 struct berval **servercredp 1382 ); 1383 1384 int ldap_simple_bind( 1385 LDAP *ld, 1386 const char *dn, 1387 const char *passwd 1388 ); 1389 1390 int ldap_simple_bind_s( 1391 LDAP *ld, 1392 const char *dn, 1393 const char *passwd 1394 ); 1395 1396 1397 1398Expires: May 2001 [Page 25] 1399 1400C LDAP API C LDAP Application Program Interface 17 November 2000 1401 1402 1403 The use of the following routines is deprecated and more complete 1404 descriptions can be found in RFC 1823: 1405 1406 int ldap_bind( LDAP *ld, const char *dn, const char *cred, 1407 int method ); 1408 1409 int ldap_bind_s( LDAP *ld, const char *dn, const char *cred, 1410 int method ); 1411 1412 int ldap_kerberos_bind( LDAP *ld, const char *dn ); 1413 1414 int ldap_kerberos_bind_s( LDAP *ld, const char *dn ); 1415 1416Parameters are: 1417 1418ld The session handle. 1419 1420dn The name of the entry to bind as. If NULL, a zero length 1421 DN is sent to the server. 1422 1423mechanism Either LDAP_SASL_SIMPLE (NULL) to get simple authentica- 1424 tion, or a text string identifying the SASL method. 1425 1426cred The credentials with which to authenticate. Arbitrary 1427 credentials can be passed using this parameter. The format 1428 and content of the credentials depends on the setting of 1429 the mechanism parameter. If the cred parameter is NULL and 1430 the mechanism is LDAP_SASL_SIMPLE, a zero-length octet 1431 string is sent to the server in the simple credentials 1432 field of the bind request. If the cred parameter is NULL 1433 and the mechanism is anything else, no credentials are sent 1434 to the server in the bind request. 1435 1436passwd For ldap_simple_bind(), the password that is sent to the 1437 server in the simple credentials field of the bind request. 1438 If NULL, a zero length password is sent to the server. 1439 1440serverctrls List of LDAP server controls, or NULL if no server controls 1441 are used. 1442 1443clientctrls List of client controls, or NULL if no client controls are 1444 used. 1445 1446msgidp This result parameter will be set to the message id of the 1447 request if the ldap_sasl_bind() call succeeds. The value 1448 is undefined if a value other than LDAP_SUCCESS is 1449 returned. 1450 1451 1452 1453 1454Expires: May 2001 [Page 26] 1455 1456C LDAP API C LDAP Application Program Interface 17 November 2000 1457 1458 1459servercredp This result parameter will be filled in with the creden- 1460 tials passed back by the server for mutual authentication, 1461 if given. An allocated berval structure is returned that 1462 SHOULD be disposed of by calling ber_bvfree(). NULL SHOULD 1463 be passed to ignore this field. If an API error occurs or 1464 the server did not return any credentials, *servercredp is 1465 set to NULL. 1466 1467Additional parameters for the deprecated routines are not described. 1468Interested readers are referred to RFC 1823. 1469 1470The ldap_sasl_bind() function initiates an asynchronous bind operation 1471and returns the constant LDAP_SUCCESS if the request was successfully 1472sent, or another LDAP result code if not. See the section below on 1473error handling for more information about possible errors and how to 1474interpret them. If successful, ldap_sasl_bind() places the message id 1475of the request in *msgidp. A subsequent call to ldap_result(), described 1476below, can be used to obtain the result of the bind. 1477 1478The ldap_simple_bind() function initiates a simple asynchronous bind 1479operation and returns the message id of the operation initiated. A sub- 1480sequent call to ldap_result(), described below, can be used to obtain 1481the result of the bind. In case of error, ldap_simple_bind() will return 1482-1, setting the session error parameters in the LDAP structure appropri- 1483ately. 1484 1485The synchronous ldap_sasl_bind_s() and ldap_simple_bind_s() functions 1486both return the result of the operation, either the constant 1487LDAP_SUCCESS if the operation was successful, or another LDAP result 1488code if it was not. See the section below on error handling for more 1489information about possible errors and how to interpret them. 1490 1491Note that if an LDAPv2 server is contacted, no other operations over the 1492connection can be attempted before a bind call has successfully com- 1493pleted. 1494 1495Subsequent bind calls can be used to re-authenticate over the same con- 1496nection, and multistep SASL sequences can be accomplished through a 1497sequence of calls to ldap_sasl_bind() or ldap_sasl_bind_s(). 1498 1499 150011.5. Closing the session 1501 1502The following functions are used to unbind from the directory, close 1503open connections, and dispose of the session handle. 1504 1505 int ldap_unbind_ext( LDAP *ld, LDAPControl **serverctrls, 1506 LDAPControl **clientctrls ); 1507 1508 1509 1510Expires: May 2001 [Page 27] 1511 1512C LDAP API C LDAP Application Program Interface 17 November 2000 1513 1514 1515 int ldap_unbind( LDAP *ld ); 1516 1517 int ldap_unbind_s( LDAP *ld ); 1518 1519Parameters are: 1520 1521ld The session handle. 1522 1523serverctrls List of LDAP server controls, or NULL if no server controls 1524 are to be used. 1525 1526clientctrls List of client controls, or NULL if no client controls are 1527 to be used. 1528 1529The ldap_unbind_ext(), ldap_unbind() and ldap_unbind_s() all work syn- 1530chronously in the sense that they send an unbind request to the server, 1531close all open connections associated with the LDAP session handle, and 1532dispose of all resources associated with the session handle before 1533returning. Note, however, that there is no server response to an LDAP 1534unbind operation. All three of the unbind functions return LDAP_SUCCESS 1535(or another LDAP result code if the request cannot be sent to the LDAP 1536server). After a call to one of the unbind functions, the session han- 1537dle ld is invalid and it is illegal to make any further LDAP API calls 1538using ld. 1539 1540The ldap_unbind() and ldap_unbind_s() functions behave identically. The 1541ldap_unbind_ext() function allows server and client controls to be 1542included explicitly, but note that since there is no server response to 1543an unbind request there is no way to receive a response to a server con- 1544trol sent with an unbind request. 1545 1546 1547 154811.6. Searching 1549 1550The following functions are used to search the LDAP directory, returning 1551a requested set of attributes for each entry matched. There are five 1552variations. 1553 1554 int ldap_search_ext( 1555 LDAP *ld, 1556 const char *base, 1557 int scope, 1558 const char *filter, 1559 char **attrs, 1560 int attrsonly, 1561 LDAPControl **serverctrls, 1562 LDAPControl **clientctrls, 1563 1564 1565 1566Expires: May 2001 [Page 28] 1567 1568C LDAP API C LDAP Application Program Interface 17 November 2000 1569 1570 1571 struct timeval *timeout, 1572 int sizelimit, 1573 int *msgidp 1574 ); 1575 1576 int ldap_search_ext_s( 1577 LDAP *ld, 1578 const char *base, 1579 int scope, 1580 const char *filter, 1581 char **attrs, 1582 int attrsonly, 1583 LDAPControl **serverctrls, 1584 LDAPControl **clientctrls, 1585 struct timeval *timeout, 1586 int sizelimit, 1587 LDAPMessage **res 1588 ); 1589 1590 int ldap_search( 1591 LDAP *ld, 1592 const char *base, 1593 int scope, 1594 const char *filter, 1595 char **attrs, 1596 int attrsonly 1597 ); 1598 1599 int ldap_search_s( 1600 LDAP *ld, 1601 const char *base, 1602 int scope, 1603 const char *filter, 1604 char **attrs, 1605 int attrsonly, 1606 LDAPMessage **res 1607 ); 1608 1609 int ldap_search_st( 1610 LDAP *ld, 1611 const char *base, 1612 int scope, 1613 const char *filter, 1614 char **attrs, 1615 int attrsonly, 1616 struct timeval *timeout, 1617 LDAPMessage **res 1618 ); 1619 1620 1621 1622Expires: May 2001 [Page 29] 1623 1624C LDAP API C LDAP Application Program Interface 17 November 2000 1625 1626 1627Parameters are: 1628 1629ld The session handle. 1630 1631base The dn of the entry at which to start the search. If NULL, 1632 a zero length DN is sent to the server. 1633 1634scope One of LDAP_SCOPE_BASE (0x00), LDAP_SCOPE_ONELEVEL (0x01), 1635 or LDAP_SCOPE_SUBTREE (0x02), indicating the scope of the 1636 search. 1637 1638filter A character string as described in [13], representing the 1639 search filter. The value NULL can be passed to indicate 1640 that the filter "(objectclass=*)" which matches all entries 1641 is to be used. Note that if the caller of the API is using 1642 LDAPv2, only a subset of the filter functionality described 1643 in [13] can be successfully used. 1644 1645attrs A NULL-terminated array of strings indicating which attri- 1646 butes to return for each matching entry. Passing NULL for 1647 this parameter causes all available user attributes to be 1648 retrieved. The special constant string LDAP_NO_ATTRS 1649 ("1.1") MAY be used as the only string in the array to 1650 indicate that no attribute types are to be returned by the 1651 server. The special constant string LDAP_ALL_USER_ATTRS 1652 ("*") can be used in the attrs array along with the names 1653 of some operational attributes to indicate that all user 1654 attributes plus the listed operational attributes are to be 1655 returned. 1656 1657attrsonly A boolean value that MUST be zero if both attribute types 1658 and values are to be returned, and non-zero if only types 1659 are wanted. 1660 1661timeout For the ldap_search_st() function, this specifies the local 1662 search timeout value (if it is NULL, the timeout is infin- 1663 ite). If a zero timeout (where tv_sec and tv_usec are both 1664 zero) is passed, API implementations SHOULD return 1665 LDAP_PARAM_ERROR. 1666 1667 For the ldap_search_ext() and ldap_search_ext_s() func- 1668 tions, the timeout parameter specifies both the local 1669 search timeout value and the operation time limit that is 1670 sent to the server within the search request. Passing a 1671 NULL value for timeout causes the default timeout stored in 1672 the LDAP session handle (set by using ldap_set_option() 1673 with the LDAP_OPT_TIMELIMIT parameter) to be sent to the 1674 server with the request but an infinite local search 1675 1676 1677 1678Expires: May 2001 [Page 30] 1679 1680C LDAP API C LDAP Application Program Interface 17 November 2000 1681 1682 1683 timeout to be used. If a zero timeout (where tv_sec and 1684 tv_usec are both zero) is passed in, API implementations 1685 SHOULD return LDAP_PARAM_ERROR. If a zero value for tv_sec 1686 is used but tv_usec is non-zero, an operation time limit of 1687 1 SHOULD be passed to the LDAP server as the operation time 1688 limit. For other values of tv_sec, the tv_sec value itself 1689 SHOULD be passed to the LDAP server. 1690 1691sizelimit For the ldap_search_ext() and ldap_search_ext_s() calls, 1692 this is a limit on the number of entries to return from the 1693 search. A value of LDAP_NO_LIMIT (0) means no limit. A 1694 value of LDAP_DEFAULT_SIZELIMIT (-1) means use the default 1695 timeout from the LDAP session handle (which is set by cal- 1696 ling ldap_set_option() with the LDAP_OPT_SIZELIMIT parame- 1697 ter). 1698 1699res For the synchronous calls, this is a result parameter which 1700 will contain the results of the search upon completion of 1701 the call. If an API error occurs or no results are 1702 returned, *res is set to NULL. 1703 1704serverctrls List of LDAP server controls, or NULL if no server controls 1705 are to be used. 1706 1707clientctrls List of client controls, or NULL if no client controls are 1708 to be used. 1709 1710msgidp This result parameter will be set to the message id of the 1711 request if the ldap_search_ext() call succeeds. The value 1712 is undefined if a value other than LDAP_SUCCESS is 1713 returned. 1714 1715There are three options in the session handle ld which potentially 1716affect how the search is performed. They are: 1717 1718 LDAP_OPT_SIZELIMIT 1719 LDAP_OPT_TIMELIMIT 1720 LDAP_OPT_DEREF 1721 1722These options are fully described in the earlier section "LDAP Session 1723Handle Options." 1724 1725The ldap_search_ext() function initiates an asynchronous search opera- 1726tion and returns the constant LDAP_SUCCESS if the request was success- 1727fully sent, or another LDAP result code if not. See the section below 1728on error handling for more information about possible errors and how to 1729interpret them. If successful, ldap_search_ext() places the message id 1730of the request in *msgidp. A subsequent call to ldap_result(), described 1731 1732 1733 1734Expires: May 2001 [Page 31] 1735 1736C LDAP API C LDAP Application Program Interface 17 November 2000 1737 1738 1739below, can be used to obtain the results from the search. These results 1740can be parsed using the result parsing routines described in detail 1741later. 1742 1743Similar to ldap_search_ext(), the ldap_search() function initiates an 1744asynchronous search operation and returns the message id of the opera- 1745tion initiated. As for ldap_search_ext(), a subsequent call to 1746ldap_result(), described below, can be used to obtain the result of the 1747bind. In case of error, ldap_search() will return -1, setting the ses- 1748sion error parameters in the LDAP structure appropriately. 1749 1750The synchronous ldap_search_ext_s(), ldap_search_s(), and 1751ldap_search_st() functions all return the result of the operation, 1752either the constant LDAP_SUCCESS if the operation was successful, or 1753another LDAP result code if it was not. See the section below on error 1754handling for more information about possible errors and how to interpret 1755them. Entries returned from the search (if any) are contained in the 1756res parameter. This parameter is opaque to the caller. Entries, attri- 1757butes, values, etc., can be extracted by calling the parsing routines 1758described below. The results contained in res SHOULD be freed when no 1759longer in use by calling ldap_msgfree(), described later. 1760 1761The ldap_search_ext() and ldap_search_ext_s() functions support LDAPv3 1762server controls, client controls, and allow varying size and time limits 1763to be easily specified for each search operation. The ldap_search_st() 1764function is identical to ldap_search_s() except that it takes an addi- 1765tional parameter specifying a local timeout for the search. The local 1766search timeout is used to limit the amount of time the API implementa- 1767tion will wait for a search to complete. After the local search timeout 1768expires, the API implementation will send an abandon operation to abort 1769the search operation. 1770 177111.7. Reading an Entry 1772 1773LDAP does not support a read operation directly. Instead, this operation 1774is emulated by a search with base set to the DN of the entry to read, 1775scope set to LDAP_SCOPE_BASE, and filter set to "(objectclass=*)" or 1776NULL. attrs contains the list of attributes to return. 1777 1778 177911.8. Listing the Children of an Entry 1780 1781LDAP does not support a list operation directly. Instead, this operation 1782is emulated by a search with base set to the DN of the entry to list, 1783scope set to LDAP_SCOPE_ONELEVEL, and filter set to "(objectclass=*)" or 1784NULL. attrs contains the list of attributes to return for each child 1785entry. 1786 1787 1788 1789 1790Expires: May 2001 [Page 32] 1791 1792C LDAP API C LDAP Application Program Interface 17 November 2000 1793 1794 179511.9. Comparing a Value Against an Entry 1796 1797The following routines are used to compare a given attribute value 1798assertion against an LDAP entry. There are four variations: 1799 1800 int ldap_compare_ext( 1801 LDAP *ld, 1802 const char *dn, 1803 const char *attr, 1804 const struct berval *bvalue, 1805 LDAPControl **serverctrls, 1806 LDAPControl **clientctrls, 1807 int *msgidp 1808 ); 1809 1810 int ldap_compare_ext_s( 1811 LDAP *ld, 1812 const char *dn, 1813 const char *attr, 1814 const struct berval *bvalue, 1815 LDAPControl **serverctrls, 1816 LDAPControl **clientctrls 1817 ); 1818 1819 int ldap_compare( 1820 LDAP *ld, 1821 const char *dn, 1822 const char *attr, 1823 const char *value 1824 ); 1825 1826 int ldap_compare_s( 1827 LDAP *ld, 1828 const char *dn, 1829 const char *attr, 1830 const char *value 1831 ); 1832 1833Parameters are: 1834 1835ld The session handle. 1836 1837dn The name of the entry to compare against. If NULL, a zero 1838 length DN is sent to the server. 1839 1840attr The attribute to compare against. 1841 1842bvalue The attribute value to compare against those found in the 1843 1844 1845 1846Expires: May 2001 [Page 33] 1847 1848C LDAP API C LDAP Application Program Interface 17 November 2000 1849 1850 1851 given entry. This parameter is used in the extended rou- 1852 tines and is a pointer to a struct berval so it is possible 1853 to compare binary values. 1854 1855value A string attribute value to compare against, used by the 1856 ldap_compare() and ldap_compare_s() functions. Use 1857 ldap_compare_ext() or ldap_compare_ext_s() if you need to 1858 compare binary values. 1859 1860serverctrls List of LDAP server controls, or NULL if no server controls 1861 are to be used. 1862 1863clientctrls List of client controls, or NULL if no client controls are 1864 to be used. 1865 1866msgidp This result parameter will be set to the message id of the 1867 request if the ldap_compare_ext() call succeeds. The value 1868 is undefined if a value other than LDAP_SUCCESS is 1869 returned. 1870 1871The ldap_compare_ext() function initiates an asynchronous compare opera- 1872tion and returns the constant LDAP_SUCCESS if the request was success- 1873fully sent, or another LDAP result code if not. See the section below 1874on error handling for more information about possible errors and how to 1875interpret them. If successful, ldap_compare_ext() places the message id 1876of the request in *msgidp. A subsequent call to ldap_result(), described 1877below, can be used to obtain the result of the compare. 1878 1879Similar to ldap_compare_ext(), the ldap_compare() function initiates an 1880asynchronous compare operation and returns the message id of the opera- 1881tion initiated. As for ldap_compare_ext(), a subsequent call to 1882ldap_result(), described below, can be used to obtain the result of the 1883bind. In case of error, ldap_compare() will return -1, setting the ses- 1884sion error parameters in the LDAP structure appropriately. 1885 1886The synchronous ldap_compare_ext_s() and ldap_compare_s() functions both 1887return the result of the operation: one of the constants 1888LDAP_COMPARE_TRUE or LDAP_COMPARE_FALSE if the operation was successful, 1889or another LDAP result code if it was not. See the section below on 1890error handling for more information about possible errors and how to 1891interpret them. 1892 1893The ldap_compare_ext() and ldap_compare_ext_s() functions support LDAPv3 1894server controls and client controls. 1895 1896 1897 1898 1899 1900 1901 1902Expires: May 2001 [Page 34] 1903 1904C LDAP API C LDAP Application Program Interface 17 November 2000 1905 1906 190711.10. Modifying an entry 1908 1909The following routines are used to modify an existing LDAP entry. There 1910are four variations: 1911 1912 typedef union mod_vals_u { 1913 char **modv_strvals; 1914 struct berval **modv_bvals; 1915 } mod_vals_u_t; 1916 1917 typedef struct ldapmod { 1918 int mod_op; 1919 char *mod_type; 1920 mod_vals_u_t mod_vals; 1921 } LDAPMod; 1922 #define mod_values mod_vals.modv_strvals 1923 #define mod_bvalues mod_vals.modv_bvals 1924 1925 int ldap_modify_ext( 1926 LDAP *ld, 1927 const char *dn, 1928 LDAPMod **mods, 1929 LDAPControl **serverctrls, 1930 LDAPControl **clientctrls, 1931 int *msgidp 1932 ); 1933 1934 int ldap_modify_ext_s( 1935 LDAP *ld, 1936 const char *dn, 1937 LDAPMod **mods, 1938 LDAPControl **serverctrls, 1939 LDAPControl **clientctrls 1940 ); 1941 1942 int ldap_modify( 1943 LDAP *ld, 1944 const char *dn, 1945 LDAPMod **mods 1946 ); 1947 1948 int ldap_modify_s( 1949 LDAP *ld, 1950 const char *dn, 1951 LDAPMod **mods 1952 ); 1953 1954Parameters are: 1955 1956 1957 1958Expires: May 2001 [Page 35] 1959 1960C LDAP API C LDAP Application Program Interface 17 November 2000 1961 1962 1963ld The session handle. 1964 1965dn The name of the entry to modify. If NULL, a zero length DN 1966 is sent to the server. 1967 1968mods A NULL-terminated array of modifications to make to the 1969 entry. 1970 1971serverctrls List of LDAP server controls, or NULL if no server controls 1972 are to be used. 1973 1974clientctrls List of client controls, or NULL if no client controls are 1975 to be used. 1976 1977msgidp This result parameter will be set to the message id of the 1978 request if the ldap_modify_ext() call succeeds. The value 1979 is undefined if a value other than LDAP_SUCCESS is 1980 returned. 1981 1982The fields in the LDAPMod structure have the following meanings: 1983 1984mod_op The modification operation to perform. It MUST be one of 1985 LDAP_MOD_ADD (0x00), LDAP_MOD_DELETE (0x01), or 1986 LDAP_MOD_REPLACE (0x02). This field also indicates the 1987 type of values included in the mod_vals union. It is logi- 1988 cally ORed with LDAP_MOD_BVALUES (0x80) to select the 1989 mod_bvalues form. Otherwise, the mod_values form is used. 1990 1991mod_type The type of the attribute to modify. 1992 1993mod_vals The values (if any) to add, delete, or replace. Only one of 1994 the mod_values or mod_bvalues variants can be used, 1995 selected by ORing the mod_op field with the constant 1996 LDAP_MOD_BVALUES. mod_values is a NULL-terminated array of 1997 zero-terminated strings and mod_bvalues is a NULL- 1998 terminated array of berval structures that can be used to 1999 pass binary values such as images. 2000 2001For LDAP_MOD_ADD modifications, the given values are added to the 2002entry, creating the attribute if necessary. 2003 2004For LDAP_MOD_DELETE modifications, the given values are deleted from the 2005entry, removing the attribute if no values remain. If the entire attri- 2006bute is to be deleted, the mod_vals field can be set to NULL. 2007 2008For LDAP_MOD_REPLACE modifications, the attribute will have the listed 2009values after the modification, having been created if necessary, or 2010removed if the mod_vals field is NULL. All modifications are performed 2011 2012 2013 2014Expires: May 2001 [Page 36] 2015 2016C LDAP API C LDAP Application Program Interface 17 November 2000 2017 2018 2019in the order in which they are listed. 2020 2021The ldap_modify_ext() function initiates an asynchronous modify opera- 2022tion and returns the constant LDAP_SUCCESS if the request was success- 2023fully sent, or another LDAP result code if not. See the section below 2024on error handling for more information about possible errors and how to 2025interpret them. If successful, ldap_modify_ext() places the message id 2026of the request in *msgidp. A subsequent call to ldap_result(), described 2027below, can be used to obtain the result of the modify. 2028 2029Similar to ldap_modify_ext(), the ldap_modify() function initiates an 2030asynchronous modify operation and returns the message id of the opera- 2031tion initiated. As for ldap_modify_ext(), a subsequent call to 2032ldap_result(), described below, can be used to obtain the result of the 2033modify. In case of error, ldap_modify() will return -1, setting the ses- 2034sion error parameters in the LDAP structure appropriately. 2035 2036The synchronous ldap_modify_ext_s() and ldap_modify_s() functions both 2037return the result of the operation, either the constant LDAP_SUCCESS if 2038the operation was successful, or another LDAP result code if it was not. 2039See the section below on error handling for more information about pos- 2040sible errors and how to interpret them. 2041 2042The ldap_modify_ext() and ldap_modify_ext_s() functions support LDAPv3 2043server controls and client controls. 2044 2045 204611.11. Modifying the Name of an Entry 2047 2048In LDAPv2, the ldap_modrdn(), ldap_modrdn_s(), ldap_modrdn2(), and 2049ldap_modrdn2_s() routines were used to change the name of an LDAP entry. 2050They could only be used to change the least significant component of a 2051name (the RDN or relative distinguished name). LDAPv3 provides the 2052Modify DN protocol operation that allows more general name change 2053access. The ldap_rename() and ldap_rename_s() routines are used to 2054change the name of an entry, and the use of the ldap_modrdn(), 2055ldap_modrdn_s(), ldap_modrdn2(), and ldap_modrdn2_s() routines is depre- 2056cated. 2057 2058 int ldap_rename( 2059 LDAP *ld, 2060 const char *dn, 2061 const char *newrdn, 2062 const char *newparent, 2063 int deleteoldrdn, 2064 LDAPControl **serverctrls, 2065 LDAPControl **clientctrls, 2066 int *msgidp 2067 2068 2069 2070Expires: May 2001 [Page 37] 2071 2072C LDAP API C LDAP Application Program Interface 17 November 2000 2073 2074 2075 ); 2076 int ldap_rename_s( 2077 LDAP *ld, 2078 const char *dn, 2079 const char *newrdn, 2080 const char *newparent, 2081 int deleteoldrdn, 2082 LDAPControl **serverctrls, 2083 LDAPControl **clientctrls 2084 ); 2085 2086 The use of the following routines is deprecated and more complete 2087 descriptions can be found in RFC 1823: 2088 2089 int ldap_modrdn( 2090 LDAP *ld, 2091 const char *dn, 2092 const char *newrdn 2093 ); 2094 int ldap_modrdn_s( 2095 LDAP *ld, 2096 const char *dn, 2097 const char *newrdn 2098 ); 2099 int ldap_modrdn2( 2100 LDAP *ld, 2101 const char *dn, 2102 const char *newrdn, 2103 int deleteoldrdn 2104 ); 2105 int ldap_modrdn2_s( 2106 LDAP *ld, 2107 const char *dn, 2108 const char *newrdn, 2109 int deleteoldrdn 2110 ); 2111 2112Parameters are: 2113 2114ld The session handle. 2115 2116dn The name of the entry whose DN is to be changed. If NULL, 2117 a zero length DN is sent to the server. 2118 2119newrdn The new RDN to give the entry. 2120 2121newparent The new parent, or superior entry. If this parameter is 2122 NULL, only the RDN of the entry is changed. The root DN 2123 2124 2125 2126Expires: May 2001 [Page 38] 2127 2128C LDAP API C LDAP Application Program Interface 17 November 2000 2129 2130 2131 SHOULD be specified by passing a zero length string, "". 2132 The newparent parameter SHOULD always be NULL when using 2133 version 2 of the LDAP protocol; otherwise the server's 2134 behavior is undefined. 2135 2136deleteoldrdn This parameter only has meaning on the rename routines if 2137 newrdn is different than the old RDN. It is a boolean 2138 value, if non-zero indicating that the old RDN value(s) is 2139 to be removed, if zero indicating that the old RDN value(s) 2140 is to be retained as non-distinguished values of the entry. 2141 2142serverctrls List of LDAP server controls, or NULL if no server controls 2143 are to be used. 2144 2145clientctrls List of client controls, or NULL if no client controls are 2146 to be used. 2147 2148msgidp This result parameter will be set to the message id of the 2149 request if the ldap_rename() call succeeds. The value is 2150 undefined if a value other than LDAP_SUCCESS is returned. 2151 2152The ldap_rename() function initiates an asynchronous modify DN operation 2153and returns the constant LDAP_SUCCESS if the request was successfully 2154sent, or another LDAP result code if not. See the section below on 2155error handling for more information about possible errors and how to 2156interpret them. If successful, ldap_rename() places the DN message id 2157of the request in *msgidp. A subsequent call to ldap_result(), described 2158below, can be used to obtain the result of the rename. 2159 2160The synchronous ldap_rename_s() returns the result of the operation, 2161either the constant LDAP_SUCCESS if the operation was successful, or 2162another LDAP result code if it was not. See the section below on error 2163handling for more information about possible errors and how to interpret 2164them. 2165 2166The ldap_rename() and ldap_rename_s() functions both support LDAPv3 2167server controls and client controls. 2168 2169 217011.12. Adding an entry 2171 2172The following functions are used to add entries to the LDAP directory. 2173There are four variations: 2174 2175 int ldap_add_ext( 2176 LDAP *ld, 2177 const char *dn, 2178 LDAPMod **attrs, 2179 2180 2181 2182Expires: May 2001 [Page 39] 2183 2184C LDAP API C LDAP Application Program Interface 17 November 2000 2185 2186 2187 LDAPControl **serverctrls, 2188 LDAPControl **clientctrls, 2189 int *msgidp 2190 ); 2191 2192 int ldap_add_ext_s( 2193 LDAP *ld, 2194 const char *dn, 2195 LDAPMod **attrs, 2196 LDAPControl **serverctrls, 2197 LDAPControl **clientctrls 2198 ); 2199 2200 int ldap_add( 2201 LDAP *ld, 2202 const char *dn, 2203 LDAPMod **attrs 2204 ); 2205 2206 int ldap_add_s( 2207 LDAP *ld, 2208 const char *dn, 2209 LDAPMod **attrs 2210 ); 2211 2212Parameters are: 2213 2214ld The session handle. 2215 2216dn The name of the entry to add. If NULL, a zero length DN is 2217 sent to the server. 2218 2219attrs The entry's attributes, specified using the LDAPMod struc- 2220 ture defined for ldap_modify(). The mod_type and mod_vals 2221 fields MUST be filled in. The mod_op field is ignored 2222 unless ORed with the constant LDAP_MOD_BVALUES, used to 2223 select the mod_bvalues case of the mod_vals union. 2224 2225serverctrls List of LDAP server controls, or NULL if no server controls 2226 are to be used. 2227 2228clientctrls List of client controls, or NULL if no client controls are 2229 to be used. 2230 2231msgidp This result parameter will be set to the message id of the 2232 request if the ldap_add_ext() call succeeds. The value is 2233 undefined if a value other than LDAP_SUCCESS is returned. 2234 2235 2236 2237 2238Expires: May 2001 [Page 40] 2239 2240C LDAP API C LDAP Application Program Interface 17 November 2000 2241 2242 2243Note that the parent of the entry being added must already exist or the 2244parent must be empty (i.e., equal to the root DN) for an add to succeed. 2245 2246The ldap_add_ext() function initiates an asynchronous add operation and 2247returns the constant LDAP_SUCCESS if the request was successfully sent, 2248or another LDAP result code if not. See the section below on error han- 2249dling for more information about possible errors and how to interpret 2250them. If successful, ldap_add_ext() places the message id of the 2251request in *msgidp. A subsequent call to ldap_result(), described below, 2252can be used to obtain the result of the add. 2253 2254Similar to ldap_add_ext(), the ldap_add() function initiates an asyn- 2255chronous add operation and returns the message id of the operation ini- 2256tiated. As for ldap_add_ext(), a subsequent call to ldap_result(), 2257described below, can be used to obtain the result of the add. In case of 2258error, ldap_add() will return -1, setting the session error parameters 2259in the LDAP structure appropriately. 2260 2261The synchronous ldap_add_ext_s() and ldap_add_s() functions both return 2262the result of the operation, either the constant LDAP_SUCCESS if the 2263operation was successful, or another LDAP result code if it was not. 2264See the section below on error handling for more information about pos- 2265sible errors and how to interpret them. 2266 2267The ldap_add_ext() and ldap_add_ext_s() functions support LDAPv3 server 2268controls and client controls. 2269 2270 2271 227211.13. Deleting an entry 2273 2274The following functions are used to delete a leaf entry from the LDAP 2275directory. There are four variations: 2276 2277 int ldap_delete_ext( 2278 LDAP *ld, 2279 const char *dn, 2280 LDAPControl **serverctrls, 2281 LDAPControl **clientctrls, 2282 int *msgidp 2283 ); 2284 2285 int ldap_delete_ext_s( 2286 LDAP *ld, 2287 const char *dn, 2288 LDAPControl **serverctrls, 2289 LDAPControl **clientctrls 2290 ); 2291 2292 2293 2294Expires: May 2001 [Page 41] 2295 2296C LDAP API C LDAP Application Program Interface 17 November 2000 2297 2298 2299 2300 int ldap_delete( 2301 LDAP *ld, 2302 const char *dn 2303 ); 2304 2305 int ldap_delete_s( 2306 LDAP *ld, 2307 const char *dn 2308 ); 2309 2310Parameters are: 2311 2312ld The session handle. 2313 2314dn The name of the entry to delete. If NULL, a zero length DN 2315 is sent to the server. 2316 2317serverctrls List of LDAP server controls, or NULL if no server controls 2318 are to be used. 2319 2320clientctrls List of client controls, or NULL if no client controls are 2321 to be used. 2322 2323msgidp This result parameter will be set to the message id of the 2324 request if the ldap_delete_ext() call succeeds. The value 2325 is undefined if a value other than LDAP_SUCCESS is 2326 returned. 2327 2328Note that the entry to delete must be a leaf entry (i.e., it must have 2329no children). Deletion of entire subtrees in a single operation is not 2330supported by LDAP. 2331 2332The ldap_delete_ext() function initiates an asynchronous delete opera- 2333tion and returns the constant LDAP_SUCCESS if the request was success- 2334fully sent, or another LDAP result code if not. See the section below 2335on error handling for more information about possible errors and how to 2336interpret them. If successful, ldap_delete_ext() places the message id 2337of the request in *msgidp. A subsequent call to ldap_result(), described 2338below, can be used to obtain the result of the delete. 2339 2340Similar to ldap_delete_ext(), the ldap_delete() function initiates an 2341asynchronous delete operation and returns the message id of the opera- 2342tion initiated. As for ldap_delete_ext(), a subsequent call to 2343ldap_result(), described below, can be used to obtain the result of the 2344delete. In case of error, ldap_delete() will return -1, setting the ses- 2345sion error parameters in the LDAP structure appropriately. 2346 2347 2348 2349 2350Expires: May 2001 [Page 42] 2351 2352C LDAP API C LDAP Application Program Interface 17 November 2000 2353 2354 2355The synchronous ldap_delete_ext_s() and ldap_delete_s() functions both 2356return the result of the operation, either the constant LDAP_SUCCESS if 2357the operation was successful, or another LDAP result code if it was not. 2358See the section below on error handling for more information about pos- 2359sible errors and how to interpret them. 2360 2361The ldap_delete_ext() and ldap_delete_ext_s() functions support LDAPv3 2362server controls and client controls. 2363 2364 236511.14. Extended Operations 2366 2367The ldap_extended_operation() and ldap_extended_operation_s() routines 2368allow extended LDAP operations to be passed to the server, providing a 2369general protocol extensibility mechanism. 2370 2371 int ldap_extended_operation( 2372 LDAP *ld, 2373 const char *requestoid, 2374 const struct berval *requestdata, 2375 LDAPControl **serverctrls, 2376 LDAPControl **clientctrls, 2377 int *msgidp 2378 ); 2379 2380 int ldap_extended_operation_s( 2381 LDAP *ld, 2382 const char *requestoid, 2383 const struct berval *requestdata, 2384 LDAPControl **serverctrls, 2385 LDAPControl **clientctrls, 2386 char **retoidp, 2387 struct berval **retdatap 2388 ); 2389 2390Parameters are: 2391 2392ld The session handle. 2393 2394requestoid The dotted-OID text string naming the request. 2395 2396requestdata The arbitrary data needed by the operation (if NULL, no 2397 data is sent to the server). 2398 2399serverctrls List of LDAP server controls, or NULL if no server controls 2400 are to be used. 2401 2402clientctrls List of client controls, or NULL if no client controls are 2403 2404 2405 2406Expires: May 2001 [Page 43] 2407 2408C LDAP API C LDAP Application Program Interface 17 November 2000 2409 2410 2411 to be used. 2412 2413msgidp This result parameter will be set to the message id of the 2414 request if the ldap_extended_operation() call succeeds. The 2415 value is undefined if a value other than LDAP_SUCCESS is 2416 returned. 2417 2418retoidp Pointer to a character string that will be set to an allo- 2419 cated, dotted-OID text string returned by the server. This 2420 string SHOULD be disposed of using the ldap_memfree() func- 2421 tion. If an API error occurs or no OID is returned by the 2422 server, *retoidp is set to NULL. 2423 2424retdatap Pointer to a berval structure pointer that will be set an 2425 allocated copy of the data returned by the server. This 2426 struct berval SHOULD be disposed of using ber_bvfree(). If 2427 an API error occurs or no data is returned by the server, 2428 *retdatap is set to NULL. 2429 2430The ldap_extended_operation() function initiates an asynchronous 2431extended operation and returns the constant LDAP_SUCCESS if the request 2432was successfully sent, or another LDAP result code if not. See the sec- 2433tion below on error handling for more information about possible errors 2434and how to interpret them. If successful, ldap_extended_operation() 2435places the message id of the request in *msgidp. A subsequent call to 2436ldap_result(), described below, can be used to obtain the result of the 2437extended operation which can be passed to ldap_parse_extended_result() 2438to obtain the OID and data contained in the response. 2439 2440The synchronous ldap_extended_operation_s() function returns the result 2441of the operation, either the constant LDAP_SUCCESS if the operation was 2442successful, or another LDAP result code if it was not. See the section 2443below on error handling for more information about possible errors and 2444how to interpret them. The retoid and retdata parameters are filled in 2445with the OID and data from the response. 2446 2447The ldap_extended_operation() and ldap_extended_operation_s() functions 2448both support LDAPv3 server controls and client controls. 2449 2450 245112. Abandoning An Operation 2452 2453The following calls are used to abandon an operation in progress: 2454 2455 int ldap_abandon_ext( 2456 LDAP *ld, 2457 int msgid, 2458 LDAPControl **serverctrls, 2459 2460 2461 2462Expires: May 2001 [Page 44] 2463 2464C LDAP API C LDAP Application Program Interface 17 November 2000 2465 2466 2467 LDAPControl **clientctrls 2468 ); 2469 2470 int ldap_abandon( 2471 LDAP *ld, 2472 int msgid 2473 ); 2474 2475 2476ld The session handle. 2477 2478msgid The message id of the request to be abandoned. 2479 2480serverctrls List of LDAP server controls, or NULL if no server controls 2481 are to be used. 2482 2483clientctrls List of client controls, or NULL if no client controls are 2484 to be used. 2485 2486ldap_abandon_ext() abandons the operation with message id msgid and 2487returns the constant LDAP_SUCCESS if the abandon was successful or 2488another LDAP result code if not. See the section below on error han- 2489dling for more information about possible errors and how to interpret 2490them. 2491 2492ldap_abandon() is identical to ldap_abandon_ext() except that it does 2493not accept client or server controls and it returns zero if the abandon 2494was successful, -1 otherwise. 2495 2496After a successful call to ldap_abandon() or ldap_abandon_ext(), results 2497with the given message id are never returned from a subsequent call to 2498ldap_result(). There is no server response to LDAP abandon operations. 2499 2500 250113. Obtaining Results and Peeking Inside LDAP Messages 2502 2503ldap_result() is used to obtain the result of a previous asynchronously 2504initiated operation. Note that depending on how it is called, 2505ldap_result() can actually return a list or "chain" of result messages. 2506The ldap_result() function only returns messages for a single request, 2507so for all LDAP operations other than search only one result message is 2508expected; that is, the only time the "result chain" can contain more 2509than one message is if results from a search operation are returned. 2510Once a chain of messages has been returned to the caller, it is no 2511longer tied in any caller-visible way to the LDAP request that produced 2512it. However, it MAY be tied to the session handle. Therefore, a chain 2513of messages returned by calling ldap_result() or by calling a synchro- 2514nous search routine will never be affected by subsequent LDAP API calls 2515 2516 2517 2518Expires: May 2001 [Page 45] 2519 2520C LDAP API C LDAP Application Program Interface 17 November 2000 2521 2522 2523except for ldap_msgfree() (which is used to dispose of a chain of mes- 2524sages) and the unbind calls (which dispose of a session handle): 2525ldap_unbind(), ldap_unbind_s(), or ldap_unbind_ext(), or functions 2526defined by extensions of this API. 2527 2528ldap_msgfree() frees the result messages (possibly an entire chain of 2529messages) obtained from a previous call to ldap_result() or from a call 2530to a synchronous search routine. 2531 2532ldap_msgtype() returns the type of an LDAP message. 2533 2534ldap_msgid() returns the message ID of an LDAP message. 2535 2536 int ldap_result( 2537 LDAP *ld, 2538 int msgid, 2539 int all, 2540 struct timeval *timeout, 2541 LDAPMessage **res 2542 ); 2543 2544 int ldap_msgfree( LDAPMessage *res ); 2545 2546 int ldap_msgtype( LDAPMessage *res ); 2547 2548 int ldap_msgid( LDAPMessage *res ); 2549 2550Parameters are: 2551 2552ld The session handle. 2553 2554msgid The message id of the operation whose results are to be 2555 returned, the constant LDAP_RES_UNSOLICITED (0) if an unsoli- 2556 cited result is desired, or or the constant LDAP_RES_ANY (-1) 2557 if any result is desired. 2558 2559all Specifies how many messages will be retrieved in a single call 2560 to ldap_result(). This parameter only has meaning for search 2561 results. Pass the constant LDAP_MSG_ONE (0x00) to retrieve one 2562 message at a time. Pass LDAP_MSG_ALL (0x01) to request that 2563 all results of a search be received before returning all 2564 results in a single chain. Pass LDAP_MSG_RECEIVED (0x02) to 2565 indicate that all messages retrieved so far are to be returned 2566 in the result chain. 2567 2568timeout A timeout specifying how long to wait for results to be 2569 returned. A NULL value causes ldap_result() to block until 2570 results are available. A timeout value of zero seconds 2571 2572 2573 2574Expires: May 2001 [Page 46] 2575 2576C LDAP API C LDAP Application Program Interface 17 November 2000 2577 2578 2579 specifies a polling behavior. 2580 2581res For ldap_result(), a result parameter that will contain the 2582 result(s) of the operation. If an API error occurs or no 2583 results are returned, *res is set to NULL. For ldap_msgfree(), 2584 the result chain to be freed, obtained from a previous call to 2585 ldap_result(), ldap_search_s(), or ldap_search_st(). If res is 2586 NULL, nothing is done and ldap_msgfree() returns zero. 2587 2588Upon successful completion, ldap_result() returns the type of the first 2589result returned in the res parameter. This will be one of the following 2590constants. 2591 2592 LDAP_RES_BIND (0x61) 2593 LDAP_RES_SEARCH_ENTRY (0x64) 2594 LDAP_RES_SEARCH_REFERENCE (0x73) -- new in LDAPv3 2595 LDAP_RES_SEARCH_RESULT (0x65) 2596 LDAP_RES_MODIFY (0x67) 2597 LDAP_RES_ADD (0x69) 2598 LDAP_RES_DELETE (0x6B) 2599 LDAP_RES_MODDN (0x6D) 2600 LDAP_RES_COMPARE (0x6F) 2601 LDAP_RES_EXTENDED (0x78) -- new in LDAPv3 2602 2603ldap_result() returns 0 if the timeout expired and -1 if an error 2604occurs, in which case the error parameters of the LDAP session handle 2605will be set accordingly. 2606 2607ldap_msgfree() frees each message in the result chain pointed to by res 2608and returns the type of the last message in the chain. If res is NULL, 2609nothing is done and the value zero is returned. 2610 2611ldap_msgtype() returns the type of the LDAP message it is passed as a 2612parameter. The type will be one of the types listed above, or -1 on 2613error. 2614 2615ldap_msgid() returns the message ID associated with the LDAP message 2616passed as a parameter, or -1 on error. 2617 2618 261914. Handling Errors and Parsing Results 2620 2621The following calls are used to extract information from results and 2622handle errors returned by other LDAP API routines. Note that 2623ldap_parse_sasl_bind_result() and ldap_parse_extended_result() must typ- 2624ically be used in addition to ldap_parse_result() to retrieve all the 2625result information from SASL Bind and Extended Operations respectively. 2626 2627 2628 2629 2630Expires: May 2001 [Page 47] 2631 2632C LDAP API C LDAP Application Program Interface 17 November 2000 2633 2634 2635 int ldap_parse_result( 2636 LDAP *ld, 2637 LDAPMessage *res, 2638 int *errcodep, 2639 char **matcheddnp, 2640 char **errmsgp, 2641 char ***referralsp, 2642 LDAPControl ***serverctrlsp, 2643 int freeit 2644 ); 2645 2646 int ldap_parse_sasl_bind_result( 2647 LDAP *ld, 2648 LDAPMessage *res, 2649 struct berval **servercredp, 2650 int freeit 2651 ); 2652 2653 int ldap_parse_extended_result( 2654 LDAP *ld, 2655 LDAPMessage *res, 2656 char **retoidp, 2657 struct berval **retdatap, 2658 int freeit 2659 ); 2660 2661 #define LDAP_NOTICE_OF_DISCONNECTION "1.3.6.1.4.1.1466.20036" 2662 2663 char *ldap_err2string( int err ); 2664 2665 The use of the following routines is deprecated and more complete 2666 descriptions can be found in RFC 1823: 2667 2668 int ldap_result2error( 2669 LDAP *ld, 2670 LDAPMessage *res, 2671 int freeit 2672 ); 2673 2674 void ldap_perror( LDAP *ld, const char *msg ); 2675 2676Parameters are: 2677 2678ld The session handle. 2679 2680res The result of an LDAP operation as returned by 2681 ldap_result() or one of the synchronous API operation 2682 calls. 2683 2684 2685 2686Expires: May 2001 [Page 48] 2687 2688C LDAP API C LDAP Application Program Interface 17 November 2000 2689 2690 2691errcodep This result parameter will be filled in with the LDAP 2692 resultCode field from the LDAPMessage message. This is the 2693 indication from the server of the outcome of the operation. 2694 NULL SHOULD be passed to ignore this field. 2695 2696matcheddnp If the server returned a matchedDN string to indicate how 2697 much of a name passed in a request was recognized, this 2698 result parameter will be filled in with that matchedDN 2699 string. Otherwise, this field will be set to NULL. NULL 2700 SHOULD be passed to ignore this field. The matched DN 2701 string SHOULD be freed by calling ldap_memfree() which is 2702 described later in this document. Note that the server may 2703 return a zero length matchedDN (in which case *matchednp is 2704 set to an allocated copy of "") which is different than not 2705 returning a value at all (in which case *matcheddnp is set 2706 to NULL). 2707 2708errmsgp This result parameter will be filled in with the contents 2709 of the error message field from the LDAPMessage message. 2710 The error message string SHOULD be freed by calling 2711 ldap_memfree() which is described later in this document. 2712 NULL SHOULD be passed to ignore this field. 2713 2714referralsp This result parameter will be filled in with the contents 2715 of the referrals field from the LDAPMessage message, indi- 2716 cating zero or more alternate LDAP servers where the 2717 request is to be retried. The referrals array SHOULD be 2718 freed by calling ldap_value_free() which is described later 2719 in this document. NULL SHOULD be passed to ignore this 2720 field. If no referrals were returned, *referralsp is set 2721 to NULL. 2722 2723serverctrlsp This result parameter will be filled in with an allocated 2724 array of controls copied out of the LDAPMessage message. 2725 If serverctrlsp is NULL, no controls are returned. The 2726 control array SHOULD be freed by calling 2727 ldap_controls_free() which was described earlier. If no 2728 controls were returned, *serverctrlsp is set to NULL. 2729 2730freeit A boolean that determines whether the res parameter is 2731 disposed of or not. Pass any non-zero value to have these 2732 routines free res after extracting the requested informa- 2733 tion. This is provided as a convenience; you can also use 2734 ldap_msgfree() to free the result later. If freeit is 2735 non-zero, the entire chain of messages represented by res 2736 is disposed of. 2737 2738servercredp For SASL bind results, this result parameter will be filled 2739 2740 2741 2742Expires: May 2001 [Page 49] 2743 2744C LDAP API C LDAP Application Program Interface 17 November 2000 2745 2746 2747 in with the credentials passed back by the server for 2748 mutual authentication, if given. An allocated berval struc- 2749 ture is returned that SHOULD be disposed of by calling 2750 ber_bvfree(). NULL SHOULD be passed to ignore this field. 2751 2752retoidp For extended results, this result parameter will be filled 2753 in with the dotted-OID text representation of the name of 2754 the extended operation response. This string SHOULD be 2755 disposed of by calling ldap_memfree(). NULL SHOULD be 2756 passed to ignore this field. If no OID was returned, 2757 *retoidp is set to NULL. The LDAP_NOTICE_OF_DISCONNECTION 2758 macro is defined as a convenience for clients that wish to 2759 check an OID to see if it matches the one used for the 2760 unsolicited Notice of Disconnection (defined in RFC 2251[2] 2761 section 4.4.1). 2762 2763retdatap For extended results, this result parameter will be filled 2764 in with a pointer to a struct berval containing the data in 2765 the extended operation response. It SHOULD be disposed of 2766 by calling ber_bvfree(). NULL SHOULD be passed to ignore 2767 this field. If no data is returned, *retdatap is set to 2768 NULL. 2769 2770err For ldap_err2string(), an LDAP result code, as returned by 2771 ldap_parse_result() or another LDAP API call. 2772 2773Additional parameters for the deprecated routines are not described. 2774Interested readers are referred to RFC 1823. 2775 2776The ldap_parse_result(), ldap_parse_sasl_bind_result(), and 2777ldap_parse_extended_result() functions all skip over messages of type 2778LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_REFERENCE when looking for a 2779result message to parse. They return the constant LDAP_SUCCESS if the 2780result was successfully parsed and another LDAP API result code if not. 2781If a value other than LDAP_SUCCESS is returned, the values of all the 2782result parameters are undefined. Note that the LDAP result code that 2783indicates the outcome of the operation performed by the server is placed 2784in the errcodep ldap_parse_result() parameter. If a chain of messages 2785that contains more than one result message is passed to these routines 2786they always operate on the first result in the chain. 2787 2788ldap_err2string() is used to convert a numeric LDAP result code, as 2789returned by ldap_parse_result(), ldap_parse_sasl_bind_result(), 2790ldap_parse_extended_result() or one of the synchronous API operation 2791calls, into an informative zero-terminated character string message 2792describing the error. It returns a pointer to static data and it MUST 2793NOT return NULL; the value returned is always a valid null-terminated 2794"C" string. 2795 2796 2797 2798Expires: May 2001 [Page 50] 2799 2800C LDAP API C LDAP Application Program Interface 17 November 2000 2801 2802 280315. Stepping Through a List of Results 2804 2805The ldap_first_message() and ldap_next_message() routines are used to 2806step through the list of messages in a result chain returned by 2807ldap_result(). For search operations, the result chain can actually 2808include referral messages, entry messages, and result messages. 2809ldap_count_messages() is used to count the number of messages returned. 2810The ldap_msgtype() function, described above, can be used to distinguish 2811between the different message types. 2812 2813 LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *res ); 2814 2815 LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *msg ); 2816 2817 int ldap_count_messages( LDAP *ld, LDAPMessage *res ); 2818 2819Parameters are: 2820 2821ld The session handle. 2822 2823res The result chain, as obtained by a call to one of the synchronous 2824 search routines or ldap_result(). 2825 2826msg The message returned by a previous call to ldap_first_message() 2827 or ldap_next_message(). 2828 2829ldap_first_message() and ldap_next_message() will return NULL when no 2830more messages exist in the result set to be returned. NULL is also 2831returned if an error occurs while stepping through the entries, in which 2832case the error parameters in the session handle ld will be set to indi- 2833cate the error. 2834 2835If successful, ldap_count_messages() returns the number of messages con- 2836tained in a chain of results; if an error occurs such as the res parame- 2837ter being invalid, -1 is returned. The ldap_count_messages() call can 2838also be used to count the number of messages that remain in a chain if 2839called with a message, entry, or reference returned by 2840ldap_first_message(), ldap_next_message(), ldap_first_entry(), 2841ldap_next_entry(), ldap_first_reference(), ldap_next_reference(). 2842 2843 284416. Parsing Search Results 2845 2846The following calls are used to parse the entries and references 2847returned by ldap_search() and friends. These results are returned in an 2848opaque structure that MAY be accessed by calling the routines described 2849below. Routines are provided to step through the entries and references 2850returned, step through the attributes of an entry, retrieve the name of 2851 2852 2853 2854Expires: May 2001 [Page 51] 2855 2856C LDAP API C LDAP Application Program Interface 17 November 2000 2857 2858 2859an entry, and retrieve the values associated with a given attribute in 2860an entry. 2861 2862 286316.1. Stepping Through a List of Entries or References 2864 2865The ldap_first_entry() and ldap_next_entry() routines are used to step 2866through and retrieve the list of entries from a search result chain. 2867The ldap_first_reference() and ldap_next_reference() routines are used 2868to step through and retrieve the list of continuation references from a 2869search result chain. ldap_count_entries() is used to count the number 2870of entries returned. ldap_count_references() is used to count the number 2871of references returned. 2872 2873 LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *res ); 2874 2875 LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry ); 2876 2877 LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *res ); 2878 2879 LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *ref ); 2880 2881 int ldap_count_entries( LDAP *ld, LDAPMessage *res ); 2882 2883 int ldap_count_references( LDAP *ld, LDAPMessage *res ); 2884 2885Parameters are: 2886 2887ld The session handle. 2888 2889res The search result, as obtained by a call to one of the synchro- 2890 nous search routines or ldap_result(). 2891 2892entry The entry returned by a previous call to ldap_first_entry() or 2893 ldap_next_entry(). 2894 2895ref The reference returned by a previous call to 2896 ldap_first_reference() or ldap_next_reference(). 2897 2898ldap_first_entry(), ldap_next_entry(), ldap_first_reference() and 2899ldap_next_reference() all return NULL when no more entries or references 2900exist in the result set to be returned. NULL is also returned if an 2901error occurs while stepping through the entries or references, in which 2902case the error parameters in the session handle ld will be set to indi- 2903cate the error. 2904 2905ldap_count_entries() returns the number of entries contained in a chain 2906of entries; if an error occurs such as the res parameter being invalid, 2907 2908 2909 2910Expires: May 2001 [Page 52] 2911 2912C LDAP API C LDAP Application Program Interface 17 November 2000 2913 2914 2915-1 is returned. The ldap_count_entries() call can also be used to count 2916the number of entries that remain in a chain if called with a message, 2917entry or reference returned by ldap_first_message(), 2918ldap_next_message(), ldap_first_entry(), ldap_next_entry(), 2919ldap_first_reference(), ldap_next_reference(). 2920 2921ldap_count_references() returns the number of references contained in a 2922chain of search results; if an error occurs such as the res parameter 2923being invalid, -1 is returned. The ldap_count_references() call can 2924also be used to count the number of references that remain in a chain. 2925 2926 292716.2. Stepping Through the Attributes of an Entry 2928 2929The ldap_first_attribute() and ldap_next_attribute() calls are used to 2930step through the list of attribute types returned with an entry. 2931 2932 char *ldap_first_attribute( 2933 LDAP *ld, 2934 LDAPMessage *entry, 2935 BerElement **ptr 2936 ); 2937 2938 char *ldap_next_attribute( 2939 LDAP *ld, 2940 LDAPMessage *entry, 2941 BerElement *ptr 2942 ); 2943 2944 void ldap_memfree( char *mem ); 2945 2946Parameters are: 2947 2948ld The session handle. 2949 2950entry The entry whose attributes are to be stepped through, as returned 2951 by ldap_first_entry() or ldap_next_entry(). 2952 2953ptr In ldap_first_attribute(), the address of a pointer used inter- 2954 nally to keep track of the current position in the entry. In 2955 ldap_next_attribute(), the pointer returned by a previous call to 2956 ldap_first_attribute(). The BerElement type itself is an opaque 2957 structure that is described in more detail later in this document 2958 in the section "Encoded ASN.1 Value Manipulation". 2959 2960mem A pointer to memory allocated by the LDAP library, such as the 2961 attribute type names returned by ldap_first_attribute() and 2962 ldap_next_attribute, or the DN returned by ldap_get_dn(). If mem 2963 2964 2965 2966Expires: May 2001 [Page 53] 2967 2968C LDAP API C LDAP Application Program Interface 17 November 2000 2969 2970 2971 is NULL, the ldap_memfree() call does nothing. 2972 2973ldap_first_attribute() and ldap_next_attribute() will return NULL when 2974the end of the attributes is reached, or if there is an error, in which 2975case the error parameters in the session handle ld will be set to indi- 2976cate the error. 2977 2978Both routines return a pointer to an allocated buffer containing the 2979current attribute name. This SHOULD be freed when no longer in use by 2980calling ldap_memfree(). 2981 2982ldap_first_attribute() will allocate and return in ptr a pointer to a 2983BerElement used to keep track of the current position. This pointer MAY 2984be passed in subsequent calls to ldap_next_attribute() to step through 2985the entry's attributes. After a set of calls to ldap_first_attribute() 2986and ldap_next_attribute(), if ptr is non-NULL, it SHOULD be freed by 2987calling ber_free( ptr, 0 ). Note that it is very important to pass the 2988second parameter as 0 (zero) in this call, since the buffer associated 2989with the BerElement does not point to separately allocated memory. 2990 2991The attribute type names returned are suitable for passing in a call to 2992ldap_get_values() and friends to retrieve the associated values. 2993 2994 299516.3. Retrieving the Values of an Attribute 2996 2997ldap_get_values() and ldap_get_values_len() are used to retrieve the 2998values of a given attribute from an entry. ldap_count_values() and 2999ldap_count_values_len() are used to count the returned values. 3000ldap_value_free() and ldap_value_free_len() are used to free the values. 3001 3002 char **ldap_get_values( 3003 LDAP *ld, 3004 LDAPMessage *entry, 3005 const char *attr 3006 ); 3007 3008 struct berval **ldap_get_values_len( 3009 LDAP *ld, 3010 LDAPMessage *entry, 3011 const char *attr 3012 ); 3013 3014 int ldap_count_values( char **vals ); 3015 3016 int ldap_count_values_len( struct berval **vals ); 3017 3018 void ldap_value_free( char **vals ); 3019 3020 3021 3022Expires: May 2001 [Page 54] 3023 3024C LDAP API C LDAP Application Program Interface 17 November 2000 3025 3026 3027 void ldap_value_free_len( struct berval **vals ); 3028 3029Parameters are: 3030 3031ld The session handle. 3032 3033entry The entry from which to retrieve values, as returned by 3034 ldap_first_entry() or ldap_next_entry(). 3035 3036attr The attribute whose values are to be retrieved, as returned by 3037 ldap_first_attribute() or ldap_next_attribute(), or a caller- 3038 supplied string (e.g., "mail"). 3039 3040vals The values returned by a previous call to ldap_get_values() or 3041 ldap_get_values_len(). 3042 3043Two forms of the various calls are provided. The first form is only 3044suitable for use with non-binary character string data. The second _len 3045form is used with any kind of data. 3046 3047ldap_get_values() and ldap_get_values_len() return NULL if no values are 3048found for attr or if an error occurs. 3049 3050ldap_count_values() and ldap_count_values_len() return -1 if an error 3051occurs such as the vals parameter being invalid. 3052 3053If a NULL vals parameter is passed to ldap_value_free() or 3054ldap_value_free_len(), nothing is done. 3055 3056Note that the values returned are dynamically allocated and SHOULD be 3057freed by calling either ldap_value_free() or ldap_value_free_len() when 3058no longer in use. 3059 3060 306116.4. Retrieving the name of an entry 3062 3063ldap_get_dn() is used to retrieve the name of an entry. 3064ldap_explode_dn() and ldap_explode_rdn() are used to break up a name 3065into its component parts. ldap_dn2ufn() is used to convert the name into 3066a more "user friendly" format. 3067 3068 char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ); 3069 3070 char **ldap_explode_dn( const char *dn, int notypes ); 3071 3072 char **ldap_explode_rdn( const char *rdn, int notypes ); 3073 3074 char *ldap_dn2ufn( const char *dn ); 3075 3076 3077 3078Expires: May 2001 [Page 55] 3079 3080C LDAP API C LDAP Application Program Interface 17 November 2000 3081 3082 3083Parameters are: 3084 3085ld The session handle. 3086 3087entry The entry whose name is to be retrieved, as returned by 3088 ldap_first_entry() or ldap_next_entry(). 3089 3090dn The dn to explode, such as returned by ldap_get_dn(). If NULL, 3091 a zero length DN is used. 3092 3093rdn The rdn to explode, such as returned in the components of the 3094 array returned by ldap_explode_dn(). If NULL, a zero length DN 3095 is used. 3096 3097notypes A boolean parameter, if non-zero indicating that the dn or rdn 3098 components are to have their type information stripped off 3099 (i.e., "cn=Babs" would become "Babs"). 3100 3101ldap_get_dn() will return NULL if there is some error parsing the dn, 3102setting error parameters in the session handle ld to indicate the error. 3103It returns a pointer to newly allocated space that the caller SHOULD 3104free by calling ldap_memfree() when it is no longer in use. Note the 3105format of the DNs returned is given by [5]. The root DN is returned as 3106a zero length string (""). 3107 3108ldap_explode_dn() returns a NULL-terminated char * array containing the 3109RDN components of the DN supplied, with or without types as indicated by 3110the notypes parameter. The components are returned in the order they 3111appear in the dn. The array returned SHOULD be freed when it is no 3112longer in use by calling ldap_value_free(). 3113 3114ldap_explode_rdn() returns a NULL-terminated char * array containing the 3115components of the RDN supplied, with or without types as indicated by 3116the notypes parameter. The components are returned in the order they 3117appear in the rdn. The array returned SHOULD be freed when it is no 3118longer in use by calling ldap_value_free(). 3119 3120ldap_dn2ufn() converts the DN into the user friendly format described in 3121[14]. The UFN returned is newly allocated space that SHOULD be freed by 3122a call to ldap_memfree() when no longer in use. 3123 3124 312516.5. Retrieving controls from an entry 3126 3127ldap_get_entry_controls() is used to extract LDAP controls from an 3128entry. 3129 3130 3131 3132 3133 3134Expires: May 2001 [Page 56] 3135 3136C LDAP API C LDAP Application Program Interface 17 November 2000 3137 3138 3139 int ldap_get_entry_controls( 3140 LDAP *ld, 3141 LDAPMessage *entry, 3142 LDAPControl ***serverctrlsp 3143 ); 3144 3145Parameters are: 3146 3147ld The session handle. 3148 3149entry The entry to extract controls from, as returned by 3150 ldap_first_entry() or ldap_next_entry(). 3151 3152serverctrlsp This result parameter will be filled in with an allocated 3153 array of controls copied out of entry. The control array 3154 SHOULD be freed by calling ldap_controls_free(). If ser- 3155 verctrlsp is NULL, no controls are returned. If no con- 3156 trols were returned, *serverctrlsp is set to NULL. 3157 3158ldap_get_entry_controls() returns an LDAP result code that indicates 3159whether the reference could be successfully parsed (LDAP_SUCCESS if all 3160goes well). If ldap_get_entry_controls() returns a value other than 3161LDAP_SUCCESS, the value of the serverctrlsp output parameter is unde- 3162fined. 3163 3164 3165 316616.6. Parsing References 3167 3168ldap_parse_reference() is used to extract referrals and controls from a 3169SearchResultReference message. 3170 3171 3172 int ldap_parse_reference( 3173 LDAP *ld, 3174 LDAPMessage *ref, 3175 char ***referralsp, 3176 LDAPControl ***serverctrlsp, 3177 int freeit 3178 ); 3179 3180Parameters are: 3181 3182ld The session handle. 3183 3184ref The reference to parse, as returned by ldap_result(), 3185 ldap_first_reference(), or ldap_next_reference(). 3186 3187 3188 3189 3190Expires: May 2001 [Page 57] 3191 3192C LDAP API C LDAP Application Program Interface 17 November 2000 3193 3194 3195referralsp This result parameter will be filled in with an allocated 3196 array of character strings. The elements of the array are 3197 the referrals (typically LDAP URLs) contained in ref. The 3198 array SHOULD be freed when no longer in used by calling 3199 ldap_value_free(). If referralsp is NULL, the referral 3200 URLs are not returned. If no referrals were returned, 3201 *referralsp is set to NULL. 3202 3203serverctrlsp This result parameter will be filled in with an allocated 3204 array of controls copied out of ref. The control array 3205 SHOULD be freed by calling ldap_controls_free(). If ser- 3206 verctrlsp is NULL, no controls are returned. If no con- 3207 trols were returned, *serverctrlsp is set to NULL. 3208 3209freeit A boolean that determines whether the ref parameter is 3210 disposed of or not. Pass any non-zero value to have this 3211 routine free ref after extracting the requested informa- 3212 tion. This is provided as a convenience; you can also use 3213 ldap_msgfree() to free the result later. 3214 3215ldap_parse_reference() returns an LDAP result code that indicates 3216whether the reference could be successfully parsed (LDAP_SUCCESS if all 3217goes well). If a value other than LDAP_SUCCESS is returned, the value 3218of the referralsp and serverctrlsp result parameters are undefined. 3219 3220 3221 322217. Encoded ASN.1 Value Manipulation 3223 3224This section describes routines which MAY be used to encode and decode 3225BER-encoded ASN.1 values, which are often used inside of control and 3226extension values. 3227 3228With the exceptions of two new functions ber_flatten() and ber_init(), 3229these functions are compatible with the University of Michigan LDAP 3.3 3230implementation of BER. 3231 3232Note that the functions defined in this section all provide a method for 3233determining success or failure but generally do not provide access to 3234specific error codes. Therefore, applications that require precise 3235error information when encoding or decoding ASN.1 values SHOULD NOT use 3236these functions. 3237 3238 323917.1. BER Data Structures and Types 3240 3241The following additional integral types are defined for use in manipula- 3242tion of BER encoded ASN.1 values: 3243 3244 3245 3246Expires: May 2001 [Page 58] 3247 3248C LDAP API C LDAP Application Program Interface 17 November 2000 3249 3250 3251 typedef <impl_tag_t> ber_tag_t; /* for BER tags */ 3252 3253 typedef <impl_int_t> ber_int_t; /* for BER ints, enums, and Booleans */ 3254 3255 typedef <impl_unit_t> ber_uint_t; /* unsigned equivalent of ber_uint_t */ 3256 3257 typedef <impl_slen_t> ber_slen_t; /* signed equivalent of ber_len_t */ 3258 3259Note that the actual definition for these four integral types is imple- 3260mentation specific; that is, `<impl_tag_t>', `<impl_int_t>', 3261`<impl_uint_t>', and `<impl_slen_t>' MUST each be replaced with an 3262appropriate implementation-specific type. 3263 3264The `ber_tag_t' type is an unsigned integral data type that is large 3265enough to hold the largest BER tag supported by the API implementation. 3266The width (number of significant bits) of `ber_tag_t' MUST be at least 326732, greater than or equal to that of `unsigned int' (so that integer 3268promotions won't promote it to `int'), and no wider than that of 3269`unsigned long'. 3270 3271The `ber_int_t' and `ber_uint_t' types are the signed and unsigned vari- 3272ants of an integral type that is large enough to hold integers for pur- 3273poses of BER encoding and decoding. The width of `ber_int_t' MUST be at 3274least 32 and no larger than that of `long'. 3275 3276The `ber_slen_t' type is the signed variant of the `ber_len_t' integral 3277type, i.e. if `ber_len_t' is unsigned long, then `ber_slen_t' is signed 3278long. The `<impl_slen_t>' in the `ber_len_t' typedef MUST be replaced 3279with an appropriate type. Note that `ber_slen_t' is not used directly 3280in the C LDAP API but is provided for the convenience of application 3281developers and for use by extensions to the API. 3282 3283 typedef struct berval { 3284 ber_len_t bv_len; 3285 char *bv_val; 3286 } BerValue; 3287 3288As defined earlier in the section "Common Data Structures", a berval 3289structure contains an arbitrary sequence of bytes and an indication of 3290its length. The bv_len element is an unsigned integer. The bv_val is 3291not necessarily zero-terminated. Applications MAY allocate their own 3292berval structures. 3293 3294As defined earlier in the section "Common Data Structures", the BerEle- 3295ment structure is an opaque structure: 3296 3297 typedef struct berelement BerElement; 3298 3299 3300 3301 3302Expires: May 2001 [Page 59] 3303 3304C LDAP API C LDAP Application Program Interface 17 November 2000 3305 3306 3307It contains not only a copy of the encoded value, but also state infor- 3308mation used in encoding or decoding. Applications cannot allocate their 3309own BerElement structures. The internal state is neither thread- 3310specific nor locked, so two threads SHOULD NOT manipulate the same 3311BerElement value simultaneously. 3312 3313A single BerElement value cannot be used for both encoding and decoding. 3314 331517.2. Memory Disposal and Utility Functions 3316 3317 void ber_bvfree( struct berval *bv ); 3318 3319ber_bvfree() frees a berval structure returned from this API. Both the 3320bv->bv_val string and the berval structure itself are freed. If bv is 3321NULL, this call does nothing. 3322 3323 void ber_bvecfree( struct berval **bv ); 3324 3325ber_bvecfree() frees an array of berval structures returned from this 3326API. Each of the berval structures in the array are freed using 3327ber_bvfree(), then the array itself is freed. If bv is NULL, this call 3328does nothing. 3329 3330 struct berval *ber_bvdup( const struct berval *bv ); 3331 3332ber_bvdup() returns a copy of a berval structure. The bv_val field in 3333the returned berval structure points to a different area of memory than 3334the bv_val field in the bv argument. The NULL pointer is returned on 3335error (e.g. out of memory). 3336 3337 void ber_free( BerElement *ber, int fbuf ); 3338 3339ber_free() frees a BerElement which is returned from the API calls 3340ber_alloc_t() or ber_init(). Each BerElement SHOULD be freed by the 3341caller. The second argument fbuf SHOULD always be set to 1 to ensure 3342that the internal buffer used by the BER functions is freed as well as 3343the BerElement container itself. If ber is NULL, this call does noth- 3344ing. 3345 3346 334717.3. Encoding 3348 3349 BerElement *ber_alloc_t( int options ); 3350 3351ber_alloc_t() constructs and returns BerElement. The NULL pointer is 3352returned on error. The options field contains a bitwise-or of options 3353which are to be used when generating the encoding of this BerElement. 3354One option is defined and SHOULD always be supplied: 3355 3356 3357 3358Expires: May 2001 [Page 60] 3359 3360C LDAP API C LDAP Application Program Interface 17 November 2000 3361 3362 3363 #define LBER_USE_DER 0x01 3364 3365When this option is present, lengths will always be encoded in the 3366minimum number of octets. Note that this option does not cause values 3367of sets to be rearranged in tag and byte order or default values to be 3368removed, so these functions are not sufficient for generating DER output 3369as defined in X.509 and X.680. If the caller takes responsibility for 3370ordering values of sets correctly and removing default values, DER out- 3371put as defined in X.509 and X.680 can be produced. 3372 3373Unrecognized option bits are ignored. 3374 3375The BerElement returned by ber_alloc_t() is initially empty. Calls to 3376ber_printf() will append bytes to the end of the ber_alloc_t(). 3377 3378 int ber_printf( BerElement *ber, const char *fmt, ... ); 3379 3380The ber_printf() routine is used to encode a BER element in much the 3381same way that sprintf() works. One important difference, though, is 3382that state information is kept in the ber argument so that multiple 3383calls can be made to ber_printf() to append to the end of the BER ele- 3384ment. ber MUST be a pointer to a BerElement returned by ber_alloc_t(). 3385ber_printf() interprets and formats its arguments according to the for- 3386mat string fmt. ber_printf() returns -1 if there is an error during 3387encoding and a non-negative number if successful. As with sprintf(), 3388each character in fmt refers to an argument to ber_printf(). 3389 3390The format string can contain the following format characters: 3391 3392't' Tag. The next argument is a ber_tag_t specifying the tag to 3393 override the next element to be written to the ber. This works 3394 across calls. The integer tag value SHOULD contain the tag 3395 class, constructed bit, and tag value. For example, a tag of 3396 "[3]" for a constructed type is 0xA3U. All implementations MUST 3397 support tags that fit in a single octet (i.e., where the tag 3398 value is less than 32) and they MAY support larger tags. 3399 3400'b' Boolean. The next argument is an ber_int_t, containing either 0 3401 for FALSE or 0xff for TRUE. A boolean element is output. If 3402 this format character is not preceded by the 't' format modif- 3403 ier, the tag 0x01U is used for the element. 3404 3405'e' Enumerated. The next argument is a ber_int_t, containing the 3406 enumerated value in the host's byte order. An enumerated ele- 3407 ment is output. If this format character is not preceded by the 3408 't' format modifier, the tag 0x0AU is used for the element. 3409 3410'i' Integer. The next argument is a ber_int_t, containing the 3411 3412 3413 3414Expires: May 2001 [Page 61] 3415 3416C LDAP API C LDAP Application Program Interface 17 November 2000 3417 3418 3419 integer in the host's byte order. An integer element is output. 3420 If this format character is not preceded by the 't' format 3421 modifier, the tag 0x02U is used for the element. 3422 3423'B' Bitstring. The next two arguments are a char * pointer to the 3424 start of the bitstring, followed by a ber_len_t containing the 3425 number of bits in the bitstring. A bitstring element is output, 3426 in primitive form. If this format character is not preceded by 3427 the 't' format modifier, the tag 0x03U is used for the element. 3428 3429'X' Reserved and not to be used. In older revisions of this specif- 3430 ication, 3431 3432'n' Null. No argument is needed. An ASN.1 NULL element is output. 3433 If this format character is not preceded by the 't' format 3434 modifier, the tag 0x05U is used for the element. 3435 3436'o' Octet string. The next two arguments are a char *, followed by 3437 a ber_len_t with the length of the string. The string MAY con- 3438 tain null bytes and are do not have to be zero-terminated. An 3439 octet string element is output, in primitive form. If this for- 3440 mat character is not preceded by the 't' format modifier, the 3441 tag 0x04U is used for the element. 3442 3443's' Octet string. The next argument is a char * pointing to a 3444 zero-terminated string. An octet string element in primitive 3445 form is output, which does not include the trailing '\0' (null) 3446 byte. If this format character is not preceded by the 't' format 3447 modifier, the tag 0x04U is used for the element. 3448 3449'v' Several octet strings. The next argument is a char **, an array 3450 of char * pointers to zero-terminated strings. The last element 3451 in the array MUST be a NULL pointer. The octet strings do not 3452 include the trailing '\0' (null) byte. Note that a construct 3453 like '{v}' is used to get an actual SEQUENCE OF octet strings. 3454 The 't' format modifier cannot be used with this format charac- 3455 ter. 3456 3457'V' Several octet strings. A NULL-terminated array of struct berval 3458 *'s is supplied. Note that a construct like '{V}' is used to 3459 get an actual SEQUENCE OF octet strings. The 't' format modifier 3460 cannot be used with this format character. 3461 3462'{' Begin sequence. No argument is needed. If this format charac- 3463 ter is not preceded by the 't' format modifier, the tag 0x30U is 3464 used. 3465 3466'}' End sequence. No argument is needed. The 't' format modifier 3467 3468 3469 3470Expires: May 2001 [Page 62] 3471 3472C LDAP API C LDAP Application Program Interface 17 November 2000 3473 3474 3475 cannot be used with this format character. 3476 3477'[' Begin set. No argument is needed. If this format character is 3478 not preceded by the 't' format modifier, the tag 0x31U is used. 3479 3480']' End set. No argument is needed. The 't' format modifier cannot 3481 be used with this format character. 3482 3483Each use of a '{' format character SHOULD be matched by a '}' character, 3484either later in the format string, or in the format string of a subse- 3485quent call to ber_printf() for that BerElement. The same applies to the 3486'[' and ']' format characters. 3487 3488Sequences and sets nest, and implementations of this API MUST maintain 3489internal state to be able to properly calculate the lengths. 3490 3491 int ber_flatten( BerElement *ber, struct berval **bvPtr ); 3492 3493The ber_flatten routine allocates a struct berval whose contents are a 3494BER encoding taken from the ber argument. The bvPtr pointer points to 3495the returned berval structure, which SHOULD be freed using ber_bvfree(). 3496This routine returns 0 on success and -1 on error. 3497 3498The ber_flatten API call is not present in U-M LDAP 3.3. 3499 3500The use of ber_flatten on a BerElement in which all '{' and '}' format 3501modifiers have not been properly matched is an error (i.e., -1 will be 3502returned by ber_flatten() if this situation is exists). 3503 3504 350517.4. Encoding Example 3506 3507The following is an example of encoding the following ASN.1 data type: 3508 3509 Example1Request ::= SEQUENCE { 3510 s OCTET STRING, -- must be printable 3511 val1 INTEGER, 3512 val2 [0] INTEGER DEFAULT 0 3513 } 3514 3515 3516 int encode_example1(const char *s, ber_int_t val1, ber_int_t val2, 3517 struct berval **bvPtr) 3518 { 3519 BerElement *ber; 3520 int rc = -1; 3521 3522 *bvPtr = NULL; /* in case of error */ 3523 3524 3525 3526Expires: May 2001 [Page 63] 3527 3528C LDAP API C LDAP Application Program Interface 17 November 2000 3529 3530 3531 ber = ber_alloc_t(LBER_USE_DER); 3532 3533 if (ber == NULL) return -1; 3534 3535 if (ber_printf(ber,"{si",s,val1) == -1) { 3536 goto done; 3537 } 3538 3539 if (val2 != 0) { 3540 if (ber_printf(ber,"ti",(ber_tag_t)0x80,val2) == -1) { 3541 goto done; 3542 } 3543 } 3544 3545 if (ber_printf(ber,"}") == -1) { 3546 goto done; 3547 } 3548 3549 rc = ber_flatten(ber,bvPtr); 3550 3551 done: 3552 ber_free(ber,1); 3553 return rc; 3554 } 3555 3556 355717.5. Decoding 3558 3559The following two macros are available to applications: LBER_ERROR and 3560LBER_DEFAULT. Both of these macros MUST be #define'd as ber_tag_t 3561integral values that are treated as invalid tags by the API implementa- 3562tion. It is RECOMMENDED that the values of LBER_ERROR and LBER_DEFAULT 3563be the same and that they be defined as values where all octets have the 3564value 0xFF. ISO C guarantees that these definitions will work: 3565 3566 #define LBER_ERROR ((ber_tag_t)-1) 3567 #define LBER_DEFAULT ((ber_tag_t)-1) 3568 3569The intent is that LBER_ERROR and LBER_DEFAULT are both defined as the 3570integer value that has all octets set to 0xFF, as such a value is not a 3571valid BER tag. 3572 3573 BerElement *ber_init( const struct berval *bv ); 3574 3575The ber_init function constructs a BerElement and returns a new BerEle- 3576ment containing a copy of the data in the bv argument. ber_init returns 3577the NULL pointer on error. 3578 3579 3580 3581 3582Expires: May 2001 [Page 64] 3583 3584C LDAP API C LDAP Application Program Interface 17 November 2000 3585 3586 3587 ber_tag_t ber_scanf( BerElement *ber, const char *fmt, ... ); 3588 3589The ber_scanf() routine is used to decode a BER element in much the same 3590way that sscanf() works. One important difference, though, is that some 3591state information is kept with the ber argument so that multiple calls 3592can be made to ber_scanf() to sequentially read from the BER element. 3593The ber argument SHOULD be a pointer to a BerElement returned by 3594ber_init(). ber_scanf interprets the bytes according to the format 3595string fmt, and stores the results in its additional arguments. 3596ber_scanf() returns LBER_ERROR on error, and a different value on suc- 3597cess. If an error occurred, the values of all the result parameters are 3598undefined. 3599 3600The format string contains conversion specifications which are used to 3601direct the interpretation of the BER element. The format string can 3602contain the following characters: 3603 3604'a' Octet string. A char ** argument MUST be supplied. Memory is 3605 allocated, filled with the contents of the octet string, zero- 3606 terminated, and the pointer to the string is stored in the argu- 3607 ment. The returned value SHOULD be freed using ldap_memfree. 3608 The tag of the element MUST indicate the primitive form (con- 3609 structed strings are not supported) but is otherwise ignored and 3610 discarded during the decoding. This format cannot be used with 3611 octet strings which could contain null bytes. 3612 3613'O' Octet string. A struct berval ** argument MUST be supplied, 3614 which upon return points to an allocated struct berval contain- 3615 ing the octet string and its length. ber_bvfree() SHOULD be 3616 called to free the allocated memory. The tag of the element 3617 MUST indicate the primitive form (constructed strings are not 3618 supported) but is otherwise ignored during the decoding. 3619 3620'b' Boolean. A pointer to a ber_int_t MUST be supplied. The 3621 ber_int_t value stored will be 0 for FALSE or nonzero for TRUE. 3622 The tag of the element MUST indicate the primitive form but is 3623 otherwise ignored during the decoding. 3624 3625'e' Enumerated. A pointer to a ber_int_t MUST be supplied. The 3626 enumerated value stored will be in host byte order. The tag of 3627 the element MUST indicate the primitive form but is otherwise 3628 ignored during the decoding. ber_scanf() will return an error 3629 if the value of the enumerated value cannot be stored in a 3630 ber_int_t. 3631 3632'i' Integer. A pointer to a ber_int_t MUST be supplied. The 3633 ber_int_t value stored will be in host byte order. The tag of 3634 the element MUST indicate the primitive form but is otherwise 3635 3636 3637 3638Expires: May 2001 [Page 65] 3639 3640C LDAP API C LDAP Application Program Interface 17 November 2000 3641 3642 3643 ignored during the decoding. ber_scanf() will return an error 3644 if the integer cannot be stored in a ber_int_t. 3645 3646'B' Bitstring. A char ** argument MUST be supplied which will point 3647 to the allocated bits, followed by a ber_len_t * argument, which 3648 will point to the length (in bits) of the bitstring returned. 3649 ldap_memfree SHOULD be called to free the bitstring. The tag of 3650 the element MUST indicate the primitive form (constructed bit- 3651 strings are not supported) but is otherwise ignored during the 3652 decoding. 3653 3654'n' Null. No argument is needed. The element is verified to have a 3655 zero-length value and is skipped. The tag is ignored. 3656 3657't' Tag. A pointer to a ber_tag_t MUST be supplied. The ber_tag_t 3658 value stored will be the tag of the next element in the BerEle- 3659 ment ber, represented so it can be written using the 't' format 3660 of ber_printf(). The decoding position within the ber argument 3661 is unchanged by this; that is, the fact that the tag has been 3662 retrieved does not affect future use of ber. 3663 3664'v' Several octet strings. A char *** argument MUST be supplied, 3665 which upon return points to an allocated NULL-terminated array 3666 of char *'s containing the octet strings. NULL is stored if the 3667 sequence is empty. ldap_memfree SHOULD be called to free each 3668 element of the array and the array itself. The tag of the 3669 sequence and of the octet strings are ignored. 3670 3671'V' Several octet strings (which could contain null bytes). A 3672 struct berval *** MUST be supplied, which upon return points to 3673 a allocated NULL-terminated array of struct berval *'s contain- 3674 ing the octet strings and their lengths. NULL is stored if the 3675 sequence is empty. ber_bvecfree() can be called to free the 3676 allocated memory. The tag of the sequence and of the octet 3677 strings are ignored. 3678 3679'x' Skip element. The next element is skipped. No argument is 3680 needed. 3681 3682'{' Begin sequence. No argument is needed. The initial sequence 3683 tag and length are skipped. 3684 3685'}' End sequence. No argument is needed. 3686 3687'[' Begin set. No argument is needed. The initial set tag and 3688 length are skipped. 3689 3690']' End set. No argument is needed. 3691 3692 3693 3694Expires: May 2001 [Page 66] 3695 3696C LDAP API C LDAP Application Program Interface 17 November 2000 3697 3698 3699 ber_tag_t ber_peek_tag( BerElement *ber, 3700 ber_len_t *lenPtr ); 3701 3702ber_peek_tag() returns the tag of the next element to be parsed in the 3703BerElement argument. The length of this element is stored in the 3704*lenPtr argument. LBER_DEFAULT is returned if there is no further data 3705to be read. The decoding position within the ber argument is unchanged 3706by this call; that is, the fact that ber_peek_tag() has been called does 3707not affect future use of ber. 3708 3709 ber_tag_t ber_skip_tag( BerElement *ber, ber_len_t *lenPtr ); 3710 3711ber_skip_tag() is similar to ber_peek_tag(), except that the state 3712pointer in the BerElement argument is advanced past the first tag and 3713length, and is pointed to the value part of the next element. This rou- 3714tine SHOULD only be used with constructed types and situations when a 3715BER encoding is used as the value of an OCTET STRING. The length of the 3716value is stored in *lenPtr. 3717 3718 ber_tag_t ber_first_element( BerElement *ber, 3719 ber_len_t *lenPtr, char **opaquePtr ); 3720 3721 ber_tag_t ber_next_element( BerElement *ber, 3722 ber_len_t *lenPtr, char *opaque ); 3723 3724ber_first_element() and ber_next_element() are used to traverse a SET, 3725SET OF, SEQUENCE or SEQUENCE OF data value. ber_first_element() calls 3726ber_skip_tag(), stores internal information in *lenPtr and *opaquePtr, 3727and calls ber_peek_tag() for the first element inside the constructed 3728value. LBER_DEFAULT is returned if the constructed value is empty. 3729ber_next_element() positions the state at the start of the next element 3730in the constructed type. LBER_DEFAULT is returned if there are no 3731further values. 3732 3733The len and opaque values SHOULD NOT be used by applications other than 3734as arguments to ber_next_element(), as shown in the example below. 3735 3736 373717.6. Decoding Example 3738 3739The following is an example of decoding an ASN.1 data type: 3740 3741 Example2Request ::= SEQUENCE { 3742 dn OCTET STRING, -- must be printable 3743 scope ENUMERATED { b (0), s (1), w (2) }, 3744 ali ENUMERATED { n (0), s (1), f (2), a (3) }, 3745 size INTEGER, 3746 time INTEGER, 3747 3748 3749 3750Expires: May 2001 [Page 67] 3751 3752C LDAP API C LDAP Application Program Interface 17 November 2000 3753 3754 3755 tonly BOOLEAN, 3756 attrs SEQUENCE OF OCTET STRING, -- must be printable 3757 [0] SEQUENCE OF SEQUENCE { 3758 type OCTET STRING -- must be printable, 3759 crit BOOLEAN DEFAULT FALSE, 3760 value OCTET STRING 3761 } OPTIONAL } 3762 3763 #define TAG_CONTROL_LIST 0xA0U /* context specific cons 0 */ 3764 3765 int decode_example2(struct berval *bv) 3766 { 3767 BerElement *ber; 3768 ber_len_t len; 3769 ber_tag_t res; 3770 ber_int_t scope, ali, size, time, tonly; 3771 char *dn = NULL, **attrs = NULL; 3772 int i,rc = 0; 3773 3774 ber = ber_init(bv); 3775 if (ber == NULL) { 3776 fputs("ERROR ber_init failed\n", stderr); 3777 return -1; 3778 } 3779 3780 res = ber_scanf(ber,"{aiiiib{v}",&dn,&scope,&ali, 3781 &size,&time,&tonly,&attrs); 3782 3783 if (res == LBER_ERROR) { 3784 fputs("ERROR ber_scanf failed\n", stderr); 3785 ber_free(ber,1); 3786 return -1; 3787 } 3788 3789 /* *** use dn */ 3790 ldap_memfree(dn); 3791 3792 for (i = 0; attrs != NULL && attrs[i] != NULL; i++) { 3793 /* *** use attrs[i] */ 3794 ldap_memfree(attrs[i]); 3795 } 3796 ldap_memfree((char *)attrs); 3797 3798 if (ber_peek_tag(ber,&len) == TAG_CONTROL_LIST) { 3799 char *opaque; 3800 ber_tag_t tag; 3801 3802 for (tag = ber_first_element(ber,&len,&opaque); 3803 3804 3805 3806Expires: May 2001 [Page 68] 3807 3808C LDAP API C LDAP Application Program Interface 17 November 2000 3809 3810 3811 tag != LBER_DEFAULT; 3812 tag = ber_next_element (ber,&len,opaque)) { 3813 3814 ber_len_t tlen; 3815 ber_tag_t ttag; 3816 char *type; 3817 ber_int_t crit; 3818 struct berval *value; 3819 3820 if (ber_scanf(ber,"{a",&type) == LBER_ERROR) { 3821 fputs("ERROR cannot parse type\n", stderr); 3822 break; 3823 } 3824 /* *** use type */ 3825 ldap_memfree(type); 3826 3827 ttag = ber_peek_tag(ber,&tlen); 3828 if (ttag == 0x01U) { /* boolean */ 3829 if (ber_scanf(ber,"b", 3830 &crit) == LBER_ERROR) { 3831 fputs("ERROR cannot parse crit\n", 3832 stderr); 3833 rc = -1; 3834 break; 3835 } 3836 } else if (ttag == 0x04U) { /* octet string */ 3837 crit = 0; 3838 } else { 3839 fputs("ERROR extra field in controls\n", 3840 stderr ); 3841 break; 3842 } 3843 3844 if (ber_scanf(ber,"O}",&value) == LBER_ERROR) { 3845 fputs("ERROR cannot parse value\n", stderr); 3846 rc = -1; 3847 break; 3848 } 3849 /* *** use value */ 3850 ber_bvfree(value); 3851 } 3852 } 3853 3854 if ( rc == 0 ) { /* no errors so far */ 3855 if (ber_scanf(ber,"}") == LBER_ERROR) { 3856 rc = -1; 3857 } 3858 } 3859 3860 3861 3862Expires: May 2001 [Page 69] 3863 3864C LDAP API C LDAP Application Program Interface 17 November 2000 3865 3866 3867 ber_free(ber,1); 3868 3869 return rc; 3870 } 3871 3872 3873 387418. Security Considerations 3875 3876LDAPv2 supports security through protocol-level authentication using 3877clear-text passwords. LDAPv3 adds support for SASL [12] (Simple Authen- 3878tication Security Layer) methods. LDAPv3 also supports operation over a 3879secure transport layer using Transport Layer Security TLS [9]. Readers 3880are referred to the protocol documents for discussion of related secu- 3881rity considerations. 3882 3883Implementations of this API SHOULD be cautious when handling authentica- 3884tion credentials. In particular, keeping long-lived copies of creden- 3885tials without the application's knowledge is discouraged. 3886 3887 388819. Acknowledgements 3889 3890Many members of the IETF ASID and LDAPEXT working groups as well as 3891members of the Internet at large have provided useful comments and 3892suggestions that have been incorporated into this document. Chris 3893Weider deserves special mention for his contributions as co-author of 3894earlier revisions of this document. 3895 3896The original material upon which this specification is based was sup- 3897ported by the National Science Foundation under Grant No. NCR-9416667. 3898 3899 390020. Copyright 3901 3902Copyright (C) The Internet Society (1997-2000). All Rights Reserved. 3903 3904This document and translations of it may be copied and furnished to oth- 3905ers, and derivative works that comment on or otherwise explain it or 3906assist in its implementation may be prepared, copied, published and dis- 3907tributed, in whole or in part, without restriction of any kind, provided 3908that the above copyright notice and this paragraph are included on all 3909such copies and derivative works. However, this document itself may not 3910be modified in any way, such as by removing the copyright notice or 3911references to the Internet Society or other Internet organizations, 3912except as needed for the purpose of developing Internet standards in 3913which case the procedures for copyrights defined in the Internet Stan- 3914dards process must be followed, or as required to translate it into 3915 3916 3917 3918Expires: May 2001 [Page 70] 3919 3920C LDAP API C LDAP Application Program Interface 17 November 2000 3921 3922 3923languages other than English. 3924 3925The limited permissions granted above are perpetual and will not be 3926revoked by the Internet Society or its successors or assigns. 3927 3928This document and the information contained herein is provided on an "AS 3929IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK 3930FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT 3931LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT 3932INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FIT- 3933NESS FOR A PARTICULAR PURPOSE. 3934 3935 393621. Bibliography 3937 3938[1] Bradner, S., "Key words for use in RFCs to Indicate Requirement 3939 Levels", RFC 2119, March 1997. 3940 3941[2] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol 3942 (v3)", RFC 2251, December 1997. 3943 3944[3] M. Wahl, A. Coulbeck, T. Howes, S. Kille, W. Yeong, C. Robbins, 3945 "Lightweight Directory Access Protocol (v3): Attribute Syntax 3946 Definitions", RFC 2252, December 1997. 3947 3948[4] The Directory: Selected Attribute Syntaxes. CCITT, Recommendation 3949 X.520. 3950 3951[5] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol 3952 (v3): A UTF-8 String Representation of Distinguished Names", RFC 3953 2253, December 1997. 3954 3955[6] F. Yergeau, "UTF-8, a transformation format of Unicode and ISO 3956 10646", RFC 2044, October 1996. 3957 3958[7] K. Simonsen, "Character Mnemonics and Character Sets," RFC 1345, 3959 June 1992. 3960 3961[8] "Programming Languages - C", ANSI/ISO Standard 9899, revised 1997. 3962 3963[9] J. Hodges, R. Morgan, M. Wahl, "Lightweight Directory Access Proto- 3964 col (v3): Extension for Transport Layer Security", INTERNET-DRAFT 3965 (work in progress) <draft-ietf-ldapext-ldapv3-tls-05.txt>, June 3966 1999. 3967 3968[10] R. Hinden, S. Deering, "IP Version 6 Addressing Architecture," RFC 3969 1884, December 1995. 3970 3971 3972 3973 3974Expires: May 2001 [Page 71] 3975 3976C LDAP API C LDAP Application Program Interface 17 November 2000 3977 3978 3979[11] A. Herron, T. Howes, M. Wahl, A. Anantha, "LDAP Control Extension 3980 for Server Side Sorting of Search Results", INTERNET-DRAFT (work in 3981 progress) <draft-ietf-ldapext-sorting-02.txt>, 5 April 1999. 3982 3983[12] J. Meyers, "Simple Authentication and Security Layer (SASL)", RFC 3984 2222, October 1997. 3985 3986[13] T. Howes, "The String Representation of LDAP Search Filters," RFC 3987 2254, December 1997. 3988 3989[14] S. Kille, "Using the OSI Directory to Achieve User Friendly Nam- 3990 ing," RFC 1781, March 1995. 3991 3992 399322. Authors' Addresses 3994 3995 Mark Smith (document editor) 3996 Netscape Communications Corp. 3997 901 San Antonio Rd. 3998 Palo Alto, CA 94303-4900 3999 Mail Stop SCA17 - 201 4000 USA 4001 +1 650 937-3477 4002 mcs@netscape.com 4003 4004 Tim Howes 4005 Loudcloud, Inc. 4006 599 N. Mathilda Avenue 4007 Sunnyvale, CA 94085 4008 USA 4009 +1 408 744-7300 4010 howes@loudcloud.com 4011 4012 Andy Herron 4013 Microsoft Corp. 4014 1 Microsoft Way 4015 Redmond, WA 98052 4016 USA 4017 +1 425 882-8080 4018 andyhe@microsoft.com 4019 4020 Mark Wahl 4021 Sun Microsystems, Inc. 4022 8911 Capital of Texas Hwy, Suite 4140 4023 Austin, TX 78759 4024 USA 4025 +1 626 919 3600 4026 Mark.Wahl@sun.com 4027 4028 4029 4030Expires: May 2001 [Page 72] 4031 4032C LDAP API C LDAP Application Program Interface 17 November 2000 4033 4034 4035 Anoop Anantha 4036 Microsoft Corp. 4037 1 Microsoft Way 4038 Redmond, WA 98052 4039 USA 4040 +1 425 882-8080 4041 anoopa@microsoft.com 4042 4043 404423. Appendix A - Sample C LDAP API Code 4045 4046 #include <stdio.h> 4047 #include <ldap.h> 4048 4049 main() 4050 { 4051 LDAP *ld; 4052 LDAPMessage *res, *e; 4053 int i, rc; 4054 char *a, *dn; 4055 BerElement *ptr; 4056 char **vals; 4057 4058 /* open an LDAP session */ 4059 if ( (ld = ldap_init( "dotted.host.name", LDAP_PORT )) == NULL ) 4060 return 1; 4061 4062 /* authenticate as nobody */ 4063 if (( rc = ldap_simple_bind_s( ld, NULL, NULL )) != LDAP_SUCCESS ) { 4064 fprintf( stderr, "ldap_simple_bind_s: %s\n", 4065 ldap_err2string( rc )); 4066 ldap_unbind( ld ); 4067 return 1; 4068 } 4069 4070 /* search for entries with cn of "Babs Jensen", return all attrs */ 4071 if (( rc = ldap_search_s( ld, "o=University of Michigan, c=US", 4072 LDAP_SCOPE_SUBTREE, "(cn=Babs Jensen)", NULL, 0, &res )) 4073 != LDAP_SUCCESS ) { 4074 fprintf( stderr, "ldap_search_s: %s\n", 4075 ldap_err2string( rc )); 4076 if ( res == NULL ) { 4077 ldap_unbind( ld ); 4078 return 1; 4079 } 4080 } 4081 4082 /* step through each entry returned */ 4083 4084 4085 4086Expires: May 2001 [Page 73] 4087 4088C LDAP API C LDAP Application Program Interface 17 November 2000 4089 4090 4091 for ( e = ldap_first_entry( ld, res ); e != NULL; 4092 e = ldap_next_entry( ld, e ) ) { 4093 /* print its name */ 4094 dn = ldap_get_dn( ld, e ); 4095 printf( "dn: %s\n", dn ); 4096 ldap_memfree( dn ); 4097 4098 /* print each attribute */ 4099 for ( a = ldap_first_attribute( ld, e, &ptr ); a != NULL; 4100 a = ldap_next_attribute( ld, e, ptr ) ) { 4101 printf( "\tattribute: %s\n", a ); 4102 4103 /* print each value */ 4104 vals = ldap_get_values( ld, e, a ); 4105 for ( i = 0; vals[i] != NULL; i++ ) { 4106 printf( "\t\tvalue: %s\n", vals[i] ); 4107 } 4108 ldap_value_free( vals ); 4109 ldap_memfree( a ); 4110 } 4111 if ( ptr != NULL ) { 4112 ber_free( ptr, 0 ); 4113 } 4114 } 4115 /* free the search results */ 4116 ldap_msgfree( res ); 4117 4118 /* close and free connection resources */ 4119 ldap_unbind( ld ); 4120 4121 return 0; 4122 } 4123 4124 412524. Appendix B - Namespace Consumed By This Specification 4126 4127The following 2 prefixes are used in this specification to name func- 4128tions: 4129 ldap_ 4130 ber_ 4131 4132The following 6 prefixes are used in this specification to name struc- 4133tures, unions, and typedefs: 4134 ldap 4135 LDAP 4136 mod_vals_u 4137 ber 4138 Ber 4139 4140 4141 4142Expires: May 2001 [Page 74] 4143 4144C LDAP API C LDAP Application Program Interface 17 November 2000 4145 4146 4147 timeval 4148 4149The following 3 prefixes are used in this specification to name #defined 4150macros: 4151 LDAP 4152 LBER_ 4153 mod_ 4154 4155 415625. Appendix C - Summary of Requirements for API Extensions 4157 4158As the LDAP protocol is extended, this C LDAP API will need to be 4159extended as well. For example, an LDAPv3 control extension has already 4160been defined for server-side sorting of search results [7]. This appen- 4161dix summarizes the requirements for extending this API. 4162 416325.1. Compatibility 4164 4165Extensions to this document SHOULD NOT, by default, alter the behavior 4166of any of the APIs specified in this document. If an extension option- 4167ally changes the behavior of any existing C LDAP API function calls, the 4168behavior change MUST be well documented. If an extension that operates 4169on an LDAP session affects a chain of messages that was previously 4170obtained by a call to ldap_result() or by calling a synchronous search 4171routine, this MUST be well documented. 4172 417325.2. Style 4174 4175Extensions to this API SHOULD follow the general style and naming con- 4176ventions used in this document. For example, function names SHOULD 4177start with "ldap_" or "ber_" and consist entirely of lowercase letters, 4178digits, and underscore ('_') characters. It is RECOMMENDED that private 4179and experimental extensions use only the following prefixes for macros, 4180types, and function names: 4181 LDAP_X_ 4182 LBER_X_ 4183 ldap_x_ 4184 ber_x_ 4185and that these prefixes not be used by standard extensions. 4186 418725.3. Dependence on Externally Defined Types 4188 4189Extensions to this API SHOULD minimize dependencies on types and macros 4190that are defined in system headers and generally use only intrinsic 4191types that are part of the C language, types defined in this specifica- 4192tion, or types defined in the extension document itself. 4193 4194 4195 4196 4197 4198Expires: May 2001 [Page 75] 4199 4200C LDAP API C LDAP Application Program Interface 17 November 2000 4201 4202 420325.4. Compile Time Information 4204 4205Extensions to this API SHOULD conform to the requirements contained in 4206the "Retrieving Information at Compile Time" section of this document. 4207That is, extensions SHOULD define a macro of the form: 4208 4209 #define LDAP_API_FEATURE_x level 4210 4211so that applications can detect the presence or absence of the extension 4212at compile time and also test the version or level of the extension pro- 4213vided by an API implementation. 4214 421525.5. Runtime Information 4216 4217Extensions to this API SHOULD conform to the requirements contained in 4218the "Retrieving Information During Execution" section of this document. 4219That is, each extension SHOULD be given a character string name and that 4220name SHOULD appear in the ldapai_extensions array field of the LDAPAPI- 4221Info structure following a successful call to ldap_get_option() with an 4222option parameter value of LDAP_OPT_API_INFO. In addition, information 4223about the extension SHOULD be available via a call to ldap_get_option() 4224with an option parameter value of LDAP_OPT_API_FEATURE_INFO. 4225 422625.6. Values Used for Session Handle Options 4227 4228Extensions to this API that add new session options (for use with the 4229ldap_get_option() and ldap_set_option() functions) SHOULD meet the 4230requirements contained in the last paragraph of the "LDAP Session Handle 4231Options" section of this document. Specifically, standards track docu- 4232ments MUST use values for option macros that are between 0x1000 and 42330x3FFF inclusive and private and experimental extensions MUST use values 4234for the option macros that are between 0x4000 and 0x7FFF inclusive. 4235 4236 423726. Appendix D - Known Incompatibilities with RFC 1823 4238 4239This appendix lists known incompatibilities between this API specifica- 4240tion and the one contained in RFC 1823, beyond the additional API func- 4241tions added in support of LDAPv3. 4242 4243 424426.1. Opaque LDAP Structure 4245 4246In RFC 1823, some fields in the LDAP structure were exposed to applica- 4247tion programmers. To provide a cleaner interface and to make it easier 4248for implementations to evolve over time without sacrificing binary com- 4249patibility with older applications, the LDAP structure is now entirely 4250opaque. The new ldap_set_option() and ldap_get_option() calls can be 4251 4252 4253 4254Expires: May 2001 [Page 76] 4255 4256C LDAP API C LDAP Application Program Interface 17 November 2000 4257 4258 4259used to manipulate per-session and global options. 4260 4261 426226.2. Additional Result Codes 4263 4264The following new result code macros were introduced to support LDAPv3: 4265 LDAP_REFERRAL 4266 LDAP_ADMINLIMIT_EXCEEDED 4267 LDAP_UNAVAILABLE_CRITICAL_EXTENSION 4268 LDAP_CONFIDENTIALITY_REQUIRED 4269 LDAP_SASL_BIND_IN_PROGRESS 4270 LDAP_AFFECTS_MULTIPLE_DSAS 4271 LDAP_CONNECT_ERROR 4272 LDAP_NOT_SUPPORTED 4273 LDAP_CONTROL_NOT_FOUND 4274 LDAP_NO_RESULTS_RETURNED 4275 LDAP_MORE_RESULTS_TO_RETURN 4276 LDAP_CLIENT_LOOP 4277 LDAP_REFERRAL_LIMIT_EXCEEDED 4278 4279 428026.3. Freeing of String Data with ldap_memfree() 4281 4282All strings received from the API (e.g., those returned by the 4283ldap_get_dn() or ldap_dn2ufn() functions) SHOULD be freed by calling 4284ldap_memfree() not free(). RFC 1823 did not define an ldap_memfree() 4285function. 4286 4287 428826.4. Changes to ldap_result() 4289 4290The meaning of the all parameter to ldap_result has changed slightly. 4291Nonzero values from RFC 1823 correspond to LDAP_MSG_ALL (0x01). There 4292is also a new possible value, LDAP_MSG_RECEIVED (0x02). 4293 4294The result type LDAP_RES_MODDN is now returned where RFC 1823 returned 4295LDAP_RES_MODRDN. The actual value for these two macros is the same 4296(0x6D). 4297 4298 429926.5. Changes to ldap_first_attribute() and ldap_next_attribute 4300 4301Each non-NULL return value SHOULD be freed by calling ldap_memfree() 4302after use. In RFC 1823, these two functions returned a pointer to a 4303per-session buffer, which was not very thread-friendly. 4304 4305After the last call to ldap_first_attribute() or ldap_next_attribute(), 4306the value set in the ptr parameter SHOULD be freed by calling ber_free( 4307 4308 4309 4310Expires: May 2001 [Page 77] 4311 4312C LDAP API C LDAP Application Program Interface 17 November 2000 4313 4314 4315ptr, 0 ). RFC 1823 did not mention that the ptr value SHOULD be freed. 4316 4317The type of the ptr parameter was changed from void * to BerElement *. 4318 4319 432026.6. Changes to ldap_modrdn() and ldap_modrdn_s() Functions 4321 4322In RFC 1823, the ldap_modrdn() and ldap_modrdn_s() functions include a 4323parameter called deleteoldrdn. This does not match the great majority 4324of implementations, so in this specification the deleteoldrdn parameter 4325was removed from ldap_modrdn() and ldap_modrdn_s(). Two additional 4326functions that support deleteoldrdn and are widely implemented as well 4327were added to this specification: ldap_modrdn2() and ldap_modrdn2_s(). 4328 4329 433026.7. Changes to the berval structure 4331 4332In RFC 1823, the bv_len element of the berval structure was defined as 4333an `unsigned long'. In this specification, the type is implementation- 4334specific, although it MUST be an unsigned integral type that is at least 433532 bits in size. See the appendix "Data Types and Legacy Implementa- 4336tions" for additional considerations. 4337 4338 433926.8. API Specification Clarified 4340 4341RFC 1823 left many things unspecified, including behavior of various 4342memory disposal functions when a NULL pointer is presented, requirements 4343for headers, values of many macros, and so on. This specification is 4344more complete and generally tighter than the one in RFC 1823. 4345 4346 434726.9. Deprecated Functions 4348 4349A number of functions that are in RFC 1823 are labeled as "deprecated" 4350in this specification. In most cases, a replacement that provides 4351equivalent functionality has been defined. The deprecated functions 4352are: 4353 4354 ldap_bind() 4355 Use ldap_simple_bind() or ldap_sasl_bind() instead. 4356 4357 ldap_bind_s() 4358 Use ldap_simple_bind_s() or ldap_sasl_bind_s() instead. 4359 4360 ldap_kerberos_bind() and ldap_kerberos_bind_s() 4361 No equivalent functions are provided. 4362 4363 4364 4365 4366Expires: May 2001 [Page 78] 4367 4368C LDAP API C LDAP Application Program Interface 17 November 2000 4369 4370 4371 ldap_modrdn() and ldap_modrdn2() 4372 Use ldap_rename() instead. 4373 4374 ldap_modrdn_s() and ldap_modrdn2_s() 4375 Use ldap_rename_s() instead. 4376 4377 ldap_open() 4378 Use ldap_init() instead. 4379 4380 ldap_perror() 4381 Use ldap_get_option( ld, LDAP_OPT_RESULT_CODE, &rc ) followed 4382 by fprintf( stderr, "%s: %s", msg, ldap_err2string( rc )) 4383 instead. 4384 4385 ldap_result2error() 4386 Use ldap_parse_result() instead. 4387 4388 438927. Appendix E - Data Types and Legacy Implementations 4390 4391The data types associated with the length of a ber value (ber_len_t), 4392and the tag (ber_tag_t) have been defined in this specification as 4393unsigned integral types of implementation-specific size. The data type 4394used for encoding and decoding ber integer, enumerated, and boolean 4395values has been defined in this specification as a signed integral type 4396of implementation-specific size. This was done so that source and 4397binary compatibility of the C LDAP API can be maintained across ILP32 4398environments (where int, long, and pointers are all 32 bits in size) and 4399LP64 environments (where ints remain 32 bits but longs and pointers grow 4400to 64 bits). 4401 4402In older implementations of the C LDAP API, such as those based on RFC 44031823, implementors may have chosen to use an `unsigned long' for length 4404and tag values. If a long data type was used for either of these items, 4405a port of an application to a 64-bit operating system using the LP64 4406data model would find the size of the types used by the C LDAP API to 4407increase. Also, if the legacy implementation had chosen to implement 4408the tag and types as an unsigned int, adoption of a specification that 4409mandated use of unsigned longs would cause a source incompatibility in 4410an LP64 application. By using implementation-specific data types, the C 4411LDAP API implementation is free to choose the correct data type and the 4412ability to maintain source compatibility. 4413 4414For example, suppose a legacy implementation chose to define the return 4415value of ber_skip_tag() as an unsigned long but wishes to have the 4416library return a 32-bit quantity in both ILP32 and LP64 data models. 4417The following typedefs for ber_tag_t will provide a fixed sized data 4418structure while preserving existing ILP32 source -- all without 4419 4420 4421 4422Expires: May 2001 [Page 79] 4423 4424C LDAP API C LDAP Application Program Interface 17 November 2000 4425 4426 4427generating compiler warnings: 4428 #include <limits.h> /* provides UINT_MAX in ISO C */ 4429 #if UINT_MAX >= 0xffffffffU 4430 typedef unsigned int ber_tag_t; 4431 #else 4432 typedef unsigned long ber_tag_t; 4433 #endif 4434 4435Similar code can be used to define appropriate ber_len_t, ber_int_t, 4436ber_slen_t and ber_uint_t types. 4437 4438 443928. Appendix F - Changes Made Since Last Document Revision 4440 4441The previous version of this document was draft-ietf-ldapext-ldap-c- 4442api-04.txt, dated 8 October 1999. This appendix lists all of the 4443changes made to that document to produce this one. 4444 444528.1. API Changes 4446 4447 "Header Requirements" section: added requirement that the simple pro- 4448 gram provided must execute as well as compile without errors. 4449 4450 "LDAP Session Handle Options" section: changed the name of the 4451 LDAP_OPT_ERROR_NUMBER option to LDAP_OPT_RESULT_CODE. Allow 4452 LDAP_OPT_ON to be defined as an implementation specific value (to 4453 avoid problems on architectures where the value ((void *)1) is not 4454 usable). 4455 4456 "Initializing an LDAP Session" section: allow use of the value zero 4457 for the `portno' parameter to mean "use port 389." 4458 4459 "Searching" section: added LDAP_DEFAULT_SIZELIMIT (-1) to allow 4460 application programmers to use the sizelimit from the LDAP session 4461 handle with ldap_search_ext() and ldap_search_ext_s(). 4462 4463 "Modifying an entry" section: moved mod_vals union out of LDAPMod and 4464 added mod_vals_u_t typedef so users of the API can declare variables 4465 using the union type. "Handling Errors and Parsing Results" section: 4466 added text to require that ldap_err2string() MUST NOT return NULL. 4467 4468 "A Client Control That Governs Referral Processing" section: modified 4469 the text to specify that a ber_uint_t value should be used to hold 4470 the flags. 4471 4472 4473 4474 4475 4476 4477 4478Expires: May 2001 [Page 80] 4479 4480C LDAP API C LDAP Application Program Interface 17 November 2000 4481 4482 448328.2. Editorial Changes and Clarifications 4484 4485 "Overview of LDAP API Use and General Requirements" section: added 4486 text to clarify our use of the term "asynchronous." 4487 4488 "Retrieving Information During Execution" section: added text 4489 describing the `ldapai_vendor_name' and `ldapai_vendor_version' 4490 fields (text was accidently deleted during a previous round of 4491 edits). 4492 4493 "LDAP Session Handle Options" section: improved the text that 4494 describes the LDAP_OPT_TIMELIMIT, LDAP_OPT_SIZELIMIT, and 4495 LDAP_OPT_RESULT_CODE options. Provided details and an example of the 4496 correct LDAP_OPT_HOST_NAME string to return when the `portno' passed 4497 to ldap_init() is not zero or 389. 4498 4499 "Result Codes" section: renamed section (was "LDAP Error Codes"). 4500 4501 "Authenticating to the directory" section: clarified that the `dn', 4502 `cred', and `passwd' parameters can be NULL. Added text indicate 4503 that the `servercredp' is set to NULL if an API error occurs. 4504 4505 "Performing LDAP Operations" section: replaced "All functions take a 4506 session handle" with "Most functions...." 4507 4508 "Search" section: removed the detailed discussion of the session han- 4509 dle options (already covered in the "Retrieving Information During 4510 Execution" section). Also removed the word "global" when discussing 4511 the session default value for the `timeout' parameter. Also clari- 4512 fied that a NULL `base' parameter means use a zero-length string for 4513 the base DN. 4514 4515 "Comparing a Value Against an Entry" section: corrected the "success- 4516 ful" return codes for ldap_compare_ext_s() and ldap_compare_s() (was 4517 LDAP_SUCCESS; changed to LDAP_COMPARE_TRUE or LDAP_COMPARE_FALSE). 4518 4519 "Extended Operations" section: added text to indicate that the 4520 `retoidp' and `retdatap' result parameters are set to NULL if an API 4521 error occurs in ldap_extended_operation_s(). 4522 4523 "Handling Errors and Parsing Results" section: added text to say that 4524 the `matcheddnp' result parameter will be set to NULL if the server 4525 does not return a matched DN string. Added text to indicate that 4526 serverctrlsp can be NULL. Added text to indicate that *retoidpp, 4527 *retdatap, *referralsp, and *serverctrlsp will be set to NULL if no 4528 items of that type are returned. Removed specific reference to 4529 LDAP_NO_SUCH_OBJECT result code when discussing the `matcheddnp' 4530 result parameter and added clarifying note about "" vs. NULL. 4531 4532 4533 4534Expires: May 2001 [Page 81] 4535 4536C LDAP API C LDAP Application Program Interface 17 November 2000 4537 4538 4539 "Parsing References" section: added text to indicate that *refer- 4540 ralsp, and *serverctrlsp will be set to NULL if no items of that type 4541 are returned. 4542 4543 "Obtaining Results and Peeking Inside LDAP Messages" section: added 4544 text to say that LDAPMessage chains MAY be tied to a session handle. 4545 4546 "BER Data Structures and Types" section: removed note about 4547 ber_uint_t not being used in this document (it is now). Changed text 4548 to simplify the description of ber_slen_t. Removed misleading sen- 4549 tence about the width of ber_uint_t. 4550 4551 "Encoded ASN.1 Value Manipulation / Encoding" section: added note 4552 that 'X' is reserved. Also fixed a few small bugs in the example 4553 code. 4554 4555 "Encoded ASN.1 Value Manipulation / Decoding" section: clarified the 4556 requirements for LBER_ERROR and LBER_DEFAULT (expressed using octets 4557 instead of bits). Also fixed a few small bugs in the example code. 4558 4559 Added the following text to all descriptions of the `serverctrls' and 4560 `clientctrls' parameters: ", or NULL if no <server/client> controls 4561 are to be used." 4562 4563 Added the following text to the description of all `dn' and `rdn' 4564 parameters: "If NULL, a zero length DN is sent to the server." 4565 4566 Replaced many occurrences of the phrase "error code" with "result 4567 code" throughout the document. 4568 4569 Added text to indicate that the value of the `msgidp' result parame- 4570 ter is undefined if an error occurs in the following functions: 4571 ldap_sasl_bind(), ldap_search_ext(), ldap_compare_ext(), 4572 ldap_modify_ext(), ldap_add_ext(), ldap_delete_ext(), 4573 ldap_extended_operation(). 4574 4575 Added text to indicate that the `res' result parameter is set to NULL 4576 if an API error occurs in the following functions: ldap_result(), 4577 ldap_search_s(), ldap_search_st(). 4578 4579 Added text to indicate that all result parameters have undefined 4580 values if an API error is returned by the following functions: 4581 ldap_parse_result(), ldap_parse_sasl_bind_result(), 4582 ldap_parse_extended_result(), ldap_parse_reference(), ber_scanf(). 4583 4584 Added angle brackets around ficticious impl_XXX_t types to make it 4585 more obvious that these are not real "C" types, e.g., typedef 4586 <impl_len_t> ber_len_t'. 4587 4588 4589 4590Expires: May 2001 [Page 82] 4591 4592C LDAP API C LDAP Application Program Interface 17 November 2000 4593 4594 4595 Appendix B: Added mod_vals_u and removed PLDAP from the struct, 4596 unions, and typedefs prefix list. 4597 4598 Appendix C: Added note in "Compatibility" section about extensions 4599 possible affecting chains of messages and the fact that that must be 4600 well documented. Appendix D: Improved text for ldap_perror() (what 4601 to use instead). 4602 4603 "Authors" section: updated contact information for Mark Smith, Tim 4604 Howes, and Mark Wahl. 4605 4606 Fixed a few obvious typos, improved indentation, added missing blank 4607 lines, and so on. 4608 4609 4610 4611 4612 4613 4614 4615 4616 4617 4618 4619 4620 4621 4622 4623 4624 4625 4626 4627 4628 4629 4630 4631 4632 4633 4634 4635 4636 4637 4638 4639 4640 4641 4642 4643 4644 4645 4646Expires: May 2001 [Page 83] 4647 4648