idnits 2.17.1 draft-ietf-ldapext-ldap-c-api-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Abstract section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There are 26 instances of too long lines in the document, the longest one being 8 characters in excess of 72. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 289: '... implementations MUST include the foll...' RFC 2119 keyword, line 311: '...is specification SHOULD define a macro...' RFC 2119 keyword, line 318: '...nsion. The name SHOULD NOT begin with...' RFC 2119 keyword, line 339: '...dap_get_option() MUST be the address o...' RFC 2119 keyword, line 353: '...n field of the LDAPAPIInfo MUST be set...' (3 more instances...) == The 'Obsoletes: ' line in the draft header should list only the _numbers_ of the RFCs which will be obsoleted by this document (if approved); it should not include the word 'RFC' in the list. -- The draft header indicates that this document obsoletes RFC1823, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 240 has weird spacing: '...ed long bv_l...' == Line 345 has weird spacing: '... int ldapa...' == Line 346 has weird spacing: '... int ldapa...' == Line 347 has weird spacing: '... int ldapa...' == Line 350 has weird spacing: '... int ldapa...' == (5 more instances...) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (7 August 1998) is 9395 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? '2' on line 2836 looks like a reference -- Missing reference section? '6' on line 2850 looks like a reference -- Missing reference section? '1' on line 2833 looks like a reference -- Missing reference section? '4' on line 2843 looks like a reference -- Missing reference section? '10' on line 2864 looks like a reference -- Missing reference section? '9' on line 2860 looks like a reference -- Missing reference section? '7' on line 2853 looks like a reference -- Missing reference section? '8' on line 2857 looks like a reference -- Missing reference section? '3' on line 2840 looks like a reference -- Missing reference section? '5' on line 2847 looks like a reference -- Missing reference section? '0' on line 2679 looks like a reference -- Missing reference section? '11' on line 3042 looks like a reference Summary: 9 errors (**), 0 flaws (~~), 8 warnings (==), 16 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Smith, Editor 3 INTERNET-DRAFT Netscape Communications Corp. 4 Intended Category: Standards Track T. Howes 5 Obsoletes: RFC 1823 Netscape Communications Corp. 6 Expires: 7 February 1999 A. Herron 7 Microsoft Corp. 8 C. Weider 9 Microsoft Corp. 10 M. Wahl 11 Critical Angle, Inc. 12 A. Anantha 13 Microsoft Corp. 15 7 August 1998 17 The C LDAP Application Program Interface 18 20 1. Status of this Memo 22 This draft document will be submitted to the RFC Editor as a Standards 23 Track document. Distribution of this memo is unlimited. Technical dis- 24 cussion of this document will take place on the IETF LDAP Extension 25 Working Group mailing list . Please send 26 editorial comments directly to the authors. 28 This document is an Internet-Draft. Internet-Drafts are working docu- 29 ments of the Internet Engineering Task Force (IETF), its areas, and its 30 working groups. Note that other groups may also distribute working 31 documents as Internet-Drafts. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference material 36 or to cite them other than as "work in progress." 38 To view the entire list of current Internet-Drafts, please check the 39 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 40 Directories on ftp.is.co.za (Africa), nic.nordu.net (Northern Europe), 41 ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific Rim), or 42 ftp.isi.edu (US West Coast). 44 Copyright (C) The Internet Society (1998). All Rights Reserved. 46 Please see the Copyright section near the end of this document for more 47 information. 49 C LDAP API The C LDAP Application Program Interface 7 August 1998 51 2. Introduction 53 This document defines a C language application program interface (API) 54 to the Lightweight Directory Access Protocol (LDAP). This document 55 replaces the previous definition of this API, defined in RFC 1823, 56 updating it to include support for features found in version 3 of the 57 LDAP protocol. New extended operation functions were added to support 58 LDAPv3 features such as controls. In addition, other LDAP API changes 59 were made to support information hiding and thread safety. 61 The C LDAP API is designed to be powerful, yet simple to use. It defines 62 compatible synchronous and asynchronous interfaces to LDAP to suit a 63 wide variety of applications. This document gives a brief overview of 64 the LDAP model, then an overview of how the API is used by an applica- 65 tion program to obtain LDAP information. The API calls are described in 66 detail, followed by an appendix that provides some example code demon- 67 strating the use of the API. 69 3. Table of Contents 71 1. Status of this Memo............................................1 72 2. Introduction...................................................2 73 3. Table of Contents..............................................2 74 4. Overview of the LDAP Model.....................................3 75 5. Overview of LDAP API Use.......................................4 76 6. Common Data Structures.........................................5 77 7. Retrieving Information About the API Implementation............6 78 7.1. Retrieving Information at Compile Time......................6 79 7.2. Retrieving Information During Execution.....................7 80 8. LDAP Error Codes...............................................9 81 9. Performing LDAP Operations.....................................10 82 9.1. Initializing an LDAP Session................................10 83 9.2. LDAP Session Handle Options.................................11 84 9.3. Working with controls.......................................15 85 9.4. Authenticating to the directory.............................16 86 9.5. Closing the session.........................................19 87 9.6. Searching...................................................19 88 9.7. Reading an Entry............................................23 89 9.8. Listing the Children of an Entry............................23 90 9.9. Comparing a Value Against an Entry..........................23 91 9.10. Modifying an entry..........................................25 92 9.11. Modifying the Name of an Entry..............................28 93 9.12. Adding an entry.............................................30 94 9.13. Deleting an entry...........................................31 95 9.14. Extended Operations.........................................33 96 10. Abandoning An Operation........................................34 97 11. Obtaining Results and Peeking Inside LDAP Messages.............35 98 12. Handling Errors and Parsing Results............................37 99 C LDAP API The C LDAP Application Program Interface 7 August 1998 101 13. Stepping Through a List of Results.............................40 102 14. Parsing Search Results.........................................41 103 14.1. Stepping Through a List of Entries..........................41 104 14.2. Stepping Through the Attributes of an Entry.................42 105 14.3. Retrieving the Values of an Attribute.......................43 106 14.4. Retrieving the name of an entry.............................44 107 14.5. Retrieving controls from an entry...........................45 108 14.6. Parsing References..........................................46 109 15. Encoded ASN.1 Value Manipulation...............................47 110 15.1. General.....................................................47 111 15.2. Encoding....................................................48 112 15.3. Encoding Example............................................51 113 15.4. Decoding....................................................52 114 15.5. Decoding Example............................................54 115 16. Security Considerations........................................56 116 17. Acknowledgements...............................................57 117 18. Copyright......................................................57 118 19. Bibliography...................................................58 119 20. Authors' Addresses.............................................58 120 21. Appendix A - Sample LDAP API Code..............................59 121 22. Appendix B - Namespace Consumed By This Specification..........61 122 23. Appendix C - Outstanding Issues................................61 123 23.1. Support for multithreaded applications......................61 124 23.2. Using Transport Layer Security (TLS)........................62 125 23.3. Client control for chasing referrals........................62 126 23.4. Potential confusion between hostname:port and IPv6 addresses62 127 23.5. Need to track SASL API standardization efforts..............62 128 23.6. Support for character sets other than UTF-8?................62 129 23.7. LDAP Session Handle Options.................................62 130 23.8. Re-bind function is not sufficiently general purpose........63 131 23.9. LDAP C API extension mechanism should be clearly specified..63 132 24. Appendix D - Changes Made Since Last Document Revision.........63 133 24.1. API Changes.................................................63 134 24.2. Editorial changes...........................................64 136 4. Overview of the LDAP Model 138 LDAP is the lightweight directory access protocol, described in [2] and 139 [6]. It can provide a lightweight frontend to the X.500 directory [1], 140 or a stand-alone service. In either mode, LDAP is based on a client- 141 server model in which a client makes a TCP connection to an LDAP server, 142 over which it sends requests and receives responses. 144 The LDAP information model is based on the entry, which contains infor- 145 mation about some object (e.g., a person). Entries are composed of 146 attributes, which have a type and one or more values. Each attribute has 147 C LDAP API The C LDAP Application Program Interface 7 August 1998 149 a syntax that determines what kinds of values are allowed in the attri- 150 bute (e.g., ASCII characters, a jpeg photograph, etc.) and how those 151 values behave during directory operations (e.g., is case significant 152 during comparisons). 154 Entries may be organized in a tree structure, usually based on politi- 155 cal, geographical, and organizational boundaries. Each entry is uniquely 156 named relative to its sibling entries by its relative distinguished name 157 (RDN) consisting of one or more distinguished attribute values from the 158 entry. At most one value from each attribute may be used in the RDN. 159 For example, the entry for the person Babs Jensen might be named with 160 the "Barbara Jensen" value from the commonName attribute. 162 A globally unique name for an entry, called a distinguished name or DN, 163 is constructed by concatenating the sequence of RDNs from the entry up 164 to the root of the tree. For example, if Babs worked for the University 165 of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen, 166 o=University of Michigan, c=US". The DN format used by LDAP is defined 167 in [4]. 169 Operations are provided to authenticate, search for and retrieve infor- 170 mation, modify information, and add and delete entries from the tree. 171 The next sections give an overview of how the API is used and detailed 172 descriptions of the LDAP API calls that implement all of these func- 173 tions. 175 5. Overview of LDAP API Use 177 An application generally uses the C LDAP API in four simple steps. 179 - Initialize an LDAP session with a primary LDAP server. The 180 ldap_init() function returns a handle to the session, allowing mul- 181 tiple connections to be open at once. 183 - Authenticate to the LDAP server. The ldap_bind() function and 184 friends support a variety of authentication methods. 186 - Perform some LDAP operations and obtain some results. ldap_search() 187 and friends return results which can be parsed by 188 ldap_parse_result(), ldap_first_entry(), ldap_next_entry(), etc. 190 - Close the session. The ldap_unbind() function closes the connec- 191 tion. 193 Operations can be performed either synchronously or asynchronously. The 194 names of the synchronous functions end in _s. For example, a synchronous 195 search can be completed by calling ldap_search_s(). An asynchronous 196 C LDAP API The C LDAP Application Program Interface 7 August 1998 198 search can be initiated by calling ldap_search(). All synchronous rou- 199 tines return an indication of the outcome of the operation (e.g, the 200 constant LDAP_SUCCESS or some other error code). The asynchronous rou- 201 tines make available to the caller the message id of the operation ini- 202 tiated. This id can be used in subsequent calls to ldap_result() to 203 obtain the result(s) of the operation. An asynchronous operation can be 204 abandoned by calling ldap_abandon() or ldap_abandon_ext(). 206 Results and errors are returned in an opaque structure called LDAPMes- 207 sage. Routines are provided to parse this structure, step through 208 entries and attributes returned, etc. Routines are also provided to 209 interpret errors. Later sections of this document describe these rou- 210 tines in more detail. 212 LDAP version 3 servers may return referrals to other servers. By 213 default, implementations of this API will attempt to follow referrals 214 automatically for the application. This behavior can be disabled glo- 215 bally (using the ldap_set_option() call) or on a per-request basis 216 through the use of a client control. 218 As in the LDAPv3 protocol itself, all DNs and string values that are 219 passed into or produced by the C LDAP API are represented as UTF-8[10] 220 characters. Some LDAP API implementations may support other character 221 sets, but the mechanisms used are not currently specified in this docu- 222 ment. 224 For compatibility with existing applications, implementations of this 225 API will by default use version 2 of the LDAP protocol. Applications 226 that intend to take advantage of LDAP version 3 features will need to 227 use the ldap_set_option() call with a LDAP_OPT_PROTOCOL_VERSION to 228 switch to version 3. 230 6. Common Data Structures 232 Some data structures that are common to several LDAP API functions are 233 defined here: 235 typedef struct ldap LDAP; 237 typedef struct ldapmsg LDAPMessage; 239 struct berval { 240 unsigned long bv_len; 241 char *bv_val; 242 }; 244 struct timeval { 246 C LDAP API The C LDAP Application Program Interface 7 August 1998 248 long tv_sec; 249 long tv_usec; 250 }; 252 The LDAP structure is an opaque data type that represents an LDAP ses- 253 sion Typically this corresponds to a connection to a single server, but 254 it may encompass several server connections in the face of LDAPv3 refer- 255 rals. 257 The LDAPMessage structure is an opaque data type that is used to return 258 entry, reference, result, and error information. An LDAPMessage struc- 259 ture may represent the beginning of a list, or chain of messages that 260 consists of a series of entries, references, and result messages as 261 returned by LDAP operations such as search. LDAP API functions such as 262 ldap_parse_result() that operate on message chains that may contain more 263 than one result message always operate on the first result message in 264 the chain. See the "Obtaining Results and Peeking Inside LDAP Messages" 265 section of this document for more information. 267 The berval structure is used to represent arbitrary binary data and its 268 fields have the following meanings: 270 bv_len Length of data in bytes. 272 bv_val A pointer to the data itself. 274 The timeval structure is used to represent an interval of time and its 275 fields have the following meanings: 277 tv_sec Seconds component of time interval. 279 tv_usec Microseconds component of time interval. 281 7. Retrieving Information About the API Implementation 283 Applications developed to this specification need to be able to deter- 284 mine information about the particular API implementation they are using 285 both at compile time and during execution. 287 7.1. Retrieving Information at Compile Time 289 All conformant implementations MUST include the following definition in 290 a header file so compile time tests can be done by LDAP software 291 developers: 293 C LDAP API The C LDAP Application Program Interface 7 August 1998 295 #define LDAP_API_VERSION level 297 where "level" is replaced with the RFC number given to this LDAP C API 298 specification when it is published as a standards track RFC. For exam- 299 ple, if this specification is published as RFC 88888, conformant imple- 300 mentations will include a macro definition like this: 302 #define LDAP_API_VERSION 88888 304 and application code can test the LDAP C API version level using a 305 construct such as this one: 307 #if (LDAP_API_VERSION > 88888) 308 /* use features supported in RFC 88888 or later */ 309 #endif 311 Documents that extend this specification SHOULD define a macro of the 312 form: 314 #define LDAP_API_FEATURE_x level 316 where "x" is replaced with a name (textual identifier) for the feature 317 and "level" is replaced with the number of the RFC that specifies the 318 API extension. The name SHOULD NOT begin with the string "X_". 320 For example, if LDAP C API extensions for Transport Layer Security [9] 321 were published in RFC 99999, that RFC might require conformant implemen- 322 tations to define a macro like this: 324 #define LDAP_API_FEATURE_TLS 99999 326 Private or experimental API extensions may be indicated by defining a 327 macro of this same form where "x" (the extension's name) begins with the 328 string "X_" and "level" is replaced with a integer number that is 329 specific to the extension. 331 7.2. Retrieving Information During Execution 333 The ldap_get_option() call (described in greater detail later in this 334 document) can be used during execution in conjunction with an option 335 parameter value of LDAP_OPT_API_INFO (0x00) to retrieve some basic 336 information about the API and about the specific implementation being 337 used. The ld parameter to ldap_get_option() can be either NULL or a 338 valid LDAP session handle which was obtained by calling ldap_init(). 339 The optdata parameter to ldap_get_option() MUST be the address of an 340 C LDAP API The C LDAP Application Program Interface 7 August 1998 342 LDAPAPIInfo structure which is defined as follows: 344 typedef struct ldapapiinfo { 345 int ldapai_info_version; /* version of LDAPAPIInfo (1) */ 346 int ldapai_api_version; /* revision of API supported */ 347 int ldapai_protocol_version; /* highest LDAP version supported */ 348 char **ldapai_extensions; /* names of API extensions */ 349 char *ldapi_vendor_name; /* name of supplier */ 350 int ldapai_vendor_version; /* supplier-specific version times 100 */ 351 } LDAPAPIInfo; 353 Note that the ldapai_info_version field of the LDAPAPIInfo MUST be set 354 to the value 1 before calling ldap_get_option(). All other fields are 355 set by the ldap_get_option() function. 357 The members of the LDAPAPIInfo structure are: 359 ldapai_info_version 360 A number that identifies the version of the LDAPAPIInfo struc- 361 ture. This MUST be set to the value 1 before calling 362 ldap_get_option(). 364 ldapai_api_version 365 A number that matches that assigned to the LDAP C API RFC sup- 366 ported by the API implementation. This should match the value 367 of the LDAP_API_VERSION macro defined earlier. 369 ldapai_protocol_version 370 The highest LDAP protocol version supported by the implementa- 371 tion. For example, if LDAPv3 is the highest version supported 372 then this field will be set to 3. 374 ldapai_extensions 375 A NULL-terminated array of character strings that lists the 376 names of the API extensions supported by the LDAP API imple- 377 mentation. These names will typically match the textual iden- 378 tifiers that appear in the "x" portion of the 379 LDAP_API_FEATURE_x macros described above, although the pre- 380 cise value MUST be defined by documents that specify LDAP C 381 API extensions. If no API extensions are supported, this 382 field will be set to NULL. The caller is reponsible for 383 disposing of the memory occupied by this array by passing it 384 to ldap_value_free() which is described later in this docu- 385 ment. 387 ldapi_vendor_name 388 A zero-terminated string that contains the name of the party 389 that produced the LDAP API implementation. This field may be 391 C LDAP API The C LDAP Application Program Interface 7 August 1998 393 set to NULL if no name is available. If non-NULL, the caller 394 is responsible for disposing of the memory occupied by passing 395 this pointer to ldap_memfree() which is described later in 396 this document. 398 ldapai_vendor_version 399 An implementation-specific version number multiplied by 100. 400 For example, if the implementation version is 4.0 then this 401 field will be set to 400. If no version information is avail- 402 able, this field will be set to 0. 404 8. LDAP Error Codes 406 Many of the LDAP API routines return LDAP error codes, some of which 407 indicate local errors and some of which may be returned by servers. All 408 of the LDAP error codes returned will be positive integers. Supported 409 error codes are (hexadecimal values are given in parentheses after the 410 constant): 412 LDAP_SUCCESS (0x00) 413 LDAP_OPERATIONS_ERROR (0x01) 414 LDAP_PROTOCOL_ERROR (0x02) 415 LDAP_TIMELIMIT_EXCEEDED (0x03) 416 LDAP_SIZELIMIT_EXCEEDED (0x04) 417 LDAP_COMPARE_FALSE (0x05) 418 LDAP_COMPARE_TRUE (0x06) 419 LDAP_STRONG_AUTH_NOT_SUPPORTED (0x07) 420 LDAP_STRONG_AUTH_REQUIRED (0x08) 421 LDAP_REFERRAL (0x0a) -- new in LDAPv3 422 LDAP_ADMINLIMIT_EXCEEDED (0x0b) -- new in LDAPv3 423 LDAP_UNAVAILABLE_CRITICAL_EXTENSION (0x0c) -- new in LDAPv3 424 LDAP_CONFIDENTIALITY_REQUIRED (0x0d) -- new in LDAPv3 425 LDAP_SASL_BIND_IN_PROGRESS (0x0e) -- new in LDAPv3 426 LDAP_NO_SUCH_ATTRIBUTE (0x10) 427 LDAP_UNDEFINED_TYPE (0x11) 428 LDAP_INAPPROPRIATE_MATCHING (0x12) 429 LDAP_CONSTRAINT_VIOLATION (0x13) 430 LDAP_TYPE_OR_VALUE_EXISTS (0x14) 431 LDAP_INVALID_SYNTAX (0x15) 432 LDAP_NO_SUCH_OBJECT (0x20) 433 LDAP_ALIAS_PROBLEM (0x21) 434 LDAP_INVALID_DN_SYNTAX (0x22) 435 LDAP_IS_LEAF (0x23) -- not used in LDAPv3 436 LDAP_ALIAS_DEREF_PROBLEM (0x24) 437 LDAP_INAPPROPRIATE_AUTH (0x30) 438 LDAP_INVALID_CREDENTIALS (0x31) 439 LDAP_INSUFFICIENT_ACCESS (0x32) 441 C LDAP API The C LDAP Application Program Interface 7 August 1998 443 LDAP_BUSY (0x33) 444 LDAP_UNAVAILABLE (0x34) 445 LDAP_UNWILLING_TO_PERFORM (0x35) 446 LDAP_LOOP_DETECT (0x36) 447 LDAP_NAMING_VIOLATION (0x40) 448 LDAP_OBJECT_CLASS_VIOLATION (0x41) 449 LDAP_NOT_ALLOWED_ON_NONLEAF (0x42) 450 LDAP_NOT_ALLOWED_ON_RDN (0x43) 451 LDAP_ALREADY_EXISTS (0x44) 452 LDAP_NO_OBJECT_CLASS_MODS (0x45) 453 LDAP_RESULTS_TOO_LARGE (0x46) -- reserved for CLDAP 454 LDAP_AFFECTS_MULTIPLE_DSAS (0x47) -- new in LDAPv3 455 LDAP_OTHER (0x50) 456 LDAP_SERVER_DOWN (0x51) 457 LDAP_LOCAL_ERROR (0x52) 458 LDAP_ENCODING_ERROR (0x53) 459 LDAP_DECODING_ERROR (0x54) 460 LDAP_TIMEOUT (0x55) 461 LDAP_AUTH_UNKNOWN (0x56) 462 LDAP_FILTER_ERROR (0x57) 463 LDAP_USER_CANCELLED (0x58) 464 LDAP_PARAM_ERROR (0x59) 465 LDAP_NO_MEMORY (0x5a) 466 LDAP_CONNECT_ERROR (0x5b) 467 LDAP_NOT_SUPPORTED (0x5c) 468 LDAP_CONTROL_NOT_FOUND (0x5d) 469 LDAP_NO_RESULTS_RETURNED (0x5e) 470 LDAP_MORE_RESULTS_TO_RETURN (0x5f) 471 LDAP_CLIENT_LOOP (0x60) 472 LDAP_REFERRAL_LIMIT_EXCEEDED (0x61) 474 9. Performing LDAP Operations 476 This section describes each LDAP operation API call in detail. All func- 477 tions take a "session handle," a pointer to an LDAP structure containing 478 per-connection information. Many routines return results in an LDAPMes- 479 sage structure. These structures and others are described as needed 480 below. 482 9.1. Initializing an LDAP Session 484 ldap_init() initializes a session with an LDAP server. The server is not 485 actually contacted until an operation is performed that requires it, 486 allowing various options to be set after initialization. 488 LDAP *ldap_init( 490 C LDAP API The C LDAP Application Program Interface 7 August 1998 492 char *hostname, 493 int portno 494 ); 496 Use of the following routine is deprecated. 498 LDAP *ldap_open( 499 char *hostname, 500 int portno 501 ); 503 Parameters are: 505 hostname Contains a space-separated list of hostnames or dotted strings 506 representing the IP address of hosts running an LDAP server to 507 connect to. Each hostname in the list can include an optional 508 port number which is separated from the host itself with a 509 colon (:) character. The hosts are tried in the order listed, 510 stopping with the first one to which a successful connection is 511 made. Note that only ldap_open() attempts to make the connec- 512 tion before returning to the caller. ldap_init() does not con- 513 nect to the LDAP server. 515 portno Contains the TCP port number to connect to. The default LDAP 516 port of 389 can be obtained by supplying the constant 517 LDAP_PORT. If a host includes a port number then this parame- 518 ter is ignored. 520 ldap_init() and ldap_open() both return a "session handle," a pointer to 521 an opaque structure that should be passed to subsequent calls pertaining 522 to the session. These routines return NULL if the session cannot be ini- 523 tialized in which case the operating system error reporting mechanism 524 can be checked to see why the call failed. 526 Note that if you connect to an LDAPv2 server, one of the ldap_bind() 527 calls described below must be completed before other operations can be 528 performed on the session. LDAPv3 does not require that a bind operation 529 be completed before other operations can be performed. 531 The calling program can set various attributes of the session by calling 532 the routines described in the next section. 534 9.2. LDAP Session Handle Options 536 The LDAP session handle returned by ldap_init() is a pointer to an 537 opaque data type representing an LDAP session. Formerly, this data type 538 was a structure exposed to the caller, and various fields in the 539 C LDAP API The C LDAP Application Program Interface 7 August 1998 541 structure could be set to control aspects of the session, such as size 542 and time limits on searches. 544 In the interest of insulating callers from inevitable changes to this 545 structure, these aspects of the session are now accessed through a pair 546 of accessor functions, described below. 548 ldap_get_option() is used to access the current value of various 549 session-wide parameters. ldap_set_option() is used to set the value of 550 these parameters. Note that some options are READ-ONLY and cannot be 551 set; it is an error to call ldap_set_option() and attempt to set a 552 READ-ONLY option. 554 int ldap_get_option( 555 LDAP *ld, 556 int option, 557 void *outvalue 558 ); 560 int ldap_set_option( 561 LDAP *ld, 562 int option, 563 void *invalue 564 ); 566 Parameters are: 568 ld The session handle. If this is NULL, a set of global defaults is 569 accessed. New LDAP session handles created with ldap_init() or 570 ldap_open() inherit their characteristics from these global 571 defaults. 573 option The name of the option being accessed or set. This parameter 574 should be one of the following constants, which have the indi- 575 cated meanings. After the constant the actual hexadecimal value 576 of the constant is listed in parentheses. 578 LDAP_OPT_DESC (0x01) 579 Type for invalue parameter: not applicable (option is READ-ONLY) 581 Type for outvalue parameter: int * 583 Description: 584 The underlying socket descriptor corresponding to the primary 585 LDAP connection. This option is READ-ONLY and cannot be set. 587 LDAP_OPT_DEREF (0x02) 588 Type for invalue parameter: int * 590 C LDAP API The C LDAP Application Program Interface 7 August 1998 592 Type for outvalue parameter: int * 594 Description: 595 Determines how aliases are handled during search. It can have 596 one of the following values: LDAP_DEREF_NEVER (0x00), 597 LDAP_DEREF_SEARCHING (0x01), LDAP_DEREF_FINDING (0x02), or 598 LDAP_DEREF_ALWAYS (0x03). The LDAP_DEREF_SEARCHING value 599 means aliases should be dereferenced during the search but 600 not when locating the base object of the search. The 601 LDAP_DEREF_FINDING value means aliases should be dereferenced 602 when locating the base object but not during the search. 604 LDAP_OPT_SIZELIMIT (0x03) 605 Type for invalue parameter: int * 607 Type for outvalue parameter: int * 609 Description: 610 A limit on the number of entries to return from a search. A 611 value of LDAP_NO_LIMIT (0) means no limit. 613 LDAP_OPT_TIMELIMIT (0x04) 614 Type for invalue parameter: int * 616 Type for outvalue parameter: int * 618 Description: 619 A limit on the number of seconds to spend on a search. A 620 value of LDAP_NO_LIMIT (0) means no limit 622 LDAP_OPT_REFERRALS (0x08) 623 Type for invalue parameter: int (LDAP_OPT_ON or LDAP_OPT_OFF) 625 Type for outvalue parameter: int * 627 Description: 628 Determines whether the LDAP library automatically follows 629 referrals returned by LDAP servers or not. It can be set to 630 one of the constants LDAP_OPT_ON (1) or LDAP_OPT_OFF (0). 632 LDAP_OPT_RESTART (0x09) 633 Type for invalue parameter: int (LDAP_OPT_ON or LDAP_OPT_OFF) 635 Type for outvalue parameter: int * 637 Description: 638 Determines whether LDAP I/O operations should automatically 639 be restarted if they abort prematurely. It should be set to 641 C LDAP API The C LDAP Application Program Interface 7 August 1998 643 one of the constants LDAP_OPT_ON or LDAP_OPT_OFF. This option 644 is useful if an LDAP I/O operation may be interrupted prema- 645 turely, for example by a timer going off, or other interrupt. 647 LDAP_OPT_PROTOCOL_VERSION (0x11) 648 Type for invalue parameter: int * 650 Type for outvalue parameter: int * 652 Description: 653 This option indicates the version of the LDAP protocol used 654 when communicating with the primary LDAP server. It must be 655 one of the constants LDAP_VERSION2 (2) or LDAP_VERSION3 (3). 656 If no version is set the default is LDAP_VERSION2 (2). 658 LDAP_OPT_SERVER_CONTROLS (0x12) 659 Type for invalue parameter: LDAPControl ** 661 Type for outvalue parameter: LDAPControl *** 663 Description: 664 A default list of LDAP server controls to be sent with each 665 request. See the Using Controls section below. 667 LDAP_OPT_CLIENT_CONTROLS (0x13) 668 Type for invalue parameter: LDAPControl ** 670 Type for outvalue parameter: LDAPControl *** 672 Description: 673 A default list of client controls that affect the LDAP ses- 674 sion. See the Using Controls section below. 676 LDAP_OPT_HOST_NAME (0x30) 677 Type for invalue parameter: char * 679 Type for outvalue parameter: char ** 681 Description: 682 The host name (or list of host) for the primary LDAP server. 684 LDAP_OPT_ERROR_NUMBER (0x31) 685 Type for invalue parameter: int * 687 Type for outvalue parameter: int * 689 Description: 690 The code of the most recent LDAP error that occurred for this 692 C LDAP API The C LDAP Application Program Interface 7 August 1998 694 session. 696 LDAP_OPT_ERROR_STRING (0x32) 697 Type for invalue parameter: char * 699 Type for outvalue parameter: char ** 701 Description: 702 The message returned with the most recent LDAP error that 703 occurred for this session. 705 outvalue The address of a place to put the value of the option. The 706 actual type of this parameter depends on the setting of the 707 option parameter. For outvalues of type char * and LDAPCon- 708 trol *, a pointer to data that is associated with the LDAP 709 session ld is returned; there is no need to dispose of the 710 memory by calling ldap_memfree() or ldap_controls_free(). 712 invalue A pointer to the value the option is to be given. The actual 713 type of this parameter depends on the setting of the option 714 parameter. The constants LDAP_OPT_ON and LDAP_OPT_OFF can be 715 given for options that have on or off settings. 717 Both ldap_get_option() and ldap_set_option() return 0 if successful and 718 -1 if an error occurs. 720 9.3. Working with controls 722 LDAPv3 operations can be extended through the use of controls. Controls 723 may be sent to a server or returned to the client with any LDAP message. 724 These controls are referred to as server controls. 726 The LDAP API also supports a client-side extension mechanism through the 727 use of client controls. These controls affect the behavior of the LDAP 728 API only and are never sent to a server. A common data structure is 729 used to represent both types of controls: 731 typedef struct ldapcontrol { 732 char *ldctl_oid; 733 struct berval ldctl_value; 734 char ldctl_iscritical; 735 } LDAPControl, *PLDAPControl; 737 The fields in the ldapcontrol structure have the following meanings: 739 ldctl_oid The control type, represented as a string. 741 C LDAP API The C LDAP Application Program Interface 7 August 1998 743 ldctl_value The data associated with the control (if any). To 744 specify a zero-length value, set ldctl_value.bv_len to 745 zero and ldctl_value.bv_val to a zero-length string. 746 To indicate that no data is associated with the con- 747 trol, set ldctl_value.bv_val to NULL. 749 ldctl_iscritical Indicates whether the control is critical of not. If 750 this field is non-zero, the operation will only be car- 751 ried out if the control is recognized by the server 752 and/or client. 754 Some LDAP API calls allocate an ldapcontrol structure or a NULL- 755 terminated array of ldapcontrol structures. The following routines can 756 be used to dispose of a single control or an array of controls: 758 void ldap_control_free( LDAPControl *ctrl ); 759 void ldap_controls_free( LDAPControl **ctrls ); 761 A set of controls that affect the entire session can be set using the 762 ldap_set_option() function (see above). A list of controls can also be 763 passed directly to some LDAP API calls such as ldap_search_ext(), in 764 which case any controls set for the session through the use of 765 ldap_set_option() are ignored. Control lists are represented as a NULL- 766 terminated array of pointers to ldapcontrol structures. 768 Server controls are defined by LDAPv3 protocol extension documents; for 769 example, a control has been proposed to support server-side sorting of 770 search results [7]. 772 No client controls are defined by this document but they may be defined 773 in future revisions or in any document that extends this API. 775 9.4. Authenticating to the directory 777 The following functions are used to authenticate an LDAP client to an 778 LDAP directory server. 780 The ldap_sasl_bind() and ldap_sasl_bind_s() functions can be used to do 781 general and extensible authentication over LDAP through the use of the 782 Simple Authentication Security Layer [8]. The routines both take the dn 783 to bind as, the method to use, as a dotted-string representation of an 784 OID identifying the method, and a struct berval holding the credentials. 785 The special constant value LDAP_SASL_SIMPLE (NULL) can be passed to 786 request simple authentication, or the simplified routines 787 ldap_simple_bind() or ldap_simple_bind_s() can be used. 789 int ldap_sasl_bind( 791 C LDAP API The C LDAP Application Program Interface 7 August 1998 793 LDAP *ld, 794 char *dn, 795 char *mechanism, 796 struct berval *cred, 797 LDAPControl **serverctrls, 798 LDAPControl **clientctrls, 799 int *msgidp 800 ); 802 int ldap_sasl_bind_s( 803 LDAP *ld, 804 char *dn, 805 char *mechanism, 806 struct berval *cred, 807 LDAPControl **serverctrls, 808 LDAPControl **clientctrls, 809 struct berval **servercredp 810 ); 812 int ldap_simple_bind( 813 LDAP *ld, 814 char *dn, 815 char *passwd 816 ); 818 int ldap_simple_bind_s( 819 LDAP *ld, 820 char *dn, 821 char *passwd 822 ); 824 The use of the following routines is deprecated: 826 int ldap_bind( LDAP *ld, char *dn, char *cred, int method ); 828 int ldap_bind_s( LDAP *ld, char *dn, char *cred, int method ); 830 int ldap_kerberos_bind( LDAP *ld, char *dn ); 832 int ldap_kerberos_bind_s( LDAP *ld, char *dn ); 834 Parameters are: 836 ld The session handle. 838 dn The name of the entry to bind as. 840 mechanism Either LDAP_SASL_SIMPLE (NULL) to get simple 841 C LDAP API The C LDAP Application Program Interface 7 August 1998 843 authentication, or a text string identifying the SASL 844 method. 846 cred The credentials with which to authenticate. Arbitrary 847 credentials can be passed using this parameter. The format 848 and content of the credentials depends on the setting of 849 the mechanism parameter. 851 passwd For ldap_simple_bind(), the password to compare to the 852 entry's userPassword attribute. 854 serverctrls List of LDAP server controls. 856 clientctrls List of client controls. 858 msgidp This result parameter will be set to the message id of the 859 request if the ldap_sasl_bind() call succeeds. 861 servercredp This result parameter will be filled in with the creden- 862 tials passed back by the server for mutual authentication, 863 if given. An allocated berval structure is returned that 864 should be disposed of by calling ber_bvfree(). NULL may be 865 passed to ignore this field. 867 Additional parameters for the deprecated routines are not described. 868 Interested readers are referred to RFC 1823. 870 The ldap_sasl_bind() function initiates an asynchronous bind operation 871 and returns the constant LDAP_SUCCESS if the request was successfully 872 sent, or another LDAP error code if not. See the section below on error 873 handling for more information about possible errors and how to interpret 874 them. If successful, ldap_sasl_bind() places the message id of the 875 request in *msgidp. A subsequent call to ldap_result(), described below, 876 can be used to obtain the result of the bind. 878 The ldap_simple_bind() function initiates a simple asynchronous bind 879 operation and returns the message id of the operation initiated. A sub- 880 sequent call to ldap_result(), described below, can be used to obtain 881 the result of the bind. In case of error, ldap_simple_bind() will return 882 -1, setting the session error parameters in the LDAP structure appropri- 883 ately. 885 The synchronous ldap_sasl_bind_s() and ldap_simple_bind_s() functions 886 both return the result of the operation, either the constant 887 LDAP_SUCCESS if the operation was successful, or another LDAP error code 888 if it was not. See the section below on error handling for more informa- 889 tion about possible errors and how to interpret them. 891 C LDAP API The C LDAP Application Program Interface 7 August 1998 893 Note that if an LDAPv2 server is contacted, no other operations over the 894 connection should be attempted before a bind call has successfully com- 895 pleted. 897 Subsequent bind calls can be used to re-authenticate over the same con- 898 nection, and multistep SASL sequences can be accomplished through a 899 sequence of calls to ldap_sasl_bind() or ldap_sasl_bind_s(). 901 9.5. Closing the session 903 The following functions are used to unbind from the directory, close the 904 connection, and dispose of the session handle. 906 int ldap_unbind( LDAP *ld ); 908 int ldap_unbind_s( LDAP *ld ); 910 Parameters are: 912 ld The session handle. 914 ldap_unbind() and ldap_unbind_s() both work synchronously, unbinding 915 from the directory, closing the connection, and freeing up the ld struc- 916 ture before returning. There is no server response to an unbind opera- 917 tion. ldap_unbind() returns LDAP_SUCCESS (or another LDAP error code if 918 the request cannot be sent to the LDAP server). After a call to 919 ldap_unbind() or ldap_unbind_s(), the session handle ld is invalid and 920 it is illegal to make any further LDAP API calls using ld. 922 9.6. Searching 924 The following functions are used to search the LDAP directory, returning 925 a requested set of attributes for each entry matched. There are five 926 variations. 928 int ldap_search_ext( 929 LDAP *ld, 930 char *base, 931 int scope, 932 char *filter, 933 char **attrs, 934 int attrsonly, 935 LDAPControl **serverctrls, 936 LDAPControl **clientctrls, 937 struct timeval *timeout, 939 C LDAP API The C LDAP Application Program Interface 7 August 1998 941 int sizelimit, 942 int *msgidp 943 ); 945 int ldap_search_ext_s( 946 LDAP *ld, 947 char *base, 948 int scope, 949 char *filter, 950 char **attrs, 951 int attrsonly, 952 LDAPControl **serverctrls, 953 LDAPControl **clientctrls, 954 struct timeval *timeout, 955 int sizelimit, 956 LDAPMessage **res 957 ); 959 int ldap_search( 960 LDAP *ld, 961 char *base, 962 int scope, 963 char *filter, 964 char **attrs, 965 int attrsonly 966 ); 968 int ldap_search_s( 969 LDAP *ld, 970 char *base, 971 int scope, 972 char *filter, 973 char **attrs, 974 int attrsonly, 975 LDAPMessage **res 976 ); 978 int ldap_search_st( 979 LDAP *ld, 980 char *base, 981 int scope, 982 char *filter, 983 char **attrs, 984 int attrsonly, 985 struct timeval *timeout, 986 LDAPMessage **res 987 ); 989 C LDAP API The C LDAP Application Program Interface 7 August 1998 991 Parameters are: 993 ld The session handle. 995 base The dn of the entry at which to start the search. 997 scope One of LDAP_SCOPE_BASE (0x00), LDAP_SCOPE_ONELEVEL (0x01), 998 or LDAP_SCOPE_SUBTREE (0x02), indicating the scope of the 999 search. 1001 filter A character string as described in [3], representing the 1002 search filter. The value NULL can be passed to indicate 1003 that the filter "(objectclass=*)" which matches all entries 1004 should be used. 1006 attrs A NULL-terminated array of strings indicating which attri- 1007 butes to return for each matching entry. Passing NULL for 1008 this parameter causes all available user attributes to be 1009 retrieved. The special constant string LDAP_NO_ATTRS 1010 ("1.1") can be used as the only in the array to indicate 1011 that no attribute types should be returned by the server. 1012 The special constant string LDAP_ALL_USER_ATTRS ("*") can 1013 be used in the attrs array along with the names of some 1014 operational attributes to indicate that all user attributes 1015 plus the listed operational attributes should be returned. 1017 attrsonly A boolean value that should be zero if both attribute types 1018 and values are to be returned, non-zero if only types are 1019 wanted. 1021 timeout For the ldap_search_st() function, this specifies the local 1022 search timeout value (if it is NULL, the timeout is infin- 1023 ite). For the ldap_search_ext() and ldap_search_ext_s() 1024 functions, this specifies both the local search timeout 1025 value and the operation time limit that is sent to the 1026 server within the search request. For the 1027 ldap_search_ext() and ldap_search_ext_s() functions, pass- 1028 ing a NULL value for timeout causes the global default 1029 timeout stored in the LDAP session handle to be used (set 1030 by using ldap_set_option() with the LDAP_OPT_TIMELIMIT 1031 parameter). 1033 sizelimit For the ldap_search_ext() and ldap_search_ext_s() calls, 1034 this is a limit on the number of entries to return from the 1035 search. A value of LDAP_NO_LIMIT (0) means no limit. 1037 res For the synchronous calls, this is a result parameter which 1038 will contain the results of the search upon completion of 1040 C LDAP API The C LDAP Application Program Interface 7 August 1998 1042 the call. 1044 serverctrls List of LDAP server controls. 1046 clientctrls List of client controls. 1048 msgidp This result parameter will be set to the message id of the 1049 request if the ldap_search_ext() call succeeds. 1051 There are three options in the session handle ld which potentially 1052 affect how the search is performed. They are: 1054 LDAP_OPT_SIZELIMIT 1055 A limit on the number of entries to return from the search. 1056 A value of LDAP_NO_LIMIT (0) means no limit. Note that the 1057 value from the session handle is ignored when using the 1058 ldap_search_ext() or ldap_search_ext_s() functions. 1060 LDAP_OPT_TIMELIMIT 1061 A limit on the number of seconds to spend on the search. A 1062 value of LDAP_NO_LIMIT (0) means no limit. Note that the 1063 value from the session handle is ignored when using the 1064 ldap_search_ext() or ldap_search_ext_s() functions. 1066 LDAP_OPT_DEREF 1067 One of LDAP_DEREF_NEVER (0x00), LDAP_DEREF_SEARCHING 1068 (0x01), LDAP_DEREF_FINDING (0x02), or LDAP_DEREF_ALWAYS 1069 (0x03), specifying how aliases should be handled during the 1070 search. The LDAP_DEREF_SEARCHING value means aliases should 1071 be dereferenced during the search but not when locating the 1072 base object of the search. The LDAP_DEREF_FINDING value 1073 means aliases should be dereferenced when locating the base 1074 object but not during the search. 1076 The ldap_search_ext() function initiates an asynchronous search opera- 1077 tion and returns the constant LDAP_SUCCESS if the request was success- 1078 fully sent, or another LDAP error code if not. See the section below on 1079 error handling for more information about possible errors and how to 1080 interpret them. If successful, ldap_search_ext() places the message id 1081 of the request in *msgidp. A subsequent call to ldap_result(), described 1082 below, can be used to obtain the results from the search. These results 1083 can be parsed using the result parsing routines described in detail 1084 later. 1086 Similar to ldap_search_ext(), the ldap_search() function initiates an 1087 asynchronous search operation and returns the message id of the opera- 1088 tion initiated. As for ldap_search_ext(), a subsequent call to 1089 ldap_result(), described below, can be used to obtain the result of the 1090 C LDAP API The C LDAP Application Program Interface 7 August 1998 1092 bind. In case of error, ldap_search() will return -1, setting the ses- 1093 sion error parameters in the LDAP structure appropriately. 1095 The synchronous ldap_search_ext_s(), ldap_search_s(), and 1096 ldap_search_st() functions all return the result of the operation, 1097 either the constant LDAP_SUCCESS if the operation was successful, or 1098 another LDAP error code if it was not. See the section below on error 1099 handling for more information about possible errors and how to interpret 1100 them. Entries returned from the search (if any) are contained in the 1101 res parameter. This parameter is opaque to the caller. Entries, attri- 1102 butes, values, etc., should be extracted by calling the parsing routines 1103 described below. The results contained in res should be freed when no 1104 longer in use by calling ldap_msgfree(), described later. 1106 The ldap_search_ext() and ldap_search_ext_s() functions support LDAPv3 1107 server controls, client controls, and allow varying size and time limits 1108 to be easily specified for each search operation. The ldap_search_st() 1109 function is identical to ldap_search_s() except that it takes an addi- 1110 tional parameter specifying a local timeout for the search. The local 1111 search timeout is used to limit the amount of time the API implementa- 1112 tion will wait for a search to complete. After the local search timeout 1113 expires, the API implementation will send an abandon operation to abort 1114 the search operation. 1116 9.7. Reading an Entry 1118 LDAP does not support a read operation directly. Instead, this operation 1119 is emulated by a search with base set to the DN of the entry to read, 1120 scope set to LDAP_SCOPE_BASE, and filter set to "(objectclass=*)" or 1121 NULL. attrs contains the list of attributes to return. 1123 9.8. Listing the Children of an Entry 1125 LDAP does not support a list operation directly. Instead, this operation 1126 is emulated by a search with base set to the DN of the entry to list, 1127 scope set to LDAP_SCOPE_ONELEVEL, and filter set to "(objectclass=*)" or 1128 NULL. attrs contains the list of attributes to return for each child 1129 entry. 1131 9.9. Comparing a Value Against an Entry 1133 The following routines are used to compare a given attribute value 1134 assertion against an LDAP entry. There are four variations: 1136 int ldap_compare_ext( 1137 LDAP *ld, 1138 char *dn, 1140 C LDAP API The C LDAP Application Program Interface 7 August 1998 1142 char *attr, 1143 struct berval *bvalue 1144 LDAPControl **serverctrls, 1145 LDAPControl **clientctrls, 1146 int *msgidp 1147 ); 1149 int ldap_compare_ext_s( 1150 LDAP *ld, 1151 char *dn, 1152 char *attr, 1153 struct berval *bvalue, 1154 LDAPControl **serverctrls, 1155 LDAPControl **clientctrls 1156 ); 1158 int ldap_compare( 1159 LDAP *ld, 1160 char *dn, 1161 char *attr, 1162 char *value 1163 ); 1165 int ldap_compare_s( 1166 LDAP *ld, 1167 char *dn, 1168 char *attr, 1169 char *value 1170 ); 1172 Parameters are: 1174 ld The session handle. 1176 dn The name of the entry to compare against. 1178 attr The attribute to compare against. 1180 bvalue The attribute value to compare against those found in the 1181 given entry. This parameter is used in the extended rou- 1182 tines and is a pointer to a struct berval so it is possible 1183 to compare binary values. 1185 value A string attribute value to compare against, used by the 1186 ldap_compare() and ldap_compare_s() functions. Use 1187 ldap_compare_ext() or ldap_compare_ext_s() if you need to 1188 compare binary values. 1190 C LDAP API The C LDAP Application Program Interface 7 August 1998 1192 serverctrls List of LDAP server controls. 1194 clientctrls List of client controls. 1196 msgidp This result parameter will be set to the message id of the 1197 request if the ldap_compare_ext() call succeeds. 1199 The ldap_compare_ext() function initiates an asynchronous compare opera- 1200 tion and returns the constant LDAP_SUCCESS if the request was success- 1201 fully sent, or another LDAP error code if not. See the section below on 1202 error handling for more information about possible errors and how to 1203 interpret them. If successful, ldap_compare_ext() places the message id 1204 of the request in *msgidp. A subsequent call to ldap_result(), described 1205 below, can be used to obtain the result of the compare. 1207 Similar to ldap_compare_ext(), the ldap_compare() function initiates an 1208 asynchronous compare operation and returns the message id of the opera- 1209 tion initiated. As for ldap_compare_ext(), a subsequent call to 1210 ldap_result(), described below, can be used to obtain the result of the 1211 bind. In case of error, ldap_compare() will return -1, setting the ses- 1212 sion error parameters in the LDAP structure appropriately. 1214 The synchronous ldap_compare_ext_s() and ldap_compare_s() functions both 1215 return the result of the operation, either the constant LDAP_SUCCESS if 1216 the operation was successful, or another LDAP error code if it was not. 1217 See the section below on error handling for more information about pos- 1218 sible errors and how to interpret them. 1220 The ldap_compare_ext() and ldap_compare_ext_s() functions support LDAPv3 1221 server controls and client controls. 1223 9.10. Modifying an entry 1225 The following routines are used to modify an existing LDAP entry. There 1226 are four variations: 1228 typedef struct ldapmod { 1229 int mod_op; 1230 char *mod_type; 1231 union { 1232 char **modv_strvals; 1233 struct berval **modv_bvals; 1234 } mod_vals; 1235 } LDAPMod; 1236 #define mod_values mod_vals.modv_strvals 1237 #define mod_bvalues mod_vals.modv_bvals 1239 C LDAP API The C LDAP Application Program Interface 7 August 1998 1241 int ldap_modify_ext( 1242 LDAP *ld, 1243 char *dn, 1244 LDAPMod **mods, 1245 LDAPControl **serverctrls, 1246 LDAPControl **clientctrls, 1247 int *msgidp 1248 ); 1250 int ldap_modify_ext_s( 1251 LDAP *ld, 1252 char *dn, 1253 LDAPMod **mods, 1254 LDAPControl **serverctrls, 1255 LDAPControl **clientctrls 1256 ); 1258 int ldap_modify( 1259 LDAP *ld, 1260 char *dn, 1261 LDAPMod **mods 1262 ); 1264 int ldap_modify_s( 1265 LDAP *ld, 1266 char *dn, 1267 LDAPMod **mods 1268 ); 1270 Parameters are: 1272 ld The session handle. 1274 dn The name of the entry to modify. 1276 mods A NULL-terminated array of modifications to make to the 1277 entry. 1279 serverctrls List of LDAP server controls. 1281 clientctrls List of client controls. 1283 msgidp This result parameter will be set to the message id of the 1284 request if the ldap_modify_ext() call succeeds. 1286 The fields in the LDAPMod structure have the following meanings: 1288 mod_op The modification operation to perform. It should be one of 1289 C LDAP API The C LDAP Application Program Interface 7 August 1998 1291 LDAP_MOD_ADD (0x00), LDAP_MOD_DELETE (0x01), or 1292 LDAP_MOD_REPLACE (0x02). This field also indicates the 1293 type of values included in the mod_vals union. It is logi- 1294 cally ORed with LDAP_MOD_BVALUES (0x80) to select the 1295 mod_bvalues form. Otherwise, the mod_values form is used. 1297 mod_type The type of the attribute to modify. 1299 mod_vals The values (if any) to add, delete, or replace. Only one of 1300 the mod_values or mod_bvalues variants should be used, 1301 selected by ORing the mod_op field with the constant 1302 LDAP_MOD_BVALUES. mod_values is a NULL-terminated array of 1303 zero-terminated strings and mod_bvalues is a NULL- 1304 terminated array of berval structures that can be used to 1305 pass binary values such as images. 1307 For LDAP_MOD_ADD modifications, the given values are added to the 1308 entry, creating the attribute if necessary. 1310 For LDAP_MOD_DELETE modifications, the given values are deleted from the 1311 entry, removing the attribute if no values remain. If the entire attri- 1312 bute is to be deleted, the mod_vals field should be set to NULL. 1314 For LDAP_MOD_REPLACE modifications, the attribute will have the listed 1315 values after the modification, having been created if necessary, or 1316 removed if the mod_vals field is NULL. All modifications are performed 1317 in the order in which they are listed. 1319 The ldap_modify_ext() function initiates an asynchronous modify opera- 1320 tion and returns the constant LDAP_SUCCESS if the request was success- 1321 fully sent, or another LDAP error code if not. See the section below on 1322 error handling for more information about possible errors and how to 1323 interpret them. If successful, ldap_modify_ext() places the message id 1324 of the request in *msgidp. A subsequent call to ldap_result(), described 1325 below, can be used to obtain the result of the modify. 1327 Similar to ldap_modify_ext(), the ldap_modify() function initiates an 1328 asynchronous modify operation and returns the message id of the opera- 1329 tion initiated. As for ldap_modify_ext(), a subsequent call to 1330 ldap_result(), described below, can be used to obtain the result of the 1331 modify. In case of error, ldap_modify() will return -1, setting the ses- 1332 sion error parameters in the LDAP structure appropriately. 1334 The synchronous ldap_modify_ext_s() and ldap_modify_s() functions both 1335 return the result of the operation, either the constant LDAP_SUCCESS if 1336 the operation was successful, or another LDAP error code if it was not. 1337 See the section below on error handling for more information about pos- 1338 sible errors and how to interpret them. 1340 C LDAP API The C LDAP Application Program Interface 7 August 1998 1342 The ldap_modify_ext() and ldap_modify_ext_s() functions support LDAPv3 1343 server controls and client controls. 1345 9.11. Modifying the Name of an Entry 1347 In LDAPv2, the ldap_modrdn() and ldap_modrdn_s() routines were used to 1348 change the name of an LDAP entry. They could only be used to change the 1349 least significant component of a name (the RDN or relative distinguished 1350 name). LDAPv3 provides the Modify DN protocol operation that allows more 1351 general name change access. The ldap_rename() and ldap_rename_s() rou- 1352 tines are used to change the name of an entry, and the use of the 1353 ldap_modrdn() and ldap_modrdn_s() routines is deprecated. 1355 int ldap_rename( 1356 LDAP *ld, 1357 char *dn, 1358 char *newrdn, 1359 char *newparent, 1360 int deleteoldrdn, 1361 LDAPControl **serverctrls, 1362 LDAPControl **clientctrls, 1363 int *msgidp 1365 ); 1366 int ldap_rename_s( 1367 LDAP *ld, 1368 char *dn, 1369 char *newrdn, 1370 char *newparent, 1371 int deleteoldrdn, 1372 LDAPControl **serverctrls, 1373 LDAPControl **clientctrls 1374 ); 1376 Use of the following routines is deprecated. 1378 int ldap_modrdn( 1379 LDAP *ld, 1380 char *dn, 1381 char *newrdn, 1382 int deleteoldrdn 1383 ); 1384 int ldap_modrdn_s( 1385 LDAP *ld, 1386 char *dn, 1387 char *newrdn, 1388 int deleteoldrdn 1390 C LDAP API The C LDAP Application Program Interface 7 August 1998 1392 ); 1394 Parameters are: 1396 ld The session handle. 1398 dn The name of the entry whose DN is to be changed. 1400 newrdn The new RDN to give the entry. 1402 newparent The new parent, or superior entry. If this parameter is 1403 NULL, only the RDN of the entry is changed. The root DN 1404 may be specified by passing a zero length string, "". The 1405 newparent parameter should always be NULL when using ver- 1406 sion 2 of the LDAP protocol; otherwise the server's 1407 behavior is undefined. 1409 deleteoldrdn This parameter only has meaning on the rename routines if 1410 newrdn is different than the old RDN. It is a boolean 1411 value, if non-zero indicating that the old RDN value(s) 1412 should be removed, if zero indicating that the old RDN 1413 value(s) should be retained as non-distinguished values of 1414 the entry. 1416 serverctrls List of LDAP server controls. 1418 clientctrls List of client controls. 1420 msgidp This result parameter will be set to the message id of the 1421 request if the ldap_rename() call succeeds. 1423 The ldap_rename() function initiates an asynchronous modify DN operation 1424 and returns the constant LDAP_SUCCESS if the request was successfully 1425 sent, or another LDAP error code if not. See the section below on error 1426 handling for more information about possible errors and how to interpret 1427 them. If successful, ldap_rename() places the DN message id of the 1428 request in *msgidp. A subsequent call to ldap_result(), described below, 1429 can be used to obtain the result of the rename. 1431 The synchronous ldap_rename_s() returns the result of the operation, 1432 either the constant LDAP_SUCCESS if the operation was successful, or 1433 another LDAP error code if it was not. See the section below on error 1434 handling for more information about possible errors and how to interpret 1435 them. 1437 The ldap_rename() and ldap_rename_s() functions both support LDAPv3 1438 server controls and client controls. 1440 C LDAP API The C LDAP Application Program Interface 7 August 1998 1442 9.12. Adding an entry 1444 The following functions are used to add entries to the LDAP directory. 1445 There are four variations: 1447 int ldap_add_ext( 1448 LDAP *ld, 1449 char *dn, 1450 LDAPMod **attrs, 1451 LDAPControl **serverctrls, 1452 LDAPControl **clientctrls, 1453 int *msgidp 1454 ); 1456 int ldap_add_ext_s( 1457 LDAP *ld, 1458 char *dn, 1459 LDAPMod **attrs, 1460 LDAPControl **serverctrls, 1461 LDAPControl **clientctrls 1462 ); 1464 int ldap_add( 1465 LDAP *ld, 1466 char *dn, 1467 LDAPMod **attrs 1468 ); 1470 int ldap_add_s( 1471 LDAP *ld, 1472 char *dn, 1473 LDAPMod **attrs 1474 ); 1476 Parameters are: 1478 ld The session handle. 1480 dn The name of the entry to add. 1482 attrs The entry's attributes, specified using the LDAPMod struc- 1483 ture defined for ldap_modify(). The mod_type and mod_vals 1484 fields should be filled in. The mod_op field is ignored 1485 unless ORed with the constant LDAP_MOD_BVALUES, used to 1486 select the mod_bvalues case of the mod_vals union. 1488 serverctrls List of LDAP server controls. 1490 C LDAP API The C LDAP Application Program Interface 7 August 1998 1492 clientctrls List of client controls. 1494 msgidp This result parameter will be set to the message id of the 1495 request if the ldap_add_ext() call succeeds. 1497 Note that the parent of the entry being added must already exist or the 1498 parent must be empty (i.e., equal to the root DN) for an add to succeed. 1500 The ldap_add_ext() function initiates an asynchronous add operation and 1501 returns the constant LDAP_SUCCESS if the request was successfully sent, 1502 or another LDAP error code if not. See the section below on error han- 1503 dling for more information about possible errors and how to interpret 1504 them. If successful, ldap_add_ext() places the message id of the 1505 request in *msgidp. A subsequent call to ldap_result(), described below, 1506 can be used to obtain the result of the add. 1508 Similar to ldap_add_ext(), the ldap_add() function initiates an asyn- 1509 chronous add operation and returns the message id of the operation ini- 1510 tiated. As for ldap_add_ext(), a subsequent call to ldap_result(), 1511 described below, can be used to obtain the result of the add. In case of 1512 error, ldap_add() will return -1, setting the session error parameters 1513 in the LDAP structure appropriately. 1515 The synchronous ldap_add_ext_s() and ldap_add_s() functions both return 1516 the result of the operation, either the constant LDAP_SUCCESS if the 1517 operation was successful, or another LDAP error code if it was not. See 1518 the section below on error handling for more information about possible 1519 errors and how to interpret them. 1521 The ldap_add_ext() and ldap_add_ext_s() functions support LDAPv3 server 1522 controls and client controls. 1524 9.13. Deleting an entry 1526 The following functions are used to delete a leaf entry from the LDAP 1527 directory. There are four variations: 1529 int ldap_delete_ext( 1530 LDAP *ld, 1531 char *dn, 1532 LDAPControl **serverctrls, 1533 LDAPControl **clientctrls, 1534 int *msgidp 1535 ); 1537 int ldap_delete_ext_s( 1539 C LDAP API The C LDAP Application Program Interface 7 August 1998 1541 LDAP *ld, 1542 char *dn, 1543 LDAPControl **serverctrls, 1544 LDAPControl **clientctrls 1545 ); 1547 int ldap_delete( 1548 LDAP *ld, 1549 char *dn 1550 ); 1552 int ldap_delete_s( 1553 LDAP *ld, 1554 char *dn 1555 ); 1557 Parameters are: 1559 ld The session handle. 1561 dn The name of the entry to delete. 1563 serverctrls List of LDAP server controls. 1565 clientctrls List of client controls. 1567 msgidp This result parameter will be set to the message id of the 1568 request if the ldap_delete_ext() call succeeds. 1570 Note that the entry to delete must be a leaf entry (i.e., it must have 1571 no children). Deletion of entire subtrees in a single operation is not 1572 supported by LDAP. 1574 The ldap_delete_ext() function initiates an asynchronous delete opera- 1575 tion and returns the constant LDAP_SUCCESS if the request was success- 1576 fully sent, or another LDAP error code if not. See the section below on 1577 error handling for more information about possible errors and how to 1578 interpret them. If successful, ldap_delete_ext() places the message id 1579 of the request in *msgidp. A subsequent call to ldap_result(), described 1580 below, can be used to obtain the result of the delete. 1582 Similar to ldap_delete_ext(), the ldap_delete() function initiates an 1583 asynchronous delete operation and returns the message id of the opera- 1584 tion initiated. As for ldap_delete_ext(), a subsequent call to 1585 ldap_result(), described below, can be used to obtain the result of the 1586 delete. In case of error, ldap_delete() will return -1, setting the ses- 1587 sion error parameters in the LDAP structure appropriately. 1589 C LDAP API The C LDAP Application Program Interface 7 August 1998 1591 The synchronous ldap_delete_ext_s() and ldap_delete_s() functions both 1592 return the result of the operation, either the constant LDAP_SUCCESS if 1593 the operation was successful, or another LDAP error code if it was not. 1594 See the section below on error handling for more information about pos- 1595 sible errors and how to interpret them. 1597 The ldap_delete_ext() and ldap_delete_ext_s() functions support LDAPv3 1598 server controls and client controls. 1600 9.14. Extended Operations 1602 The ldap_extended_operation() and ldap_extended_operation_s() routines 1603 allow extended LDAP operations to be passed to the server, providing a 1604 general protocol extensibility mechanism. 1606 int ldap_extended_operation( 1607 LDAP *ld, 1608 char *exoid, 1609 struct berval *exdata, 1610 LDAPControl **serverctrls, 1611 LDAPControl **clientctrls, 1612 int *msgidp 1613 ); 1615 int ldap_extended_operation_s( 1616 LDAP *ld, 1617 char *exoid, 1618 struct berval *exdata, 1619 LDAPControl **serverctrls, 1620 LDAPControl **clientctrls, 1621 char **retoidp, 1622 struct berval **retdatap 1623 ); 1625 Parameters are: 1627 ld The session handle. 1629 requestoid The dotted-OID text string naming the request. 1631 requestdata The arbitrary data required by the operation (if NULL, no 1632 data is sent to the server). 1634 serverctrls List of LDAP server controls. 1636 clientctrls List of client controls. 1638 C LDAP API The C LDAP Application Program Interface 7 August 1998 1640 msgidp This result parameter will be set to the message id of the 1641 request if the ldap_extended_operation() call succeeds. 1643 retoidp Pointer to a character string that will be set to an allo- 1644 cated, dotted-OID text string returned by the server. This 1645 string should be disposed of using the ldap_memfree() func- 1646 tion. If no OID was returned, *retoidp is set to NULL. 1648 retdatap Pointer to a berval structure pointer that will be set an 1649 allocated copy of the data returned by the server. This 1650 struct berval should be disposed of using ber_bvfree(). If 1651 no data is returned, *retdatap is set to NULL. 1653 The ldap_extended_operation() function initiates an asynchronous 1654 extended operation and returns the constant LDAP_SUCCESS if the request 1655 was successfully sent, or another LDAP error code if not. See the sec- 1656 tion below on error handling for more information about possible errors 1657 and how to interpret them. If successful, ldap_extended_operation() 1658 places the message id of the request in *msgidp. A subsequent call to 1659 ldap_result(), described below, can be used to obtain the result of the 1660 extended operation which can be passed to ldap_parse_extended_result() 1661 to obtain the OID and data contained in the response. 1663 The synchronous ldap_extended_operation_s() function returns the result 1664 of the operation, either the constant LDAP_SUCCESS if the operation was 1665 successful, or another LDAP error code if it was not. See the section 1666 below on error handling for more information about possible errors and 1667 how to interpret them. The retoid and retdata parameters are filled in 1668 with the OID and data from the response. If no OID or data was 1669 returned, these parameters are set to NULL. 1671 The ldap_extended_operation() and ldap_extended_operation_s() functions 1672 both support LDAPv3 server controls and client controls. 1674 10. Abandoning An Operation 1676 The following calls are used to abandon an operation in progress: 1678 int ldap_abandon_ext( 1679 LDAP *ld, 1680 int msgid, 1681 LDAPControl **serverctrls, 1682 LDAPControl **clientctrls 1683 ); 1685 int ldap_abandon( 1686 LDAP *ld, 1688 C LDAP API The C LDAP Application Program Interface 7 August 1998 1690 int msgid 1691 ); 1693 ld The session handle. 1695 msgid The message id of the request to be abandoned. 1697 serverctrls List of LDAP server controls. 1699 clientctrls List of client controls. 1701 ldap_abandon_ext() abandons the operation with message id msgid and 1702 returns the constant LDAP_SUCCESS if the abandon was successful or 1703 another LDAP error code if not. See the section below on error handling 1704 for more information about possible errors and how to interpret them. 1706 ldap_abandon() is identical to ldap_abandon_ext() except that it does 1707 not accept client or server controls and it returns zero if the abandon 1708 was successful, -1 otherwise and does not support LDAPv3 server controls 1709 or client controls. 1711 After a successful call to ldap_abandon() or ldap_abandon_ext(), results 1712 with the given message id are never returned from a subsequent call to 1713 ldap_result(). There is no server response to LDAP abandon operations. 1715 11. Obtaining Results and Peeking Inside LDAP Messages 1717 ldap_result() is used to obtain the result of a previous asynchronously 1718 initiated operation. Note that depending on how it is called, 1719 ldap_result() may actually return a list or "chain" of result messages. 1720 Once a chain of messages has been returned to the caller, it is no 1721 longer tied in any caller-visible way to the LDAP request that produced 1722 it. Therefore, a chain of messages returned by calling ldap_result() or 1723 by calling a synchronous search routine will never be affected by subse- 1724 quent LDAP API calls (except for ldap_msgfree() which is used to dispose 1725 of a chain of messages). 1727 ldap_msgfree() frees the result messages (possibly an entire chain of 1728 messages) obtained from a previous call to ldap_result() or from a call 1729 to a synchronous search routine. 1731 ldap_msgtype() returns the type of an LDAP message. ldap_msgid() 1732 returns the message ID of an LDAP message. 1734 int ldap_result( 1735 LDAP *ld, 1737 C LDAP API The C LDAP Application Program Interface 7 August 1998 1739 int msgid, 1740 int all, 1741 struct timeval *timeout, 1742 LDAPMessage **res 1743 ); 1745 int ldap_msgfree( LDAPMessage *res ); 1747 int ldap_msgtype( LDAPMessage *res ); 1749 int ldap_msgid( LDAPMessage *res ); 1751 Parameters are: 1753 ld The session handle. 1755 msgid The message id of the operation whose results are to be 1756 returned, or the constant LDAP_RES_ANY (-1) if any result is 1757 desired. 1759 all Specifies how many messages will be retrieved in a single call 1760 to ldap_result(). This parameter only has meaning for search 1761 results. Pass the constant LDAP_MSG_ONE (0x00) to retrieve one 1762 message at a time. Pass LDAP_MSG_ALL (0x01) to request that 1763 all results of a search be received before returning all 1764 results in a single chain. Pass LDAP_MSG_RECEIVED (0x02) to 1765 indicate that all results retrieved so far should be returned 1766 in the result chain. 1768 timeout A timeout specifying how long to wait for results to be 1769 returned. A NULL value causes ldap_result() to block until 1770 results are available. A timeout value of zero seconds speci- 1771 fies a polling behavior. 1773 res For ldap_result(), a result parameter that will contain the 1774 result(s) of the operation. For ldap_msgfree(), the result 1775 chain to be freed, obtained from a previous call to 1776 ldap_result(), ldap_search_s(), or ldap_search_st(). 1778 Upon successful completion, ldap_result() returns the type of the first 1779 result returned in the res parameter. This will be one of the following 1780 constants. 1782 LDAP_RES_BIND (0x61) 1783 LDAP_RES_SEARCH_ENTRY (0x64) 1784 LDAP_RES_SEARCH_REFERENCE (0x73) -- new in LDAPv3 1785 LDAP_RES_SEARCH_RESULT (0x65) 1786 LDAP_RES_MODIFY (0x67) 1788 C LDAP API The C LDAP Application Program Interface 7 August 1998 1790 LDAP_RES_ADD (0x69) 1791 LDAP_RES_DELETE (0x6B) 1792 LDAP_RES_MODDN (0x6D) 1793 LDAP_RES_COMPARE (0x6F) 1794 LDAP_RES_EXTENDED (0x78) -- new in LDAPv3 1796 ldap_result() returns 0 if the timeout expired and -1 if an error 1797 occurs, in which case the error parameters of the LDAP session handle 1798 will be set accordingly. 1800 ldap_msgfree() frees the result structure pointed to by res and returns 1801 the type of the message it freed. 1803 ldap_msgtype() returns the type of the LDAP message it is passed as a 1804 parameter. The type will be one of the types listed above, or -1 on 1805 error. 1807 ldap_msgid() returns the message ID associated with the LDAP message 1808 passed as a parameter. 1810 12. Handling Errors and Parsing Results 1812 The following calls are used to extract information from results and 1813 handle errors returned by other LDAP API routines. Note that 1814 ldap_parse_sasl_bind_result() and ldap_parse_extended_result() must typ- 1815 ically be used in addition to ldap_parse_result() to retrieve all the 1816 result information from SASL Bind and Extended Operations respectively. 1818 int ldap_parse_result( 1819 LDAP *ld, 1820 LDAPMessage *res, 1821 int *errcodep, 1822 char **matcheddnp, 1823 char **errmsgp, 1824 char ***referralsp, 1825 LDAPControl ***serverctrlsp, 1826 int freeit 1827 ); 1829 int ldap_parse_sasl_bind_result( 1830 LDAP *ld, 1831 LDAPMessage *res, 1832 struct berval **servercredp, 1833 int freeit 1834 ); 1836 int ldap_parse_extended_result( 1838 C LDAP API The C LDAP Application Program Interface 7 August 1998 1840 LDAP *ld, 1841 LDAPMessage *res, 1842 char **resultoidp, 1843 struct berval **resultdata, 1844 int freeit 1845 ); 1847 char *ldap_err2string( int err ); 1849 The use of the following routines is deprecated. 1851 int ldap_result2error( 1852 LDAP *ld, 1853 LDAPMessage *res, 1854 int freeit 1855 ); 1857 void ldap_perror( LDAP *ld, char *msg ); 1859 Parameters are: 1861 ld The session handle. 1863 res The result of an LDAP operation as returned by 1864 ldap_result() or one of the synchronous API operation 1865 calls. 1867 errcodep This result parameter will be filled in with the LDAP error 1868 code field from the LDAPResult message. This is the indi- 1869 cation from the server of the outcome of the operation. 1870 NULL may be passed to ignore this field. 1872 matcheddnp In the case of a return of LDAP_NO_SUCH_OBJECT, this result 1873 parameter will be filled in with a DN indicating how much 1874 of the name in the request was recognized. NULL may be 1875 passed to ignore this field. The matched DN string should 1876 be freed by calling ldap_memfree() which is described later 1877 in this document. 1879 errmsgp This result parameter will be filled in with the contents 1880 of the error message field from the LDAPResult message. 1881 The error message string should be freed by calling 1882 ldap_memfree() which is described later in this document. 1883 NULL may be passed to ignore this field. 1885 referralsp This result parameter will be filled in with the contents 1886 of the referrals field from the LDAPResult message, indi- 1887 cating zero or more alternate LDAP servers where the 1889 C LDAP API The C LDAP Application Program Interface 7 August 1998 1891 request should be retried. The referrals array should be 1892 freed by calling ldap_value_free() which is described later 1893 in this document. NULL may be passed to ignore this field. 1895 serverctrlsp This result parameter will be filled in with an allocated 1896 array of controls copied out of the LDAPResult message. 1897 The control array should be freed by calling 1898 ldap_controls_free() which was described earlier. 1900 freeit A boolean that determines whether the res parameter is 1901 disposed of or not. Pass any non-zero value to have these 1902 routines free res after extracting the requested informa- 1903 tion. This is provided as a convenience; you can also use 1904 ldap_msgfree() to free the result later. If freeit is 1905 non-zero, the entire chain of messages represented by res 1906 is disposed of. 1908 servercredp For SASL bind results, this result parameter will be filled 1909 in with the credentials passed back by the server for 1910 mutual authentication, if given. An allocated berval struc- 1911 ture is returned that should be disposed of by calling 1912 ber_bvfree(). NULL may be passed to ignore this field. 1914 resultoidp For extended results, this result parameter will be filled 1915 in with the dotted-OID text representation of the name of 1916 the extended operation response. This string should be 1917 disposed of by calling ldap_memfree(). NULL may be passed 1918 to ignore this field. 1920 resultdatap For extended results, this result parameter will be filled 1921 in with a pointer to a struct berval containing the data in 1922 the extended operation response. It should be disposed of 1923 by calling ber_bvfree(). NULL may be passed to ignore this 1924 field. 1926 err For ldap_err2string(), an LDAP error code, as returned by 1927 ldap_parse_result() or another LDAP API call. 1929 Additional parameters for the deprecated routines are not described. 1930 Interested readers are referred to RFC 1823. 1932 All three of the ldap_parse_*_result() routines skip over messages of 1933 type LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_REFERENCE when looking 1934 for a result message to parse. They return the constant LDAP_SUCCESS if 1935 the result was successfully parsed and another LDAP error code if not. 1936 Note that the LDAP error code that indicates the outcome of the opera- 1937 tion performed by the server is placed in the errcodep 1938 ldap_parse_result() parameter. If a chain of messages that contains 1939 C LDAP API The C LDAP Application Program Interface 7 August 1998 1941 more than one result message is passed to these routines they always 1942 operate on the first result in the chain. 1944 ldap_err2string() is used to convert a numeric LDAP error code, as 1945 returned by one of the three ldap_parse_*_result() routines, or one of 1946 the synchronous API operation calls, into an informative zero-terminated 1947 character string message describing the error. It returns a pointer to 1948 static data. 1950 13. Stepping Through a List of Results 1952 The ldap_first_message() and ldap_next_message() routines are used to 1953 step through the list of messages in a result chain returned by 1954 ldap_result(). For search operations, the result chain may actually 1955 include referral messages, entry messages, and result messages. 1956 ldap_count_messages() is used to count the number of messages returned. 1957 The ldap_msgtype() function, described above, can be used to distinguish 1958 between the different message types. 1960 LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *res ); 1962 LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *msg ); 1964 int ldap_count_messages( LDAP *ld, LDAPMessage *res ); 1966 Parameters are: 1968 ld The session handle. 1970 res The result chain, as obtained by a call to one of the synchronous 1971 search routines or ldap_result(). 1973 msg The message returned by a previous call to ldap_first_message() 1974 or ldap_next_message(). 1976 ldap_first_message() and ldap_next_message() will return NULL when no 1977 more messages exist in the result set to be returned. NULL is also 1978 returned if an error occurs while stepping through the entries, in which 1979 case the error parameters in the session handle ld will be set to indi- 1980 cate the error. 1982 ldap_count_messages() returns the number of messages contained in a 1983 chain of results. It can also be used to count the number of messages 1984 that remain in a chain if called with a message, entry, or reference 1985 returned by ldap_first_message(), ldap_next_message(), 1986 ldap_first_entry(), ldap_next_entry(), ldap_first_reference(), 1987 ldap_next_reference(). 1989 C LDAP API The C LDAP Application Program Interface 7 August 1998 1991 14. Parsing Search Results 1993 The following calls are used to parse the entries and references 1994 returned by ldap_search() and friends. These results are returned in an 1995 opaque structure that should only be accessed by calling the routines 1996 described below. Routines are provided to step through the entries and 1997 references returned, step through the attributes of an entry, retrieve 1998 the name of an entry, and retrieve the values associated with a given 1999 attribute in an entry. 2001 14.1. Stepping Through a List of Entries 2003 The ldap_first_entry() and ldap_next_entry() routines are used to step 2004 through and retrieve the list of entries from a search result chain. 2005 The ldap_first_reference() and ldap_next_reference() routines are used 2006 to step through and retrieve the list of continuation references from a 2007 search result chain. ldap_count_entries() is used to count the number 2008 of entries returned. ldap_count_references() is used to count the number 2009 of references returned. 2011 LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *res ); 2013 LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry ); 2015 LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *res ); 2017 LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *ref ); 2019 int ldap_count_entries( LDAP *ld, LDAPMessage *res ); 2021 int ldap_count_references( LDAP *ld, LDAPMessage *res ); 2023 Parameters are: 2025 ld The session handle. 2027 res The search result, as obtained by a call to one of the synchro- 2028 nous search routines or ldap_result(). 2030 entry The entry returned by a previous call to ldap_first_entry() or 2031 ldap_next_entry(). 2033 ldap_first_entry() and ldap_next_entry() will return NULL when no more 2034 entries or references exist in the result set to be returned. NULL is 2035 also returned if an error occurs while stepping through the entries, in 2036 which case the error parameters in the session handle ld will be set to 2037 indicate the error. 2039 C LDAP API The C LDAP Application Program Interface 7 August 1998 2041 ldap_count_entries() returns the number of entries contained in a chain 2042 of entries. It can also be used to count the number of entries that 2043 remain in a chain if called with a message, entry or reference returned 2044 by ldap_first_message(), ldap_next_message(), ldap_first_entry(), 2045 ldap_next_entry(), ldap_first_reference(), ldap_next_reference(). 2047 ldap_count_references() returns the number of references contained in a 2048 chain of search results. It can also be used to count the number of 2049 references that remain in a chain. 2051 14.2. Stepping Through the Attributes of an Entry 2053 The ldap_first_attribute() and ldap_next_attribute() calls are used to 2054 step through the list of attribute types returned with an entry. 2056 char *ldap_first_attribute( 2057 LDAP *ld, 2058 LDAPMessage *entry, 2059 BerElement **ptr 2060 ); 2062 char *ldap_next_attribute( 2063 LDAP *ld, 2064 LDAPMessage *entry, 2065 BerElement *ptr 2066 ); 2068 void ldap_memfree( char *mem ); 2070 Parameters are: 2072 ld The session handle. 2074 entry The entry whose attributes are to be stepped through, as returned 2075 by ldap_first_entry() or ldap_next_entry(). 2077 ptr In ldap_first_attribute(), the address of a pointer used inter- 2078 nally to keep track of the current position in the entry. In 2079 ldap_next_attribute(), the pointer returned by a previous call to 2080 ldap_first_attribute(). 2082 mem A pointer to memory allocated by the LDAP library, such as the 2083 attribute type names returned by ldap_first_attribute() and 2084 ldap_next_attribute, or the DN returned by ldap_get_dn(). 2086 ldap_first_attribute() and ldap_next_attribute() will return NULL when 2087 the end of the attributes is reached, or if there is an error, in which 2088 C LDAP API The C LDAP Application Program Interface 7 August 1998 2090 case the error parameters in the session handle ld will be set to indi- 2091 cate the error. 2093 Both routines return a pointer to an allocated buffer containing the 2094 current attribute name. This should be freed when no longer in use by 2095 calling ldap_memfree(). 2097 ldap_first_attribute() will allocate and return in ptr a pointer to a 2098 BerElement used to keep track of the current position. This pointer 2099 should be passed in subsequent calls to ldap_next_attribute() to step 2100 through the entry's attributes. After a set of calls to 2101 ldap_first_attribute() and ldap_next_attribute(), if ptr is non-NULL, it 2102 should be freed by calling ber_free( ptr, 0 ). Note that it is very 2103 important to pass the second parameter as 0 (zero) in this call, since 2104 the buffer associated with the BerElement does not point to separately 2105 allocated memory. 2107 The attribute type names returned are suitable for passing in a call to 2108 ldap_get_values() and friends to retrieve the associated values. 2110 14.3. Retrieving the Values of an Attribute 2112 ldap_get_values() and ldap_get_values_len() are used to retrieve the 2113 values of a given attribute from an entry. ldap_count_values() and 2114 ldap_count_values_len() are used to count the returned values. 2115 ldap_value_free() and ldap_value_free_len() are used to free the values. 2117 char **ldap_get_values( 2118 LDAP *ld, 2119 LDAPMessage *entry, 2120 char *attr 2121 ); 2123 struct berval **ldap_get_values_len( 2124 LDAP *ld, 2125 LDAPMessage *entry, 2126 char *attr 2127 ); 2129 int ldap_count_values( char **vals ); 2131 int ldap_count_values_len( struct berval **vals ); 2133 void ldap_value_free( char **vals ); 2135 void ldap_value_free_len( struct berval **vals ); 2137 C LDAP API The C LDAP Application Program Interface 7 August 1998 2139 Parameters are: 2141 ld The session handle. 2143 entry The entry from which to retrieve values, as returned by 2144 ldap_first_entry() or ldap_next_entry(). 2146 attr The attribute whose values are to be retrieved, as returned by 2147 ldap_first_attribute() or ldap_next_attribute(), or a caller- 2148 supplied string (e.g., "mail"). 2150 vals The values returned by a previous call to ldap_get_values() or 2151 ldap_get_values_len(). 2153 Two forms of the various calls are provided. The first form is only 2154 suitable for use with non-binary character string data. The second _len 2155 form is used with any kind of data. 2157 ldap_get_values() and ldap_get_values_len() return NULL if no values are 2158 found for attr or if an error occurs. 2160 ldap_count_values() and ldap_count_values_len() return -1 if an error 2161 occurs such as the vals parameter being invalid. 2163 Note that the values returned are dynamically allocated and should be 2164 freed by calling either ldap_value_free() or ldap_value_free_len() when 2165 no longer in use. 2167 14.4. Retrieving the name of an entry 2169 ldap_get_dn() is used to retrieve the name of an entry. 2170 ldap_explode_dn() and ldap_explode_rdn() are used to break up a name 2171 into its component parts. ldap_dn2ufn() is used to convert the name into 2172 a more "user friendly" format. 2174 char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ); 2176 char **ldap_explode_dn( char *dn, int notypes ); 2178 char **ldap_explode_rdn( char *rdn, int notypes ); 2180 char *ldap_dn2ufn( char *dn ); 2182 Parameters are: 2184 ld The session handle. 2186 C LDAP API The C LDAP Application Program Interface 7 August 1998 2188 entry The entry whose name is to be retrieved, as returned by 2189 ldap_first_entry() or ldap_next_entry(). 2191 dn The dn to explode, such as returned by ldap_get_dn(). 2193 rdn The rdn to explode, such as returned in the components of the 2194 array returned by ldap_explode_dn(). 2196 notypes A boolean parameter, if non-zero indicating that the dn or rdn 2197 components should have their type information stripped off 2198 (i.e., "cn=Babs" would become "Babs"). 2200 ldap_get_dn() will return NULL if there is some error parsing the dn, 2201 setting error parameters in the session handle ld to indicate the error. 2202 It returns a pointer to newly allocated space that the caller should 2203 free by calling ldap_memfree() when it is no longer in use. Note the 2204 format of the DNs returned is given by [4]. 2206 ldap_explode_dn() returns a NULL-terminated char * array containing the 2207 RDN components of the DN supplied, with or without types as indicated by 2208 the notypes parameter. The components are returned in the order they 2209 appear in the dn. The array returned should be freed when it is no 2210 longer in use by calling ldap_value_free(). 2212 ldap_explode_rdn() returns a NULL-terminated char * array containing the 2213 components of the RDN supplied, with or without types as indicated by 2214 the notypes parameter. The components are returned in the order they 2215 appear in the rdn. The array returned should be freed when it is no 2216 longer in use by calling ldap_value_free(). 2218 ldap_dn2ufn() converts the DN into the user friendly format described in 2219 [5]. The UFN returned is newly allocated space that should be freed by a 2220 call to ldap_memfree() when no longer in use. 2222 14.5. Retrieving controls from an entry 2224 ldap_get_entry_controls() is used to extract LDAP controls from an 2225 entry. 2227 int ldap_get_entry_controls( 2228 LDAP *ld, 2229 LDAPMessage *entry, 2230 LDAPControl ***serverctrlsp 2231 ); 2233 Parameters are: 2235 C LDAP API The C LDAP Application Program Interface 7 August 1998 2237 ld The session handle. 2239 entry The entry to extract controls from, as returned by 2240 ldap_first_entry() or ldap_next_entry(). 2242 serverctrlsp This result parameter will be filled in with an allocated 2243 array of controls copied out of entry. The control array 2244 should be freed by calling ldap_controls_free(). If ser- 2245 verctrlsp is NULL, no controls are returned. 2247 ldap_get_entry_controls() returns an LDAP error code that indicates 2248 whether the reference could be successfully parsed (LDAP_SUCCESS if all 2249 goes well). 2251 14.6. Parsing References 2253 ldap_parse_reference() is used to extract referrals and controls from a 2254 SearchResultReference message. 2256 int ldap_parse_reference( 2257 LDAP *ld, 2258 LDAPMessage *ref, 2259 char ***referralsp, 2260 LDAPControl ***serverctrlsp, 2261 int freeit 2262 ); 2264 Parameters are: 2266 ld The session handle. 2268 ref The reference to parse, as returned by ldap_result(), 2269 ldap_first_reference(), or ldap_next_reference(). 2271 referralsp This result parameter will be filled in with an allocated 2272 array of character strings. The elements of the array are 2273 the referrals (typically LDAP URLs) contained in ref. The 2274 array should be freed when no longer in used by calling 2275 ldap_value_free(). If referralsp is NULL, the referral 2276 URLs are not returned. 2278 serverctrlsp This result parameter will be filled in with an allocated 2279 array of controls copied out of ref. The control array 2280 should be freed by calling ldap_controls_free(). If ser- 2281 verctrlsp is NULL, no controls are returned. 2283 C LDAP API The C LDAP Application Program Interface 7 August 1998 2285 freeit A boolean that determines whether the ref parameter is 2286 disposed of or not. Pass any non-zero value to have these 2287 routines free res after extracting the requested informa- 2288 tion. This is provided as a convenience; you can also use 2289 ldap_msgfree() to free the result later. 2291 ldap_parse_reference() returns an LDAP error code that indicates whether 2292 the reference could be successfully parsed (LDAP_SUCCESS if all goes 2293 well). 2295 15. Encoded ASN.1 Value Manipulation 2297 This section describes routines which may be used to encode and decode 2298 BER-encoded ASN.1 values, which are often used inside of control and 2299 extension values. 2301 With the exceptions of two new functions ber_flatten() and ber_init(), 2302 these functions are compatible with the University of Michigan LDAP 3.3 2303 implementation of BER. 2305 15.1. General 2307 struct berval { 2308 unsigned long bv_len; 2309 char *bv_val; 2310 }; 2312 A struct berval contains a sequence of bytes and an indication of its 2313 length. The bv_val is not null terminated. bv_len must always be a 2314 nonnegative number. Applications may allocate their own berval struc- 2315 tures. 2317 typedef struct berelement { 2318 /* opaque */ 2319 } BerElement; 2321 The BerElement structure contains not only a copy of the encoded value, 2322 but also state information used in encoding or decoding. Applications 2323 cannot allocate their own BerElement structures. The internal state is 2324 neither thread-specific nor locked, so two threads should not manipulate 2325 the same BerElement value simultaneously. 2327 A single BerElement value cannot be used for both encoding and decoding. 2329 void ber_bvfree( struct berval *bv ); 2331 C LDAP API The C LDAP Application Program Interface 7 August 1998 2333 ber_bvfree() frees a berval returned from this API. Both the bv->bv_val 2334 string and the berval itself are freed. Applications should not use 2335 ber_bvfree() with bervals which the application has allocated. 2337 void ber_bvecfree ( struct berval **bv ); 2339 ber_bvecfree() frees an array of bervals returned from this API. Each 2340 of the bervals in the array are freed using ber_bvfree(), then the array 2341 itself is freed. 2343 struct berval *ber_bvdup (struct berval *bv ); 2345 ber_bvdup() returns a copy of a berval. The bv_val field in the 2346 returned berval points to a different area of memory as the bv_val field 2347 in the argument berval. The null pointer is returned on error (e.g. out 2348 of memory). 2350 void ber_free ( BerElement *ber, int fbuf ); 2352 ber_free() frees a BerElement which is returned from the API calls 2353 ber_alloc_t() or ber_init(). Each BerElement must be freed by the 2354 caller. The second argument fbuf should always be set to 1 to ensure 2355 that the internal buffer used by the BER functions is freed as well as 2356 the BerElement container itself. 2358 15.2. Encoding 2360 BerElement *ber_alloc_t(int options); 2362 ber_alloc_t() constructs and returns BerElement. The null pointer is 2363 returned on error. The options field contains a bitwise-or of options 2364 which are to be used when generating the encoding of this BerElement. 2365 One option is defined and must always be supplied: 2367 #define LBER_USE_DER 0x01 2369 When this option is present, lengths will always be encoded in the 2370 minimum number of octets. Note that this option does not cause values 2371 of sets and sequences to be rearranged in tag and byte order, so these 2372 functions are not sufficient for generating DER output as defined in 2373 X.509 and X.680. If the caller takes responsibility for ordering values 2374 of sets and sequences correctly, DER output as defined in X.509 and 2375 X.680 can be produced. 2377 Unrecognized option bits are ignored. 2379 The BerElement returned by ber_alloc_t() is initially empty. Calls to 2380 C LDAP API The C LDAP Application Program Interface 7 August 1998 2382 ber_printf() will append bytes to the end of the ber_alloc_t(). 2384 int ber_printf(BerElement *ber, char *fmt, ... ) 2386 The ber_printf() routine is used to encode a BER element in much the 2387 same way that sprintf() works. One important difference, though, is 2388 that state information is kept in the ber argument so that multiple 2389 calls can be made to ber_printf() to append to the end of the BER ele- 2390 ment. ber must be a pointer to a BerElement returned by ber_alloc_t(). 2391 ber_printf() interprets and formats its arguments according to the for- 2392 mat string fmt. ber_printf() returns -1 if there is an error during 2393 encoding and a positive number if successful. As with sprintf(), each 2394 character in fmt refers to an argument to ber_printf(). 2396 The format string can contain the following format characters: 2398 't' Tag. The next argument is an int specifying the tag to override 2399 the next element to be written to the ber. This works across 2400 calls. The int value must contain the tag class, constructed 2401 bit, and tag value. The tag value must fit in a single octet 2402 (tag value is less than 32). For example, a tag of "[3]" for a 2403 constructed type is 0xA3. 2405 'b' Boolean. The next argument is an int, containing either 0 for 2406 FALSE or 0xff for TRUE. A boolean element is output. If this 2407 format character is not preceded by the 't' format modifier, the 2408 tag 0x01 is used for the element. 2410 'i' Integer. The next argument is an int, containing the integer in 2411 the host's byte order. An integer element is output. If this 2412 format character is not preceded by the 't' format modifier, the 2413 tag 0x02 is used for the element. 2415 'X' Bitstring. The next two arguments are a char * pointer to the 2416 start of the bitstring, followed by an int containing the number 2417 of bits in the bitstring. A bitstring element is output, in 2418 primitive form. If this format character is not preceded by the 2419 't' format modifier, the tag 0x03 is used for the element. 2421 'n' Null. No argument is required. An ASN.1 NULL element is out- 2422 put. If this format character is not preceded by the 't' format 2423 modifier, the tag 0x05 is used for the element. 2425 'o' Octet string. The next two arguments are a char *, followed by 2426 an int with the length of the string. The string may contain 2427 null bytes and need not by zero-terminated. An octet string 2428 element is output, in primitive form. If this format character 2429 is not preceded by the 't' format modifier, the tag 0x04 is used 2431 C LDAP API The C LDAP Application Program Interface 7 August 1998 2433 for the element. 2435 's' Octet string. The next argument is a char * pointing to a 2436 zero-terminated string. An octet string element in primitive 2437 form is output, which does not include the trailing ' ' byte. If 2438 this format character is not preceded by the 't' format modif- 2439 ier, the tag 0x04 is used for the element. 2441 'v' Several octet strings. The next argument is a char **, an array 2442 of char * pointers to zero-terminated strings. The last element 2443 in the array must be a null pointer. The octet strings do not 2444 include the trailing SEQUENCE OF octet strings. The 't' format 2445 modifier cannot be used with this format character. 2447 'V' Several octet strings. A NULL-terminated array of berval *'s is 2448 supplied. Note that a construct like '{V}' is required to get an 2449 actual SEQUENCE OF octet strings. The 't' format modifier cannot 2450 be used with this format character. 2452 '{' Begin sequence. No argument is required. If this format char- 2453 acter is not preceded by the 't' format modifier, the tag 0x30 2454 is used. 2456 '}' End sequence. No argument is required. The 't' format modifier 2457 cannot be used with this format character. 2459 '[' Begin set. No argument is required. If this format character 2460 is not preceded by the 't' format modifier, the tag 0x31 is 2461 used. 2463 ']' End set. No argument is required. The 't' format modifier can- 2464 not be used with this format character. 2466 Each use of a '{' format character must be matched by a '}' character, 2467 either later in the format string, or in the format string of a subse- 2468 quent call to ber_printf() for that BerElement. The same applies to the 2469 '[' and 2471 Sequences and sets nest, and implementations of this API must maintain 2472 internal state to be able to properly calculate the lengths. 2474 int ber_flatten (BerElement *ber, struct berval **bvPtr); 2476 The ber_flatten routine allocates a struct berval whose contents are a 2477 BER encoding taken from the ber argument. The bvPtr pointer points to 2478 the returned berval, which must be freed using ber_bvfree(). This rou- 2479 tine returns 0 on success and -1 on error. 2481 C LDAP API The C LDAP Application Program Interface 7 August 1998 2483 The ber_flatten API call is not present in U-M LDAP 3.3. 2485 The use of ber_flatten on a BerElement in which all '{' and '}' format 2486 modifiers have not been properly matched is an error (i.e., -1 will be 2487 returned by ber_flatten() if this situation is exists). 2489 15.3. Encoding Example 2491 The following is an example of encoding the following ASN.1 data type: 2493 Example1Request ::= SEQUENCE { 2494 s OCTET STRING, -- must be printable 2495 val1 INTEGER, 2496 val2 [0] INTEGER DEFAULT 0 2497 } 2499 int encode_example1(char *s,int val1,int val2,struct berval **bvPtr) 2500 { 2501 BerElement *ber; 2502 int rc; 2504 ber = ber_alloc_t(LBER_USE_DER); 2506 if (ber == NULL) return -1; 2508 if (ber_printf(ber,"{si",s,val1) == -1) { 2509 ber_free(ber,1); 2510 return -1; 2511 } 2513 if (val2 != 0) { 2514 if (ber_printf(ber,"ti",0x80,val2) == -1) { 2515 ber_free(ber,1); 2516 return -1; 2517 } 2518 } 2520 if (ber_printf(ber,"}") == -1) { 2521 ber_free(ber,1); 2522 return -1; 2523 } 2525 rc = ber_flatten(ber,bvPtr); 2526 ber_free(ber,1); 2527 return rc; 2528 } 2530 C LDAP API The C LDAP Application Program Interface 7 August 1998 2532 15.4. Decoding 2534 The following two symbols are available to applications. 2536 #define LBER_ERROR 0xffffffffL 2537 #define LBER_DEFAULT 0xffffffffL 2539 BerElement *ber_init (struct berval *bv); 2541 The ber_init function constructs a BerElement and returns a new BerEle- 2542 ment containing a copy of the data in the bv argument. ber_init returns 2543 the null pointer on error. 2545 unsigned long ber_scanf (BerElement *ber, char *fmt, ... ); 2547 The ber_scanf() routine is used to decode a BER element in much the same 2548 way that sscanf() works. One important difference, though, is that some 2549 state information is kept with the ber argument so that multiple calls 2550 can be made to ber_scanf() to sequentially read from the BER element. 2551 The ber argument must be a pointer to a BerElement returned by 2552 ber_init(). ber_scanf interprets the bytes according to the format 2553 string fmt, and stores the results in its additional arguments. 2554 ber_scanf() returns LBER_ERROR on error, and a different value on suc- 2555 cess. 2557 The format string contains conversion specifications which are used to 2558 direct the interpretation of the BER element. The format string can 2559 contain the following characters: 2561 'a' Octet string. A char ** argument should be supplied. Memory is 2562 allocated, filled with the contents of the octet string, null- 2563 terminated, and the pointer to the string is stored in the argu- 2564 ment. The returned value must be freed using ldap_memfree. The 2565 tag of the element must indicate the primitive form (constructed 2566 strings are not supported) but is otherwise ignored and dis- 2567 carded during the decoding. This format cannot be used with 2568 octet strings which could contain null bytes. 2570 'O' Octet string. A struct berval ** argument should be supplied, 2571 which upon return points to a allocated struct berval containing 2572 the octet string and its length. ber_bvfree() must be called to 2573 free the allocated memory. The tag of the element must indicate 2574 the primitive form (constructed strings are not supported) but 2575 is otherwise ignored during the decoding. 2577 'b' Boolean. A pointer to an int should be supplied. The int value 2578 stored will be 0 for FALSE or nonzero for TRUE. The tag of the 2579 element must indicate the primitive form but is otherwise 2581 C LDAP API The C LDAP Application Program Interface 7 August 1998 2583 ignored during the decoding. 2585 'i' Integer. A pointer to an int should be supplied. The int value 2586 stored will be in host byte order. The tag of the element must 2587 indicate the primitive form but is otherwise ignored during the 2588 decoding. ber_scanf() will return an error if the integer can- 2589 not be stored in an int. 2591 'B' Bitstring. A char ** argument should be supplied which will 2592 point to the allocated bits, followed by an unsigned long * 2593 argument, which will point to the length (in bits) of the bit- 2594 string returned. ldap_memfree must be called to free the bit- 2595 string. The tag of the element must indicate the primitive form 2596 (constructed bitstrings are not supported) but is otherwise 2597 ignored during the decoding. 2599 'n' Null. No argument is required. The element is simply skipped 2600 if it is recognized as a zero-length element. The tag is 2601 ignored. 2603 'v' Several octet strings. A char *** argument should be supplied, 2604 which upon return points to a allocated null-terminated array of 2605 char *'s containing the octet strings. NULL is stored if the 2606 sequence is empty. ldap_memfree must be called to free each 2607 element of the array and the array itself. The tag of the 2608 sequence and of the octet strings are ignored. 2610 'V' Several octet strings (which could contain null bytes). A 2611 struct berval *** should be supplied, which upon return points 2612 to a allocated null-terminated array of struct berval *'s con- 2613 taining the octet strings and their lengths. NULL is stored if 2614 the sequence is empty. ber_bvecfree() can be called to free the 2615 allocated memory. The tag of the sequence and of the octet 2616 strings are ignored. 2618 'x' Skip element. The next element is skipped. No argument is 2619 required. 2621 '{' Begin sequence. No argument is required. The initial sequence 2622 tag and length are skipped. 2624 '}' End sequence. No argument is required. 2626 '[' Begin set. No argument is required. The initial set tag and 2627 length are skipped. 2629 ']' End set. No argument is required. 2631 C LDAP API The C LDAP Application Program Interface 7 August 1998 2633 unsigned long ber_peek_tag (BerElement *ber, unsigned long *lenPtr); 2635 ber_peek_tag() returns the tag of the next element to be parsed in the 2636 BerElement argument. The length of this element is stored in the 2637 *lenPtr argument. LBER_DEFAULT is returned if there is no further data 2638 to be read. The ber argument is not modified. 2640 unsigned long ber_skip_tag (BerElement *ber, unsigned long *lenPtr); 2642 ber_skip_tag() is similar to ber_peek_tag(), except that the state 2643 pointer in the BerElement argument is advanced past the first tag and 2644 length, and is pointed to the value part of the next element. This rou- 2645 tine should only be used with constructed types and situations when a 2646 BER encoding is used as the value of an OCTET STRING. The length of the 2647 value is stored in *lenPtr. 2649 unsigned long ber_first_element(BerElement *ber, 2650 unsigned long *lenPtr, char **opaquePtr); 2652 unsigned long ber_next_element (BerElement *ber, 2653 unsigned long *lenPtr, char *opaque); 2655 ber_first_element() and ber_next_element() are used to traverse a SET, 2656 SET OF, SEQUENCE or SEQUENCE OF data value. ber_first_element() calls 2657 ber_skip_tag(), stores internal information in *lenPtr and *opaquePtr, 2658 and calls ber_peek_tag() for the first element inside the constructed 2659 value. LBER_DEFAULT is returned if the constructed value is empty. 2660 ber_next_element() positions the state at the start of the next element 2661 in the constructed type. LBER_DEFAULT is returned if there are no 2662 further values. 2664 The len and opaque values should not be used by applications other than 2665 as arguments to ber_next_element(), as shown in the example below. 2667 15.5. Decoding Example 2669 The following is an example of decoding an ASN.1 data type: 2671 Example2Request ::= SEQUENCE { 2672 dn OCTET STRING, -- must be printable 2673 scope ENUMERATED { b (0), s (1), w (2) }, 2674 ali ENUMERATED { n (0), s (1), f (2), a (3) }, 2675 size INTEGER, 2676 time INTEGER, 2677 tonly BOOLEAN, 2678 attrs SEQUENCE OF OCTET STRING, -- must be printable 2679 [0] SEQUENCE OF SEQUENCE { 2681 C LDAP API The C LDAP Application Program Interface 7 August 1998 2683 type OCTET STRING -- must be printable, 2684 crit BOOLEAN DEFAULT FALSE, 2685 value OCTET STRING 2686 } OPTIONAL } 2688 #define LDAP_TAG_CONTROL_LIST 0xA0L /* context specific cons 0 */ 2690 int decode_example2(struct berval *bv) 2691 { 2692 BerElement *ber; 2693 unsigned long len; 2694 int scope, ali, size, time, tonly; 2695 char *dn = NULL, **attrs = NULL; 2696 int res,i,rc = 0; 2698 ber = ber_init(bv); 2699 if (ber == NULL) { 2700 printf("ERROR ber_init failed0); 2701 return -1; 2702 } 2704 res = ber_scanf(ber,"{aiiiiib{v}",&dn,&scope,&ali, 2705 &size,&time,&tonly,&attrs); 2707 if (res == -1) { 2708 printf("ERROR ber_scanf failed0); 2709 ber_free(ber,1); 2710 return -1; 2711 } 2713 /* *** use dn */ 2714 ldap_memfree(dn); 2716 for (i = 0; attrs != NULL && attrs[i] != NULL; i++) { 2717 /* *** use attrs[i] */ 2718 ldap_memfree(attrs[i]); 2719 } 2720 ldap_memfree(attrs); 2722 if (ber_peek_tag(ber,&len) == LDAP_TAG_CONTROL_LIST) { 2723 char *opaque; 2724 unsigned long tag; 2726 for (tag = ber_first_element(ber,&len,&opaque); 2727 tag != LBER_DEFAULT; 2728 tag = ber_next_element (ber,&len,opaque)) { 2730 unsigned long ttag, tlen; 2732 C LDAP API The C LDAP Application Program Interface 7 August 1998 2734 char *type; 2735 int crit; 2736 struct berval *value; 2738 if (ber_scanf(ber,"{a",&type) == LBER_ERROR) { 2739 printf("ERROR cannot parse type0); 2740 break; 2741 } 2742 /* *** use type */ 2743 ldap_memfree(type); 2745 ttag = ber_peek_tag(ber,&tlen); 2746 if (ttag == 0x01) { /* boolean */ 2747 if (ber_scanf(ber,"b", 2748 &crit) == LBER_ERROR) { 2749 printf("ERROR cannot parse crit0); 2750 rc = -1; 2751 break; 2752 } 2753 } else if (ttag == 0x04) { /* octet string */ 2754 crit = 0; 2755 } else { 2756 printf("ERROR extra field in controls0); 2757 break; 2758 } 2760 if (ber_scanf(ber,"O}",&value) == LBER_ERROR) { 2761 printf("ERROR cannot parse value0); 2762 rc = -1; 2763 break; 2764 } 2765 /* *** use value */ 2766 ber_bvfree(value); 2767 } 2768 } 2770 ber_scanf(ber,"}"); 2772 ber_free(ber,1); 2774 return rc; 2775 } 2777 16. Security Considerations 2779 LDAPv2 supports security through protocol-level authentication using 2780 C LDAP API The C LDAP Application Program Interface 7 August 1998 2782 clear-text passwords. LDAPv3 adds support for SASL [8] (Simple Authen- 2783 tication Security Layer) methods. LDAPv3 also supports operation over a 2784 secure transport layer using Transport Layer Security TLS [9]. Readers 2785 are referred to the protocol documents for discussion of related secu- 2786 rity considerations. 2788 Implementations of this API should be cautious when handling authentica- 2789 tion credentials. In particular, keeping long-lived copies of creden- 2790 tials without the application's knowledge is discouraged. 2792 17. Acknowledgements 2794 Many members of the IETF ASID and LDAPEXT working groups as well as 2795 members of the Internet at large have provided useful comments and 2796 suggestions that have been incorporated into this revision. 2798 This original material upon which this revision is based was based upon 2799 work supported by the National Science Foundation under Grant No. NCR- 2800 9416667. 2802 18. Copyright 2804 Copyright (C) The Internet Society (1998). All Rights Reserved. 2806 This document and translations of it may be copied and furnished to oth- 2807 ers, and derivative works that comment on or otherwise explain it or 2808 assist in its implementation may be prepared, copied, published and dis- 2809 tributed, in whole or in part, without restriction of any kind, provided 2810 that the above copyright notice and this paragraph are included on all 2811 such copies and derivative works. However, this document itself may not 2812 be modified in any way, such as by removing the copyright notice or 2813 references to the Internet Society or other Internet organizations, 2814 except as needed for the purpose of developing Internet standards in 2815 which case the procedures for copyrights defined in the Internet Stan- 2816 dards process must be followed, or as required to translate it into 2817 languages other than English. 2819 The limited permissions granted above are perpetual and will not be 2820 revoked by the Internet Society or its successors or assigns. 2822 This document and the information contained herein is provided on an "AS 2823 IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK 2824 FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT 2825 LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT 2826 INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FIT- 2827 NESS FOR A PARTICULAR PURPOSE. 2829 C LDAP API The C LDAP Application Program Interface 7 August 1998 2831 19. Bibliography 2833 [1] The Directory: Selected Attribute Syntaxes. CCITT, Recommendation 2834 X.520. 2836 [2] M. Wahl, A. Coulbeck, T. Howes, S. Kille, W. Yeong, C. Robbins, 2837 "Lightweight Directory Access Protocol (v3): Attribute Syntax 2838 Definitions", RFC 2252, December 1997. 2840 [3] T. Howes, "The String Representation of LDAP Search Filters," RFC 2841 2254, December 1997. 2843 [4] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol 2844 (v3): A UTF-8 String Representation of Distinguished Names", RFC 2845 2253, December 1997. 2847 [5] S. Kille, "Using the OSI Directory to Achieve User Friendly Nam- 2848 ing," RFC 1781, March 1995. 2850 [6] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol 2851 (v3)", RFC 2251, December 1997. 2853 [7] A. Herron, T. Howes, M. Wahl, C. Weider, A. Anantha, "LDAP Control 2854 Extension for Server Side Sorting of Search Results", INTERNET- 2855 DRAFT , 10 March 1998. 2857 [8] J. Meyers, "Simple Authentication and Security Layer (SASL)", RFC 2858 2222, October 1997. 2860 [9] "Lightweight Directory Access Protocol (v3): Extension for Tran- 2861 sport Layer Security", INTERNET-DRAFT , July 1998. 2864 [10] "UTF-8, a transformation format of Unicode and ISO 10646", RFC 2865 2044, October 1996. 2867 [11] "IP Version 6 Addressing Architecture,", RFC 1884, December 1995. 2869 20. Authors' Addresses 2871 Mark Smith 2872 Netscape Communications Corp. 2873 501 E. Middlefield Rd., Mailstop MV068 2874 Mountain View, CA 94043 2875 USA 2876 +1 650 937-3477 2877 mcs@netscape.com 2879 C LDAP API The C LDAP Application Program Interface 7 August 1998 2881 Tim Howes 2882 Netscape Communications Corp. 2883 501 E. Middlefield Rd., Mailstop MV068 2884 Mountain View, CA 94043 2885 USA 2886 +1 650 937-3419 2887 howes@netscape.com 2889 Andy Herron 2890 Microsoft Corp. 2891 1 Microsoft Way 2892 Redmond, WA 98052 2893 USA 2894 +1 425 882-8080 2895 andyhe@microsoft.com 2897 Chris Weider 2898 Microsoft Corp. 2899 1 Microsoft Way 2900 Redmond, WA 98052 2901 USA 2902 +1 425 882-8080 2903 cweider@microsoft.com 2905 Mark Wahl 2906 Innosoft International, Inc. 2907 8911 Capital of Texas Hwy, Suite 4140 2908 Austin, TX 78759 2909 USA 2910 +1 626 919 3600 2911 Mark.Wahl@innosoft.com 2913 Anoop Anantha 2914 Microsoft Corp. 2915 1 Microsoft Way 2916 Redmond, WA 98052 2917 USA 2918 +1 425 882-8080 2919 anoopa@microsoft.com 2921 21. Appendix A - Sample LDAP API Code 2923 #include 2925 main() 2926 { 2927 LDAP *ld; 2929 C LDAP API The C LDAP Application Program Interface 7 August 1998 2931 LDAPMessage *res, *e; 2932 int i, rc; 2933 char *a, *dn; 2934 BerElement *ptr; 2935 char **vals; 2937 /* open an LDAP session */ 2938 if ( (ld = ldap_init( "dotted.host.name", LDAP_PORT )) == NULL ) 2939 exit( 1 ); 2941 /* authenticate as nobody */ 2942 if (( rc = ldap_simple_bind_s( ld, NULL, NULL )) != LDAP_SUCCESS ) { 2943 fprintf( stderr, "ldap_simple_bind_s: %s\n", 2944 ldap_err2string( rc )); 2945 exit( 1 ); 2946 } 2948 /* search for entries with cn of "Babs Jensen", return all attrs */ 2949 if (( rc = ldap_search_s( ld, "o=University of Michigan, c=US", 2950 LDAP_SCOPE_SUBTREE, "(cn=Babs Jensen)", NULL, 0, &res )) 2951 != LDAP_SUCCESS ) { 2952 fprintf( stderr, "ldap_search_s: %s\n", 2953 ldap_err2string( rc )); 2954 exit( 1 ); 2955 } 2957 /* step through each entry returned */ 2958 for ( e = ldap_first_entry( ld, res ); e != NULL; 2959 e = ldap_next_entry( ld, e ) ) { 2960 /* print its name */ 2961 dn = ldap_get_dn( ld, e ); 2962 printf( "dn: %s\n", dn ); 2963 ldap_memfree( dn ); 2965 /* print each attribute */ 2966 for ( a = ldap_first_attribute( ld, e, &ptr ); a != NULL; 2967 a = ldap_next_attribute( ld, e, ptr ) ) { 2968 printf( "attribute: %s\n", a ); 2970 /* print each value */ 2971 vals = ldap_get_values( ld, e, a ); 2972 for ( i = 0; vals[i] != NULL; i++ ) { 2973 printf( "value: %s\n", vals[i] ); 2974 } 2975 ldap_value_free( vals ); 2976 ldap_memfree( a ); 2977 } 2978 if ( ptr != NULL ) { 2980 C LDAP API The C LDAP Application Program Interface 7 August 1998 2982 ber_free( ptr, 0 ); 2983 } 2984 } 2985 /* free the search results */ 2986 ldap_msgfree( res ); 2988 /* close and free connection resources */ 2989 ldap_unbind( ld ); 2990 } 2992 22. Appendix B - Namespace Consumed By This Specification 2994 The following 2 prefixes are used in this specification to name func- 2995 tions: 2996 ldap_ 2997 ber_ 2999 The following 6 prefixes are used in this specification to name struc- 3000 tures, unions, and typedefs: 3001 ldap 3002 LDAP 3003 PLDAP 3004 ber 3005 Ber 3006 timeval 3008 The following 3 prefixes are used in this specification to name #defined 3009 macros: 3010 LDAP 3011 LBER_ 3012 mod_ 3014 23. Appendix C - Outstanding Issues 3016 23.1. Support for multithreaded applications 3018 In order to support multithreaded applications in a platform-independent 3019 way, some additions to the LDAP API are needed. Different implementors 3020 have taken different paths to solve this problem in the past. A common 3021 set of thread-related API calls must be defined so that application 3022 developers are not unduly burdened. These will be added to a future 3023 revision of this specification. 3025 C LDAP API The C LDAP Application Program Interface 7 August 1998 3027 23.2. Using Transport Layer Security (TLS) 3029 The API calls used to support TLS must be specified. They will be added 3030 to a future revision of this specification or to an LDAP C API extension 3031 document. 3033 23.3. Client control for chasing referrals 3035 A client control has been defined that can be used to specify on a per- 3036 operation basis whether references and external referrals are automati- 3037 cally chased by the client library. This will be added to a future 3038 revision of this specification. 3040 23.4. Potential confusion between hostname:port and IPv6 addresses 3042 String representations of IPv6 network addresses [11] can contain colon 3043 characters. The ldap_init() call is specified to take strings of the 3044 form "hostname:port" or "ipaddress:port". If IPv6 addresses are used, 3045 the latter could be ambiguous. A future revision of this specification 3046 will resolve this issue. 3048 23.5. Need to track SASL API standardization efforts 3050 If a standard Simple Authentication and Security Layer API is defined, 3051 it may be necessary to modify the LDAP API to accommodate it. 3053 23.6. Support for character sets other than UTF-8? 3055 Some application developers would prefer to pass string data using a 3056 character set other than UTF-8. If this feature is added, the number of 3057 different character sets supported should definitely be minimized. 3059 23.7. LDAP Session Handle Options 3061 The use of void * as the third parameter to ldap_get_option() and 3062 ldap_set_option() is messy and requires callers of the API to use 3063 pointers even when passing in scaler values. One suggestion is to use 3064 functions declared like these instead: 3065 int ldap_get_global_option( LDAP *ld, int option, ... ); 3066 int ldap_set_global_option( LDAP *ld, int option, ... ); 3067 The type of the third parameter would of course depend on the value for 3068 the second. 3070 C LDAP API The C LDAP Application Program Interface 7 August 1998 3072 23.8. Re-bind function is not sufficiently general purpose 3074 The "re-bind" callback function specified in older revisions of this 3075 document is not sufficient to support challenge/response SASL authenti- 3076 cation mechanisms such as CRAM-MD5. A new, more functional mechanism 3077 should be specified. Client implementors would also like to receive the 3078 host and port number and a reason why the re-bind callback has been 3079 called so they can make secure, intelligent decisions when processing 3080 re-binds. 3082 23.9. LDAP C API extension mechanism should be clearly specified. 3084 The "Retrieving Information About the API Implementation" section of 3085 this document discusses some of the requirements that should be met by 3086 documents that extend this LDAP C API specification. A simple procedure 3087 for defining LDAP C API extensions should be completely specified and 3088 summarized in one place within this document. 3090 24. Appendix D - Changes Made Since Last Document Revision 3092 The previous version of this document was draft-ietf-ldapext-ldap-c- 3093 api-00.txt, dated 13 March 1998. This appendix lists all of the changes 3094 made to that document to produce the one you are reading now. 3096 24.1. API Changes 3098 The "Retrieving Information About the API Implementation" section was 3099 completely re-written. The ldap_version() call was eliminated in 3100 favor of a new LDAP_STANDARD_API_VERSION macro combined with a new 3101 option for ldap_get_option() called LDAP_OPT_API_INFO. 3103 In the "LDAP Session Handle Options" section: added notes about free- 3104 ing of char * and LDAPControl * values, provided separate types for 3105 each option for the "outvalue" and "invalue" parameters, and added 3106 information about READ-ONLY options. The only option that is 3107 currently specified as READ-ONLY is LDAP_OPT_DESC. 3109 In the "Searching", "Reading an Entry", and "Listing the Children of 3110 an Entry" sections: passing NULL for the filter string to one of the 3111 search functions is equivalent to passing the string 3112 "(objectclass=*)". This seems like a convenient shorthand to provide 3113 for users of the API. 3115 The "Handling re-authentication (re-bind)" section was completely 3116 removed. 3118 C LDAP API The C LDAP Application Program Interface 7 August 1998 3120 In the "LDAP Session Handle Options" section: removed all references 3121 to the inadequate "re-bind proc" related options. 3123 In the "Stepping Through the Attributes of an Entry" section: removed 3124 ldap_ber_free() function since it serves the same purpose as 3125 ber_free(). 3127 In the "Parsing References" section: added missing * to the 3128 ldap_parse_reference() referralsp parameter. 3130 In the "Encoded ASN.1 Value Manipulation: Encoding" section: changed 3131 the description of ber_flatten() to specify that unbalanced '{' and 3132 '}' format modifiers result in an error. 3134 24.2. Editorial changes 3136 In the "Introduction" section: removed old, conflicting text that 3137 said that this document specifies information only for the Internet 3138 community only and not a standard. 3140 In the "Status of this Memo" section: updated the text to reflect the 3141 current list of Internet-Drafts Shadow directories. 3143 In the "Overview of LDAP API Use" and "LDAP Session Handle Options" 3144 sections: replaced references to "default LDAP server" with "primary 3145 LDAP server." 3147 In the "Overview of LDAP API Use" section: made it clear the message 3148 id is not necessarily returned by the asynchronous function calls as 3149 their return value. 3151 In the "Overview of LDAP API Use" section: mentioned that some LDAP 3152 API implementations may support character sets other than UTF-8. 3154 In the "Common Data Structures", "Obtaining Results and Peeking 3155 Inside LDAP Messages", and "Handling Errors and Parsing Results" sec- 3156 tions: added more information about "result chains" to the 3158 In the "Authenticating to the directory" section: fix text to indi- 3159 cate the SASL mechanisms are identified using text strings, not OIDs. 3161 In the "LDAP Error Codes" section: eliminated a repeated sentence. 3163 In the "Searching" section: changed ldap_search_ext() and 3164 ldap_search_ext_s() prototypes to use timeout instead of timeoutp for 3165 struct timeval * parameter. 3167 C LDAP API The C LDAP Application Program Interface 7 August 1998 3169 In the "Handling Errors and Parsing Results" section: added a note to 3170 clarify that ldap_parse_extended_result() and 3171 ldap_parse_sasl_bind_result() are used in addition to 3172 ldap_parse_result(). 3174 In the "Closing the session" section: added a note to clarify that 3175 once ldap_unbind() or ldap_unbind_s() has been done it is illegal to 3176 use the session handle in any future API calls. 3178 In the "Encoded ASN.1 Value Manipulation: Encoding" section: added 3179 note near LBER_USE_DER that if the caller takes responsibility for 3180 ordering values of sets and sequences correctly DER output as defined 3181 in X.509 and X.680 can be produced. 3183 In the "Encoded ASN.1 Value Manipulation: Encoding Example" section: 3184 corrected the example code to return rc instead of always returning 3185 -1. 3187 In the "Bibliography" section: updated references to the LDAPv3 TLS 3188 and Sorting drafts. 3190 In "Authors' Addresses" section: updated Mark Wahl's address. 3192 In "Appendix - Outstanding Issues": added "Re-bind function is not 3193 sufficiently general purpose" and "LDAP C API extension mechanism 3194 should be clearly specified" issues. 3196 In "Appendix - Sample LDAP API Code": added a missing ldap_memfree() 3197 call. 3199 Added new appendix: "Namespace Consumed By This Specification." 3201 Move "Table of Contents" from very end to the early part of this 3202 document.