idnits 2.17.1 draft-howes-ldap-api-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-16) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. 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 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** 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. ** Expected the document's filename to be given on the first page, but didn't find any ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 32 longer pages, the longest (page 2) being 60 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 33 pages 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 5 instances of too long lines in the document, the longest one being 7 characters in excess of 72. == The 'Obsoletes: ' line in the draft header should list only the _numbers_ of the RFCs which will be obsoleted by this document (if approved); it should not include the word 'RFC' in the list. -- The draft header indicates that this document obsoletes RFC1823, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 315 has weird spacing: '... berval sc_v...' == Line 511 has weird spacing: '... long tv_...' == Line 512 has weird spacing: '... long tv_...' == Line 729 has weird spacing: '...r -1 on error...' == Line 826 has weird spacing: '... values are ...' == (4 more instances...) == Couldn't figure out when the document was first submitted -- there may comments or warnings related to the use of a disclaimer for pre-RFC5378 work that could not be issued because of this. Please check the Legal Provisions document at https://trustee.ietf.org/license-info to determine if you need the pre-RFC5378 disclaimer. -- Couldn't find a document date in the document -- date freshness check skipped. -- 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 1561 looks like a reference -- Missing reference section? '7' on line 1576 looks like a reference -- Missing reference section? '1' on line 1558 looks like a reference -- Missing reference section? '4' on line 1570 looks like a reference -- Missing reference section? '3' on line 1567 looks like a reference -- Missing reference section? '5' on line 1573 looks like a reference Summary: 11 errors (**), 0 flaws (~~), 11 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group Timothy A Howes 3 INTERNET-DRAFT Mark C Smith 4 OBSOLETES: RFC 1823 Netscape Communications Corp. 6 The LDAP Application Program Interface 8 1. Status of this Memo 10 This draft document will be submitted to the RFC Editor as an informa- 11 tional document. Distribution of this memo is unlimited. Please send 12 comments to the authors. 14 This document is an Internet-Draft. Internet-Drafts are working docu- 15 ments of the Internet Engineering Task Force (IETF), its areas, and its 16 working groups. Note that other groups may also distribute working 17 documents as Internet-Drafts. 19 Internet-Drafts are draft documents valid for a maximum of six months 20 and may be updated, replaced, or obsoleted by other documents at any 21 time. It is inappropriate to use Internet-Drafts as reference material 22 or to cite them other than as ``work in progress.'' 24 To learn the current status of any Internet-Draft, please check the 25 ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow 26 Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), 27 ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). 29 2. Introduction 31 This document defines a C language application program interface to the 32 lightweight directory access protocol (LDAP). This document replaces the 33 previous definition of this API, defined in RFC 1823, updating it to 34 include support for features found in version 3 of the LDAP protocol, as 35 well as other changes to support information hiding and thread safety. 37 The LDAP API is designed to be powerful, yet simple to use. It defines 38 compatible synchronous and asynchronous interfaces to LDAP to suit a 39 wide variety of applications. This document gives a brief overview of 40 the LDAP model, then an overview of how the API is used by an applica- 41 tion program to obtain LDAP information. The API calls are described in 42 detail, followed by an appendix that provides some example code demon- 43 strating the use of the API. This document provides information to the 44 Internet community. It does not specify any standard. 46 LDAP API October 1996 48 3. Overview of the LDAP Model 50 LDAP is the lightweight directory access protocol, described in [2] and 51 [7]. It can provide a lightweight frontend to the X.500 directory [1], 52 or a stand-alone service. In either mode, LDAP is based on a client- 53 server model in which a client makes a TCP connection to an LDAP server, 54 over which it sends requests and receives responses. LDAPv3 can also be 55 used over UDP transport. 57 The LDAP information model is based on the entry, which contains infor- 58 mation about some object (e.g., a person). Entries are composed of 59 attributes, which have a type and one or more values. Each attribute has 60 a syntax that determines what kinds of values are allowed in the attri- 61 bute (e.g., ASCII characters, a jpeg photograph, etc.) and how those 62 values behave during directory operations (e.g., is case significant 63 during comparisons). 65 Entries may be organized in a tree structure, usually based on politi- 66 cal, geographical, and organizational boundaries. Each entry is uniquely 67 named relative to its sibling entries by its relative distinguished name 68 (RDN) consisting of one or more distinguished attribute values from the 69 entry. At most one value from each attribute may be used in the RDN. 70 For example, the entry for the person Babs Jensen might be named with 71 the "Barbara Jensen" value from the commonName attribute. 73 A globally unique name for an entry, called a distinguished name or DN, 74 is constructed by concatenating the sequence of RDNs from the entry up 75 to the root of the tree. For example, if Babs worked for the University 76 of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen, 77 o=University of Michigan, c=US". The DN format used by LDAP is defined 78 in [4]. 80 Operations are provided to authenticate, search for and retrieve infor- 81 mation, modify information, and add and delete entries from the tree. 82 The next sections give an overview of how the API is used and detailed 83 descriptions of the LDAP API calls that implement all of these func- 84 tions. 86 4. Overview of LDAP API Use 88 An application generally uses the LDAP API in four simple steps. 90 - Initialize an LDAP session with a default LDAP server. The 91 ldap_init() call returns a handle to the session, allowing multiple 92 connections to be open at once. 94 - Authenticate to the LDAP server. The ldap_bind() call and friends 95 support a variety of authentication methods. 97 LDAP API October 1996 99 - Perform some LDAP operations and obtain some results. ldap_search() 100 and friends return results which can be parsed by 101 ldap_result2error(), ldap_first_entry(), ldap_next_entry(), etc. 103 - Close the connection. The ldap_unbind() call closes the connection. 105 Operations can be performed either synchronously or asynchronously. The 106 names of the synchronous calls end in _s. For example, a synchronous 107 search can be completed by calling ldap_search_s(). An asynchronous 108 search can be initiated by calling ldap_search(). All synchronous rou- 109 tines return an indication of the outcome of the operation (e.g, the 110 constant LDAP_SUCCESS or some other error code). The asynchronous rou- 111 tines return the message id of the operation initiated. This id can be 112 used in subsequent calls to ldap_result() to obtain the result(s) of the 113 operation. An asynchronous operation can be abandoned by calling 114 ldap_abandon(). 116 Results and errors are returned in an opaque structure called LDAPMes- 117 sage. Routines are provided to parse this structure, step through 118 entries and attributes returned, etc. Routines are also provided to 119 interpret errors. The next sections describe these routines in more 120 detail. 122 5. Calls for performing LDAP operations 124 This section describes each LDAP operation API call in detail. All calls 125 take a "connection handle," a pointer to an LDAP structure containing 126 per-connection information. Many routines return results in an LDAPMes- 127 sage structure. These structures and others are described as needed 128 below. 130 5.1. Initializing an LDAP Session 132 ldap_init() initializes a session with an LDAP server. The server is not 133 actually contacted until an operation is performed that requires it, 134 allowing various options to be set after initialization. 136 ldap_sslinit() functions the same as ldap_init(), but it also optionally 137 allows the caller to set up a secure LDAP connection over SSL to the 138 LDAP server. 140 typedef struct ldap LDAP; 142 LDAP *ldap_init( char *hostname, int portno ); 144 LDAP *ldap_sslinit( char *hostname, int portno, int secure ); 146 Use of the following routine is deprecated. 148 LDAP API October 1996 150 LDAP *ldap_open( char *hostname, int portno ); 152 Parameters are: 154 hostname Contains a space-separated list of hostnames or dotted strings 155 representing the IP address of hosts running an LDAP server to 156 connect to. The hosts are tried in the order listed, stopping 157 with the first one to which a successful connection is made. 158 Note that only ldap_open() attempts to make the connection 159 before returning to the caller. Neither ldap_init() or 160 ldap_sslinit() connect to the LDAP server. 162 portno Contains the TCP or UDP port number to connect to or contact. 163 The default LDAP port of 389 can be obtained by supplying the 164 constant LDAP_PORT. The default secure (LDAP over SSL) LDAP 165 port of 636 can be selected by supplying the constant 166 LDAPS_PORT. 168 secure Is non-zero to intialize a secure LDAP session over SSL. If 169 secure is zero, regular LDAP session will be initialized. 171 ldap_init(), ldap_sslinit(), and ldap_open() all return a "session han- 172 dle," a pointer to an opaque structure that should be passed to subse- 173 quent calls pertaining to the session. These routines return NULL if the 174 session cannot be initialized. 176 One of the ldap_bind calls described below must be completed before 177 other operations can be performed on the session. 179 The calling program can set various attributes of the session by calling 180 the routines described in the next section. 182 5.2. LDAP Session Handle Options 184 The LDAP session handle returned by ldap_init() and friends is a pointer 185 to an opaque data type representing an LDAP session. Formerly, this data 186 type was a structure exposed to the caller, and various fields in the 187 structure could be set to control aspects of the session, such as size 188 and time limits on searches. 190 In the interest of insulating callers from inevitable changes to this 191 structure, these aspects of the session are now accessed through a pair 192 of accessor functions, described below. 194 ldap_get_option() is used to access the current value of various 195 session-wide parameters. ldap_set_option() is used to set the value of 196 these parameters. 198 LDAP API October 1996 200 int ldap_get_option( LDAP *ld, int option, void *outvalue ); 202 int ldap_set_option( LDAP *ld, int option, void *invalue ); 204 Parameters are: 206 ld The session handle. 208 option The name of the option being accessed or set. This parameter 209 should be one of the following constants, which have the follow- 210 ing meanings. 212 LDAP_OPT_DESC 213 The underlying socket descriptor corresponding to the default 214 LDAP connection. 216 LDAP_OPT_DEREF 217 Controls how aliases are handled during search. It can have 218 one of the following values: LDAP_DEREF_NEVER, 219 LDAP_DEREF_SEARCHING, LDAP_DEREF_FINDING, or 220 LDAP_DEREF_ALWAYS. The LDAP_DEREF_SEARCHING value means 221 aliases should be dereferenced during the search but not when 222 locating the base object of the search. The LDAP_DEREF_FINDING 223 value means aliases should be dereferenced when locating the 224 base object but not during the search. 226 LDAP_OPT_SIZELIMIT 227 A limit on the number of entries to return from a search. A 228 value of zero means no limit. 230 LDAP_OPT_TIMELIMIT 231 A limit on the number of seconds to spend on a search. A value 232 of zero means no limit 234 LDAP_OPT_IO_FN_PTRS 235 See the discussion of I/O environments in Section X. 237 LDAP_OPT_THREAD_FN_PTRS 238 See the discussion of threading environments in Section X. 240 LDAP_OPT_REBIND_FN 241 See the discussion of ldap_bind() and friends below. 243 LDAP_OPT_REBIND_ARG 244 See the discussion of ldap_bind() and friends below. 246 LDAP_OPT_CACHE_FN_PTRS 247 See the discussion of LDAP caching in Section X. 249 LDAP API October 1996 251 LDAP_OPT_CACHE_STRATEGY 252 See the discussion of LDAP caching in Section X. 254 LDAP_OPT_CACHE_ENABLE 255 See the discussion of LDAP caching in Section X. 257 LDAP_OPT_REFERRALS 258 This option controls whether the LDAP library automatically 259 follows referrals returned by LDAP servers or not. It can be 260 set to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF. 262 LDAP_OPT_SSL 263 This option controls whether the default LDAP connection is 264 made secure over SSL or not. It can be set to one of the con- 265 stants LDAP_OPT_ON or LDAP_OPT_OFF. Note that if 266 LDAP_OPT_REFERRALS is set to LDAP_OPT_ON and the LDAP library 267 gets a referral to an SSL LDAP server, it will still do SSL if 268 possible. This setting has no bearing on connections made when 269 chasing referrals. 271 LDAP_OPT_RESTART 272 This option controls whether LDAP I/O operations should 273 automatically be restarted if they abort prematurely. It 274 should be set to one of the constants LDAP_OPT_ON or 275 LDAP_OPT_OFF. This option is useful if an LDAP I/O operation 276 may be interrupted prematurely, for example by a timer going 277 off, or other interrrupt. 279 LDAP_OPT_VERSION 280 This option indicates the version of the default LDAP server. 281 It can be one of the constants LDAP_VERSION2 or LDAP_VERSION3. 283 LDAP_OPT_SORTKEYS 284 This option indicates sort keys that should be sent to the 285 server on subsequent search requests. The value of this option 286 is a NULL-terminated array of pointers to structures with the 287 following definition. 289 struct ldapsortkey { 290 char *sk_attrtype; 291 char *sk_matchruleoid; 292 int sk_reverseorder; 293 }; 295 outvalue The address of a place to put the value of the option. The 296 actual type of this parameter depends on the setting of the 297 option parameter. 299 LDAP API October 1996 301 invalue A pointer to the value the option is to be given. The actual 302 type of this parameter depends on the setting of the option 303 parameter. The constants LDAP_OPT_ON and LDAP_OPT_OFF can be 304 given for options that have on or off settings. 306 5.3. Setting Session Parameters 308 The ldap_session() and ldap_session_s() calls are used to request that 309 the LDAP server set certain session parameters. These session parame- 310 ters are maintained by the server, as opposed to the LDAP * session 311 parameters described above, which are maintained by the client. 313 struct ldapsessctl { 314 char *sc_type; 315 struct berval sc_value; 316 int sc_critical; 317 }; 319 int ldap_session( 320 LDAP *ld; 321 struct ldapsessctl **controls; 322 ); 324 int ldap_session_s( 325 LDAP *ld; 326 struct ldapsessctl **controls; 327 LDAPMessage **result; 328 ); 330 Parameters are: 332 ld The session handle. 334 controls A NULL-terminated array of pointers to ldapsessctl structures 335 indicating the requested session controls. 337 result A result parameter that will be filled in with the result of 338 the session control operation. This parameter is suitable for 339 passing to ldap_parse_session_result(), described below. 341 The following constants are defined and may be assigned to the sc_type 342 field in the ldapsessctl structure. The controls have the following 343 meanings. 345 LDAP_SESSION_ATTR_SIZELIMIT 346 This control sets a limit on the size of any attribute value the 347 server will return to the client. The sc_value field should point 348 to a string containing the decimal string representation of the 350 LDAP API October 1996 352 size limit in bytes. 354 LDAP_SESSION_NO_COPY 355 This control instructs the server not to perform operations against 356 copies of the data, only to use the master version. It can be set 357 to LDAP_OPT_ON or LDAP_OPT_OFF. 359 LDAP_SESSION_PARTIAL_COPY 360 This control instructs the server that it should return search 361 results from partial replicas of the directory. It can be set to 362 LDAP_OPT_ON or LDAP_OPT_OFF. 364 LDAP_SESSION_REFERRING_SERVER 365 This control tells the server which server (if any) referred the 366 client to the server. It is useful in debugging, and should contain 367 a URL. 369 LDAP_SESSION_NO_CHAINING 370 This control instructs the server not to chain requests on the 371 client's behalf. It should be set to either LDAP_OPT_ON or 372 LDAP_OPT_OFF. 374 LDAP_SESSION_SUPPORTED_PROTOCOL 375 This control instructs the server in which protocols the client 376 supports for returned referrals. It should be a null-terminated 377 array of string protocol names, such as "ldap", "cldap", etc. 379 LDAP_SESSION_ALIAS_ON_UPDATE 380 This control instructs the server that it should follow aliases on 381 update (add, delete, modify, modify dn) operations. It should be 382 set to LDAP_OPT_ON or LDAP_OPT_OFF. 384 LDAP_SESSION_MANAGE_SERVER 385 This control instructs the server that the client wants to manage 386 server data, such as knowledge references, rather than follow the 387 links they provide. It should be set to LDAP_OPT_ON or 388 LDAP_OPT_OFF. 390 LDAP_SESSION_PREFERRED_LANGUAGE 391 This control tells the server the list of the client's preferred 392 languages. 394 ldap_session_s() is synchronous and returns an LDAP error code indicat- 395 ing the success or failure of the operation. 397 ldap_session() is asynchronous and returns the message id of the opera- 398 tion it initiates, or -1 in case of trouble. The result of the operation 399 may be obtained by a subsequent call to ldap_result(). 401 LDAP API October 1996 403 5.4. Authenticating to the directory 405 ldap_bind() and friends are used to authenticate an LDAP client to an 406 LDAP directory server. 408 The ldap_extended_bind() and ldap_extended_bind_s() calls can be used to 409 do general and extensible authentication over LDAP. The routines both 410 take the dn to bind as, the method to use, as a dotted-string represen- 411 tation of an OID identifying the method, and a struct berval holding the 412 credentials. The special constant value LDAP_AUTH_SIMPLE_OID can be 413 passed to request simple authentication, or the simplified routines 414 ldap_simple_bind() or ldap_simple_bind_s() can be used. 416 typedef struct ldapmsg LDAPMessage; 418 int ldap_extended_bind( LDAP *ld, char *dn, char *methodoid, 419 struct berval *credentials ); 421 int ldap_extended_bind_s( LDAP *ld, char *dn, char *methodoid, 422 struct berval *credentials, LDAPMessage **result ); 424 int ldap_simple_bind( LDAP *ld, char *dn, char *passwd ); 426 int ldap_simple_bind_s( LDAP *ld, char *dn, char *passwd ); 428 The use of the following routines is deprecated: 430 int ldap_bind( LDAP *ld, char *dn, char *cred, int method ); 432 int ldap_bind_s( LDAP *ld, char *dn, char *cred, int method ); 434 int ldap_kerberos_bind( LDAP *ld, char *dn ); 436 int ldap_kerberos_bind_s( LDAP *ld, char *dn ); 438 Parameters are: 440 ld The connection handle. 442 dn The name of the entry to bind as. 444 methodoid 445 Either LDAP_AUTH_SIMPLE_OID, to get simple authentication, or a 446 dotted text string representing an OID identifying the bind 447 method. 449 credentials 450 The credentials with which to authenticate. Arbitrary credentials 452 LDAP API October 1996 454 can be passed using this parameter. The format and content of the 455 credentials depends on the setting of the methodoid parameter. 457 result For the synchronous version of extended bind, 458 ldap_extended_bind_s(), this is a result-parameter that will be 459 set to the LDAPMessage containing the result of the bind. This 460 result is suitable for passing to ldap_parse_result() or 461 ldap_parse_bind_result(), both described below. 463 passwd For ldap_simple_bind(), the password to compare to the entry's 464 userPassword attribute. 466 Additional parameters for the deprecated routines are not described. 467 Interested readers are referred to RFC 1823. 469 Synchronous versions of the routines have names that end in _s. These 470 routines return the result of the bind operation, either the constant 471 LDAP_SUCCESS if the operation was successful, or another LDAP error code 472 if it was not. See the section below on error handling for more informa- 473 tion about possible errors and how to interpret them. 475 Asynchronous versions of these routines return the message id of the 476 bind operation initiated. A subsequent call to ldap_result(), described 477 below, can be used to obtain the result of the bind. In case of error, 478 these routines will return -1, setting the session error parameters in 479 the LDAP structure appropriately. 481 Note that no other operations over the connection should be attempted 482 before a bind call has successfully completed. Subsequent bind calls can 483 be used to re-authenticate over the same connection. 485 5.5. Closing the connection 487 ldap_unbind() is used to unbind from the directory, close the connec- 488 tion, and dispose of the connection handle. 490 int ldap_unbind( LDAP *ld ); 492 Parameters are: 494 ld The connection handle. 496 ldap_unbind() works synchronously, unbinding from the directory, closing 497 the connection, and freeing up the ld structure before returning. 498 ldap_unbind() returns LDAP_SUCCESS (or another LDAP error code if the 499 request cannot be sent to the LDAP server). After a call to 500 ldap_unbind(), the ld connection handle is invalid. 502 LDAP API October 1996 504 5.6. Searching 506 ldap_search() and friends are used to search the LDAP directory, return- 507 ing a requested set of attributes for each entry matched. There are 508 three variations. 510 struct timeval { 511 long tv_sec; 512 long tv_usec; 513 }; 514 int ldap_search( 515 LDAP *ld, 516 char *base, 517 int scope, 518 char *filter, 519 char *attrs[], 520 int attrsonly 521 ); 522 int ldap_search_s( 523 LDAP *ld, 524 char *base, 525 int scope, 526 char *filter, 527 char *attrs[], 528 int attrsonly, 529 LDAPMessage **res 530 ); 531 int ldap_search_st( 532 LDAP *ld, 533 char *base, 534 int scope, 535 char *filter, 536 char *attrs[], 537 int attrsonly, 538 struct timeval *timeout, 539 LDAPMessage **res 540 ); 542 Parameters are: 544 ld The connection handle. 546 base The dn of the entry at which to start the search. 548 scope One of LDAP_SCOPE_BASE, LDAP_SCOPE_ONELEVEL, or 549 LDAP_SCOPE_SUBTREE, indicating the scope of the search. 551 filter A character string as described in RFC 1960 [3], representing 553 LDAP API October 1996 555 the search filter. 557 attrs A NULL-terminated array of strings indicating which attributes 558 to return for each matching entry. Passing NULL for this 559 parameter causes all available attributes to be retrieved. 561 attrsonly A boolean value that should be zero if both attribute types 562 and values are to be returned, non-zero if only types are 563 wanted. 565 timeout For the ldap_search_st() call, this specifies the local search 566 timeout value. 568 res For the synchronous calls, this is a result parameter which 569 will contain the results of the search upon completion of the 570 call. 572 There are three options in the ld connection handle which control how 573 the search is performed. They are: 575 LDAP_OPT_SIZELIMIT 576 A limit on the number of entries to return from the search. 577 A value of zero means no limit. 579 LDAP_OPT_TIMELIMIT 580 A limit on the number of seconds to spend on the search. A 581 value of zero means no limit. 583 LDAP_OPT_DEREFOne of LDAP_DEREF_NEVER, LDAP_DEREF_SEARCHING, 584 LDAP_DEREF_FINDING, or LDAP_DEREF_ALWAYS, specifying how 585 aliases should be handled during the search. The 586 LDAP_DEREF_SEARCHING value means aliases should be derefer- 587 enced during the search but not when locating the base 588 object of the search. The LDAP_DEREF_FINDING value means 589 aliases should be dereferenced when locating the base 590 object but not during the search. 592 An asynchronous search is initiated by calling ldap_search(). It returns 593 the message id of the initiated search. The results of the search can be 594 obtained by a subsequent call to ldap_result(). The results can be 595 parsed by the result parsing routines described in detail later. In 596 case of error, -1 is returned and the session error parameters in the 597 LDAP structure are set appropriately. 599 A synchronous search is performed by calling ldap_search_s() or 600 ldap_search_st(). The routines are identical, except that 601 ldap_search_st() takes an additional parameter specifying a local 602 timeout for the search. Both routines return an indication of the 604 LDAP API October 1996 606 result of the search, either LDAP_SUCCESS or some error indication (see 607 Error Handling below). The entries returned from the search (if any) 608 are contained in the res parameter. This parameter is opaque to the 609 caller. Entries, attributes, values, etc., should be extracted by cal- 610 ling the parsing routines described below. The results contained in res 611 should be freed when no longer in use by calling ldap_msgfree(), 612 described later. 614 5.7. Reading an Entry 616 LDAP does not support a read operation directly. Instead, this operation 617 is emulated by a search with base set to the DN of the entry to read, 618 scope set to LDAP_SCOPE_BASE, and filter set to "(objectclass=*)". attrs 619 contains the list of attributes to return. 621 5.8. Listing the Children of an Entry 623 LDAP does not support a list operation directly. Instead, this operation 624 is emulated by a search with base set to the DN of the entry to list, 625 scope set to LDAP_SCOPE_ONELEVEL, and filter set to "(objectclass=*)". 626 attrs contains the list of attributes to return for each child entry. 628 5.9. Returning Search Results a Page at a Time 630 New to LDAPv3 is support in the protocol for retrieving search results a 631 page at a time. The ldap_search_init_page() and ldap_search_get_page() 632 routines provide an API interface to this capability. 634 typedef struct ldapsearch LDAPSearch; 636 LDAPSearch *ldap_search_init_page( 637 LDAP *ld, 638 char *base, 639 int scope, 640 char *filter, 641 char *attrs[], 642 int attrsonly, 643 struct ldapsortkey **sortkeys 644 ); 646 int ldap_search_get_page( 647 LDAP *ld, 648 LDAPSearch *searchhandle, 649 int startatentry, 650 int pagesize, 651 int *totalcount 652 ); 654 LDAP API October 1996 656 int ldap_search_get_page_s( 657 LDAP *ld, 658 LDAPSearch *searchhandle, 659 int startatentry, 660 int pagesize, 661 int *totalcount, 662 LDAPMessage **result 663 ); 665 int ldap_search_abandon_page( 666 LDAP *ld, 667 LDAPSearch *searchhandle 668 ); 670 The parameters to ldap_search_init_page() are exactly the same as those 671 to ldap_search(), except for the additional sortkeys parameter. This 672 parameter and parameters to ldap_search_get_page() are: 674 ld The connection handle. 676 sortkeys If the results of the search are desired back in sorted order, 677 this parameter is a NULL-terminated array of pointers to struct 678 sortkeys, indicating the attribute types and matching rules by 679 which the results are to be sorted. If this parameter is NULL, 680 the default value for sortkeys, if any, is taken from the LDAP 681 session parameter LDAP_OPT_SORTKEYS. 683 searchhandle 684 A handle to an opaque data type returned from a successful call 685 to ldap_search_init_page(). This parameter should be passed to 686 all subsequent calls to ldap_search_get_page() or 687 ldap_search_get_page_s() pertaining to the same search. 689 startatentry 690 The number of entries in the search result before which the 691 page to be retrieved begins. To start at the beginning of the 692 search result, supply 0 (zero) for startatentry. To begin in 693 the middle of a 100-entry search result, supply 50 for starta- 694 tentry. 696 pagesize The number of entries that should be returned in the page. No 697 more than this many entries will be returned from the search, 698 though fewer can be returned if the page extends beyond the 699 total size of the result set. 701 totalcount A result-parameter that will be set to the total number of 702 entries in the search result. This parameter may change on 703 subsequent calls to ldap_search_get_page() or 705 LDAP API October 1996 707 ldap_search_get_page_s(), if the size of the result set 708 changes (for example, because of additions or deletions to 709 the directory between calls). 711 result A result-parameter that will be set to an LDAPMessage contain- 712 ing the result of the search, which will be either a "page" of 713 entries, suitable for passing to ldap_first_entry() and friends 714 (just like a result from ldap_search_s()), or or an LDAPMessage 715 containing an explanation of an error that occurred, suitable 716 for passing to ldap_parse_result(). 718 ldap_search_init_page() returns a pointer to an opaque data structure 719 representing the search, or NULL on error. The non-NULL return value 720 should be passed to a subsequent call to ldap_search_get_page() or 721 ldap_search_get_page_s() to retrieve the actual pages of results from 722 the search. 724 ldap_search_get_page_s() is synchronous and returns the LDAP error code 725 resulting from the search operation. This code can be interpreted by 726 ldap_perror() and friends. 728 ldap_search_get_page() is asynchronous and returns the message id of the 729 request it initiates, or -1 on error. The result of the operation can 730 be obtained by calling ldap_result(). 732 ldap_search_abandon_page() abandons the current search-page sequence 733 begun by calling ldap_search_init_page(). It frees the searchhandle 734 structure, which is invalid after the call. 736 5.10. Comparing a Value Against an Entry 738 The ldap_compare() and ldap_compare_s() routines are used to compare a 739 given attribute value assertion against an LDAP entry. 741 int ldap_compare( 742 LDAP *ld, 743 const char *dn, 744 const char *attr, 745 struct berval *bvalue 746 ); 748 int ldap_compare_s( 749 LDAP *ld, 750 const char *dn, 751 const char *attr, 752 struct berval *bvalue, 753 char **matchedtype 754 ); 756 LDAP API October 1996 758 Parameters are: 760 ld The connection handle. 762 dn The name of the entry to compare against. 764 attr The attribute to compare against. 766 bvalue The attribute value to compare against those found in the 767 entry. This parameter is a pointer to a struct berval so it is 768 possible to compare binary values. 770 matchedtype 771 This result-parameter will be set to the attribute type actu- 772 ally used to match the compare. This is useful if attribute 773 sub-typing is involved, and the attr given is a parent type. If 774 no attribute sub-typing is involed (or is not supported, as in 775 the case of LDAPv2 servers), this result-parameter will be set 776 to NULL. 778 5.11. Modifying an entry 780 The ldap_modify() and ldap_modify_s() routines are used to modify an 781 existing LDAP entry. 783 typedef struct ldapmod { 784 int mod_op; 785 char *mod_type; 786 union { 787 char **modv_strvals; 788 struct berval **modv_bvals; 789 } mod_vals; 790 } LDAPMod; 791 #define mod_values mod_vals.modv_strvals 792 #define mod_bvalues mod_vals.modv_bvals 794 int ldap_modify( LDAP *ld, char *dn, LDAPMod *mods[] ); 796 int ldap_modify_s( LDAP *ld, char *dn, LDAPMod *mods[] ); 798 Parameters are: 800 ld The connection handle; 802 dn The name of the entry to modify; 804 mods A NULL-terminated array of modifications to make to the entry. 806 LDAP API October 1996 808 The fields in the LDAPMod structure have the following meanings: 810 mod_op The modification operation to perform. It should be one of 811 LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE. This field 812 also indicates the type of values included in the mod_vals 813 union. It is ORed with LDAP_MOD_BVALUES to select the 814 mod_bvalues form. Otherwise, the mod_values form is used. 816 mod_type The type of the attribute to modify. 818 mod_vals The values (if any) to add, delete, or replace. Only one of the 819 mod_values or mod_bvalues variants should be used, selected by 820 ORing the mod_op field with the constant LDAP_MOD_BVALUES. 821 mod_values is a NULL-terminated array of zero-terminated 822 strings and mod_bvalues is a NULL-terminated array of berval 823 structures that can be used to pass binary values such as 824 images. 826 For LDAP_MOD_ADD modifications, the given values are added to the 827 entry, creating the attribute if necessary. For LDAP_MOD_DELETE 828 modifications, the given values are deleted from the entry, removing the 829 attribute if no values remain. If the entire attribute is to be 830 deleted, the mod_vals field should be set to NULL. For 831 LDAP_MOD_REPLACE modifications, the attribute will have the listed 832 values after the modification, having been created if necessary. All 833 modifications are performed in the order in which they are listed. 835 ldap_modify_s() is synchronous and returns the LDAP error code resulting 836 from the modify operation. This code can be interpreted by ldap_perror() 837 and friends. 839 ldap_modify() is asynchronous and returns the message id of the request 840 it initiates, or -1 on error. The result of the operation can be 841 obtained by calling ldap_result(). 843 5.12. Modifying the Name of an Entry 845 In LDAPv2, the ldap_modrdn() and ldap_modrdn_s() routines were used to 846 change the name of an LDAP entry. They could only be used to change the 847 least significant component of a name (the RDN or relative distinguished 848 name). LDAPv3 provides the Modify DN protocol operation that allows more 849 general name change access. The ldap_moddn() and ldap_moddn_s() routines 850 are used to change the name of an entry, and the use of the 851 ldap_modrdn() and ldap_modrdn_s() routines is deprecated. 853 int ldap_moddn( 854 LDAP *ld, 855 char *dn, 857 LDAP API October 1996 859 char *newdn, 860 int deleteoldrdn 861 ); 862 int ldap_moddn_s( 863 LDAP *ld, 864 char *dn, 865 char *newdn, 866 int deleteoldrdn 867 ); 869 Use of the following routines is deprecated. 871 int ldap_modrdn( 872 LDAP *ld, 873 char *dn, 874 char *newrdn, 875 int deleteoldrdn 876 ); 877 int ldap_modrdn_s( 878 LDAP *ld, 879 char *dn, 880 char *newrdn, 881 int deleteoldrdn 882 ); 884 Parameters are: 886 ld The session handle. 888 dn The name of the entry whose DN is to be changed. 890 newdn The new DN to give the entry. 892 deleteoldrdn 893 This parameter only has meaning on the modify DN routines if 894 the newdn has a different RDN than the old DN. It is a boolean 895 value, if non-zero indicating that the old RDN value(s) should 896 be removed, if zero indicating that the old RDN value(s) should 897 be retained as non-distinguished values of the entry. 899 Parameters of the deprecated routines are not described. Interested 900 readers are referred to RFC 1823. 902 The ldap_moddn_s() routine is synchronous, returning the LDAP error code 903 indicating the outcome of the operation. 905 The ldap_moddn() routine is asynchronous, returning the message id of 906 the operation it initiates, or -1 in case of trouble. The result of the 908 LDAP API October 1996 910 operation can be obtained by calling ldap_result(). 912 5.13. Adding an entry 914 ldap_add() and ldap_add_s() are used to add entries to the LDAP direc- 915 tory. 917 int ldap_add( LDAP *ld, char *dn, LDAPMod *attrs[] ); 919 int ldap_add_s( LDAP *ld, char *dn, LDAPMod *attrs[] ); 921 Parameters are: 923 ld The session handle. 925 dn The name of the entry to add. 927 attrs The entry's attributes, specified using the LDAPMod structure 928 defined for ldap_modify(). The mod_type and mod_vals fields should 929 be filled in. The mod_op field is ignored unless ORed with the 930 constant LDAP_MOD_BVALUES, used to select the mod_bvalues case of 931 the mod_vals union. 933 Note that the parent of the entry must already exist. 935 ldap_add_s() is synchronous, returning the LDAP error code indicating 936 the outcome of the operation. 938 ldap_add() is asynchronous, returning the message id of the operation it 939 initiates, or -1 in case of trouble. The result of the operation can be 940 obtained by calling ldap_result(). 942 5.14. Deleting an entry 944 ldap_delete() and ldap_delete_s() are used to delete entries from the 945 LDAP directory. 947 int ldap_delete( LDAP *ld, char *dn ); 949 int ldap_delete_s( LDAP *ld, char *dn ); 951 Parameters are: 953 ld The session handle. 955 dn The name of the entry to delete. 957 Note that the entry to delete must be a leaf entry (i.e., it must have 959 LDAP API October 1996 961 no children). Deletion of entire subtrees is not supported by LDAP. 963 ldap_delete_s() is synchronous, returning the LDAP error code indicating 964 the outcome of the operation. 966 ldap_delete() is asynchronous, returning the message id of the operation 967 it initiates, or -1 in case of trouble. The result of the operation can 968 be obtained by calling ldap_result(). 970 5.15. Extended Operations 972 The ldap_extended() and ldap_extended_s() routines allow extended LDAP 973 operations to be passed to the server, providing a general protocol 974 extensibility mechanism. 976 int ldap_extended( 977 LDAP *ld, 978 char *requestoid, 979 struct berval *requestdata 980 ); 982 int ldap_extended_s( 983 LDAP *ld, 984 char *requestoid, 985 struct berval *requestdata, 986 LDAPMessage **result 987 ); 989 Parameters are: 991 ld The session handle. 993 requestoidThe dotted-oid text string naming the request. 995 requestdata 996 The arbitrary data required by the operation. 998 result A result parameter that will be filled in with the result of 999 the operation, suitable for passing to 1000 ldap_parse_extended_result(). 1002 The ldap_extended_s() routine is synchronous and returns an LDAP error 1003 code indicating the success or failure of the extended operation. 1005 The ldap_extended() routine is asynchronous and returns the message id 1006 of the operation it initiates, or -1 in case of trouble. The result of 1007 the operation can be obtained by calling ldap_result(). 1009 LDAP API October 1996 1011 6. Calls for abandoning an operation 1013 ldap_abandon() is used to abandon an operation in progress. 1015 int ldap_abandon( LDAP *ld, int msgid ); 1017 ld The session handle. 1019 msgid The message id of the request to be abandoned. 1021 ldap_abandon() abandons the operation with message id msgid. It returns 1022 zero if the abandon was successful, -1 otherwise. After a successful 1023 call to ldap_abandon(), results with the given message id are never 1024 returned from a call to ldap_result(). 1026 7. Calls for obtaining results 1028 ldap_result() is used to obtain the result of a previous asynchronously 1029 initiated operation. ldap_msgfree() frees the results obtained from a 1030 previous call to ldap_result(), or a synchronous search routine. 1031 ldap_msgtype() returns the type of an LDAP message. 1033 int ldap_result( 1034 LDAP *ld, 1035 int msgid, 1036 int all, 1037 struct timeval *timeout, 1038 LDAPMessage **res 1039 ); 1041 int ldap_msgfree( LDAPMessage *res ); 1043 int ldap_msgtype( LDAPMessage *res ); 1045 Parameters are: 1047 ld The connection handle; 1049 msgid The message id of the operation whose results are to be 1050 returned, or the constant LDAP_RES_ANY if any result is 1051 desired; 1053 all A boolean parameter that only has meaning for search results. 1054 If non-zero it indicates that all results of a search should be 1055 retrieved before any are returned. If zero, search results 1056 (entries) will be returned one at a time as they arrive; 1058 LDAP API October 1996 1060 timeout A timeout specifying how long to wait for results to be 1061 returned. A NULL value causes ldap_result() to block until 1062 results are available. A timeout value of zero seconds speci- 1063 fies a polling behavior; 1065 res For ldap_result(), a result parameter that will contain the 1066 result(s) of the operation. For ldap_msgfree(), the result 1067 chain to be freed, obtained from a previous call to 1068 ldap_result(), ldap_search_s(), ldap_search_st(), or 1069 ldap_search_get_page_s(). 1071 Upon successful completion, ldap_result() returns the type of the result 1072 returned in the res parameter. This will be one of the following con- 1073 stants. 1075 LDAP_RES_BIND 1076 LDAP_RES_SEARCH_ENTRY 1077 LDAP_RES_SEARCH_REFERENCE -- new 1078 LDAP_RES_SEARCH_RESULT 1079 LDAP_RES_MODIFY 1080 LDAP_RES_ADD 1081 LDAP_RES_DELETE 1082 LDAP_RES_MODRDN 1083 LDAP_RES_COMPARE 1084 LDAP_RES_SESSION -- new 1085 LDAP_RES_EXTENDED -- new 1087 ldap_result() returns 0 if the timeout expired and -1 if an error 1088 occurs, in which case the error parameters of the LDAP session handle 1089 will be set accordingly. 1091 ldap_msgfree() frees the result structure pointed to be res and returns 1092 the type of the message it freed. 1094 ldap_msgtype() returns the type of the LDAP message it is passed as a 1095 parameter. The type will be one of the types listed above, or -1 on 1096 error. 1098 8. Calls for Error and Result Handling 1100 The following calls are used to interpret errors returned by other LDAP 1101 API routines. 1103 int ldap_parse_result( 1104 LDAP *ld, 1105 LDAPMessage *result, 1106 char **matched, 1107 char **errmsg, 1109 LDAP API October 1996 1111 char ***referrals 1112 ); 1113 int ldap_parse_bind_result( 1114 LDAP *ld, 1115 LDAPMessage *result, 1116 char **matched, 1117 char **errmsg, 1118 char ***referrals, 1119 int *version, 1120 char *serverurl, 1121 struct berval **servercreds 1122 ); 1123 int ldap_parse_search_result( 1124 LDAP *ld, 1125 LDAPMessage *result, 1126 char **matched, 1127 char **errmsg, 1128 char ***referrals, 1129 int *totalcount 1130 ); 1131 int ldap_parse_compare_result( 1132 LDAP *ld, 1133 LDAPMessage *result, 1134 char **matched, 1135 char **errmsg, 1136 char ***referrals, 1137 char **matchedtype 1138 ); 1139 int ldap_parse_session_result( 1140 LDAP *ld, 1141 LDAPMessage *result, 1142 char **matched, 1143 char **errmsg, 1144 char ***referrals, 1145 char ***unsupported 1146 ); 1147 int ldap_parse_extended_result( 1148 LDAP *ld, 1149 LDAPMessage *result, 1150 char **matched, 1151 char **errmsg, 1152 char ***referrals, 1153 char **resultoid, 1154 struct berval **resultdata 1155 ); 1157 char *ldap_err2string( int err ); 1159 LDAP API October 1996 1161 void ldap_perror( LDAP *ld, char *msg ); 1163 The use of the following routines is deprecated. 1165 int ldap_result2error( 1166 LDAP *ld, 1167 LDAPMessage *result, 1168 int freeit 1169 ); 1171 Parameters are: 1173 ld The connection handle. 1175 result The result of an LDAP operation as returned by ldap_result() or 1176 one of the synchronous API operation calls. 1178 matched In the case of a return of LDAP_NO_SUCH_OBJECT, this result 1179 parameter will be filled in with a DN indicating how much of 1180 the name in the request was recognized. NULL may be passed to 1181 ignore this field. 1183 errmsg This result parameter will be filled in with the contents of 1184 the error message field from the LDAPResult message. NULL may 1185 be passed to ignore this field. 1187 referralsThis result parameter will be filled in with the contents of 1188 the referrals field from the LDAPResult message, indicating 1189 zero or more alternate LDAP servers where the request should be 1190 retried. NULL may be passed to ignore this field. 1192 version For bind results, this result parameter will be filled in with 1193 the version number returned by the LDAP server, indicating the 1194 highest version number the server supports. NULL may be passed 1195 to ignore this field. 1197 serverurlFor bind results, this result parameter will be filled in with 1198 the official LDAP URL for accessing this server, if given. NULL 1199 may be passed to ignore this field. 1201 servercreds 1202 For bind results, this result parameter will be filled in with 1203 the credentials passed back by the server for mutual authenti- 1204 cation, if given. NULL may be passed to ignore this field. 1206 totalcountFor search results, this result parameter will be filled in 1207 with the total count from a paged search request. NULL may be 1208 passed to ignore this field. 1210 LDAP API October 1996 1212 matchedtype 1213 For compare results, this result parameter will be filled in 1214 with the name of the attribute type actually used in the com- 1215 pare match. NULL may be passed to ignore this field. 1217 unsupported 1218 For session results, this result parameter will be filled in with 1219 a NULL-terminated array of string OIDs identifying unsupported 1220 session controls from the corresponding session request. NULL may 1221 be passed to ignore this field. 1223 resultoidFor extended results, this result parameter will be filled in 1224 with the dotted-OID text representation of the name of the 1225 extended operation response. NULL may be passed to ignore this 1226 field. 1228 resultdataFor extended results, this result parameter will be filled in 1229 with a pointer to a struct berval containing the data in the 1230 extended operation response. NULL may be passed to ignore this 1231 field. 1233 err For ldap_err2string(), an LDAP error code, as returned by 1234 ldap_result2error() or one of the synchronous API operation 1235 calls. 1237 msg For ldap_perror(), a message to be displayed before the LDAP 1238 error message. 1240 Parameters for the deprecated calls are not described. Interested 1241 readers are referred to RFC 1823. 1243 All of the ldap_parse*_result() routines return an LDAP error code indi- 1244 cating the outcome of the operation. This is one of the following con- 1245 stants: 1247 LDAP_SUCCESS 1248 LDAP_OPERATIONS_ERROR 1249 LDAP_PROTOCOL_ERROR 1250 LDAP_TIMELIMIT_EXCEEDED 1251 LDAP_SIZELIMIT_EXCEEDED 1252 LDAP_COMPARE_FALSE 1253 LDAP_COMPARE_TRUE 1254 LDAP_STRONG_AUTH_NOT_SUPPORTED 1255 LDAP_STRONG_AUTH_REQUIRED 1256 LDAP_REFERRAL -- new 1257 LDAP_ADMIN_LIMIT_EXCEEDED -- new 1258 LDAP_UNAVAILALBLE_EXTENSION -- new 1259 LDAP_NO_SUCH_ATTRIBUTE 1261 LDAP API October 1996 1263 LDAP_UNDEFINED_TYPE 1264 LDAP_INAPPROPRIATE_MATCHING 1265 LDAP_CONSTRAINT_VIOLATION 1266 LDAP_TYPE_OR_VALUE_EXISTS 1267 LDAP_INVALID_SYNTAX 1268 LDAP_NO_SUCH_OBJECT 1269 LDAP_ALIAS_PROBLEM 1270 LDAP_INVALID_DN_SYNTAX 1271 LDAP_IS_LEAF 1272 LDAP_ALIAS_DEREF_PROBLEM 1273 LDAP_INAPPROPRIATE_AUTH 1274 LDAP_INVALID_CREDENTIALS 1275 LDAP_INSUFFICIENT_ACCESS 1276 LDAP_BUSY 1277 LDAP_UNAVAILABLE 1278 LDAP_UNWILLING_TO_PERFORM 1279 LDAP_LOOP_DETECT 1280 LDAP_NAMING_VIOLATION 1281 LDAP_OBJECT_CLASS_VIOLATION 1282 LDAP_NOT_ALLOWED_ON_NONLEAF 1283 LDAP_NOT_ALLOWED_ON_RDN 1284 LDAP_ALREADY_EXISTS 1285 LDAP_NO_OBJECT_CLASS_MODS 1286 LDAP_RESULTS_TOO_LARGE 1287 LDAP_AFFECTS_MULTIPLE_SERVERS -- new 1288 LDAP_OTHER 1289 LDAP_SERVER_DOWN 1290 LDAP_LOCAL_ERROR 1291 LDAP_ENCODING_ERROR 1292 LDAP_DECODING_ERROR 1293 LDAP_TIMEOUT 1294 LDAP_AUTH_UNKNOWN 1295 LDAP_FILTER_ERROR 1296 LDAP_USER_CANCELLED 1297 LDAP_PARAM_ERROR 1298 LDAP_NO_MEMORY 1299 LDAP_CONNECT_ERROR 1301 In case of trouble (failure to parse the result), -1 is returned. 1303 ldap_err2string() is used to convert a numeric LDAP error code, as 1304 returned by one of the ldap_parse*_result() routines, or one of the syn- 1305 chronous API operation calls, into an informative NULL-terminated char- 1306 acter string message describing the error. It returns a pointer to 1307 static data. 1309 ldap_perror() is used to print the message supplied in msg, followed by 1310 an indication of the error contained in the ld_errno field of the ld 1312 LDAP API October 1996 1314 connection handle, to standard error. 1316 9. Calls for Parsing Search Entries 1318 The following calls are used to parse the entries and references 1319 returned by ldap_search() and friends. These results are returned in an 1320 opaque structure that should only be accessed by calling the routines 1321 described below. Routines are provided to step through the entries and 1322 references returned, step through the attributes of an entry, retrieve 1323 the name of an entry, and retrieve the values associated with a given 1324 attribute in an entry. 1326 9.1. Stepping Through a Set of Entries 1328 The ldap_first_entry() and ldap_next_entry() routines are used to step 1329 through a set of entries and references in a search result. 1330 ldap_count_entries() is used to count the number of entries returned. 1331 ldap_count_references() is used to count the number of references 1332 returned. ldap_msgtype(), described above, can be used to distinguish 1333 between entries and references. 1335 LDAPMesage *ldap_first_entry( LDAP *ld, LDAPMessage *res ); 1337 LDAPMesage *ldap_next_entry( LDAP *ld, LDAPMessage *entry ); 1339 int ldap_count_entries( LDAP *ld, LDAPMessage *res ); 1341 int ldap_count_references( LDAP *ld, LDAPMessage *res ); 1343 Parameters are: 1345 ld The connection handle; 1347 res The search result, as obtained by a call to one of the synchro- 1348 nous search routines or ldap_result(); 1350 entry The entry returned by a previous call to ldap_first_entry() or 1351 ldap_next_entry(). 1353 ldap_first_entry() and ldap_next_entry() will return NULL when no more 1354 entries or references exist in the result set to be returned. NULL is 1355 also returned if an error occurs while stepping through the entries, in 1356 which case the error parameters in the ld session handle will be set to 1357 indicate the error. 1359 ldap_count_entries() returns the number of entries contained in a chain 1360 of entries. It can also be used to count the number of entries that 1361 remain in a chain if called with an entry or reference returned by 1363 LDAP API October 1996 1365 ldap_first_entry() or ldap_next_entry(). 1367 ldap_count_refernces() returns the number of references contained in a 1368 chain of search results. It can also be used to count the number of 1369 references that remain in a chain if called with an entry or references 1370 returned by ldap_first_entry() or ldap_next_entry(). 1372 9.2. Stepping Through the Attributes of an Entry 1374 The ldap_first_attribute() and ldap_next_attribute() calls are used to 1375 step through the list of attribute types returned with an entry. 1377 char *ldap_first_attribute( 1378 LDAP *ld, 1379 LDAPMessage *entry, 1380 BerElement **ptr 1381 ); 1383 char *ldap_next_attribute( 1384 LDAP *ld, 1385 LDAPMessage *entry, 1386 BerElement *ptr 1387 ); 1389 void ldap_memfree( char *mem ); 1391 Parameters are: 1393 ld The connection handle; 1395 entry The entry whose attributes are to be stepped through, as returned 1396 by ldap_first_entry() or ldap_next_entry(); 1398 ptr In ldap_first_attribute(), the address of a pointer used inter- 1399 nally to keep track of the current position in the entry. In 1400 ldap_next_attribute(), the pointer returned by a previous call to 1401 ldap_first_attribute(). 1403 mem A pointer to memory allocated by the LDAP library, such as the 1404 attribute names returned by ldap_first_attribute() and 1405 ldap_next_attribute, or the DN returned by ldap_get_dn(). 1407 ldap_first_attribute() and ldap_next_attribute() will return NULL when 1408 the end of the attributes is reached, or if there is an error, in which 1409 case the error parameters in the ld session handle will be set to indi- 1410 cate the error. 1412 Both routines return a pointer to an allocated buffer containing the 1414 LDAP API October 1996 1416 current attribute name. This should be freed when no longer in use by 1417 calling ldap_memfree(). 1419 ldap_first_attribute() will allocate and return in ptr a pointer to a 1420 BerElement used to keep track of the current position. This pointer 1421 should be passed in subsequent calls to ldap_next_attribute() to step 1422 through the entry's attributes. After a set of calls to 1423 ldap_first_attribute() and ldap_next_attibute(), if ptr is non-NULL, it 1424 should be freed by calling ber_free( ptr, 0 ). Note that it is very 1425 important to pass the second parameter as 0 (zero) in this call. 1427 The attribute names returned are suitable for passing in a call to 1428 ldap_get_values() and friends to retrieve the associated values. 1430 9.3. Retrieving the Values of an Attribute 1432 ldap_get_values() and ldap_get_values_len() are used to retrieve the 1433 values of a given attribute from an entry. ldap_count_values() and 1434 ldap_count_values_len() are used to count the returned values. 1435 ldap_value_free() and ldap_value_free_len() are used to free the values. 1437 typedef struct berval { 1438 unsigned long bv_len; 1439 char *bv_val; 1440 }; 1442 char **ldap_get_values( 1443 LDAP *ld, 1444 LDAPMessage *entry, 1445 char *attr 1446 ); 1448 struct berval **ldap_get_values_len( 1449 LDAP *ld, 1450 LDAPMessage *entry, 1451 char *attr 1452 ); 1454 int ldap_count_values( char **vals ); 1456 int ldap_count_values_len( struct berval **vals ); 1458 int ldap_value_free( char **vals ); 1460 int ldap_value_free_len( struct berval **vals ); 1462 Parameters are: 1464 LDAP API October 1996 1466 ld The connection handle. 1468 entry The entry from which to retrieve values, as returned by 1469 ldap_first_entry() or ldap_next_entry(). 1471 attr The attribute whose values are to be retrieved, as returned by 1472 ldap_first_attribute() or ldap_next_attribute(), or a caller- 1473 supplied string (e.g., "mail"). 1475 vals The values returned by a previous call to ldap_get_values() or 1476 ldap_get_values_len(). 1478 Two forms of the various calls are provided. The first form is only 1479 suitable for use with non-binary character string data only. The second 1480 _len form is used with any kind of data. 1482 Note that the values returned are dynamically allocated and should be 1483 freed by calling either ldap_value_free() or ldap_value_free_len() when 1484 no longer in use. 1486 9.4. Retrieving the name of an entry 1488 ldap_get_dn() is used to retrieve the name of an entry. 1489 ldap_explode_dn() is used to break up the name into its component parts. 1490 ldap_dn2ufn() is used to convert the name into a more "user friendly" 1491 format. 1493 char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ); 1495 char **ldap_explode_dn( char *dn, int notypes ); 1497 char **ldap_explode_rdn( char *rdn, int notypes ); 1499 char *ldap_dn2ufn( char *dn ); 1501 Parameters are: 1503 ld The connection handle. 1505 entry The entry whose name is to be retrieved, as returned by 1506 ldap_first_entry() or ldap_next_entry(). 1508 dn The dn to explode, such as returned by ldap_get_dn(). 1510 rdn The rdn to explode, such as returned in the components of the 1511 array returned by ldap_explode_dn(). 1513 notypes A boolean parameter, if non-zero indicating that the dn or rdn 1515 LDAP API October 1996 1517 components should have their type information stripped off 1518 (i.e., "cn=Babs" would become "Babs"). 1520 ldap_get_dn() will return NULL if there is some error parsing the dn, 1521 setting error parameters in the ld session handle to indicate the error. 1522 It returns a pointer to malloc'ed space that the caller should free by 1523 calling free() when it is no longer in use. Note the format of the DNs 1524 returned is given by [4]. 1526 ldap_explode_dn() returns a NULL-terminated char * array containing the 1527 RDN components of the DN supplied, with or without types as indicated by 1528 the notypes parameter. The array returned should be freed when it is no 1529 longer in use by calling ldap_value_free(). 1531 ldap_explode_rdn() returns a NULL-terminated char * array containing the 1532 components of the RDN supplied, with or without types as indicated by 1533 the notypes parameter. The array returned should be freed when it is no 1534 longer in use by calling ldap_value_free(). 1536 ldap_dn2ufn() converts the DN into the user friendly format described in 1537 [5]. The UFN returned is malloc'ed space that should be freed by a call 1538 to free() when no longer in use. 1540 10. Security Considerations 1542 LDAP supports security through protocol-level authentication, using 1543 clear-text passwords or other more secure mechanisms. It also supports 1544 running over SSL, which provides strong security at the transport layer. 1546 11. Acknowledgements 1548 Many members of the IETF ASID working group as well as members of the 1549 Internet at large have provided useful comments and suggestions that 1550 have been incorporated into this revision. 1552 This original material upon which this revision is based was based upon 1553 work supported by the National Science Foundation under Grant No. NCR- 1554 9416667. 1556 12. Bibliography 1558 [1] The Directory: Selected Attribute Syntaxes. CCITT, Recommendation 1559 X.520. 1561 [2] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory 1562 Access Protocol: Standard and Pilot Attribute Definitions", Inter- 1563 net Draft draft-ietf-asid-ldapv3-attributes-03.txt, October 1996 1565 LDAP API October 1996 1567 [3] T. Howes, "A String Representation of LDAP Search Filters," RFC 1568 1960, June 1996. 1570 [4] S. Kille, "A String Representation of Distinguished Names," RFC 1571 1779, March 1995. 1573 [5] S. Kille, "Using the OSI Directory to Achieve User Friendly Nam- 1574 ing," RFC 1781, March 1995. 1576 [7] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol 1577 (v3)", Internet Draft draft-ietf-asid-ldapv3-protocol-03.txt, 1578 October 1996. 1580 13. Author's Addresses 1582 Tim Howes 1583 Netscape Communications Corp. 1584 501 E. Middlefield Rd. 1585 Mountain View, CA 94043 1586 USA 1587 +1 415 937-3419 1588 howes@netscape.com 1590 Mark Smith 1591 Netscape Communications Corp. 1592 501 E. Middlefield Rd. 1593 Mountain View, CA 94043 1594 USA 1595 +1 313 937-3477 1596 mcs@netscape.com 1598 14. Appendix A - Sample LDAP API Code 1600 #include 1602 main() 1603 { 1604 LDAP *ld; 1605 LDAPMessage *res, *e; 1606 int i; 1607 char *a, *dn; 1608 BerElement *ptr; 1609 char **vals; 1611 /* open a connection */ 1612 if ( (ld = ldap_init( "dotted.host.name", LDAP_PORT )) == NULL ) 1613 exit( 1 ); 1615 LDAP API October 1996 1617 /* authenticate as nobody */ 1618 if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) { 1619 ldap_perror( ld, "ldap_simple_bind_s" ); 1620 exit( 1 ); 1621 } 1623 /* search for entries with cn of "Babs Jensen", return all attrs */ 1624 if ( ldap_search_s( ld, "o=University of Michigan, c=US", 1625 LDAP_SCOPE_SUBTREE, "(cn=Babs Jensen)", NULL, 0, &res ) 1626 != LDAP_SUCCESS ) { 1627 ldap_perror( ld, "ldap_search_s" ); 1628 exit( 1 ); 1629 } 1631 /* step through each entry returned */ 1632 for ( e = ldap_first_entry( ld, res ); e != NULL; 1633 e = ldap_next_entry( ld, e ) ) { 1634 /* print its name */ 1635 dn = ldap_get_dn( ld, e ); 1636 printf( "dn: %s\n", dn ); 1637 free( dn ); 1639 /* print each attribute */ 1640 for ( a = ldap_first_attribute( ld, e, &ptr ); a != NULL; 1641 a = ldap_next_attribute( ld, e, ptr ) ) { 1642 printf( "attribute: %s\n", a ); 1644 /* print each value */ 1645 vals = ldap_get_values( ld, e, a ); 1646 for ( i = 0; vals[i] != NULL; i++ ) { 1647 printf( "value: %s\n", vals[i] ); 1648 } 1649 ldap_value_free( vals ); 1650 } 1651 } 1652 /* free the search results */ 1653 ldap_msgfree( res ); 1655 /* close and free connection resources */ 1656 ldap_unbind( ld ); 1657 }