idnits 2.17.1 draft-ietf-asid-ldap-c-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-19) 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. ** The document is more than 15 pages and seems to lack a Table of Contents. == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 60 lines 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 20 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 2166: '... } OPTIONAL }...' == 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 156 has weird spacing: '...ed long bv_l...' == Line 434 has weird spacing: '... berval ldct...' == Line 952 has weird spacing: '...dded to the...' == Line 957 has weird spacing: '...e is to be de...' == Line 1812 has weird spacing: '...ed long bv_l...' -- 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 (29 July 1997) is 9761 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 2282 looks like a reference -- Missing reference section? '6' on line 2297 looks like a reference -- Missing reference section? '1' on line 2279 looks like a reference -- Missing reference section? '4' on line 2290 looks like a reference -- Missing reference section? '10' on line 2312 looks like a reference -- Missing reference section? '7' on line 2301 looks like a reference -- Missing reference section? '8' on line 2305 looks like a reference -- Missing reference section? '3' on line 2287 looks like a reference -- Missing reference section? '5' on line 2294 looks like a reference -- Missing reference section? '0' on line 2162 looks like a reference -- Missing reference section? '9' on line 2308 looks like a reference -- Missing reference section? '11' on line 2446 looks like a reference Summary: 11 errors (**), 0 flaws (~~), 7 warnings (==), 16 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Howes 3 INTERNET-DRAFT Netscape Communications Corp. 4 Intended Category: Standards Track M. Smith 5 Obsoletes: RFC 1823 Netscape Communications Corp. 6 Expires: January 1998 A. Herron 7 Microsoft Corp. 8 C. Weider 9 Microsoft Corp. 10 M. Wahl 11 Critical Angle, Inc. 13 29 July 1997 15 The C LDAP Application Program Interface 16 18 1. Status of this Memo 20 This draft document will be submitted to the RFC Editor as a Standards 21 Track document. Distribution of this memo is unlimited. Please send com- 22 ments to the authors. 24 This document is an Internet-Draft. Internet-Drafts are working docu- 25 ments of the Internet Engineering Task Force (IETF), its areas, and its 26 working groups. Note that other groups may also distribute working 27 documents as Internet-Drafts. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference material 32 or to cite them other than as ``work in progress.'' 34 To learn the current status of any Internet-Draft, please check the 35 ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow 36 Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), 37 ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). 39 2. Introduction 41 This document defines a C language application program interface to the 42 lightweight directory access protocol (LDAP). This document replaces the 43 previous definition of this API, defined in RFC 1823, updating it to 44 include support for features found in version 3 of the LDAP protocol. 45 New extended operation functions were added to support LDAPv3 features 46 such as controls. In addition, other LDAP API changes were made to 47 support information hiding and thread safety. 49 The C LDAP API is designed to be powerful, yet simple to use. It defines 50 compatible synchronous and asynchronous interfaces to LDAP to suit a 51 wide variety of applications. This document gives a brief overview of 52 the LDAP model, then an overview of how the API is used by an applica- 53 tion program to obtain LDAP information. The API calls are described in 54 detail, followed by an appendix that provides some example code demon- 55 strating the use of the API. This document provides information to the 56 Internet community. It does not specify any standard. 58 3. Overview of the LDAP Model 60 LDAP is the lightweight directory access protocol, described in [2] and 61 [6]. It can provide a lightweight frontend to the X.500 directory [1], 62 or a stand-alone service. In either mode, LDAP is based on a client- 63 server model in which a client makes a TCP connection to an LDAP server, 64 over which it sends requests and receives responses. 66 The LDAP information model is based on the entry, which contains infor- 67 mation about some object (e.g., a person). Entries are composed of 68 attributes, which have a type and one or more values. Each attribute has 69 a syntax that determines what kinds of values are allowed in the attri- 70 bute (e.g., ASCII characters, a jpeg photograph, etc.) and how those 71 values behave during directory operations (e.g., is case significant 72 during comparisons). 74 Entries may be organized in a tree structure, usually based on politi- 75 cal, geographical, and organizational boundaries. Each entry is uniquely 76 named relative to its sibling entries by its relative distinguished name 77 (RDN) consisting of one or more distinguished attribute values from the 78 entry. At most one value from each attribute may be used in the RDN. 79 For example, the entry for the person Babs Jensen might be named with 80 the "Barbara Jensen" value from the commonName attribute. 82 A globally unique name for an entry, called a distinguished name or DN, 83 is constructed by concatenating the sequence of RDNs from the entry up 84 to the root of the tree. For example, if Babs worked for the University 85 of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen, 86 o=University of Michigan, c=US". The DN format used by LDAP is defined 87 in [4]. 89 Operations are provided to authenticate, search for and retrieve infor- 90 mation, modify information, and add and delete entries from the tree. 91 The next sections give an overview of how the API is used and detailed 92 descriptions of the LDAP API calls that implement all of these func- 93 tions. 95 4. Overview of LDAP API Use 97 An application generally uses the C LDAP API in four simple steps. 99 - Initialize an LDAP session with a default LDAP server. The 100 ldap_init() function returns a handle to the session, allowing mul- 101 tiple connections to be open at once. 103 - Authenticate to the LDAP server. The ldap_bind() function and 104 friends support a variety of authentication methods. 106 - Perform some LDAP operations and obtain some results. ldap_search() 107 and friends return results which can be parsed by 108 ldap_result2error(), ldap_first_entry(), ldap_next_entry(), etc. 110 - Close the session. The ldap_unbind() function closes the connec- 111 tion. 113 Operations can be performed either synchronously or asynchronously. The 114 names of the synchronous functions end in _s. For example, a synchronous 115 search can be completed by calling ldap_search_s(). An asynchronous 116 search can be initiated by calling ldap_search(). All synchronous rou- 117 tines return an indication of the outcome of the operation (e.g, the 118 constant LDAP_SUCCESS or some other error code). The asynchronous rou- 119 tines return the message id of the operation initiated. This id can be 120 used in subsequent calls to ldap_result() to obtain the result(s) of the 121 operation. An asynchronous operation can be abandoned by calling 122 ldap_abandon(). 124 Results and errors are returned in an opaque structure called LDAPMes- 125 sage. Routines are provided to parse this structure, step through 126 entries and attributes returned, etc. Routines are also provided to 127 interpret errors. Later sections of this document describe these rou- 128 tines in more detail. 130 LDAP version 3 servers may return referrals to other servers. By 131 default, implementations of this API will attempt to follow referrals 132 automatically for the application. This behavior can be disabled glo- 133 bally (using the ldap_set_option() call) or on a per-request basis 134 through the use of a client control. 136 As in the LDAPv3 protocol itself, all DNs and string values that are 137 passed into or produced by the C LDAP API are represented as UTF-8[10] 138 characters. 140 For compatibility with existing applications, implementations of this 141 API will by default use version 2 of the LDAP protocol. Applications 142 that intend to take advantage of LDAP version 3 features will need to 143 use the ldap_set_option() call with a LDAP_OPT_PROTOCOL_VERSION to 144 switch to version 3. 146 5. Common Data Structures 148 Some data structures that are common to several LDAP API functions are 149 defined here: 151 typedef struct ldap LDAP; 153 typedef struct ldapmsg LDAPMessage; 155 struct berval { 156 unsigned long bv_len; 157 char *bv_val; 158 }; 160 struct timeval { 161 long tv_sec; 162 long tv_usec; 163 }; 165 The LDAP structure is an opaque data type that represents an LDAP ses- 166 sion Typically this corresponds to a connection to a single server, but 167 it may encompass several server connections in the face of LDAPv3 refer- 168 rals. 170 The LDAPMessage structure is an opaque data type that is used to return 171 results and error information. 173 The berval structure is used to represent arbitrary binary data and its 174 fields have the following meanings: 176 bv_len Length of data in bytes. 178 bv_val A pointer to the data itself. 180 The timeval structure is used to represent an interval of time and its 181 fields have the following meanings: 183 tv_sec Seconds component of time interval. 185 tv_usec Microseconds component of time interval. 187 6. LDAP Error Codes 189 Many of the LDAP API routines return LDAP error codes, some of which 190 indicate local errors and some of which may be returned by servers. 191 Supported error codes are (hexadecimal values are given in parentheses 192 after the constant): 194 LDAP_SUCCESS (0x00) 195 LDAP_OPERATIONS_ERROR( 0x01) 196 LDAP_PROTOCOL_ERROR (0x02) 197 LDAP_TIMELIMIT_EXCEEDED (0x03) 198 LDAP_SIZELIMIT_EXCEEDED (0x04) 199 LDAP_COMPARE_FALSE (0x05) 200 LDAP_COMPARE_TRUE (0x06) 201 LDAP_STRONG_AUTH_NOT_SUPPORTED (0x07) 202 LDAP_STRONG_AUTH_REQUIRED (0x08) 203 LDAP_REFERRAL (0x0a) -- new in LDAPv3 204 LDAP_ADMINLIMIT_EXCEEDED (0x0b) -- new in LDAPv3 205 LDAP_UNAVAILABLE_CRITICAL_EXTENSION (0x0c) -- new in LDAPv3 206 LDAP_CONFIDENTIALITY_REQUIRED (0x0d) -- new in LDAPv3 207 LDAP_NO_SUCH_ATTRIBUTE (0x10) 208 LDAP_UNDEFINED_TYPE (0x11) 209 LDAP_INAPPROPRIATE_MATCHING (0x12) 210 LDAP_CONSTRAINT_VIOLATION (0x13) 211 LDAP_TYPE_OR_VALUE_EXISTS (0x14) 212 LDAP_INVALID_SYNTAX (0x15) 213 LDAP_NO_SUCH_OBJECT (0x20) 214 LDAP_ALIAS_PROBLEM (0x21) 215 LDAP_INVALID_DN_SYNTAX (0x22) 216 LDAP_IS_LEAF (0x23) -- not used in LDAPv3 217 LDAP_ALIAS_DEREF_PROBLEM (0x24) 218 LDAP_INAPPROPRIATE_AUTH (0x30) 219 LDAP_INVALID_CREDENTIALS (0x31) 220 LDAP_INSUFFICIENT_ACCESS (0x32) 221 LDAP_BUSY (0x33) 222 LDAP_UNAVAILABLE (0x34) 223 LDAP_UNWILLING_TO_PERFORM (0x35) 224 LDAP_LOOP_DETECT (0x36) 225 LDAP_NAMING_VIOLATION (0x40) 226 LDAP_OBJECT_CLASS_VIOLATION (0x41) 227 LDAP_NOT_ALLOWED_ON_NONLEAF (0x42) 228 LDAP_NOT_ALLOWED_ON_RDN (0x43) 229 LDAP_ALREADY_EXISTS (0x44) 230 LDAP_NO_OBJECT_CLASS_MODS (0x45) 231 LDAP_RESULTS_TOO_LARGE (0x46) 232 LDAP_AFFECTS_MULTIPLE_DSAS (0x47) -- new in LDAPv3 233 LDAP_OTHER (0x50) 234 LDAP_SERVER_DOWN (0x51) 235 LDAP_LOCAL_ERROR (0x52) 236 LDAP_ENCODING_ERROR (0x53) 237 LDAP_DECODING_ERROR (0x54) 238 LDAP_TIMEOUT (0x55) 239 LDAP_AUTH_UNKNOWN (0x56) 240 LDAP_FILTER_ERROR (0x57) 241 LDAP_USER_CANCELLED (0x58) 242 LDAP_PARAM_ERROR (0x59) 243 LDAP_NO_MEMORY (0x5a) 244 LDAP_CONNECT_ERROR (0x5b) 245 LDAP_NOT_SUPPORTED (0x5c) 246 LDAP_CONTROL_NOT_FOUND (0x5d) 247 LDAP_NO_RESULTS_RETURNED (0x5e) 248 LDAP_MORE_RESULTS_TO_RETURN (0x5f) 249 LDAP_CLIENT_LOOP (0x60) 250 LDAP_REFERRAL_LIMIT_EXCEEDED (0x61) 252 7. Performing LDAP Operations 254 This section describes each LDAP operation API call in detail. All func- 255 tions take a "session handle," a pointer to an LDAP structure containing 256 per-connection information. Many routines return results in an LDAPMes- 257 sage structure. These structures and others are described as needed 258 below. 260 7.1. Initializing an LDAP Session 262 ldap_init() initializes a session with an LDAP server. The server is not 263 actually contacted until an operation is performed that requires it, 264 allowing various options to be set after initialization. 266 LDAP *ldap_init( 267 char *hostname, 268 int portno 269 ); 271 Use of the following routine is deprecated. 273 LDAP *ldap_open( 274 char *hostname, 275 int portno 276 ); 278 Parameters are: 280 hostname Contains a space-separated list of hostnames or dotted strings 281 representing the IP address of hosts running an LDAP server to 282 connect to. Each hostname in the list can include an optional 283 port number which is separated from the host itself with a 284 colon (:) character. The hosts are tried in the order listed, 285 stopping with the first one to which a successful connection is 286 made. Note that only ldap_open() attempts to make the connec- 287 tion before returning to the caller. ldap_init() does not con- 288 nect to the LDAP server. 290 portno Contains the TCP port number to connect to. The default LDAP 291 port of 389 can be obtained by supplying the constant 292 LDAP_PORT. If a host includes a port number then this parame- 293 ter is ignored. 295 ldap_init() and ldap_open() both return a "session handle," a pointer to 296 an opaque structure that should be passed to subsequent calls pertaining 297 to the session. These routines return NULL if the session cannot be ini- 298 tialized in which case the operating system error reporting mechanism 299 can be checked to see why the call failed. 301 Note that if you connect to an LDAPv2 server, one of the ldap_bind() 302 calls described below must be completed before other operations can be 303 performed on the session. LDAPv3 does not require that a bind operation 304 be completed before other operations can be performed. 306 The calling program can set various attributes of the session by calling 307 the routines described in the next section. 309 7.2. LDAP Session Handle Options 311 The LDAP session handle returned by ldap_init() is a pointer to an 312 opaque data type representing an LDAP session. Formerly, this data type 313 was a structure exposed to the caller, and various fields in the struc- 314 ture could be set to control aspects of the session, such as size and 315 time limits on searches. 317 In the interest of insulating callers from inevitable changes to this 318 structure, these aspects of the session are now accessed through a pair 319 of accessor functions, described below. 321 ldap_get_option() is used to access the current value of various 322 session-wide parameters. ldap_set_option() is used to set the value of 323 these parameters. 325 int ldap_get_option( 326 LDAP *ld, 327 int option, 328 void *outvalue 329 ); 331 int ldap_set_option( 332 LDAP *ld, 333 int option, 334 void *invalue 335 ); 337 Parameters are: 339 ld The session handle. 341 option The name of the option being accessed or set. This parameter 342 should be one of the following constants, which have the indi- 343 cated meanings. After the constant the actual value of the con- 344 stant is listed in hexadecimal in parentheses followed by the 345 type of the corresponding outvalue or invalue parameter. 347 LDAP_OPT_DESC (0x01) int * 348 The underlying socket descriptor corresponding to the default 349 LDAP connection. 351 LDAP_OPT_DEREF (0x02) int * 352 Controls how aliases are handled during search. It can have 353 one of the following values: LDAP_DEREF_NEVER (0x00), 354 LDAP_DEREF_SEARCHING (0x01), LDAP_DEREF_FINDING (0x02), or 355 LDAP_DEREF_ALWAYS (0x03). The LDAP_DEREF_SEARCHING value 356 means aliases should be dereferenced during the search but not 357 when locating the base object of the search. The 358 LDAP_DEREF_FINDING value means aliases should be dereferenced 359 when locating the base object but not during the search. 361 LDAP_OPT_SIZELIMIT (0x03) int * 362 A limit on the number of entries to return from a search. A 363 value of zero means no limit. 365 LDAP_OPT_TIMELIMIT (0x04) int * 366 A limit on the number of seconds to spend on a search. A value 367 of zero means no limit 369 LDAP_OPT_REBIND_FN (0x06) function pointer 370 See the discussion of ldap_bind() and friends below. 372 LDAP_OPT_REBIND_ARG (0x07) void * 373 See the discussion of ldap_bind() and friends below. 375 LDAP_OPT_REFERRALS (0x08) void * 376 This option controls whether the LDAP library automatically 377 follows referrals returned by LDAP servers or not. It can be 378 set to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF. 380 LDAP_OPT_RESTART (0x09) void * 381 This option controls whether LDAP I/O operations should 382 automatically be restarted if they abort prematurely. It 383 should be set to one of the constants LDAP_OPT_ON or 384 LDAP_OPT_OFF. This option is useful if an LDAP I/O operation 385 may be interrupted prematurely, for example by a timer going 386 off, or other interrrupt. 388 LDAP_OPT_PROTOCOL_VERSION (0x11) int * 389 This option indicates the version of the default LDAP server. 390 It can be one of the constants LDAP_VERSION2 or LDAP_VERSION3. 391 If no version is set the default is LDAP_VERSION2. 393 LDAP_OPT_SERVER_CONTROLS (0x12) LDAPControl ** 394 A default list of LDAP server controls to be sent with each 395 request. See the Using Controls section below. 397 LDAP_OPT_CLIENT_CONTROLS (0x13) LDAPControl ** 398 A default list of client controls that affect the LDAP ses- 399 sion. See the Using Controls section below. 401 LDAP_OPT_HOST_NAME (0x30) char ** 402 The host name of the default LDAP server. 404 LDAP_OPT_ERROR_NUMBER (0x31) int * 405 The code of the most recent LDAP error that occurred for this 406 session. 408 LDAP_OPT_ERROR_STRING (0x32) char ** 409 The message returned with the most recent LDAP error that 410 occurred for this session. 412 outvalue The address of a place to put the value of the option. The 413 actual type of this parameter depends on the setting of the 414 option parameter. 416 invalue A pointer to the value the option is to be given. The actual 417 type of this parameter depends on the setting of the option 418 parameter. The constants LDAP_OPT_ON and LDAP_OPT_OFF can be 419 given for options that have on or off settings. 421 7.3. Working with controls 423 LDAPv3 operations can be extended through the use of controls. Controls 424 may be sent to a server or returned to the client with any LDAP message. 425 These controls are referred to as server controls. 427 The LDAP API also supports a client-side extension mechanism through the 428 use of client controls. These controls affect the behavior of the LDAP 429 API only and are never sent to a server. A common data structure is 430 used to represent both types of controls: 432 typedef struct ldapcontrol { 433 char *ldctl_oid; 434 struct berval ldctl_value; 435 char ldctl_iscritical; 436 } LDAPControl, *PLDAPControl; 438 The fields in the ldapcontrol structure have the following meanings: 440 ldctl_oid The control type, represented as a string. 442 ldctl_value The data associated with the control (if any). 444 ldctl_iscritical Indicates whether the control is critical of not. If 445 this field is non-zero, the operation will only be car- 446 ried out if the control is recognized by the server 447 and/or client. 449 Some LDAP API calls allocate an ldapcontrol structure or a NULL- 450 terminated array of ldapcontrol structures. The following routines can 451 be used to dispose of a single control or an array of controls: 453 void ldap_control_free( LDAPControl *ctrl ); 454 void ldap_controls_free( LDAPControl **ctrls ); 456 A set of controls that affect the entire session can be set using the 457 ldap_set_option() function (see above). A list of controls can also be 458 passed directly to some LDAP API calls such as ldap_search_ext(), in 459 which case any controls set for the session through the use of 460 ldap_set_option() are ignored. Control lists are represented as a NULL- 461 terminated array of pointers to ldapcontrol structures. 463 Server controls are defined by LDAPv3 protocol extension documents; for 464 example, a control has been proposed to support server-side sorting of 465 search results [7]. 467 No client controls are defined by this document but they may be defined 468 in future revisions or in any document that extends this API. 470 7.4. Authenticating to the directory 472 The following functions are used to authenticate an LDAP client to an 473 LDAP directory server. 475 The ldap_sasl_bind() and ldap_sasl_bind_s() functions can be used to do 476 general and extensible authentication over LDAP through the use of the 477 Simple Authentication Security Layer [8]. The routines both take the dn 478 to bind as, the method to use, as a dotted-string representation of an 479 OID identifying the method, and a struct berval holding the credentials. 480 The special constant value LDAP_SASL_SIMPLE ("") can be passed to 481 request simple authentication, or the simplified routines 482 ldap_simple_bind() or ldap_simple_bind_s() can be used. 484 int ldap_sasl_bind( 485 LDAP *ld, 486 char *dn, 487 char *mechanism, 488 struct berval *cred, 489 LDAPControl **serverctrls, 490 LDAPControl **clientctrls, 491 int *msgidp 492 ); 494 int ldap_sasl_bind_s( 495 LDAP *ld, 496 char *dn, 497 char *mechanism, 498 struct berval *cred, 499 LDAPControl **serverctrls, 500 LDAPControl **clientctrls, 501 struct berval **servercredp 502 ); 504 int ldap_simple_bind( 505 LDAP *ld, 506 char *dn, 507 char *passwd 508 ); 510 int ldap_simple_bind_s( 511 LDAP *ld, 512 char *dn, 513 char *passwd 514 ); 516 The use of the following routines is deprecated: 518 int ldap_bind( LDAP *ld, char *dn, char *cred, int method ); 520 int ldap_bind_s( LDAP *ld, char *dn, char *cred, int method ); 522 int ldap_kerberos_bind( LDAP *ld, char *dn ); 524 int ldap_kerberos_bind_s( LDAP *ld, char *dn ); 526 Parameters are: 528 ld The session handle. 530 dn The name of the entry to bind as. 532 mechanism Either LDAP_AUTH_SIMPLE_OID to get simple authentication, 533 or a dotted text string representing an OID identifying the 534 SASL method. 536 cred The credentials with which to authenticate. Arbitrary 537 credentials can be passed using this parameter. The format 538 and content of the credentials depends on the setting of 539 the mechanism parameter. 541 passwd For ldap_simple_bind(), the password to compare to the 542 entry's userPassword attribute. 544 serverctrls List of LDAP server controls. 546 clientctrls List of client controls. 548 msgidp This result parameter will be set to the message id of the 549 request if the ldap_sasl_bind() call succeeds. 551 servercredp This result parameter will be set to the credentials 552 returned by the server. This should be freed by calling 553 ldap_If no credentials are returned it will be set to NULL. 555 Additional parameters for the deprecated routines are not described. 556 Interested readers are referred to RFC 1823. 558 The ldap_sasl_bind() function initiates an asynchronous bind operation 559 and returns the constant LDAP_SUCCESS if the request was successfully 560 sent, or another LDAP error code if not. See the section below on error 561 handling for more information about possible errors and how to interpret 562 them. If successful, ldap_sasl_bind() places the message id of the 563 request in *msgidp. A subsequent call to ldap_result(), described below, 564 can be used to obtain the result of the bind. 566 The ldap_simple_bind() function initiates a simple asynchronous bind 567 operation and returns the message id of the operation initiated. A sub- 568 sequent call to ldap_result(), described below, can be used to obtain 569 the result of the bind. In case of error, ldap_simple_bind() will return 570 -1, setting the session error parameters in the LDAP structure appropri- 571 ately. 573 The synchronous ldap_sasl_bind_s() and ldap_simple_bind_s() functions 574 both return the result of the operation, either the constant 575 LDAP_SUCCESS if the operation was successful, or another LDAP error code 576 if it was not. See the section below on error handling for more informa- 577 tion about possible errors and how to interpret them. 579 Note that if an LDAPv2 server is contacted, no other operations over the 580 connection should be attempted before a bind call has successfully com- 581 pleted. 583 Subsequent bind calls can be used to re-authenticate over the same con- 584 nection, and multistep SASL sequences can be accomplished through a 585 sequence of calls to ldap_sasl_bind() or ldap_sasl_bind_s(). 587 7.5. Closing the session 589 The following functions are used to unbind from the directory, close the 590 connection, and dispose of the session handle. 592 int ldap_unbind( LDAP *ld ); 594 int ldap_unbind_s( LDAP *ld ); 596 Parameters are: 598 ld The session handle. 600 ldap_unbind() and ldap_unbind_s() both work synchronously, unbinding 601 from the directory, closing the connection, and freeing up the ld struc- 602 ture before returning. There is no server response to an unbind opera- 603 tion. ldap_unbind() returns LDAP_SUCCESS (or another LDAP error code if 604 the request cannot be sent to the LDAP server). After a call to 605 ldap_unbind() or ldap_unbind_s(), the session handle ld is invalid. 607 7.6. Searching 609 The following functions are used to search the LDAP directory, returning 610 a requested set of attributes for each entry matched. There are five 611 variations. 613 int ldap_search_ext( 614 LDAP *ld, 615 char *base, 616 int scope, 617 char *filter, 618 char **attrs, 619 int attrsonly, 620 LDAPControl **serverctrls, 621 LDAPControl **clientctrls, 622 struct timeval *timeoutp, 623 int sizelimit, 624 int *msgidp 625 ); 627 int ldap_search_ext_s( 628 LDAP *ld, 629 char *base, 630 int scope, 631 char *filter, 632 char **attrs, 633 int attrsonly, 634 LDAPControl **serverctrls, 635 LDAPControl **clientctrls, 636 struct timeval *timeoutp, 637 int sizelimit, 638 LDAPMessage **res 639 ); 641 int ldap_search( 642 LDAP *ld, 643 char *base, 644 int scope, 645 char *filter, 646 char **attrs, 647 int attrsonly 648 ); 650 int ldap_search_s( 651 LDAP *ld, 652 char *base, 653 int scope, 654 char *filter, 655 char **attrs, 656 int attrsonly, 657 LDAPMessage **res 658 ); 660 int ldap_search_st( 661 LDAP *ld, 662 char *base, 663 int scope, 664 char *filter, 665 char **attrs, 666 int attrsonly, 667 struct timeval *timeout, 668 LDAPMessage **res 669 ); 671 Parameters are: 673 ld The session handle. 675 base The dn of the entry at which to start the search. 677 scope One of LDAP_SCOPE_BASE (0x00), LDAP_SCOPE_ONELEVEL (0x01), 678 or LDAP_SCOPE_SUBTREE (0x02), indicating the scope of the 679 search. 681 filter A character string as described in [3], representing the 682 search filter. 684 attrs A NULL-terminated array of strings indicating which attri- 685 butes to return for each matching entry. Passing NULL for 686 this parameter causes all available attributes to be 687 retrieved. 689 attrsonly A boolean value that should be zero if both attribute types 690 and values are to be returned, non-zero if only types are 691 wanted. 693 timeout For the ldap_search_st() function, this specifies the local 694 search timeout value. For the ldap_search_ext() and 695 ldap_search_ext_s() functions, this specifies both the 696 local search timeout value and the operation time limit 697 that is sent to the server within the search request. 699 res For the synchronous calls, this is a result parameter which 700 will contain the results of the search upon completion of 701 the call. 703 serverctrls List of LDAP server controls. 705 clientctrls List of client controls. 707 msgidp This result parameter will be set to the message id of the 708 request if the ldap_search_ext() call succeeds. 710 There are three options in the session handle ld which potentially 711 affect how the search is performed. They are: 713 LDAP_OPT_SIZELIMIT 714 A limit on the number of entries to return from the search. 715 A value of zero means no limit. Note that the value from 716 the session handle is ignored when using the 717 ldap_search_ext() or ldap_search_ext_s() functions. 719 LDAP_OPT_TIMELIMIT 720 A limit on the number of seconds to spend on the search. A 721 value of zero means no limit. Note that the value from the 722 session handle is ignored when using the ldap_search_ext() 723 or ldap_search_ext_s() functions. 725 LDAP_OPT_DEREF 726 One of LDAP_DEREF_NEVER (0x00), LDAP_DEREF_SEARCHING 727 (0x01), LDAP_DEREF_FINDING (0x02), or LDAP_DEREF_ALWAYS 728 (0x03), specifying how aliases should be handled during the 729 search. The LDAP_DEREF_SEARCHING value means aliases should 730 be dereferenced during the search but not when locating the 731 base object of the search. The LDAP_DEREF_FINDING value 732 means aliases should be dereferenced when locating the base 733 object but not during the search. 735 The ldap_search_ext() function initiates an asynchronous search opera- 736 tion and returns the constant LDAP_SUCCESS if the request was success- 737 fully sent, or another LDAP error code if not. See the section below on 738 error handling for more information about possible errors and how to 739 interpret them. If successful, ldap_search_ext() places the message id 740 of the request in *msgidp. A subsequent call to ldap_result(), described 741 below, can be used to obtain the results from the search. These results 742 can be parsed using the result parsing routines described in detail 743 later. 745 Similar to ldap_search_ext(), the ldap_search() function initiates an 746 asynchronous search operation and returns the message id of the opera- 747 tion initiated. As for ldap_search_ext(), a subsequent call to 748 ldap_result(), described below, can be used to obtain the result of the 749 bind. In case of error, ldap_search() will return -1, setting the ses- 750 sion error parameters in the LDAP structure appropriately. 752 The synchronous ldap_search_ext_s(), ldap_search_s(), and 753 ldap_search_st() functions all return the result of the operation, 754 either the constant LDAP_SUCCESS if the operation was successful, or 755 another LDAP error code if it was not. See the section below on error 756 handling for more information about possible errors and how to interpret 757 them. Entries returned from the search (if any) are contained in the 758 res parameter. This parameter is opaque to the caller. Entries, attri- 759 butes, values, etc., should be extracted by calling the parsing routines 760 described below. The results contained in res should be freed when no 761 longer in use by calling ldap_msgfree(), described later. 763 The ldap_search_ext() and ldap_search_ext_s() functions support LDAPv3 764 server controls, client controls, and allow varying size and time limits 765 to be easily specified for each search operation. The ldap_search_st() 766 function is identical to ldap_search_s() except that it takes an addi- 767 tional parameter specifying a local timeout for the search. 769 7.7. Reading an Entry 771 LDAP does not support a read operation directly. Instead, this operation 772 is emulated by a search with base set to the DN of the entry to read, 773 scope set to LDAP_SCOPE_BASE, and filter set to "(objectclass=*)". attrs 774 contains the list of attributes to return. 776 7.8. Listing the Children of an Entry 778 LDAP does not support a list operation directly. Instead, this operation 779 is emulated by a search with base set to the DN of the entry to list, 780 scope set to LDAP_SCOPE_ONELEVEL, and filter set to "(objectclass=*)". 781 attrs contains the list of attributes to return for each child entry. 783 7.9. Comparing a Value Against an Entry 785 The following routines are used to compare a given attribute value 786 assertion against an LDAP entry. There are four variations: 788 int ldap_compare_ext( 789 LDAP *ld, 790 char *dn, 791 char *attr, 792 struct berval *bvalue 793 LDAPControl **serverctrls, 794 LDAPControl **clientctrls, 795 int *msgidp 796 ); 798 int ldap_compare_ext_s( 799 LDAP *ld, 800 char *dn, 801 char *attr, 802 struct berval *bvalue, 803 LDAPControl **serverctrls, 804 LDAPControl **clientctrls 806 ); 808 int ldap_compare( 809 LDAP *ld, 810 char *dn, 811 char *attr, 812 char *value 813 ); 815 int ldap_compare_s( 816 LDAP *ld, 817 char *dn, 818 char *attr, 819 char *value 820 ); 822 Parameters are: 824 ld The session handle. 826 dn The name of the entry to compare against. 828 attr The attribute to compare against. 830 bvalue The attribute value to compare against those found in the 831 given entry. This parameter is used in the extended rou- 832 tines and is a pointer to a struct berval so it is possible 833 to compare binary values. 835 value A string attribute value to compare against, used by the 836 ldap_compare() and ldap_compare_s() functions. Use 837 ldap_compare_ext() or ldap_compare_ext_s() if you need to 838 compare binary values. 840 serverctrls List of LDAP server controls. 842 clientctrls List of client controls. 844 msgidp This result parameter will be set to the message id of the 845 request if the ldap_compare_ext() call succeeds. 847 The ldap_compare_ext() function initiates an asynchronous compare opera- 848 tion and returns the constant LDAP_SUCCESS if the request was success- 849 fully sent, or another LDAP error code if not. See the section below on 850 error handling for more information about possible errors and how to 851 interpret them. If successful, ldap_compare_ext() places the message id 852 of the request in *msgidp. A subsequent call to ldap_result(), described 853 below, can be used to obtain the result of the compare. 855 Similar to ldap_compare_ext(), the ldap_compare() function initiates an 856 asynchronous compare operation and returns the message id of the opera- 857 tion initiated. As for ldap_compare_ext(), a subsequent call to 858 ldap_result(), described below, can be used to obtain the result of the 859 bind. In case of error, ldap_compare() will return -1, setting the ses- 860 sion error parameters in the LDAP structure appropriately. 862 The synchronous ldap_compare_ext_s() and ldap_compare_s() functions both 863 return the result of the operation, either the constant LDAP_SUCCESS if 864 the operation was successful, or another LDAP error code if it was not. 865 See the section below on error handling for more information about pos- 866 sible errors and how to interpret them. 868 The ldap_compare_ext() and ldap_compare_ext_s() functions support LDAPv3 869 server controls and client controls. 871 7.10. Modifying an entry 873 The following routines are used to modify an existing LDAP entry. There 874 are four variations: 876 typedef struct ldapmod { 877 int mod_op; 878 char *mod_type; 879 union { 880 char **modv_strvals; 881 struct berval **modv_bvals; 882 } mod_vals; 883 } LDAPMod; 884 #define mod_values mod_vals.modv_strvals 885 #define mod_bvalues mod_vals.modv_bvals 887 int ldap_modify_ext( 888 LDAP *ld, 889 char *dn, 890 LDAPMod **mods, 891 LDAPControl **serverctrls, 892 LDAPControl **clientctrls, 893 int *msgidp 894 ); 896 int ldap_modify_ext_s( 897 LDAP *ld, 898 char *dn, 899 LDAPMod **mods, 900 LDAPControl **serverctrls, 901 LDAPControl **clientctrls 903 ); 905 int ldap_modify( 906 LDAP *ld, 907 char *dn, 908 LDAPMod **mods 909 ); 911 int ldap_modify_s( 912 LDAP *ld, 913 char *dn, 914 LDAPMod **mods 915 ); 917 Parameters are: 919 ld The session handle. 921 dn The name of the entry to modify. 923 mods A NULL-terminated array of modifications to make to the 924 entry. 926 serverctrls List of LDAP server controls. 928 clientctrls List of client controls. 930 msgidp This result parameter will be set to the message id of the 931 request if the ldap_modify_ext() call succeeds. 933 The fields in the LDAPMod structure have the following meanings: 935 mod_op The modification operation to perform. It should be one of 936 LDAP_MOD_ADD (0x00), LDAP_MOD_DELETE (0x01), or 937 LDAP_MOD_REPLACE (0x02). This field also indicates the 938 type of values included in the mod_vals union. It is logi- 939 cally ORed with LDAP_MOD_BVALUES (0x80) to select the 940 mod_bvalues form. Otherwise, the mod_values form is used. 942 mod_type The type of the attribute to modify. 944 mod_vals The values (if any) to add, delete, or replace. Only one of 945 the mod_values or mod_bvalues variants should be used, 946 selected by ORing the mod_op field with the constant 947 LDAP_MOD_BVALUES. mod_values is a NULL-terminated array of 948 zero-terminated strings and mod_bvalues is a NULL- 949 terminated array of berval structures that can be used to 950 pass binary values such as images. 952 For LDAP_MOD_ADD modifications, the given values are added to the 953 entry, creating the attribute if necessary. 955 For LDAP_MOD_DELETE modifications, the given values are deleted from the 956 entry, removing the attribute if no values remain. If the entire attri- 957 bute is to be deleted, the mod_vals field should be set to NULL. 959 For LDAP_MOD_REPLACE modifications, the attribute will have the listed 960 values after the modification, having been created if necessary, or 961 removed if the mod_vals field is NULL. All modifications are performed 962 in the order in which they are listed. 964 The ldap_modify_ext() function initiates an asynchronous modify opera- 965 tion and returns the constant LDAP_SUCCESS if the request was success- 966 fully sent, or another LDAP error code if not. See the section below on 967 error handling for more information about possible errors and how to 968 interpret them. If successful, ldap_modify_ext() places the message id 969 of the request in *msgidp. A subsequent call to ldap_result(), described 970 below, can be used to obtain the result of the modify. 972 Similar to ldap_modify_ext(), the ldap_modify() function initiates an 973 asynchronous modify operation and returns the message id of the opera- 974 tion initiated. As for ldap_modify_ext(), a subsequent call to 975 ldap_result(), described below, can be used to obtain the result of the 976 modify. In case of error, ldap_modify() will return -1, setting the ses- 977 sion error parameters in the LDAP structure appropriately. 979 The synchronous ldap_modify_ext_s() and ldap_modify_s() functions both 980 return the result of the operation, either the constant LDAP_SUCCESS if 981 the operation was successful, or another LDAP error code if it was not. 982 See the section below on error handling for more information about pos- 983 sible errors and how to interpret them. 985 The ldap_modify_ext() and ldap_modify_ext_s() functions support LDAPv3 986 server controls and client controls. 988 7.11. Modifying the Name of an Entry 990 In LDAPv2, the ldap_modrdn() and ldap_modrdn_s() routines were used to 991 change the name of an LDAP entry. They could only be used to change the 992 least significant component of a name (the RDN or relative distinguished 993 name). LDAPv3 provides the Modify DN protocol operation that allows more 994 general name change access. The ldap_rename() and ldap_rename_s() rou- 995 tines are used to change the name of an entry, and the use of the 996 ldap_modrdn() and ldap_modrdn_s() routines is deprecated. 998 int ldap_rename( 999 LDAP *ld, 1000 char *dn, 1001 char *newrdn, 1002 char *newparent, 1003 int deleteoldrdn, 1004 LDAPControl **serverctrls, 1005 LDAPControl **clientctrls, 1006 int *msgidp 1008 ); 1009 int ldap_rename_s( 1010 LDAP *ld, 1011 char *dn, 1012 char *newrdn, 1013 char *newparent, 1014 int deleteoldrdn, 1015 LDAPControl **serverctrls, 1016 LDAPControl **clientctrls 1017 ); 1019 Use of the following routines is deprecated. 1021 int ldap_modrdn( 1022 LDAP *ld, 1023 char *dn, 1024 char *newrdn, 1025 int deleteoldrdn 1026 ); 1027 int ldap_modrdn_s( 1028 LDAP *ld, 1029 char *dn, 1030 char *newrdn, 1031 int deleteoldrdn 1032 ); 1034 Parameters are: 1036 ld The session handle. 1038 dn The name of the entry whose DN is to be changed. 1040 newrdn The new RDN to give the entry. 1042 newparent The new parent, or superior entry. If this parameter is 1043 NULL, only the RDN of the entry is changed. The root DN 1044 may be specified by passing a zero length string, "". The 1045 newparent parameter should always be NULL when using ver- 1046 sion 2 of the LDAP protocol; otherwise the server's 1047 behavior is undefined. 1049 deleteoldrdn This parameter only has meaning on the rename routines if 1050 newrdn is different than the old RDN. It is a boolean 1051 value, if non-zero indicating that the old RDN value(s) 1052 should be removed, if zero indicating that the old RDN 1053 value(s) should be retained as non-distinguished values of 1054 the entry. 1056 serverctrls List of LDAP server controls. 1058 clientctrls List of client controls. 1060 msgidp This result parameter will be set to the message id of the 1061 request if the ldap_rename() call succeeds. 1063 The ldap_rename() function initiates an asynchronous modify DN operation 1064 and returns the constant LDAP_SUCCESS if the request was successfully 1065 sent, or another LDAP error code if not. See the section below on error 1066 handling for more information about possible errors and how to interpret 1067 them. If successful, ldap_rename() places the DN message id of the 1068 request in *msgidp. A subsequent call to ldap_result(), described below, 1069 can be used to obtain the result of the rename. 1071 The synchronous ldap_rename_s() returns the result of the operation, 1072 either the constant LDAP_SUCCESS if the operation was successful, or 1073 another LDAP error code if it was not. See the section below on error 1074 handling for more information about possible errors and how to interpret 1075 them. 1077 The ldap_rename() and ldap_rename_s() functions both support LDAPv3 1078 server controls and client controls. 1080 7.12. Adding an entry 1082 The following functions are used to add entries to the LDAP directory. 1083 There are four variations: 1085 int ldap_add_ext( 1086 LDAP *ld, 1087 char *dn, 1088 LDAPMod **attrs, 1089 LDAPControl **serverctrls, 1090 LDAPControl **clientctrls, 1091 int *msgidp 1092 ); 1093 int ldap_add_ext_s( 1094 LDAP *ld, 1095 char *dn, 1096 LDAPMod **attrs, 1097 LDAPControl **serverctrls, 1098 LDAPControl **clientctrls 1099 ); 1101 int ldap_add( 1102 LDAP *ld, 1103 char *dn, 1104 LDAPMod **attrs 1105 ); 1107 int ldap_add_s( 1108 LDAP *ld, 1109 char *dn, 1110 LDAPMod **attrs 1111 ); 1113 Parameters are: 1115 ld The session handle. 1117 dn The name of the entry to add. 1119 attrs The entry's attributes, specified using the LDAPMod struc- 1120 ture defined for ldap_modify(). The mod_type and mod_vals 1121 fields should be filled in. The mod_op field is ignored 1122 unless ORed with the constant LDAP_MOD_BVALUES, used to 1123 select the mod_bvalues case of the mod_vals union. 1125 serverctrls List of LDAP server controls. 1127 clientctrls List of client controls. 1129 msgidp This result parameter will be set to the message id of the 1130 request if the ldap_add_ext() call succeeds. 1132 Note that the parent of the entry being added must already exist or the 1133 parent must be empty (i.e., equal to the root DN) for an add to succeed. 1135 The ldap_add_ext() function initiates an asynchronous add operation and 1136 returns the constant LDAP_SUCCESS if the request was successfully sent, 1137 or another LDAP error code if not. See the section below on error han- 1138 dling for more information about possible errors and how to interpret 1139 them. If successful, ldap_add_ext() places the message id of the 1140 request in *msgidp. A subsequent call to ldap_result(), described below, 1141 can be used to obtain the result of the add. 1143 Similar to ldap_add_ext(), the ldap_add() function initiates an asyn- 1144 chronous add operation and returns the message id of the operation ini- 1145 tiated. As for ldap_add_ext(), a subsequent call to ldap_result(), 1146 described below, can be used to obtain the result of the add. In case of 1147 error, ldap_add() will return -1, setting the session error parameters 1148 in the LDAP structure appropriately. 1150 The synchronous ldap_add_ext_s() and ldap_add_s() functions both return 1151 the result of the operation, either the constant LDAP_SUCCESS if the 1152 operation was successful, or another LDAP error code if it was not. See 1153 the section below on error handling for more information about possible 1154 errors and how to interpret them. 1156 The ldap_add_ext() and ldap_add_ext_s() functions support LDAPv3 server 1157 controls and client controls. 1159 7.13. Deleting an entry 1161 The following functions are used to delete a leaf entry from the LDAP 1162 directory. There are four variations: 1164 int ldap_delete_ext( 1165 LDAP *ld, 1166 char *dn, 1167 LDAPControl **serverctrls, 1168 LDAPControl **clientctrls, 1169 int *msgidp 1170 ); 1172 int ldap_delete_ext_s( 1173 LDAP *ld, 1174 char *dn, 1175 LDAPControl **serverctrls, 1176 LDAPControl **clientctrls 1177 ); 1179 int ldap_delete( 1180 LDAP *ld, 1181 char *dn 1182 ); 1184 int ldap_delete_s( 1185 LDAP *ld, 1186 char *dn 1188 ); 1190 Parameters are: 1192 ld The session handle. 1194 dn The name of the entry to delete. 1196 serverctrls List of LDAP server controls. 1198 clientctrls List of client controls. 1200 msgidp This result parameter will be set to the message id of the 1201 request if the ldap_delete_ext() call succeeds. 1203 Note that the entry to delete must be a leaf entry (i.e., it must have 1204 no children). Deletion of entire subtrees in a single operation is not 1205 supported by LDAP. 1207 The ldap_delete_ext() function initiates an asynchronous delete opera- 1208 tion and returns the constant LDAP_SUCCESS if the request was success- 1209 fully sent, or another LDAP error code if not. See the section below on 1210 error handling for more information about possible errors and how to 1211 interpret them. If successful, ldap_delete_ext() places the message id 1212 of the request in *msgidp. A subsequent call to ldap_result(), described 1213 below, can be used to obtain the result of the delete. 1215 Similar to ldap_delete_ext(), the ldap_delete() function initiates an 1216 asynchronous delete operation and returns the message id of the opera- 1217 tion initiated. As for ldap_delete_ext(), a subsequent call to 1218 ldap_result(), described below, can be used to obtain the result of the 1219 delete. In case of error, ldap_delete() will return -1, setting the ses- 1220 sion error parameters in the LDAP structure appropriately. 1222 The synchronous ldap_delete_ext_s() and ldap_delete_s() functions both 1223 return the result of the operation, either the constant LDAP_SUCCESS if 1224 the operation was successful, or another LDAP error code if it was not. 1225 See the section below on error handling for more information about pos- 1226 sible errors and how to interpret them. 1228 The ldap_delete_ext() and ldap_delete_ext_s() functions support LDAPv3 1229 server controls and client controls. 1231 7.14. Extended Operations 1233 The ldap_extended_operation() and ldap_extended_operation_s() routines 1234 allow extended LDAP operations to be passed to the server, providing a 1235 general protocol extensibility mechanism. 1237 int ldap_extended_operation( 1238 LDAP *ld, 1239 char *exoid, 1240 struct berval *exdata, 1241 LDAPControl **serverctrls, 1242 LDAPControl **clientctrls, 1243 int *msgidp 1244 ); 1246 int ldap_extended_operation_s( 1247 LDAP *ld, 1248 char *exoid, 1249 struct berval *exdata, 1250 LDAPControl **serverctrls, 1251 LDAPControl **clientctrls, 1252 char **retoidp, 1253 struct berval **retdatap 1254 ); 1256 Parameters are: 1258 ld The session handle. 1260 requestoid The dotted-OID text string naming the request. 1262 requestdata The arbitrary data required by the operation (if NULL, no 1263 data is sent to the server). 1265 serverctrls List of LDAP server controls. 1267 clientctrls List of client controls. 1269 msgidp This result parameter will be set to the message id of the 1270 request if the ldap_extended_operation() call succeeds. 1272 retoidp Pointer to a character string that will be set to an allo- 1273 cated, dotted-OID text string returned by the server. This 1274 string should be disposed of using the ldap_memfree() func- 1275 tion. If no OID was returned, *retoidp is set to NULL. 1277 retdatap Pointer to a berval structure pointer that will be set an 1278 allocated copy of the data returned by the server. This 1279 struct berval should be disposed of using ber_bvfree(). If 1280 no data is returned, *retdatap is set to NULL. 1282 The ldap_extended_operation() function initiates an asynchronous 1283 extended operation and returns the constant LDAP_SUCCESS if the request 1284 was successfully sent, or another LDAP error code if not. See the sec- 1285 tion below on error handling for more information about possible errors 1286 and how to interpret them. If successful, ldap_extended_operation() 1287 places the message id of the request in *msgidp. A subsequent call to 1288 ldap_result(), described below, can be used to obtain the result of the 1289 extended operation which can be passed to ldap_parse_extended_result() 1290 to obtain the OID and data contained in the response. 1292 The synchronous ldap_extended_operation_s() function returns the result 1293 of the operation, either the constant LDAP_SUCCESS if the operation was 1294 successful, or another LDAP error code if it was not. See the section 1295 below on error handling for more information about possible errors and 1296 how to interpret them. The retoid and retdata parameters are filled in 1297 with the OID and data from the response. If no OID or data was 1298 returned, these parameters are set to NULL. 1300 The ldap_extended_operation() and ldap_extended_operation_s() functions 1301 both support LDAPv3 server controls and client controls. 1303 8. Abandoning An Operation 1305 The following calls are used to abandon an operation in progress: 1307 int ldap_abandon_ext( 1308 LDAP *ld, 1309 int msgid, 1310 LDAPControl **serverctrls, 1311 LDAPControl **clientctrls 1312 ); 1314 int ldap_abandon( 1315 LDAP *ld, 1316 int msgid 1317 ); 1319 ld The session handle. 1321 msgid The message id of the request to be abandoned. 1323 serverctrls List of LDAP server controls. 1325 clientctrls List of client controls. 1327 ldap_abandon_ext() abandons the operation with message id msgid and 1328 returns the constant LDAP_SUCCESS if the abandon was successful or 1329 another LDAP error code if not. See the section below on error handling 1330 for more information about possible errors and how to interpret them. 1332 ldap_abandon() is identical to ldap_abandon_ext() except that it returns 1333 zero if the abandon was successful, -1 otherwise and does not support 1334 LDAPv3 server controls or client controls. 1336 After a successful call to ldap_abandon() or ldap_abandon_ext(), results 1337 with the given message id are never returned from a subsequent call to 1338 ldap_result(). There is no server response to LDAP abandon operations. 1340 9. Obtaining Results and Peeking Inside LDAP Messages 1342 ldap_result() is used to obtain the result of a previous asynchronously 1343 initiated operation. Note that depending on how it is called, 1344 ldap_result() may actually return a list or "chain" of messages. 1346 ldap_msgfree() frees the results obtained from a previous call to 1347 ldap_result(), or a synchronous search routine. 1349 ldap_msgtype() returns the type of an LDAP message. ldap_msgid() 1350 returns the message ID of an LDAP message. 1352 int ldap_result( 1353 LDAP *ld, 1354 int msgid, 1355 int all, 1356 struct timeval *timeout, 1357 LDAPMessage **res 1358 ); 1360 int ldap_msgfree( LDAPMessage *res ); 1362 int ldap_msgtype( LDAPMessage *res ); 1364 int ldap_msgid( LDAPMessage *res ); 1366 Parameters are: 1368 ld The session handle. 1370 msgid The message id of the operation whose results are to be 1371 returned, or the constant LDAP_RES_ANY (-1) if any result is 1372 desired. 1374 all Specifies how many messages will be retrieved in a single call 1375 to ldap_result(). This parameter only has meaning for search 1376 results. Pass the constant LDAP_MSG_ONE (0x00) to retrieve one 1377 message at a time. Pass LDAP_MSG_ALL (0x01) to request that 1378 all results of a search be received before returning all 1379 results in a single chain. Pass LDAP_MSG_RECEIVED (0x02) to 1380 indicate that all results retrieved so far should be returned 1381 in the result chain. 1383 timeout A timeout specifying how long to wait for results to be 1384 returned. A NULL value causes ldap_result() to block until 1385 results are available. A timeout value of zero seconds speci- 1386 fies a polling behavior. 1388 res For ldap_result(), a result parameter that will contain the 1389 result(s) of the operation. For ldap_msgfree(), the result 1390 chain to be freed, obtained from a previous call to 1391 ldap_result(), ldap_search_s(), or ldap_search_st(). 1393 Upon successful completion, ldap_result() returns the type of the first 1394 result returned in the res parameter. This will be one of the following 1395 constants. 1397 LDAP_RES_BIND (0x61) 1398 LDAP_RES_SEARCH_ENTRY (0x64) 1399 LDAP_RES_SEARCH_REFERENCE (0x73) -- new in LDAPv3 1400 LDAP_RES_SEARCH_RESULT (0x65) 1401 LDAP_RES_MODIFY (0x67) 1402 LDAP_RES_ADD (0x69) 1403 LDAP_RES_DELETE (0x6B) 1404 LDAP_RES_MODDN (0x6D) 1405 LDAP_RES_COMPARE (0x6F) 1406 LDAP_RES_EXTENDED (0x78) -- new in LDAPv3 1408 ldap_result() returns 0 if the timeout expired and -1 if an error 1409 occurs, in which case the error parameters of the LDAP session handle 1410 will be set accordingly. 1412 ldap_msgfree() frees the result structure pointed to by res and returns 1413 the type of the message it freed. 1415 ldap_msgtype() returns the type of the LDAP message it is passed as a 1416 parameter. The type will be one of the types listed above, or -1 on 1417 error. 1419 ldap_msgid() returns the message ID associated with the LDAP message 1420 passed as a parameter. 1422 10. Handling Errors and Parsing Results 1424 The following calls are used to extract information from results and 1425 handle errors returned by other LDAP API routines. 1427 int ldap_parse_result( 1428 LDAP *ld, 1429 LDAPMessage *res, 1430 int *errcodep, 1431 char **matcheddnp, 1432 char **errmsgp, 1433 char ***referralsp, 1434 LDAPControl ***serverctrlsp, 1435 int freeit 1436 ); 1438 int ldap_parse_sasl_bind_result( 1439 LDAP *ld, 1440 LDAPMessage *res, 1441 struct berval **servercredp, 1442 int freeit 1443 ); 1445 int ldap_parse_extended_result( 1446 LDAP *ld, 1447 LDAPMessage *res, 1448 char **resultoidp, 1449 struct berval **resultdata, 1450 int freeit 1451 ); 1453 char *ldap_err2string( int err ); 1455 The use of the following routines is deprecated. 1457 int ldap_result2error( 1458 LDAP *ld, 1459 LDAPMessage *res, 1460 int freeit 1461 ); 1463 void ldap_perror( LDAP *ld, char *msg ); 1465 Parameters are: 1467 ld The session handle. 1469 res The result of an LDAP operation as returned by 1470 ldap_result() or one of the synchronous API operation 1471 calls. 1473 errcodep This result parameter will be filled in with the LDAP error 1474 code field from the LDAPResult message. This is the indi- 1475 cation from the server of the outcome of the operation. 1476 NULL may be passed to ignore this field. 1478 matcheddnp In the case of a return of LDAP_NO_SUCH_OBJECT, this result 1479 parameter will be filled in with a DN indicating how much 1480 of the name in the request was recognized. NULL may be 1481 passed to ignore this field. The matched DN string should 1482 be freed by calling ldap_memfree() which is described later 1483 in this document. 1485 errmsgp This result parameter will be filled in with the contents 1486 of the error message field from the LDAPResult message. 1487 The error message string should be freed by calling 1488 ldap_memfree() which is described later in this document. 1489 NULL may be passed to ignore this field. 1491 referralsp This result parameter will be filled in with the contents 1492 of the referrals field from the LDAPResult message, indi- 1493 cating zero or more alternate LDAP servers where the 1494 request should be retried. The referrals array should be 1495 freed by calling ldap_value_free() which is described later 1496 in this document. NULL may be passed to ignore this field. 1498 serverctrlsp This result parameter will be filled in with an allocated 1499 array of controls copied out of the LDAPResult message. 1500 The control array should be freed by calling 1501 ldap_controls_free() which was described earlier. 1503 freeit A boolean that determines whether the res parameter is 1504 disposed of or not. Pass any non-zero value to have these 1505 routines free res after extracting the requested informa- 1506 tion. This is provided as a convenience; you can also use 1507 ldap_msgfree() to free the result later. 1509 servercredp For SASL bind results, this result parameter will be filled 1510 in with the credentials passed back by the server for 1511 mutual authentication, if given. An allocated berval struc- 1512 ture is returned that should be disposed of by calling 1513 ldap_ber_free(). NULL may be passed to ignore this field. 1515 resultoidp For extended results, this result parameter will be filled 1516 in with the dotted-OID text representation of the name of 1517 the extended operation response. This string should be 1518 disposed of by calling ldap_memfree(). NULL may be passed 1519 to ignore this field. 1521 resultdatap For extended results, this result parameter will be filled 1522 in with a pointer to a struct berval containing the data in 1523 the extended operation response. It should be disposed of 1524 by calling ldap_ber_free(). NULL may be passed to ignore 1525 this field. 1527 err For ldap_err2string(), an LDAP error code, as returned by 1528 ldap_result2error() or another LDAP API call. 1530 Additional parameters for the deprecated routines are not described. 1531 Interested readers are referred to RFC 1823. 1533 All of the ldap_parse_*_result() routines skip over messages of type 1534 LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_REFERENCE when looking for a 1535 result message to parse. They return the constant LDAP_SUCCESS if the 1536 result was successfully parsed and another LDAP error code if not. Note 1537 that the LDAP error code that indicates the outcome of the operation 1538 performed by the server is placed in the errcodep ldap_parse_result() 1539 parameter. 1541 ldap_err2string() is used to convert a numeric LDAP error code, as 1542 returned by one of the ldap_parse_*_result() routines, or one of the 1543 synchronous API operation calls, into an informative NULL-terminated 1544 character string message describing the error. It returns a pointer to 1545 static data. 1547 11. Stepping Through a List of Results 1549 The ldap_first_message() and ldap_next_message() routines are used to 1550 step through the list of messages in a result chain returned by 1551 ldap_result(). For search operations, the result chain may actually 1552 include referral messages, entry messages, and result messages. 1553 ldap_count_messages() is used to count the number of messages returned. 1554 The ldap_msgtype() function, described above, can be used to distinguish 1555 between the different message types. 1557 LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *res ); 1559 LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *msg ); 1561 int ldap_count_messages( LDAP *ld, LDAPMessage *res ); 1563 Parameters are: 1565 ld The session handle. 1567 res The result chain, as obtained by a call to one of the synchronous 1568 search routines or ldap_result(). 1570 msg The message returned by a previous call to ldap_first_message() 1571 or ldap_next_message(). 1573 ldap_first_message() and ldap_next_message() will return NULL when no 1574 more messages exist in the result set to be returned. NULL is also 1575 returned if an error occurs while stepping through the entries, in which 1576 case the error parameters in the session handle ld will be set to indi- 1577 cate the error. 1579 ldap_count_messages() returns the number of messages contained in a 1580 chain of results. It can also be used to count the number of messages 1581 that remain in a chain if called with a message, entry, or reference 1582 returned by ldap_first_message(), ldap_next_message(), 1583 ldap_first_entry(), ldap_next_entry(), ldap_first_reference(), 1584 ldap_next_reference(). 1586 12. Parsing Search Results 1588 The following calls are used to parse the entries and references 1589 returned by ldap_search() and friends. These results are returned in an 1590 opaque structure that should only be accessed by calling the routines 1591 described below. Routines are provided to step through the entries and 1592 references returned, step through the attributes of an entry, retrieve 1593 the name of an entry, and retrieve the values associated with a given 1594 attribute in an entry. 1596 12.1. Stepping Through a List of Entries 1598 The ldap_first_entry() and ldap_next_entry() routines are used to step 1599 through and retrieve the list of entries from a search result chain. 1600 The ldap_first_reference() and ldap_next_reference() routines are used 1601 to step through and retrieve the list of continuation references from a 1602 search result chain. ldap_count_entries() is used to count the number 1603 of entries returned. ldap_count_references() is used to count the number 1604 of references returned. 1606 LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *res ); 1608 LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry ); 1610 LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *res ); 1611 LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *ref ); 1613 int ldap_count_entries( LDAP *ld, LDAPMessage *res ); 1615 int ldap_count_references( LDAP *ld, LDAPMessage *res ); 1617 Parameters are: 1619 ld The session handle. 1621 res The search result, as obtained by a call to one of the synchro- 1622 nous search routines or ldap_result(). 1624 entry The entry returned by a previous call to ldap_first_entry() or 1625 ldap_next_entry(). 1627 ldap_first_entry() and ldap_next_entry() will return NULL when no more 1628 entries or references exist in the result set to be returned. NULL is 1629 also returned if an error occurs while stepping through the entries, in 1630 which case the error parameters in the session handle ld will be set to 1631 indicate the error. 1633 ldap_count_entries() returns the number of entries contained in a chain 1634 of entries. It can also be used to count the number of entries that 1635 remain in a chain if called with a message, entry or reference returned 1636 by ldap_first_message(), ldap_next_message(), ldap_first_entry(), 1637 ldap_next_entry(), ldap_first_reference(), ldap_next_reference(). 1639 ldap_count_references() returns the number of references contained in a 1640 chain of search results. It can also be used to count the number of 1641 references that remain in a chain. 1643 12.2. Stepping Through the Attributes of an Entry 1645 The ldap_first_attribute() and ldap_next_attribute() calls are used to 1646 step through the list of attribute types returned with an entry. 1648 char *ldap_first_attribute( 1649 LDAP *ld, 1650 LDAPMessage *entry, 1651 BerElement **ptr 1652 ); 1654 char *ldap_next_attribute( 1655 LDAP *ld, 1656 LDAPMessage *entry, 1657 BerElement *ptr 1659 ); 1661 void ldap_memfree( char *mem ); 1663 Parameters are: 1665 ld The session handle. 1667 entry The entry whose attributes are to be stepped through, as returned 1668 by ldap_first_entry() or ldap_next_entry(). 1670 ptr In ldap_first_attribute(), the address of a pointer used inter- 1671 nally to keep track of the current position in the entry. In 1672 ldap_next_attribute(), the pointer returned by a previous call to 1673 ldap_first_attribute(). 1675 mem A pointer to memory allocated by the LDAP library, such as the 1676 attribute names returned by ldap_first_attribute() and 1677 ldap_next_attribute, or the DN returned by ldap_get_dn(). 1679 ldap_first_attribute() and ldap_next_attribute() will return NULL when 1680 the end of the attributes is reached, or if there is an error, in which 1681 case the error parameters in the session handle ld will be set to indi- 1682 cate the error. 1684 Both routines return a pointer to an allocated buffer containing the 1685 current attribute name. This should be freed when no longer in use by 1686 calling ldap_memfree(). 1688 ldap_first_attribute() will allocate and return in ptr a pointer to a 1689 BerElement used to keep track of the current position. This pointer 1690 should be passed in subsequent calls to ldap_next_attribute() to step 1691 through the entry's attributes. After a set of calls to 1692 ldap_first_attribute() and ldap_next_attibute(), if ptr is non-NULL, it 1693 should be freed by calling ldap_ber_free( ptr, 0 ). Note that it is very 1694 important to pass the second parameter as 0 (zero) in this call. 1696 The attribute names returned are suitable for passing in a call to 1697 ldap_get_values() and friends to retrieve the associated values. 1699 12.3. Retrieving the Values of an Attribute 1701 ldap_get_values() and ldap_get_values_len() are used to retrieve the 1702 values of a given attribute from an entry. ldap_count_values() and 1703 ldap_count_values_len() are used to count the returned values. 1704 ldap_value_free() and ldap_value_free_len() are used to free the values. 1706 char **ldap_get_values( 1707 LDAP *ld, 1708 LDAPMessage *entry, 1709 char *attr 1710 ); 1712 struct berval **ldap_get_values_len( 1713 LDAP *ld, 1714 LDAPMessage *entry, 1715 char *attr 1716 ); 1718 int ldap_count_values( char **vals ); 1720 int ldap_count_values_len( struct berval **vals ); 1722 int ldap_value_free( char **vals ); 1724 int ldap_value_free_len( struct berval **vals ); 1726 Parameters are: 1728 ld The session handle. 1730 entry The entry from which to retrieve values, as returned by 1731 ldap_first_entry() or ldap_next_entry(). 1733 attr The attribute whose values are to be retrieved, as returned by 1734 ldap_first_attribute() or ldap_next_attribute(), or a caller- 1735 supplied string (e.g., "mail"). 1737 vals The values returned by a previous call to ldap_get_values() or 1738 ldap_get_values_len(). 1740 Two forms of the various calls are provided. The first form is only 1741 suitable for use with non-binary character string data. The second _len 1742 form is used with any kind of data. 1744 Note that the values returned are dynamically allocated and should be 1745 freed by calling either ldap_value_free() or ldap_value_free_len() when 1746 no longer in use. 1748 12.4. Retrieving the name of an entry 1750 ldap_get_dn() is used to retrieve the name of an entry. 1751 ldap_explode_dn() and ldap_explode_rdn() are used to break up a name 1752 into its component parts. ldap_dn2ufn() is used to convert the name into 1753 a more "user friendly" format. 1755 char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ); 1757 char **ldap_explode_dn( char *dn, int notypes ); 1759 char **ldap_explode_rdn( char *rdn, int notypes ); 1761 char *ldap_dn2ufn( char *dn ); 1763 Parameters are: 1765 ld The session handle. 1767 entry The entry whose name is to be retrieved, as returned by 1768 ldap_first_entry() or ldap_next_entry(). 1770 dn The dn to explode, such as returned by ldap_get_dn(). 1772 rdn The rdn to explode, such as returned in the components of the 1773 array returned by ldap_explode_dn(). 1775 notypes A boolean parameter, if non-zero indicating that the dn or rdn 1776 components should have their type information stripped off 1777 (i.e., "cn=Babs" would become "Babs"). 1779 ldap_get_dn() will return NULL if there is some error parsing the dn, 1780 setting error parameters in the session handle ld to indicate the error. 1781 It returns a pointer to malloc'ed space that the caller should free by 1782 calling ldap_memfree() when it is no longer in use. Note the format of 1783 the DNs returned is given by [4]. 1785 ldap_explode_dn() returns a NULL-terminated char * array containing the 1786 RDN components of the DN supplied, with or without types as indicated by 1787 the notypes parameter. The array returned should be freed when it is no 1788 longer in use by calling ldap_value_free(). 1790 ldap_explode_rdn() returns a NULL-terminated char * array containing the 1791 components of the RDN supplied, with or without types as indicated by 1792 the notypes parameter. The array returned should be freed when it is no 1793 longer in use by calling ldap_value_free(). 1795 ldap_dn2ufn() converts the DN into the user friendly format described in 1796 [5]. The UFN returned is malloc'ed space that should be freed by a call 1797 to ldap_memfree() when no longer in use. 1799 13. Encoded ASN.1 Value Manipulation 1801 This section describes routines which may be used to encode and decode 1802 BER-encoded ASN.1 values, which are often used inside of control and 1803 extension values. 1805 With the exceptions of two new functions ber_flatten() and ber_init(), 1806 these functions are compatible with the University of Michigan LDAP 3.3 1807 implementation of BER. 1809 13.1. General 1811 struct berval { 1812 unsigned long bv_len; 1813 char *bv_val; 1814 }; 1816 A struct berval contains a sequence of bytes and an indication of its 1817 length. The bv_val is not null terminated. bv_len must always be a 1818 nonnegative number. Applications may allocate their own berval struc- 1819 tures. 1821 typedef struct berelement { 1822 /* opaque */ 1823 } BerElement; 1825 The BerElement structure contains not only a copy of the encoded value, 1826 but also state information used in encoding or decoding. Applications 1827 cannot allocate their own BerElement structures. The internal state is 1828 neither thread-specific nor locked, so two threads should not manipulate 1829 the same BerElement value simultaneously. 1831 A single BerElement value cannot be used for both encoding and decoding. 1833 void ber_bvfree ( struct berval *bv); 1835 ber_bvfree() frees a berval returned from this API. Both the bv->bv_val 1836 string and the berval itself are freed. Applications should not use 1837 ber_bvfree() with bervals which the application has allocated. 1839 void ber_bvecfree ( struct berval **bv ); 1841 ber_bvecfree() frees an array of bervals returned from this API. Each 1842 of the bervals in the array are freed using ber_bvfree(), then the array 1843 itself is freed. 1845 struct berval *ber_bvdup (struct berval *bv ); 1847 ber_bvdup() returns a copy of a berval. The bv_val field in the 1848 returned berval points to a different area of memory as the bv_val field 1849 in the argument berval. The null pointer is returned on error (e.g. out 1850 of memory). 1852 void ber_free ( BerElement *ber, int fbuf ); 1854 ber_free() frees a BerElement which is returned from the API calls 1855 ber_alloc_t() or ber_init(). Each BerElement must be freed by the 1856 caller. The second argument fbuf should always be set to 1. 1858 13.2. Encoding 1860 BerElement *ber_alloc_t(int options); 1862 ber_alloc_t() constructs and returns BerElement. The null pointer is 1863 returned on error. The options field contains a bitwise-or of options 1864 which are to be used when generating the encoding of this BerElement. 1865 One option is defined and must always be supplied: 1867 #define LBER_USE_DER 0x01 1869 When this option is present, lengths will always be encoded in the 1870 minimum number of octets. Note that this option does not cause values 1871 of sets and sequences to be rearranged in tag and byte order, so these 1872 functions are not suitable for generating DER output as defined in X.509 1873 and X.680. 1875 Unrecognized option bits are ignored. 1877 The BerElement returned by ber_alloc_t() is initially empty. Calls to 1878 ber_printf() will append bytes to the end of the ber_alloc_t(). 1880 int ber_printf(BerElement *ber, char *fmt, ... ) 1882 The ber_printf() routine is used to encode a BER element in much the 1883 same way that sprintf() works. One important difference, though, is 1884 that state information is kept in the ber argument so that multiple 1885 calls can be made to ber_printf() to append to the end of the BER ele- 1886 ment. ber must be a pointer to a BerElement returned by ber_alloc_t(). 1887 ber_printf() interprets and formats its arguments according to the for- 1888 mat string fmt. ber_printf() returns -1 if there is an error during 1889 encoding. As with sprintf(), each character in fmt refers to an argu- 1890 ment to ber_printf(). 1892 The format string can contain the following format characters: 1894 't' Tag. The next argument is an int specifying the tag to override 1895 the next element to be written to the ber. This works across 1896 calls. The int value must contain the tag class, constructed 1897 bit, and tag value. The tag value must fit in a single octet 1898 (tag value is less than 32). For example, a tag of "[3]" for a 1899 constructed type is 0xA3. 1901 'b' Boolean. The next argument is an int, containing either 0 for 1902 FALSE or 0xff for TRUE. A boolean element is output. If this 1903 format character is not preceded by the 't' format modifier, the 1904 tag 0x01 is used for the element. 1906 'i' Integer. The next argument is an int, containing the integer in 1907 the host's byte order. An integer element is output. If this 1908 format character is not preceded by the 't' format modifier, the 1909 tag 0x02 is used for the element. 1911 'X' Bitstring. The next two arguments are a char * pointer to the 1912 start of the bitstring, followed by an int containing the number 1913 of bits in the bitstring. A bitstring element is output, in 1914 primitive form. If this format character is not preceded by the 1915 't' format modifier, the tag 0x03 is used for the element. 1917 'n' Null. No argument is required. An ASN.1 NULL element is out- 1918 put. If this format character is not preceded by the 't' format 1919 modifier, the tag 0x05 is used for the element. 1921 'o' Octet string. The next two arguments are a char *, followed by 1922 an int with the length of the string. The string may contain 1923 null bytes and need not by null-terminated. An octet string 1924 element is output, in primitive form. If this format character 1925 is not preceded by the 't' format modifier, the tag 0x04 is used 1926 for the element. 1928 's' Octet string. The next argument is a char * pointing to a 1929 null-terminated string. An octet string element in primitive 1930 form is output, which does not include the trailing ' ' byte. If 1931 this format character is not preceded by the 't' format modif- 1932 ier, the tag 0x04 is used for the element. 1934 'v' Several octet strings. The next argument is a char **, an array 1935 of char * pointers to null-terminated strings. The last element 1936 in the array must be a null pointer. The octet strings do not 1937 include the trailing SEQUENCE OF octet strings. The 't' format 1938 modifier cannot be used with this format character. 1940 'V' Several octet strings. A null-terminated array of berval *'s is 1941 supplied. Note that a construct like '{V}' is required to get an 1942 actual SEQUENCE OF octet strings. The 't' format modifier cannot 1943 be used with this format character. 1945 '{' Begin sequence. No argument is required. If this format char- 1946 acter is not preceded by the 't' format modifier, the tag 0x30 1947 is used. 1949 '}' End sequence. No argument is required. The 't' format modifier 1950 cannot be used with this format character. 1952 '[' Begin set. No argument is required. If this format character 1953 is not preceded by the 't' format modifier, the tag 0x31 is 1954 used. 1956 ']' End set. No argument is required. The 't' format modifier can- 1957 not be used with this format character. 1959 Each use of a '{' format character must be matched by a '}' character, 1960 either later in the format string, or in the format string of a subse- 1961 quent call to ber_printf() for that BerElement. The same applies to the 1962 '[' and 1964 Sequences and sets nest, and implementations of this API must maintain 1965 internal state to be able to properly calculate the lengths. 1967 int ber_flatten (BerElement *ber, struct berval **bvPtr); 1969 The ber_flatten routine allocates a struct berval whose contents are a 1970 BER encoding taken from the ber argument. The bvPtr pointer points to 1971 the returned berval, which must be freed using ber_bvfree(). This rou- 1972 tine returns 0 on success and -1 on error. 1974 The ber_flatten API call is not present in U-M LDAP 3.3. 1976 The use of ber_flatten on a BerElement in which all '{' and '}' format 1977 modifiers have not been properly matched can result in a berval whose 1978 contents are not a valid BER encoding. 1980 13.3. Encoding Example 1982 The following is an example of encoding the following ASN.1 data type: 1984 Example1Request ::= SEQUENCE { 1985 s OCTET STRING, -- must be printable 1986 val1 INTEGER, 1987 val2 [0] INTEGER DEFAULT 0 1988 } 1989 int encode_example1(char *s,int val1,int val2,struct berval **bvPtr) 1990 { 1991 BerElement *ber; 1992 int rc; 1994 ber = ber_alloc_t(LBER_USE_DER); 1996 if (ber == NULL) return -1; 1998 if (ber_printf(ber,"{si",s,val1) == -1) { 1999 ber_free(ber,1); 2000 return -1; 2001 } 2003 if (val2 != 0) { 2004 if (ber_printf(ber,"ti",0x80,val2) == -1) { 2005 ber_free(ber,1); 2006 return -1; 2007 } 2008 } 2010 if (ber_printf(ber,"}") == -1) { 2011 ber_free(ber,1); 2012 return -1; 2013 } 2015 rc = ber_flatten(ber,bvPtr); 2016 ber_free(ber,1); 2017 return -1; 2018 } 2020 13.4. Decoding 2022 The following two symbols are available to applications. 2024 #define LBER_ERROR 0xffffffffL 2025 #define LBER_DEFAULT 0xffffffffL 2027 BerElement *ber_init (struct berval *bv); 2029 The ber_init functions construct BerElement and returns a new BerElement 2030 containing a copy of the data in the bv argument. ber_init returns the 2031 null pointer on error. 2033 unsigned long ber_scanf (BerElement *ber, char *fmt, ... ); 2035 The ber_scanf() routine is used to decode a BER element in much the same 2036 way that sscanf() works. One important difference, though, is that some 2037 state information is kept with the ber argument so that multiple calls 2038 can be made to ber_scanf() to sequentially read from the BER element. 2039 The ber argument must be a pointer to a BerElement returned by 2040 ber_init(). ber_scanf interprets the bytes according to the format 2041 string fmt, and stores the results in its additional arguments. 2042 ber_scanf() returns LBER_ERROR on error, and a nonnegative number on 2043 success. 2045 The format string contains conversion specifications which are used to 2046 direct the interpretation of the BER element. The format string can 2047 contain the following characters: 2049 'a' Octet string. A char ** argument should be supplied. Memory is 2050 allocated, filled with the contents of the octet string, null- 2051 terminated, and the pointer to the string is stored in the argu- 2052 ment. The returned value must be freed using ldap_memfree. The 2053 tag of the element must indicate the primitive form (constructed 2054 strings are not supported) but is otherwise ignored and dis- 2055 carded during the decoding. This format cannot be used with 2056 octet strings which could contain null bytes. 2058 'O' Octet string. A struct berval ** argument should be supplied, 2059 which upon return points to a allocated struct berval containing 2060 the octet string and its length. ber_bvfree() must be called to 2061 free the allocated memory. The tag of the element must indicate 2062 the primitive form (constructed strings are not supported) but 2063 is otherwise ignored during the decoding. 2065 'b' Boolean. A pointer to an int should be supplied. The int value 2066 stored will be 0 for FALSE or nonzero for TRUE. The tag of the 2067 element must indicate the primitive form but is otherwise 2068 ignored during the decoding. 2070 'i' Integer. A pointer to an int should be supplied. The int value 2071 stored will be in host byte order. The tag of the element must 2072 indicate the primitive form but is otherwise ignored during the 2073 decoding. ber_scanf() will return an error if the integer can- 2074 not be stored in an int. 2076 'B' Bitstring. A char ** argument should be supplied which will 2077 point to the allocated bits, followed by an unsigned long * 2078 argument, which will point to the length (in bits) of the bit- 2079 string returned. ldap_memfree must be called to free the bit- 2080 string. The tag of the element must indicate the primitive form 2081 (constructed bitstrings are not supported) but is otherwise 2082 ignored during the decoding. 2084 'n' Null. No argument is required. The element is simply skipped 2085 if it is recognized as a zero-length element. The tag is 2086 ignored. 2088 'v' Several octet strings. A char *** argument should be supplied, 2089 which upon return points to a allocated null-terminated array of 2090 char *'s containing the octet strings. NULL is stored if the 2091 sequence is empty. ldap_memfree must be called to free each 2092 element of the array and the array itself. The tag of the 2093 sequence and of the octet strings are ignored. 2095 'V' Several octet strings (which could contain null bytes). A 2096 struct berval *** should be supplied, which upon return points 2097 to a allocated null-terminated array of struct berval *'s con- 2098 taining the octet strings and their lengths. NULL is stored if 2099 the sequence is empty. ber_bvecfree() can be called to free the 2100 allocated memory. The tag of the sequence and of the octet 2101 strings are ignored. 2103 'x' Skip element. The next element is skipped. No argument is 2104 required. 2106 '{' Begin sequence. No argument is required. The initial sequence 2107 tag and length are skipped. 2109 '}' End sequence. No argument is required. 2111 '[' Begin set. No argument is required. The initial set tag and 2112 length are skipped. 2114 ']' End set. No argument is required. 2116 unsigned long ber_peek_tag (BerElement *ber, unsigned long *lenPtr); 2118 ber_peek_tag() returns the tag of the next element to be parsed in the 2119 BerElement argument. The length of this element is stored in the 2120 *lenPtr argument. LBER_DEFAULT is returned if there is no further data 2121 to be read. The ber argument is not modified. 2123 unsigned long ber_skip_tag (BerElement *ber, unsigned long *lenPtr); 2125 ber_skip_tag() is similar to ber_peek_tag(), except that the state 2126 pointer in the BerElement argument is advanced past the first tag and 2127 length, and is pointed to the value part of the next element. This rou- 2128 tine should only be used with constructed types and situations when a 2129 BER encoding is used as the value of an OCTET STRING. The length of the 2130 value is stored in *lenPtr. 2132 unsigned long ber_first_element(BerElement *ber, 2133 unsigned long *lenPtr, char **opaquePtr); 2135 unsigned long ber_next_element (BerElement *ber, 2136 unsigned long *lenPtr, char *opaque); 2138 ber_first_element() and ber_next_element() are used to traverse a SET, 2139 SET OF, SEQUENCE or SEQUENCE OF data value. ber_first_element() calls 2140 ber_skip_tag(), stores internal information in *lenPtr and *opaquePtr, 2141 and calls ber_peek_tag() for the first element inside the constructed 2142 value. LBER_DEFAULT is returned if the constructed value is empty. 2143 ber_next_element() positions the state at the start of the next element 2144 in the constructed type. LBER_DEFAULT is returned if there are no 2145 further values. 2147 The len and opaque values should not be used by applications other than 2148 as arguments to ber_next_element(), as shown in the example below. 2150 13.5. Decoding Example 2152 The following is an example of decoding an ASN.1 data type: 2154 Example2Request ::= SEQUENCE { 2155 dn OCTET STRING, -- must be printable 2156 scope ENUMERATED { b (0), s (1), w (2) }, 2157 ali ENUMERATED { n (0), s (1), f (2), a (3) }, 2158 size INTEGER, 2159 time INTEGER, 2160 tonly BOOLEAN, 2161 attrs SEQUENCE OF OCTET STRING, -- must be printable 2162 [0] SEQUENCE OF SEQUENCE { 2163 type OCTET STRING -- must be printable, 2164 crit BOOLEAN DEFAULT FALSE, 2165 value OCTET STRING 2166 } OPTIONAL } 2168 #define LDAP_TAG_CONTROL_LIST 0xA0L /* context specific cons 0 */ 2170 int decode_example2(struct berval *bv) 2171 { 2172 BerElement *ber; 2173 unsigned long len; 2174 int scope, ali, size, time, tonly; 2175 char *dn = NULL, **attrs = NULL; 2176 int res,i,rc = 0; 2178 ber = ber_init(bv); 2179 if (ber == NULL) { 2180 printf("ERROR ber_init failed0); 2181 return -1; 2182 } 2184 res = ber_scanf(ber,"{aiiiiib{v}",&dn,&scope,&ali, 2185 &size,&time,&tonly,&attrs); 2187 if (res == -1) { 2188 printf("ERROR ber_scanf failed0); 2189 ber_free(ber,1); 2190 return -1; 2191 } 2193 /* *** use dn */ 2194 ldap_memfree(dn); 2196 for (i = 0; attrs != NULL && attrs[i] != NULL; i++) { 2197 /* *** use attrs[i] */ 2198 ldap_memfree(attrs[i]); 2199 } 2200 ldap_memfree(attrs); 2202 if (ber_peek_tag(ber,&len) == LDAP_TAG_CONTROL_LIST) { 2203 char *opaque; 2204 unsigned long tag; 2206 for (tag = ber_first_element(ber,&len,&opaque); 2207 tag != LBER_DEFAULT; 2208 tag = ber_next_element (ber,&len,opaque)) { 2210 unsigned long ttag, tlen; 2211 char *type; 2212 int crit; 2213 struct berval *value; 2215 if (ber_scanf(ber,"{a",&type) == LBER_ERROR) { 2216 printf("ERROR cannot parse type0); 2217 break; 2218 } 2219 /* *** use type */ 2220 ldap_memfree(type); 2222 ttag = ber_peek_tag(ber,&tlen); 2223 if (ttag == 0x01) { /* boolean */ 2224 if (ber_scanf(ber,"b", 2225 &crit) == LBER_ERROR) { 2226 printf("ERROR cannot parse crit0); 2227 rc = -1; 2228 break; 2229 } 2230 } else if (ttag == 0x04) { /* octet string */ 2231 crit = 0; 2232 } else { 2233 printf("ERROR extra field in controls0); 2234 break; 2235 } 2237 if (ber_scanf(ber,"O}",&value) == LBER_ERROR) { 2238 printf("ERROR cannot parse value0); 2239 rc = -1; 2240 break; 2241 } 2242 /* *** use value */ 2243 ldap_bvfree(value); 2244 } 2245 } 2247 ber_scanf(ber,"}"); 2249 ber_free(ber,1); 2251 return rc; 2252 } 2254 14. Security Considerations 2256 LDAPv2 supports security through protocol-level authentication using 2257 clear-text passwords. LDAPv3 adds support for SASL [8] (Simple Authen- 2258 tication Security Layer) methods. LDAPv3 also supports operation over a 2259 secure transport layer using Transport Layer Security TLS [8]. Readers 2260 are referred to the protocol documents for discussion of related secu- 2261 rity considerations. 2263 Implementations of this API should be cautious when handling authentica- 2264 tion credentials. In particular, keeping long-lived copies of creden- 2265 tials without the application's knowledge is discouraged. 2267 15. Acknowledgements 2269 Many members of the IETF ASID working group as well as members of the 2270 Internet at large have provided useful comments and suggestions that 2271 have been incorporated into this revision. 2273 This original material upon which this revision is based was based upon 2274 work supported by the National Science Foundation under Grant No. NCR- 2275 9416667. 2277 16. Bibliography 2279 [1] The Directory: Selected Attribute Syntaxes. CCITT, Recommendation 2280 X.520. 2282 [2] M. Wahl, A. Coulbeck, T. Howes, S. Kille, W. Yeong, C. Robbins, 2283 "Lightweight Directory Access Protocol Attribute Syntax Defini- 2284 tions", INTERNET-DRAFT , 2285 11 July 1997. 2287 [3] T. Howes, "A String Representation of LDAP Search Filters," 2288 INTERNET-DRAFT , May 1997. 2290 [4] S. Kille, M. Wahl, "A UTF-8 String Representation of Distinguished 2291 Names", INTERNET-DRAFT , 29 April 2292 1997. 2294 [5] S. Kille, "Using the OSI Directory to Achieve User Friendly Nam- 2295 ing," RFC 1781, March 1995. 2297 [6] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol 2298 (v3)", INTERNET-DRAFT , 11 2299 July 1997. 2301 [7] A. Herron, T. Howes, M. Wahl, "LDAP Control Extension for Server 2302 Side Sorting of Search Result," INTERNET-DRAFT , 16 April 1997. 2305 [8] J. Meyers, "Simple Authentication and Security Layer", INTERNET- 2306 DRAFT , April 1997. 2308 [9] "Lightweight Directory Access Protocol (v3) Extension for Transport 2309 Layer Security", INTERNET-DRAFT , June 1997. 2312 [10] "UTF-8, a transformation format of Unicode and ISO 10646", RFC 2313 2044, October 1996. 2315 [11] "IP Version 6 Addressing Architecture,", RFC 1884, December 1995. 2317 17. Author's Addresses 2319 Tim Howes 2320 Netscape Communications Corp. 2321 501 E. Middlefield Rd., Mailstop MV068 2322 Mountain View, CA 94043 2323 USA 2324 +1 415 937-3419 2325 howes@netscape.com 2327 Mark Smith 2328 Netscape Communications Corp. 2329 501 E. Middlefield Rd., Mailstop MV068 2330 Mountain View, CA 94043 2331 USA 2332 +1 415 937-3477 2333 mcs@netscape.com 2335 Andy Herron 2336 Microsoft Corp. 2337 1 Microsoft Way 2338 Redmond, WA 98052 2339 USA 2340 +1 425 882-8080 2341 andyhe@microsoft.com 2343 Chris Weider 2344 Microsoft Corp. 2345 1 Microsoft Way 2346 Redmond, WA 98052 2347 USA 2348 +1 425 882-8080 2349 cweider@microsoft.com 2351 Mark Wahl 2352 Critical Angle Inc. 2353 4815 W Braker Lane #502-385 2354 Austin, TX 78759 2355 USA 2356 M.Wahl@critical-angle.com 2358 18. Appendix A - Sample LDAP API Code 2360 #include 2362 main() 2363 { 2364 LDAP *ld; 2365 LDAPMessage *res, *e; 2366 int i; 2367 char *a, *dn; 2368 BerElement *ptr; 2369 char **vals; 2371 /* open an LDAP session */ 2372 if ( (ld = ldap_init( "dotted.host.name", LDAP_PORT )) == NULL ) 2373 exit( 1 ); 2375 /* authenticate as nobody */ 2376 if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) { 2377 ldap_perror( ld, "ldap_simple_bind_s" ); 2378 exit( 1 ); 2379 } 2381 /* search for entries with cn of "Babs Jensen", return all attrs */ 2382 if ( ldap_search_s( ld, "o=University of Michigan, c=US", 2383 LDAP_SCOPE_SUBTREE, "(cn=Babs Jensen)", NULL, 0, &res ) 2384 != LDAP_SUCCESS ) { 2385 ldap_perror( ld, "ldap_search_s" ); 2386 exit( 1 ); 2387 } 2389 /* step through each entry returned */ 2390 for ( e = ldap_first_entry( ld, res ); e != NULL; 2391 e = ldap_next_entry( ld, e ) ) { 2392 /* print its name */ 2393 dn = ldap_get_dn( ld, e ); 2394 printf( "dn: %s\n", dn ); 2395 ldap_memfree( dn ); 2397 /* print each attribute */ 2398 for ( a = ldap_first_attribute( ld, e, &ptr ); a != NULL; 2399 a = ldap_next_attribute( ld, e, ptr ) ) { 2400 printf( "attribute: %s\n", a ); 2402 /* print each value */ 2403 vals = ldap_get_values( ld, e, a ); 2404 for ( i = 0; vals[i] != NULL; i++ ) { 2405 printf( "value: %s\n", vals[i] ); 2406 } 2407 ldap_value_free( vals ); 2408 } 2409 if ( ptr != NULL ) { 2410 ldap_ber_free( ptr, 0 ); 2412 } 2413 } 2414 /* free the search results */ 2415 ldap_msgfree( res ); 2417 /* close and free connection resources */ 2418 ldap_unbind( ld ); 2419 } 2421 19. Appendix B - Outstanding Issues 2423 19.1. Support for multithreaded applications 2425 In order to support multithreaded applications in a platform-independent 2426 way, some additions to the LDAP API are needed. Different implementors 2427 have taken different paths to solve this problem in the past. A common 2428 set of thread-related API calls must be defined so that application 2429 developers are not unduly burdened. These will be added to a future 2430 revision of this specification. 2432 19.2. Using Transport Layer Security (TLS) 2434 The API calls used to support TLS must be specified. They will be added 2435 to a future revision of this specification. 2437 19.3. Client control for chasing referrals 2439 A client control has been defined that can be used to specify on a per- 2440 operation basis whether references and external referrals are automati- 2441 cally chased by the client library. This will be added to a future 2442 revision of this specification. 2444 19.4. Potential confusion between hostname:port and IPv6 addresses 2446 String representations of IPv6 network addresses [11] can contain colon 2447 characters. The ldap_init() call is specified to take strings of the 2448 form "hostname:port" or "ipaddress:port". If IPv6 addresses are used, 2449 the latter could be ambiguous. A future revision of this specification 2450 will resolve this issue. 2452 19.5. Need to track SASL API standardization efforts 2454 If a standard Simple Authentication and Security Layer API is defined, 2455 it may be necessary to modify the LDAP API to accommodate it. 2457 19.6. Support for character sets other than UTF-8? 2459 Some application developers would prefer to pass string data using a 2460 character set other than UTF-8. This could be accommodated by adding a 2461 new option to ldap_set_option() that supports choosing a character set. 2462 If this feature is added, the number of different character sets sup- 2463 ported should definitely be minimized. 2465 19.7. Use of UTF-8 with LDAPv2 servers 2467 Strings are always passed as UTF-8 in this API but LDAP version 2 2468 servers do not support the full range of UTF-8 characters. The expected 2469 behavior of this API when using LDAP version 2 with unsupported charac- 2470 ters should be specified. 2472 1. Status of this Memo............................................1 2473 2. Introduction...................................................1 2474 3. Overview of the LDAP Model.....................................2 2475 4. Overview of LDAP API Use.......................................3 2476 5. Common Data Structures.........................................4 2477 6. LDAP Error Codes...............................................5 2478 7. Performing LDAP Operations.....................................6 2479 7.1. Initializing an LDAP Session................................6 2480 7.2. LDAP Session Handle Options.................................7 2481 7.3. Working with controls.......................................10 2482 7.4. Authenticating to the directory.............................11 2483 7.5. Closing the session.........................................13 2484 7.6. Searching...................................................13 2485 7.7. Reading an Entry............................................17 2486 7.8. Listing the Children of an Entry............................17 2487 7.9. Comparing a Value Against an Entry..........................17 2488 7.10. Modifying an entry..........................................19 2489 7.11. Modifying the Name of an Entry..............................21 2490 7.12. Adding an entry.............................................23 2491 7.13. Deleting an entry...........................................25 2492 7.14. Extended Operations.........................................26 2493 8. Abandoning An Operation........................................28 2494 9. Obtaining Results and Peeking Inside LDAP Messages.............29 2495 10. Handling Errors and Parsing Results............................31 2496 11. Stepping Through a List of Results.............................33 2497 12. Parsing Search Results.........................................34 2498 12.1. Stepping Through a List of Entries..........................34 2499 12.2. Stepping Through the Attributes of an Entry.................35 2500 12.3. Retrieving the Values of an Attribute.......................36 2501 12.4. Retrieving the name of an entry.............................37 2502 13. Encoded ASN.1 Value Manipulation...............................39 2503 13.1. General.....................................................39 2504 13.2. Encoding....................................................40 2505 13.3. Encoding Example............................................42 2506 13.4. Decoding....................................................43 2507 13.5. Decoding Example............................................46 2508 14. Security Considerations........................................48 2509 15. Acknowledgements...............................................48 2510 16. Bibliography...................................................49 2511 17. Author's Addresses.............................................50 2512 18. Appendix A - Sample LDAP API Code..............................50 2513 19. Appendix B - Outstanding Issues................................52 2514 19.1. Support for multithreaded applications......................52 2515 19.2. Using Transport Layer Security (TLS)........................52 2516 19.3. Client control for chasing referrals........................52 2517 19.4. Potential confusion between hostname:port and IPv6 addresses52 2518 19.5. Need to track SASL API standardization efforts..............53 2519 19.6. Support for character sets other than UTF-8?................53 2520 19.7. Use of UTF-8 with LDAPv2 servers............................53