├── Makefile ├── remove-eldap-fsm.patch ├── .gitignore ├── license_info ├── eldap-appify.patch ├── eldap-no-ssl-seed.patch ├── package.mk ├── CONTRIBUTING.md └── remove-ietf-doc.patch /Makefile: -------------------------------------------------------------------------------- 1 | include ../umbrella.mk 2 | -------------------------------------------------------------------------------- /remove-eldap-fsm.patch: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rabbitmq/eldap-wrapper/master/remove-eldap-fsm.patch -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *~ 2 | .sw? 3 | .*.sw? 4 | *.beam 5 | erl_crash.dump 6 | /build/ 7 | /cover/ 8 | /dist/ 9 | /ebin/ 10 | /eldap-git/ 11 | /hash.mk 12 | /tmp/ 13 | -------------------------------------------------------------------------------- /license_info: -------------------------------------------------------------------------------- 1 | Eldap is "Copyright (c) 2010, Torbjorn Tornkvist" and is covered by 2 | the MIT license. It was downloaded from https://github.com/etnt/eldap 3 | 4 | -------------------------------------------------------------------------------- /eldap-appify.patch: -------------------------------------------------------------------------------- 1 | diff -Naur eldap.orig/ebin/eldap.app eldap/ebin/eldap.app 2 | --- eldap.orig/ebin/eldap.app 1970-01-01 01:00:00.000000000 +0100 3 | +++ eldap/ebin/eldap.app 2011-01-20 12:47:04.377399296 +0000 4 | @@ -0,0 +1,10 @@ 5 | +{application, eldap, 6 | + [{description, "LDAP Client Library"}, 7 | + {vsn, "0.01"}, 8 | + {modules, [ 9 | + eldap, 10 | + 'ELDAPv3' 11 | + ]}, 12 | + {registered, []}, 13 | + {applications, [kernel, stdlib]} 14 | + ]}. 15 | -------------------------------------------------------------------------------- /eldap-no-ssl-seed.patch: -------------------------------------------------------------------------------- 1 | diff --git a/src/eldap.erl b/src/eldap.erl 2 | index 9a78270..b0cdb2e 100644 3 | --- a/src/eldap.erl 4 | +++ b/src/eldap.erl 5 | @@ -363,12 +363,5 @@ do_connect(Host, Data, Opts) when Data#eldap.use_tls == false -> 6 | gen_tcp:connect(Host, Data#eldap.port, Opts, Data#eldap.timeout); 7 | do_connect(Host, Data, Opts) when Data#eldap.use_tls == true -> 8 | - Vsn = erlang:system_info(version), 9 | - if Vsn >= "5.3" -> 10 | - %% In R9C, but not in R9B 11 | - {_,_,X} = erlang:now(), 12 | - ssl:seed("bkrlnateqqo" ++ integer_to_list(X)); 13 | - true -> true 14 | - end, 15 | ssl:connect(Host, Data#eldap.port, [{verify,0}|Opts]). 16 | 17 | 18 | -------------------------------------------------------------------------------- /package.mk: -------------------------------------------------------------------------------- 1 | APP_NAME:=eldap 2 | 3 | UPSTREAM_GIT:=https://github.com/rabbitmq/eldap.git 4 | UPSTREAM_REVISION:=e309de4db4b78d67d623 5 | WRAPPER_PATCHES:=eldap-appify.patch remove-eldap-fsm.patch eldap-no-ssl-seed.patch remove-ietf-doc.patch 6 | 7 | ORIGINAL_APP_FILE:=$(CLONE_DIR)/ebin/$(APP_NAME).app 8 | DO_NOT_GENERATE_APP_FILE=true 9 | 10 | GENERATED_DIR:=$(CLONE_DIR)/generated 11 | PACKAGE_ERLC_OPTS+=-I $(GENERATED_DIR) 12 | INCLUDE_HRLS+=$(GENERATED_DIR)/ELDAPv3.hrl 13 | EBIN_BEAMS+=$(GENERATED_DIR)/ELDAPv3.beam 14 | 15 | define package_rules 16 | 17 | $(CLONE_DIR)/src/ELDAPv3.asn: $(CLONE_DIR)/.done 18 | 19 | $(GENERATED_DIR)/ELDAPv3.hrl $(GENERATED_DIR)/ELDAPv3.beam: $(CLONE_DIR)/src/ELDAPv3.asn 20 | @mkdir -p $(GENERATED_DIR) 21 | $(ERLC) $(PACKAGE_ERLC_OPTS) -o $(GENERATED_DIR) $$< 22 | 23 | $(PACKAGE_DIR)+clean:: 24 | rm -rf $(GENERATED_DIR) $(EBIN_DIR) 25 | 26 | # This rule is run *before* the one in do_package.mk 27 | $(PLUGINS_SRC_DIST_DIR)/$(PACKAGE_DIR)/.srcdist_done:: 28 | cp $(CLONE_DIR)/LICENSE $(PACKAGE_DIR)/LICENSE-MIT-eldap 29 | 30 | endef 31 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | ## Overview 2 | 3 | RabbitMQ projects use pull requests to discuss, collaborate on and accept code contributions. 4 | Pull requests is the primary place of discussing code changes. 5 | 6 | ## How to Contribute 7 | 8 | The process is fairly standard: 9 | 10 | * Fork the repository or repositories you plan on contributing to 11 | * Clone [RabbitMQ umbrella repository](https://github.com/rabbitmq/rabbitmq-public-umbrella) 12 | * `cd umbrella`, `make co` 13 | * Create a branch with a descriptive name in the relevant repositories 14 | * Make your changes, run tests, commit with a [descriptive message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), push to your fork 15 | * Submit pull requests with an explanation what has been changed and **why** 16 | * Submit a filled out and signed [Contributor Agreement](https://github.com/rabbitmq/ca#how-to-submit) if needed (see below) 17 | * Be patient. We will get to your pull request eventually 18 | 19 | If what you are going to work on is a substantial change, please first ask the core team 20 | of their opinion on [RabbitMQ mailing list](https://groups.google.com/forum/#!forum/rabbitmq-users). 21 | 22 | 23 | ## (Brief) Code of Conduct 24 | 25 | In one line: don't be a dick. 26 | 27 | Be respectful to the maintainers and other contributors. Open source 28 | contributors put long hours into developing projects and doing user 29 | support. Those projects and user support are available for free. We 30 | believe this deserves some respect. 31 | 32 | Be respectful to people of all races, genders, religious beliefs and 33 | political views. Regardless of how brilliant a pull request is 34 | technically, we will not tolerate disrespectful or aggressive 35 | behaviour. 36 | 37 | Contributors who violate this straightforward Code of Conduct will see 38 | their pull requests closed and locked. 39 | 40 | 41 | ## Contributor Agreement 42 | 43 | If you want to contribute a non-trivial change, please submit a signed copy of our 44 | [Contributor Agreement](https://github.com/rabbitmq/ca#how-to-submit) around the time 45 | you submit your pull request. This will make it much easier (in some cases, possible) 46 | for the RabbitMQ team at Pivotal to merge your contribution. 47 | 48 | 49 | ## Where to Ask Questions 50 | 51 | If something isn't clear, feel free to ask on our [mailing list](https://groups.google.com/forum/#!forum/rabbitmq-users). 52 | -------------------------------------------------------------------------------- /remove-ietf-doc.patch: -------------------------------------------------------------------------------- 1 | diff --git a/doc/draft-ietf-asid-ldap-c-api-00.txt b/doc/draft-ietf-asid-ldap-c-api-00.txt 2 | deleted file mode 100755 3 | index 5f2e856..0000000 4 | --- a/doc/draft-ietf-asid-ldap-c-api-00.txt 5 | +++ /dev/null 6 | @@ -1,3030 +0,0 @@ 7 | - 8 | - 9 | - 10 | - 11 | - 12 | - 13 | -Network Working Group T. Howes 14 | -INTERNET-DRAFT Netscape Communications Corp. 15 | -Intended Category: Standards Track M. Smith 16 | -Obsoletes: RFC 1823 Netscape Communications Corp. 17 | -Expires: January 1998 A. Herron 18 | - Microsoft Corp. 19 | - C. Weider 20 | - Microsoft Corp. 21 | - M. Wahl 22 | - Critical Angle, Inc. 23 | - 24 | - 29 July 1997 25 | - 26 | - 27 | - The C LDAP Application Program Interface 28 | - 29 | - 30 | - 31 | - 32 | -1. Status of this Memo 33 | - 34 | -This draft document will be submitted to the RFC Editor as a Standards 35 | -Track document. Distribution of this memo is unlimited. Please send com- 36 | -ments to the authors. 37 | - 38 | -This document is an Internet-Draft. Internet-Drafts are working docu- 39 | -ments of the Internet Engineering Task Force (IETF), its areas, and its 40 | -working groups. Note that other groups may also distribute working 41 | -documents as Internet-Drafts. 42 | - 43 | -Internet-Drafts are draft documents valid for a maximum of six months 44 | -and may be updated, replaced, or obsoleted by other documents at any 45 | -time. It is inappropriate to use Internet-Drafts as reference material 46 | -or to cite them other than as ``work in progress.'' 47 | - 48 | -To learn the current status of any Internet-Draft, please check the 49 | -``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow 50 | -Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), 51 | -ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). 52 | - 53 | -2. Introduction 54 | - 55 | -This document defines a C language application program interface to the 56 | -lightweight directory access protocol (LDAP). This document replaces the 57 | -previous definition of this API, defined in RFC 1823, updating it to 58 | -include support for features found in version 3 of the LDAP protocol. 59 | -New extended operation functions were added to support LDAPv3 features 60 | -such as controls. In addition, other LDAP API changes were made to 61 | - 62 | - 63 | - 64 | -Expires: January 1998 [Page 1] 65 | - 66 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 67 | - 68 | - 69 | -support information hiding and thread safety. 70 | - 71 | -The C LDAP API is designed to be powerful, yet simple to use. It defines 72 | -compatible synchronous and asynchronous interfaces to LDAP to suit a 73 | -wide variety of applications. This document gives a brief overview of 74 | -the LDAP model, then an overview of how the API is used by an applica- 75 | -tion program to obtain LDAP information. The API calls are described in 76 | -detail, followed by an appendix that provides some example code demon- 77 | -strating the use of the API. This document provides information to the 78 | -Internet community. It does not specify any standard. 79 | - 80 | -3. Overview of the LDAP Model 81 | - 82 | -LDAP is the lightweight directory access protocol, described in [2] and 83 | -[6]. It can provide a lightweight frontend to the X.500 directory [1], 84 | -or a stand-alone service. In either mode, LDAP is based on a client- 85 | -server model in which a client makes a TCP connection to an LDAP server, 86 | -over which it sends requests and receives responses. 87 | - 88 | -The LDAP information model is based on the entry, which contains infor- 89 | -mation about some object (e.g., a person). Entries are composed of 90 | -attributes, which have a type and one or more values. Each attribute has 91 | -a syntax that determines what kinds of values are allowed in the attri- 92 | -bute (e.g., ASCII characters, a jpeg photograph, etc.) and how those 93 | -values behave during directory operations (e.g., is case significant 94 | -during comparisons). 95 | - 96 | -Entries may be organized in a tree structure, usually based on politi- 97 | -cal, geographical, and organizational boundaries. Each entry is uniquely 98 | -named relative to its sibling entries by its relative distinguished name 99 | -(RDN) consisting of one or more distinguished attribute values from the 100 | -entry. At most one value from each attribute may be used in the RDN. 101 | -For example, the entry for the person Babs Jensen might be named with 102 | -the "Barbara Jensen" value from the commonName attribute. 103 | - 104 | -A globally unique name for an entry, called a distinguished name or DN, 105 | -is constructed by concatenating the sequence of RDNs from the entry up 106 | -to the root of the tree. For example, if Babs worked for the University 107 | -of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen, 108 | -o=University of Michigan, c=US". The DN format used by LDAP is defined 109 | -in [4]. 110 | - 111 | -Operations are provided to authenticate, search for and retrieve infor- 112 | -mation, modify information, and add and delete entries from the tree. 113 | -The next sections give an overview of how the API is used and detailed 114 | -descriptions of the LDAP API calls that implement all of these func- 115 | -tions. 116 | - 117 | - 118 | - 119 | - 120 | -Expires: January 1998 [Page 2] 121 | - 122 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 123 | - 124 | - 125 | -4. Overview of LDAP API Use 126 | - 127 | -An application generally uses the C LDAP API in four simple steps. 128 | - 129 | -- Initialize an LDAP session with a default LDAP server. The 130 | - ldap_init() function returns a handle to the session, allowing mul- 131 | - tiple connections to be open at once. 132 | - 133 | -- Authenticate to the LDAP server. The ldap_bind() function and 134 | - friends support a variety of authentication methods. 135 | - 136 | -- Perform some LDAP operations and obtain some results. ldap_search() 137 | - and friends return results which can be parsed by 138 | - ldap_result2error(), ldap_first_entry(), ldap_next_entry(), etc. 139 | - 140 | -- Close the session. The ldap_unbind() function closes the connec- 141 | - tion. 142 | - 143 | -Operations can be performed either synchronously or asynchronously. The 144 | -names of the synchronous functions end in _s. For example, a synchronous 145 | -search can be completed by calling ldap_search_s(). An asynchronous 146 | -search can be initiated by calling ldap_search(). All synchronous rou- 147 | -tines return an indication of the outcome of the operation (e.g, the 148 | -constant LDAP_SUCCESS or some other error code). The asynchronous rou- 149 | -tines return the message id of the operation initiated. This id can be 150 | -used in subsequent calls to ldap_result() to obtain the result(s) of the 151 | -operation. An asynchronous operation can be abandoned by calling 152 | -ldap_abandon(). 153 | - 154 | -Results and errors are returned in an opaque structure called LDAPMes- 155 | -sage. Routines are provided to parse this structure, step through 156 | -entries and attributes returned, etc. Routines are also provided to 157 | -interpret errors. Later sections of this document describe these rou- 158 | -tines in more detail. 159 | - 160 | -LDAP version 3 servers may return referrals to other servers. By 161 | -default, implementations of this API will attempt to follow referrals 162 | -automatically for the application. This behavior can be disabled glo- 163 | -bally (using the ldap_set_option() call) or on a per-request basis 164 | -through the use of a client control. 165 | - 166 | -As in the LDAPv3 protocol itself, all DNs and string values that are 167 | -passed into or produced by the C LDAP API are represented as UTF-8[10] 168 | -characters. 169 | - 170 | -For compatibility with existing applications, implementations of this 171 | -API will by default use version 2 of the LDAP protocol. Applications 172 | -that intend to take advantage of LDAP version 3 features will need to 173 | - 174 | - 175 | - 176 | -Expires: January 1998 [Page 3] 177 | - 178 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 179 | - 180 | - 181 | -use the ldap_set_option() call with a LDAP_OPT_PROTOCOL_VERSION to 182 | -switch to version 3. 183 | - 184 | - 185 | -5. Common Data Structures 186 | - 187 | -Some data structures that are common to several LDAP API functions are 188 | -defined here: 189 | - 190 | - typedef struct ldap LDAP; 191 | - 192 | - typedef struct ldapmsg LDAPMessage; 193 | - 194 | - struct berval { 195 | - unsigned long bv_len; 196 | - char *bv_val; 197 | - }; 198 | - 199 | - struct timeval { 200 | - long tv_sec; 201 | - long tv_usec; 202 | - }; 203 | - 204 | -The LDAP structure is an opaque data type that represents an LDAP ses- 205 | -sion Typically this corresponds to a connection to a single server, but 206 | -it may encompass several server connections in the face of LDAPv3 refer- 207 | -rals. 208 | - 209 | -The LDAPMessage structure is an opaque data type that is used to return 210 | -results and error information. 211 | - 212 | -The berval structure is used to represent arbitrary binary data and its 213 | -fields have the following meanings: 214 | - 215 | -bv_len Length of data in bytes. 216 | - 217 | -bv_val A pointer to the data itself. 218 | - 219 | - 220 | -The timeval structure is used to represent an interval of time and its 221 | -fields have the following meanings: 222 | - 223 | -tv_sec Seconds component of time interval. 224 | - 225 | -tv_usec Microseconds component of time interval. 226 | - 227 | - 228 | - 229 | - 230 | - 231 | - 232 | -Expires: January 1998 [Page 4] 233 | - 234 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 235 | - 236 | - 237 | -6. LDAP Error Codes 238 | - 239 | -Many of the LDAP API routines return LDAP error codes, some of which 240 | -indicate local errors and some of which may be returned by servers. 241 | -Supported error codes are (hexadecimal values are given in parentheses 242 | -after the constant): 243 | - 244 | - LDAP_SUCCESS (0x00) 245 | - LDAP_OPERATIONS_ERROR( 0x01) 246 | - LDAP_PROTOCOL_ERROR (0x02) 247 | - LDAP_TIMELIMIT_EXCEEDED (0x03) 248 | - LDAP_SIZELIMIT_EXCEEDED (0x04) 249 | - LDAP_COMPARE_FALSE (0x05) 250 | - LDAP_COMPARE_TRUE (0x06) 251 | - LDAP_STRONG_AUTH_NOT_SUPPORTED (0x07) 252 | - LDAP_STRONG_AUTH_REQUIRED (0x08) 253 | - LDAP_REFERRAL (0x0a) -- new in LDAPv3 254 | - LDAP_ADMINLIMIT_EXCEEDED (0x0b) -- new in LDAPv3 255 | - LDAP_UNAVAILABLE_CRITICAL_EXTENSION (0x0c) -- new in LDAPv3 256 | - LDAP_CONFIDENTIALITY_REQUIRED (0x0d) -- new in LDAPv3 257 | - LDAP_NO_SUCH_ATTRIBUTE (0x10) 258 | - LDAP_UNDEFINED_TYPE (0x11) 259 | - LDAP_INAPPROPRIATE_MATCHING (0x12) 260 | - LDAP_CONSTRAINT_VIOLATION (0x13) 261 | - LDAP_TYPE_OR_VALUE_EXISTS (0x14) 262 | - LDAP_INVALID_SYNTAX (0x15) 263 | - LDAP_NO_SUCH_OBJECT (0x20) 264 | - LDAP_ALIAS_PROBLEM (0x21) 265 | - LDAP_INVALID_DN_SYNTAX (0x22) 266 | - LDAP_IS_LEAF (0x23) -- not used in LDAPv3 267 | - LDAP_ALIAS_DEREF_PROBLEM (0x24) 268 | - LDAP_INAPPROPRIATE_AUTH (0x30) 269 | - LDAP_INVALID_CREDENTIALS (0x31) 270 | - LDAP_INSUFFICIENT_ACCESS (0x32) 271 | - LDAP_BUSY (0x33) 272 | - LDAP_UNAVAILABLE (0x34) 273 | - LDAP_UNWILLING_TO_PERFORM (0x35) 274 | - LDAP_LOOP_DETECT (0x36) 275 | - LDAP_NAMING_VIOLATION (0x40) 276 | - LDAP_OBJECT_CLASS_VIOLATION (0x41) 277 | - LDAP_NOT_ALLOWED_ON_NONLEAF (0x42) 278 | - LDAP_NOT_ALLOWED_ON_RDN (0x43) 279 | - LDAP_ALREADY_EXISTS (0x44) 280 | - LDAP_NO_OBJECT_CLASS_MODS (0x45) 281 | - LDAP_RESULTS_TOO_LARGE (0x46) 282 | - LDAP_AFFECTS_MULTIPLE_DSAS (0x47) -- new in LDAPv3 283 | - LDAP_OTHER (0x50) 284 | - LDAP_SERVER_DOWN (0x51) 285 | - 286 | - 287 | - 288 | -Expires: January 1998 [Page 5] 289 | - 290 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 291 | - 292 | - 293 | - LDAP_LOCAL_ERROR (0x52) 294 | - LDAP_ENCODING_ERROR (0x53) 295 | - LDAP_DECODING_ERROR (0x54) 296 | - LDAP_TIMEOUT (0x55) 297 | - LDAP_AUTH_UNKNOWN (0x56) 298 | - LDAP_FILTER_ERROR (0x57) 299 | - LDAP_USER_CANCELLED (0x58) 300 | - LDAP_PARAM_ERROR (0x59) 301 | - LDAP_NO_MEMORY (0x5a) 302 | - LDAP_CONNECT_ERROR (0x5b) 303 | - LDAP_NOT_SUPPORTED (0x5c) 304 | - LDAP_CONTROL_NOT_FOUND (0x5d) 305 | - LDAP_NO_RESULTS_RETURNED (0x5e) 306 | - LDAP_MORE_RESULTS_TO_RETURN (0x5f) 307 | - LDAP_CLIENT_LOOP (0x60) 308 | - LDAP_REFERRAL_LIMIT_EXCEEDED (0x61) 309 | - 310 | - 311 | -7. Performing LDAP Operations 312 | - 313 | -This section describes each LDAP operation API call in detail. All func- 314 | -tions take a "session handle," a pointer to an LDAP structure containing 315 | -per-connection information. Many routines return results in an LDAPMes- 316 | -sage structure. These structures and others are described as needed 317 | -below. 318 | - 319 | - 320 | -7.1. Initializing an LDAP Session 321 | - 322 | -ldap_init() initializes a session with an LDAP server. The server is not 323 | -actually contacted until an operation is performed that requires it, 324 | -allowing various options to be set after initialization. 325 | - 326 | - LDAP *ldap_init( 327 | - char *hostname, 328 | - int portno 329 | - ); 330 | - 331 | -Use of the following routine is deprecated. 332 | - 333 | - LDAP *ldap_open( 334 | - char *hostname, 335 | - int portno 336 | - ); 337 | - 338 | -Parameters are: 339 | - 340 | -hostname Contains a space-separated list of hostnames or dotted strings 341 | - 342 | - 343 | - 344 | -Expires: January 1998 [Page 6] 345 | - 346 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 347 | - 348 | - 349 | - representing the IP address of hosts running an LDAP server to 350 | - connect to. Each hostname in the list can include an optional 351 | - port number which is separated from the host itself with a 352 | - colon (:) character. The hosts are tried in the order listed, 353 | - stopping with the first one to which a successful connection is 354 | - made. Note that only ldap_open() attempts to make the connec- 355 | - tion before returning to the caller. ldap_init() does not con- 356 | - nect to the LDAP server. 357 | - 358 | -portno Contains the TCP port number to connect to. The default LDAP 359 | - port of 389 can be obtained by supplying the constant 360 | - LDAP_PORT. If a host includes a port number then this parame- 361 | - ter is ignored. 362 | - 363 | -ldap_init() and ldap_open() both return a "session handle," a pointer to 364 | -an opaque structure that should be passed to subsequent calls pertaining 365 | -to the session. These routines return NULL if the session cannot be ini- 366 | -tialized in which case the operating system error reporting mechanism 367 | -can be checked to see why the call failed. 368 | - 369 | -Note that if you connect to an LDAPv2 server, one of the ldap_bind() 370 | -calls described below must be completed before other operations can be 371 | -performed on the session. LDAPv3 does not require that a bind operation 372 | -be completed before other operations can be performed. 373 | - 374 | -The calling program can set various attributes of the session by calling 375 | -the routines described in the next section. 376 | - 377 | - 378 | -7.2. LDAP Session Handle Options 379 | - 380 | -The LDAP session handle returned by ldap_init() is a pointer to an 381 | -opaque data type representing an LDAP session. Formerly, this data type 382 | -was a structure exposed to the caller, and various fields in the struc- 383 | -ture could be set to control aspects of the session, such as size and 384 | -time limits on searches. 385 | - 386 | -In the interest of insulating callers from inevitable changes to this 387 | -structure, these aspects of the session are now accessed through a pair 388 | -of accessor functions, described below. 389 | - 390 | -ldap_get_option() is used to access the current value of various 391 | -session-wide parameters. ldap_set_option() is used to set the value of 392 | -these parameters. 393 | - 394 | - int ldap_get_option( 395 | - LDAP *ld, 396 | - int option, 397 | - 398 | - 399 | - 400 | -Expires: January 1998 [Page 7] 401 | - 402 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 403 | - 404 | - 405 | - void *outvalue 406 | - ); 407 | - 408 | - int ldap_set_option( 409 | - LDAP *ld, 410 | - int option, 411 | - void *invalue 412 | - ); 413 | - 414 | -Parameters are: 415 | - 416 | -ld The session handle. 417 | - 418 | -option The name of the option being accessed or set. This parameter 419 | - should be one of the following constants, which have the indi- 420 | - cated meanings. After the constant the actual value of the con- 421 | - stant is listed in hexadecimal in parentheses followed by the 422 | - type of the corresponding outvalue or invalue parameter. 423 | - 424 | - LDAP_OPT_DESC (0x01) int * 425 | - The underlying socket descriptor corresponding to the default 426 | - LDAP connection. 427 | - 428 | - LDAP_OPT_DEREF (0x02) int * 429 | - Controls how aliases are handled during search. It can have 430 | - one of the following values: LDAP_DEREF_NEVER (0x00), 431 | - LDAP_DEREF_SEARCHING (0x01), LDAP_DEREF_FINDING (0x02), or 432 | - LDAP_DEREF_ALWAYS (0x03). The LDAP_DEREF_SEARCHING value 433 | - means aliases should be dereferenced during the search but not 434 | - when locating the base object of the search. The 435 | - LDAP_DEREF_FINDING value means aliases should be dereferenced 436 | - when locating the base object but not during the search. 437 | - 438 | - LDAP_OPT_SIZELIMIT (0x03) int * 439 | - A limit on the number of entries to return from a search. A 440 | - value of zero means no limit. 441 | - 442 | - LDAP_OPT_TIMELIMIT (0x04) int * 443 | - A limit on the number of seconds to spend on a search. A value 444 | - of zero means no limit 445 | - 446 | - LDAP_OPT_REBIND_FN (0x06) function pointer 447 | - See the discussion of ldap_bind() and friends below. 448 | - 449 | - LDAP_OPT_REBIND_ARG (0x07) void * 450 | - See the discussion of ldap_bind() and friends below. 451 | - 452 | - LDAP_OPT_REFERRALS (0x08) void * 453 | - 454 | - 455 | - 456 | -Expires: January 1998 [Page 8] 457 | - 458 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 459 | - 460 | - 461 | - This option controls whether the LDAP library automatically 462 | - follows referrals returned by LDAP servers or not. It can be 463 | - set to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF. 464 | - 465 | - LDAP_OPT_RESTART (0x09) void * 466 | - This option controls whether LDAP I/O operations should 467 | - automatically be restarted if they abort prematurely. It 468 | - should be set to one of the constants LDAP_OPT_ON or 469 | - LDAP_OPT_OFF. This option is useful if an LDAP I/O operation 470 | - may be interrupted prematurely, for example by a timer going 471 | - off, or other interrrupt. 472 | - 473 | - LDAP_OPT_PROTOCOL_VERSION (0x11) int * 474 | - This option indicates the version of the default LDAP server. 475 | - It can be one of the constants LDAP_VERSION2 or LDAP_VERSION3. 476 | - If no version is set the default is LDAP_VERSION2. 477 | - 478 | - LDAP_OPT_SERVER_CONTROLS (0x12) LDAPControl ** 479 | - A default list of LDAP server controls to be sent with each 480 | - request. See the Using Controls section below. 481 | - 482 | - LDAP_OPT_CLIENT_CONTROLS (0x13) LDAPControl ** 483 | - A default list of client controls that affect the LDAP ses- 484 | - sion. See the Using Controls section below. 485 | - 486 | - LDAP_OPT_HOST_NAME (0x30) char ** 487 | - The host name of the default LDAP server. 488 | - 489 | - LDAP_OPT_ERROR_NUMBER (0x31) int * 490 | - The code of the most recent LDAP error that occurred for this 491 | - session. 492 | - 493 | - LDAP_OPT_ERROR_STRING (0x32) char ** 494 | - The message returned with the most recent LDAP error that 495 | - occurred for this session. 496 | - 497 | - 498 | -outvalue The address of a place to put the value of the option. The 499 | - actual type of this parameter depends on the setting of the 500 | - option parameter. 501 | - 502 | -invalue A pointer to the value the option is to be given. The actual 503 | - type of this parameter depends on the setting of the option 504 | - parameter. The constants LDAP_OPT_ON and LDAP_OPT_OFF can be 505 | - given for options that have on or off settings. 506 | - 507 | - 508 | - 509 | - 510 | - 511 | - 512 | -Expires: January 1998 [Page 9] 513 | - 514 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 515 | - 516 | - 517 | -7.3. Working with controls 518 | - 519 | -LDAPv3 operations can be extended through the use of controls. Controls 520 | -may be sent to a server or returned to the client with any LDAP message. 521 | -These controls are referred to as server controls. 522 | - 523 | -The LDAP API also supports a client-side extension mechanism through the 524 | -use of client controls. These controls affect the behavior of the LDAP 525 | -API only and are never sent to a server. A common data structure is 526 | -used to represent both types of controls: 527 | - 528 | - typedef struct ldapcontrol { 529 | - char *ldctl_oid; 530 | - struct berval ldctl_value; 531 | - char ldctl_iscritical; 532 | - } LDAPControl, *PLDAPControl; 533 | - 534 | -The fields in the ldapcontrol structure have the following meanings: 535 | - 536 | -ldctl_oid The control type, represented as a string. 537 | - 538 | -ldctl_value The data associated with the control (if any). 539 | - 540 | -ldctl_iscritical Indicates whether the control is critical of not. If 541 | - this field is non-zero, the operation will only be car- 542 | - ried out if the control is recognized by the server 543 | - and/or client. 544 | - 545 | -Some LDAP API calls allocate an ldapcontrol structure or a NULL- 546 | -terminated array of ldapcontrol structures. The following routines can 547 | -be used to dispose of a single control or an array of controls: 548 | - 549 | - void ldap_control_free( LDAPControl *ctrl ); 550 | - void ldap_controls_free( LDAPControl **ctrls ); 551 | - 552 | -A set of controls that affect the entire session can be set using the 553 | -ldap_set_option() function (see above). A list of controls can also be 554 | -passed directly to some LDAP API calls such as ldap_search_ext(), in 555 | -which case any controls set for the session through the use of 556 | -ldap_set_option() are ignored. Control lists are represented as a NULL- 557 | -terminated array of pointers to ldapcontrol structures. 558 | - 559 | -Server controls are defined by LDAPv3 protocol extension documents; for 560 | -example, a control has been proposed to support server-side sorting of 561 | -search results [7]. 562 | - 563 | -No client controls are defined by this document but they may be defined 564 | -in future revisions or in any document that extends this API. 565 | - 566 | - 567 | - 568 | -Expires: January 1998 [Page 10] 569 | - 570 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 571 | - 572 | - 573 | -7.4. Authenticating to the directory 574 | - 575 | -The following functions are used to authenticate an LDAP client to an 576 | -LDAP directory server. 577 | - 578 | -The ldap_sasl_bind() and ldap_sasl_bind_s() functions can be used to do 579 | -general and extensible authentication over LDAP through the use of the 580 | -Simple Authentication Security Layer [8]. The routines both take the dn 581 | -to bind as, the method to use, as a dotted-string representation of an 582 | -OID identifying the method, and a struct berval holding the credentials. 583 | -The special constant value LDAP_SASL_SIMPLE ("") can be passed to 584 | -request simple authentication, or the simplified routines 585 | -ldap_simple_bind() or ldap_simple_bind_s() can be used. 586 | - 587 | - int ldap_sasl_bind( 588 | - LDAP *ld, 589 | - char *dn, 590 | - char *mechanism, 591 | - struct berval *cred, 592 | - LDAPControl **serverctrls, 593 | - LDAPControl **clientctrls, 594 | - int *msgidp 595 | - ); 596 | - 597 | - int ldap_sasl_bind_s( 598 | - LDAP *ld, 599 | - char *dn, 600 | - char *mechanism, 601 | - struct berval *cred, 602 | - LDAPControl **serverctrls, 603 | - LDAPControl **clientctrls, 604 | - struct berval **servercredp 605 | - ); 606 | - 607 | - int ldap_simple_bind( 608 | - LDAP *ld, 609 | - char *dn, 610 | - char *passwd 611 | - ); 612 | - 613 | - int ldap_simple_bind_s( 614 | - LDAP *ld, 615 | - char *dn, 616 | - char *passwd 617 | - ); 618 | - 619 | - The use of the following routines is deprecated: 620 | - 621 | - 622 | - 623 | - 624 | -Expires: January 1998 [Page 11] 625 | - 626 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 627 | - 628 | - 629 | - int ldap_bind( LDAP *ld, char *dn, char *cred, int method ); 630 | - 631 | - int ldap_bind_s( LDAP *ld, char *dn, char *cred, int method ); 632 | - 633 | - int ldap_kerberos_bind( LDAP *ld, char *dn ); 634 | - 635 | - int ldap_kerberos_bind_s( LDAP *ld, char *dn ); 636 | - 637 | -Parameters are: 638 | - 639 | -ld The session handle. 640 | - 641 | -dn The name of the entry to bind as. 642 | - 643 | -mechanism Either LDAP_AUTH_SIMPLE_OID to get simple authentication, 644 | - or a dotted text string representing an OID identifying the 645 | - SASL method. 646 | - 647 | -cred The credentials with which to authenticate. Arbitrary 648 | - credentials can be passed using this parameter. The format 649 | - and content of the credentials depends on the setting of 650 | - the mechanism parameter. 651 | - 652 | -passwd For ldap_simple_bind(), the password to compare to the 653 | - entry's userPassword attribute. 654 | - 655 | -serverctrls List of LDAP server controls. 656 | - 657 | -clientctrls List of client controls. 658 | - 659 | -msgidp This result parameter will be set to the message id of the 660 | - request if the ldap_sasl_bind() call succeeds. 661 | - 662 | -servercredp This result parameter will be set to the credentials 663 | - returned by the server. This should be freed by calling 664 | - ldap_If no credentials are returned it will be set to NULL. 665 | - 666 | -Additional parameters for the deprecated routines are not described. 667 | -Interested readers are referred to RFC 1823. 668 | - 669 | -The ldap_sasl_bind() function initiates an asynchronous bind operation 670 | -and returns the constant LDAP_SUCCESS if the request was successfully 671 | -sent, or another LDAP error code if not. See the section below on error 672 | -handling for more information about possible errors and how to interpret 673 | -them. If successful, ldap_sasl_bind() places the message id of the 674 | -request in *msgidp. A subsequent call to ldap_result(), described below, 675 | -can be used to obtain the result of the bind. 676 | - 677 | - 678 | - 679 | - 680 | -Expires: January 1998 [Page 12] 681 | - 682 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 683 | - 684 | - 685 | -The ldap_simple_bind() function initiates a simple asynchronous bind 686 | -operation and returns the message id of the operation initiated. A sub- 687 | -sequent call to ldap_result(), described below, can be used to obtain 688 | -the result of the bind. In case of error, ldap_simple_bind() will return 689 | --1, setting the session error parameters in the LDAP structure appropri- 690 | -ately. 691 | - 692 | -The synchronous ldap_sasl_bind_s() and ldap_simple_bind_s() functions 693 | -both return the result of the operation, either the constant 694 | -LDAP_SUCCESS if the operation was successful, or another LDAP error code 695 | -if it was not. See the section below on error handling for more informa- 696 | -tion about possible errors and how to interpret them. 697 | - 698 | -Note that if an LDAPv2 server is contacted, no other operations over the 699 | -connection should be attempted before a bind call has successfully com- 700 | -pleted. 701 | - 702 | -Subsequent bind calls can be used to re-authenticate over the same con- 703 | -nection, and multistep SASL sequences can be accomplished through a 704 | -sequence of calls to ldap_sasl_bind() or ldap_sasl_bind_s(). 705 | - 706 | - 707 | -7.5. Closing the session 708 | - 709 | -The following functions are used to unbind from the directory, close the 710 | -connection, and dispose of the session handle. 711 | - 712 | - int ldap_unbind( LDAP *ld ); 713 | - 714 | - int ldap_unbind_s( LDAP *ld ); 715 | - 716 | -Parameters are: 717 | - 718 | -ld The session handle. 719 | - 720 | -ldap_unbind() and ldap_unbind_s() both work synchronously, unbinding 721 | -from the directory, closing the connection, and freeing up the ld struc- 722 | -ture before returning. There is no server response to an unbind opera- 723 | -tion. ldap_unbind() returns LDAP_SUCCESS (or another LDAP error code if 724 | -the request cannot be sent to the LDAP server). After a call to 725 | -ldap_unbind() or ldap_unbind_s(), the session handle ld is invalid. 726 | - 727 | - 728 | -7.6. Searching 729 | - 730 | -The following functions are used to search the LDAP directory, returning 731 | -a requested set of attributes for each entry matched. There are five 732 | -variations. 733 | - 734 | - 735 | - 736 | -Expires: January 1998 [Page 13] 737 | - 738 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 739 | - 740 | - 741 | - int ldap_search_ext( 742 | - LDAP *ld, 743 | - char *base, 744 | - int scope, 745 | - char *filter, 746 | - char **attrs, 747 | - int attrsonly, 748 | - LDAPControl **serverctrls, 749 | - LDAPControl **clientctrls, 750 | - struct timeval *timeoutp, 751 | - int sizelimit, 752 | - int *msgidp 753 | - ); 754 | - 755 | - int ldap_search_ext_s( 756 | - LDAP *ld, 757 | - char *base, 758 | - int scope, 759 | - char *filter, 760 | - char **attrs, 761 | - int attrsonly, 762 | - LDAPControl **serverctrls, 763 | - LDAPControl **clientctrls, 764 | - struct timeval *timeoutp, 765 | - int sizelimit, 766 | - LDAPMessage **res 767 | - ); 768 | - 769 | - int ldap_search( 770 | - LDAP *ld, 771 | - char *base, 772 | - int scope, 773 | - char *filter, 774 | - char **attrs, 775 | - int attrsonly 776 | - ); 777 | - 778 | - int ldap_search_s( 779 | - LDAP *ld, 780 | - char *base, 781 | - int scope, 782 | - char *filter, 783 | - char **attrs, 784 | - int attrsonly, 785 | - LDAPMessage **res 786 | - ); 787 | - 788 | - int ldap_search_st( 789 | - 790 | - 791 | - 792 | -Expires: January 1998 [Page 14] 793 | - 794 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 795 | - 796 | - 797 | - LDAP *ld, 798 | - char *base, 799 | - int scope, 800 | - char *filter, 801 | - char **attrs, 802 | - int attrsonly, 803 | - struct timeval *timeout, 804 | - LDAPMessage **res 805 | - ); 806 | - 807 | -Parameters are: 808 | - 809 | -ld The session handle. 810 | - 811 | -base The dn of the entry at which to start the search. 812 | - 813 | -scope One of LDAP_SCOPE_BASE (0x00), LDAP_SCOPE_ONELEVEL (0x01), 814 | - or LDAP_SCOPE_SUBTREE (0x02), indicating the scope of the 815 | - search. 816 | - 817 | -filter A character string as described in [3], representing the 818 | - search filter. 819 | - 820 | -attrs A NULL-terminated array of strings indicating which attri- 821 | - butes to return for each matching entry. Passing NULL for 822 | - this parameter causes all available attributes to be 823 | - retrieved. 824 | - 825 | -attrsonly A boolean value that should be zero if both attribute types 826 | - and values are to be returned, non-zero if only types are 827 | - wanted. 828 | - 829 | -timeout For the ldap_search_st() function, this specifies the local 830 | - search timeout value. For the ldap_search_ext() and 831 | - ldap_search_ext_s() functions, this specifies both the 832 | - local search timeout value and the operation time limit 833 | - that is sent to the server within the search request. 834 | - 835 | -res For the synchronous calls, this is a result parameter which 836 | - will contain the results of the search upon completion of 837 | - the call. 838 | - 839 | -serverctrls List of LDAP server controls. 840 | - 841 | -clientctrls List of client controls. 842 | - 843 | -msgidp This result parameter will be set to the message id of the 844 | - request if the ldap_search_ext() call succeeds. 845 | - 846 | - 847 | - 848 | -Expires: January 1998 [Page 15] 849 | - 850 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 851 | - 852 | - 853 | -There are three options in the session handle ld which potentially 854 | -affect how the search is performed. They are: 855 | - 856 | -LDAP_OPT_SIZELIMIT 857 | - A limit on the number of entries to return from the search. 858 | - A value of zero means no limit. Note that the value from 859 | - the session handle is ignored when using the 860 | - ldap_search_ext() or ldap_search_ext_s() functions. 861 | - 862 | -LDAP_OPT_TIMELIMIT 863 | - A limit on the number of seconds to spend on the search. A 864 | - value of zero means no limit. Note that the value from the 865 | - session handle is ignored when using the ldap_search_ext() 866 | - or ldap_search_ext_s() functions. 867 | - 868 | -LDAP_OPT_DEREF 869 | - One of LDAP_DEREF_NEVER (0x00), LDAP_DEREF_SEARCHING 870 | - (0x01), LDAP_DEREF_FINDING (0x02), or LDAP_DEREF_ALWAYS 871 | - (0x03), specifying how aliases should be handled during the 872 | - search. The LDAP_DEREF_SEARCHING value means aliases should 873 | - be dereferenced during the search but not when locating the 874 | - base object of the search. The LDAP_DEREF_FINDING value 875 | - means aliases should be dereferenced when locating the base 876 | - object but not during the search. 877 | - 878 | -The ldap_search_ext() function initiates an asynchronous search opera- 879 | -tion and returns the constant LDAP_SUCCESS if the request was success- 880 | -fully sent, or another LDAP error code if not. See the section below on 881 | -error handling for more information about possible errors and how to 882 | -interpret them. If successful, ldap_search_ext() places the message id 883 | -of the request in *msgidp. A subsequent call to ldap_result(), described 884 | -below, can be used to obtain the results from the search. These results 885 | -can be parsed using the result parsing routines described in detail 886 | -later. 887 | - 888 | -Similar to ldap_search_ext(), the ldap_search() function initiates an 889 | -asynchronous search operation and returns the message id of the opera- 890 | -tion initiated. As for ldap_search_ext(), a subsequent call to 891 | -ldap_result(), described below, can be used to obtain the result of the 892 | -bind. In case of error, ldap_search() will return -1, setting the ses- 893 | -sion error parameters in the LDAP structure appropriately. 894 | - 895 | -The synchronous ldap_search_ext_s(), ldap_search_s(), and 896 | -ldap_search_st() functions all return the result of the operation, 897 | -either the constant LDAP_SUCCESS if the operation was successful, or 898 | -another LDAP error code if it was not. See the section below on error 899 | -handling for more information about possible errors and how to interpret 900 | -them. Entries returned from the search (if any) are contained in the 901 | - 902 | - 903 | - 904 | -Expires: January 1998 [Page 16] 905 | - 906 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 907 | - 908 | - 909 | -res parameter. This parameter is opaque to the caller. Entries, attri- 910 | -butes, values, etc., should be extracted by calling the parsing routines 911 | -described below. The results contained in res should be freed when no 912 | -longer in use by calling ldap_msgfree(), described later. 913 | - 914 | -The ldap_search_ext() and ldap_search_ext_s() functions support LDAPv3 915 | -server controls, client controls, and allow varying size and time limits 916 | -to be easily specified for each search operation. The ldap_search_st() 917 | -function is identical to ldap_search_s() except that it takes an addi- 918 | -tional parameter specifying a local timeout for the search. 919 | - 920 | -7.7. Reading an Entry 921 | - 922 | -LDAP does not support a read operation directly. Instead, this operation 923 | -is emulated by a search with base set to the DN of the entry to read, 924 | -scope set to LDAP_SCOPE_BASE, and filter set to "(objectclass=*)". attrs 925 | -contains the list of attributes to return. 926 | - 927 | - 928 | -7.8. Listing the Children of an Entry 929 | - 930 | -LDAP does not support a list operation directly. Instead, this operation 931 | -is emulated by a search with base set to the DN of the entry to list, 932 | -scope set to LDAP_SCOPE_ONELEVEL, and filter set to "(objectclass=*)". 933 | -attrs contains the list of attributes to return for each child entry. 934 | - 935 | -7.9. Comparing a Value Against an Entry 936 | - 937 | -The following routines are used to compare a given attribute value 938 | -assertion against an LDAP entry. There are four variations: 939 | - 940 | - int ldap_compare_ext( 941 | - LDAP *ld, 942 | - char *dn, 943 | - char *attr, 944 | - struct berval *bvalue 945 | - LDAPControl **serverctrls, 946 | - LDAPControl **clientctrls, 947 | - int *msgidp 948 | - ); 949 | - 950 | - int ldap_compare_ext_s( 951 | - LDAP *ld, 952 | - char *dn, 953 | - char *attr, 954 | - struct berval *bvalue, 955 | - LDAPControl **serverctrls, 956 | - LDAPControl **clientctrls 957 | - 958 | - 959 | - 960 | -Expires: January 1998 [Page 17] 961 | - 962 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 963 | - 964 | - 965 | - ); 966 | - 967 | - int ldap_compare( 968 | - LDAP *ld, 969 | - char *dn, 970 | - char *attr, 971 | - char *value 972 | - ); 973 | - 974 | - int ldap_compare_s( 975 | - LDAP *ld, 976 | - char *dn, 977 | - char *attr, 978 | - char *value 979 | - ); 980 | - 981 | -Parameters are: 982 | - 983 | -ld The session handle. 984 | - 985 | -dn The name of the entry to compare against. 986 | - 987 | -attr The attribute to compare against. 988 | - 989 | -bvalue The attribute value to compare against those found in the 990 | - given entry. This parameter is used in the extended rou- 991 | - tines and is a pointer to a struct berval so it is possible 992 | - to compare binary values. 993 | - 994 | -value A string attribute value to compare against, used by the 995 | - ldap_compare() and ldap_compare_s() functions. Use 996 | - ldap_compare_ext() or ldap_compare_ext_s() if you need to 997 | - compare binary values. 998 | - 999 | -serverctrls List of LDAP server controls. 1000 | - 1001 | -clientctrls List of client controls. 1002 | - 1003 | -msgidp This result parameter will be set to the message id of the 1004 | - request if the ldap_compare_ext() call succeeds. 1005 | - 1006 | -The ldap_compare_ext() function initiates an asynchronous compare opera- 1007 | -tion and returns the constant LDAP_SUCCESS if the request was success- 1008 | -fully sent, or another LDAP error code if not. See the section below on 1009 | -error handling for more information about possible errors and how to 1010 | -interpret them. If successful, ldap_compare_ext() places the message id 1011 | -of the request in *msgidp. A subsequent call to ldap_result(), described 1012 | -below, can be used to obtain the result of the compare. 1013 | - 1014 | - 1015 | - 1016 | -Expires: January 1998 [Page 18] 1017 | - 1018 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 1019 | - 1020 | - 1021 | -Similar to ldap_compare_ext(), the ldap_compare() function initiates an 1022 | -asynchronous compare operation and returns the message id of the opera- 1023 | -tion initiated. As for ldap_compare_ext(), a subsequent call to 1024 | -ldap_result(), described below, can be used to obtain the result of the 1025 | -bind. In case of error, ldap_compare() will return -1, setting the ses- 1026 | -sion error parameters in the LDAP structure appropriately. 1027 | - 1028 | -The synchronous ldap_compare_ext_s() and ldap_compare_s() functions both 1029 | -return the result of the operation, either the constant LDAP_SUCCESS if 1030 | -the operation was successful, or another LDAP error code if it was not. 1031 | -See the section below on error handling for more information about pos- 1032 | -sible errors and how to interpret them. 1033 | - 1034 | -The ldap_compare_ext() and ldap_compare_ext_s() functions support LDAPv3 1035 | -server controls and client controls. 1036 | - 1037 | - 1038 | -7.10. Modifying an entry 1039 | - 1040 | -The following routines are used to modify an existing LDAP entry. There 1041 | -are four variations: 1042 | - 1043 | - typedef struct ldapmod { 1044 | - int mod_op; 1045 | - char *mod_type; 1046 | - union { 1047 | - char **modv_strvals; 1048 | - struct berval **modv_bvals; 1049 | - } mod_vals; 1050 | - } LDAPMod; 1051 | - #define mod_values mod_vals.modv_strvals 1052 | - #define mod_bvalues mod_vals.modv_bvals 1053 | - 1054 | - int ldap_modify_ext( 1055 | - LDAP *ld, 1056 | - char *dn, 1057 | - LDAPMod **mods, 1058 | - LDAPControl **serverctrls, 1059 | - LDAPControl **clientctrls, 1060 | - int *msgidp 1061 | - ); 1062 | - 1063 | - int ldap_modify_ext_s( 1064 | - LDAP *ld, 1065 | - char *dn, 1066 | - LDAPMod **mods, 1067 | - LDAPControl **serverctrls, 1068 | - LDAPControl **clientctrls 1069 | - 1070 | - 1071 | - 1072 | -Expires: January 1998 [Page 19] 1073 | - 1074 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 1075 | - 1076 | - 1077 | - ); 1078 | - 1079 | - int ldap_modify( 1080 | - LDAP *ld, 1081 | - char *dn, 1082 | - LDAPMod **mods 1083 | - ); 1084 | - 1085 | - int ldap_modify_s( 1086 | - LDAP *ld, 1087 | - char *dn, 1088 | - LDAPMod **mods 1089 | - ); 1090 | - 1091 | -Parameters are: 1092 | - 1093 | -ld The session handle. 1094 | - 1095 | -dn The name of the entry to modify. 1096 | - 1097 | -mods A NULL-terminated array of modifications to make to the 1098 | - entry. 1099 | - 1100 | -serverctrls List of LDAP server controls. 1101 | - 1102 | -clientctrls List of client controls. 1103 | - 1104 | -msgidp This result parameter will be set to the message id of the 1105 | - request if the ldap_modify_ext() call succeeds. 1106 | - 1107 | -The fields in the LDAPMod structure have the following meanings: 1108 | - 1109 | -mod_op The modification operation to perform. It should be one of 1110 | - LDAP_MOD_ADD (0x00), LDAP_MOD_DELETE (0x01), or 1111 | - LDAP_MOD_REPLACE (0x02). This field also indicates the 1112 | - type of values included in the mod_vals union. It is logi- 1113 | - cally ORed with LDAP_MOD_BVALUES (0x80) to select the 1114 | - mod_bvalues form. Otherwise, the mod_values form is used. 1115 | - 1116 | -mod_type The type of the attribute to modify. 1117 | - 1118 | -mod_vals The values (if any) to add, delete, or replace. Only one of 1119 | - the mod_values or mod_bvalues variants should be used, 1120 | - selected by ORing the mod_op field with the constant 1121 | - LDAP_MOD_BVALUES. mod_values is a NULL-terminated array of 1122 | - zero-terminated strings and mod_bvalues is a NULL- 1123 | - terminated array of berval structures that can be used to 1124 | - pass binary values such as images. 1125 | - 1126 | - 1127 | - 1128 | -Expires: January 1998 [Page 20] 1129 | - 1130 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 1131 | - 1132 | - 1133 | -For LDAP_MOD_ADD modifications, the given values are added to the 1134 | -entry, creating the attribute if necessary. 1135 | - 1136 | -For LDAP_MOD_DELETE modifications, the given values are deleted from the 1137 | -entry, removing the attribute if no values remain. If the entire attri- 1138 | -bute is to be deleted, the mod_vals field should be set to NULL. 1139 | - 1140 | -For LDAP_MOD_REPLACE modifications, the attribute will have the listed 1141 | -values after the modification, having been created if necessary, or 1142 | -removed if the mod_vals field is NULL. All modifications are performed 1143 | -in the order in which they are listed. 1144 | - 1145 | -The ldap_modify_ext() function initiates an asynchronous modify opera- 1146 | -tion and returns the constant LDAP_SUCCESS if the request was success- 1147 | -fully sent, or another LDAP error code if not. See the section below on 1148 | -error handling for more information about possible errors and how to 1149 | -interpret them. If successful, ldap_modify_ext() places the message id 1150 | -of the request in *msgidp. A subsequent call to ldap_result(), described 1151 | -below, can be used to obtain the result of the modify. 1152 | - 1153 | -Similar to ldap_modify_ext(), the ldap_modify() function initiates an 1154 | -asynchronous modify operation and returns the message id of the opera- 1155 | -tion initiated. As for ldap_modify_ext(), a subsequent call to 1156 | -ldap_result(), described below, can be used to obtain the result of the 1157 | -modify. In case of error, ldap_modify() will return -1, setting the ses- 1158 | -sion error parameters in the LDAP structure appropriately. 1159 | - 1160 | -The synchronous ldap_modify_ext_s() and ldap_modify_s() functions both 1161 | -return the result of the operation, either the constant LDAP_SUCCESS if 1162 | -the operation was successful, or another LDAP error code if it was not. 1163 | -See the section below on error handling for more information about pos- 1164 | -sible errors and how to interpret them. 1165 | - 1166 | -The ldap_modify_ext() and ldap_modify_ext_s() functions support LDAPv3 1167 | -server controls and client controls. 1168 | - 1169 | - 1170 | -7.11. Modifying the Name of an Entry 1171 | - 1172 | -In LDAPv2, the ldap_modrdn() and ldap_modrdn_s() routines were used to 1173 | -change the name of an LDAP entry. They could only be used to change the 1174 | -least significant component of a name (the RDN or relative distinguished 1175 | -name). LDAPv3 provides the Modify DN protocol operation that allows more 1176 | -general name change access. The ldap_rename() and ldap_rename_s() rou- 1177 | -tines are used to change the name of an entry, and the use of the 1178 | -ldap_modrdn() and ldap_modrdn_s() routines is deprecated. 1179 | - 1180 | - int ldap_rename( 1181 | - 1182 | - 1183 | - 1184 | -Expires: January 1998 [Page 21] 1185 | - 1186 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 1187 | - 1188 | - 1189 | - LDAP *ld, 1190 | - char *dn, 1191 | - char *newrdn, 1192 | - char *newparent, 1193 | - int deleteoldrdn, 1194 | - LDAPControl **serverctrls, 1195 | - LDAPControl **clientctrls, 1196 | - int *msgidp 1197 | - 1198 | - ); 1199 | - int ldap_rename_s( 1200 | - LDAP *ld, 1201 | - char *dn, 1202 | - char *newrdn, 1203 | - char *newparent, 1204 | - int deleteoldrdn, 1205 | - LDAPControl **serverctrls, 1206 | - LDAPControl **clientctrls 1207 | - ); 1208 | - 1209 | - Use of the following routines is deprecated. 1210 | - 1211 | - int ldap_modrdn( 1212 | - LDAP *ld, 1213 | - char *dn, 1214 | - char *newrdn, 1215 | - int deleteoldrdn 1216 | - ); 1217 | - int ldap_modrdn_s( 1218 | - LDAP *ld, 1219 | - char *dn, 1220 | - char *newrdn, 1221 | - int deleteoldrdn 1222 | - ); 1223 | - 1224 | -Parameters are: 1225 | - 1226 | -ld The session handle. 1227 | - 1228 | -dn The name of the entry whose DN is to be changed. 1229 | - 1230 | -newrdn The new RDN to give the entry. 1231 | - 1232 | -newparent The new parent, or superior entry. If this parameter is 1233 | - NULL, only the RDN of the entry is changed. The root DN 1234 | - may be specified by passing a zero length string, "". The 1235 | - newparent parameter should always be NULL when using ver- 1236 | - sion 2 of the LDAP protocol; otherwise the server's 1237 | - 1238 | - 1239 | - 1240 | -Expires: January 1998 [Page 22] 1241 | - 1242 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 1243 | - 1244 | - 1245 | - behavior is undefined. 1246 | - 1247 | -deleteoldrdn This parameter only has meaning on the rename routines if 1248 | - newrdn is different than the old RDN. It is a boolean 1249 | - value, if non-zero indicating that the old RDN value(s) 1250 | - should be removed, if zero indicating that the old RDN 1251 | - value(s) should be retained as non-distinguished values of 1252 | - the entry. 1253 | - 1254 | -serverctrls List of LDAP server controls. 1255 | - 1256 | -clientctrls List of client controls. 1257 | - 1258 | -msgidp This result parameter will be set to the message id of the 1259 | - request if the ldap_rename() call succeeds. 1260 | - 1261 | -The ldap_rename() function initiates an asynchronous modify DN operation 1262 | -and returns the constant LDAP_SUCCESS if the request was successfully 1263 | -sent, or another LDAP error code if not. See the section below on error 1264 | -handling for more information about possible errors and how to interpret 1265 | -them. If successful, ldap_rename() places the DN message id of the 1266 | -request in *msgidp. A subsequent call to ldap_result(), described below, 1267 | -can be used to obtain the result of the rename. 1268 | - 1269 | -The synchronous ldap_rename_s() returns the result of the operation, 1270 | -either the constant LDAP_SUCCESS if the operation was successful, or 1271 | -another LDAP error code if it was not. See the section below on error 1272 | -handling for more information about possible errors and how to interpret 1273 | -them. 1274 | - 1275 | -The ldap_rename() and ldap_rename_s() functions both support LDAPv3 1276 | -server controls and client controls. 1277 | - 1278 | - 1279 | -7.12. Adding an entry 1280 | - 1281 | -The following functions are used to add entries to the LDAP directory. 1282 | -There are four variations: 1283 | - 1284 | - int ldap_add_ext( 1285 | - LDAP *ld, 1286 | - char *dn, 1287 | - LDAPMod **attrs, 1288 | - LDAPControl **serverctrls, 1289 | - LDAPControl **clientctrls, 1290 | - int *msgidp 1291 | - ); 1292 | - 1293 | - 1294 | - 1295 | - 1296 | -Expires: January 1998 [Page 23] 1297 | - 1298 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 1299 | - 1300 | - 1301 | - int ldap_add_ext_s( 1302 | - LDAP *ld, 1303 | - char *dn, 1304 | - LDAPMod **attrs, 1305 | - LDAPControl **serverctrls, 1306 | - LDAPControl **clientctrls 1307 | - ); 1308 | - 1309 | - int ldap_add( 1310 | - LDAP *ld, 1311 | - char *dn, 1312 | - LDAPMod **attrs 1313 | - ); 1314 | - 1315 | - int ldap_add_s( 1316 | - LDAP *ld, 1317 | - char *dn, 1318 | - LDAPMod **attrs 1319 | - ); 1320 | - 1321 | -Parameters are: 1322 | - 1323 | -ld The session handle. 1324 | - 1325 | -dn The name of the entry to add. 1326 | - 1327 | -attrs The entry's attributes, specified using the LDAPMod struc- 1328 | - ture defined for ldap_modify(). The mod_type and mod_vals 1329 | - fields should be filled in. The mod_op field is ignored 1330 | - unless ORed with the constant LDAP_MOD_BVALUES, used to 1331 | - select the mod_bvalues case of the mod_vals union. 1332 | - 1333 | -serverctrls List of LDAP server controls. 1334 | - 1335 | -clientctrls List of client controls. 1336 | - 1337 | -msgidp This result parameter will be set to the message id of the 1338 | - request if the ldap_add_ext() call succeeds. 1339 | - 1340 | -Note that the parent of the entry being added must already exist or the 1341 | -parent must be empty (i.e., equal to the root DN) for an add to succeed. 1342 | - 1343 | -The ldap_add_ext() function initiates an asynchronous add operation and 1344 | -returns the constant LDAP_SUCCESS if the request was successfully sent, 1345 | -or another LDAP error code if not. See the section below on error han- 1346 | -dling for more information about possible errors and how to interpret 1347 | -them. If successful, ldap_add_ext() places the message id of the 1348 | -request in *msgidp. A subsequent call to ldap_result(), described below, 1349 | - 1350 | - 1351 | - 1352 | -Expires: January 1998 [Page 24] 1353 | - 1354 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 1355 | - 1356 | - 1357 | -can be used to obtain the result of the add. 1358 | - 1359 | -Similar to ldap_add_ext(), the ldap_add() function initiates an asyn- 1360 | -chronous add operation and returns the message id of the operation ini- 1361 | -tiated. As for ldap_add_ext(), a subsequent call to ldap_result(), 1362 | -described below, can be used to obtain the result of the add. In case of 1363 | -error, ldap_add() will return -1, setting the session error parameters 1364 | -in the LDAP structure appropriately. 1365 | - 1366 | -The synchronous ldap_add_ext_s() and ldap_add_s() functions both return 1367 | -the result of the operation, either the constant LDAP_SUCCESS if the 1368 | -operation was successful, or another LDAP error code if it was not. See 1369 | -the section below on error handling for more information about possible 1370 | -errors and how to interpret them. 1371 | - 1372 | -The ldap_add_ext() and ldap_add_ext_s() functions support LDAPv3 server 1373 | -controls and client controls. 1374 | - 1375 | - 1376 | - 1377 | -7.13. Deleting an entry 1378 | - 1379 | -The following functions are used to delete a leaf entry from the LDAP 1380 | -directory. There are four variations: 1381 | - 1382 | - int ldap_delete_ext( 1383 | - LDAP *ld, 1384 | - char *dn, 1385 | - LDAPControl **serverctrls, 1386 | - LDAPControl **clientctrls, 1387 | - int *msgidp 1388 | - ); 1389 | - 1390 | - int ldap_delete_ext_s( 1391 | - LDAP *ld, 1392 | - char *dn, 1393 | - LDAPControl **serverctrls, 1394 | - LDAPControl **clientctrls 1395 | - ); 1396 | - 1397 | - int ldap_delete( 1398 | - LDAP *ld, 1399 | - char *dn 1400 | - ); 1401 | - 1402 | - int ldap_delete_s( 1403 | - LDAP *ld, 1404 | - char *dn 1405 | - 1406 | - 1407 | - 1408 | -Expires: January 1998 [Page 25] 1409 | - 1410 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 1411 | - 1412 | - 1413 | - ); 1414 | - 1415 | -Parameters are: 1416 | - 1417 | -ld The session handle. 1418 | - 1419 | -dn The name of the entry to delete. 1420 | - 1421 | -serverctrls List of LDAP server controls. 1422 | - 1423 | -clientctrls List of client controls. 1424 | - 1425 | -msgidp This result parameter will be set to the message id of the 1426 | - request if the ldap_delete_ext() call succeeds. 1427 | - 1428 | -Note that the entry to delete must be a leaf entry (i.e., it must have 1429 | -no children). Deletion of entire subtrees in a single operation is not 1430 | -supported by LDAP. 1431 | - 1432 | -The ldap_delete_ext() function initiates an asynchronous delete opera- 1433 | -tion and returns the constant LDAP_SUCCESS if the request was success- 1434 | -fully sent, or another LDAP error code if not. See the section below on 1435 | -error handling for more information about possible errors and how to 1436 | -interpret them. If successful, ldap_delete_ext() places the message id 1437 | -of the request in *msgidp. A subsequent call to ldap_result(), described 1438 | -below, can be used to obtain the result of the delete. 1439 | - 1440 | -Similar to ldap_delete_ext(), the ldap_delete() function initiates an 1441 | -asynchronous delete operation and returns the message id of the opera- 1442 | -tion initiated. As for ldap_delete_ext(), a subsequent call to 1443 | -ldap_result(), described below, can be used to obtain the result of the 1444 | -delete. In case of error, ldap_delete() will return -1, setting the ses- 1445 | -sion error parameters in the LDAP structure appropriately. 1446 | - 1447 | -The synchronous ldap_delete_ext_s() and ldap_delete_s() functions both 1448 | -return the result of the operation, either the constant LDAP_SUCCESS if 1449 | -the operation was successful, or another LDAP error code if it was not. 1450 | -See the section below on error handling for more information about pos- 1451 | -sible errors and how to interpret them. 1452 | - 1453 | -The ldap_delete_ext() and ldap_delete_ext_s() functions support LDAPv3 1454 | -server controls and client controls. 1455 | - 1456 | - 1457 | -7.14. Extended Operations 1458 | - 1459 | -The ldap_extended_operation() and ldap_extended_operation_s() routines 1460 | -allow extended LDAP operations to be passed to the server, providing a 1461 | - 1462 | - 1463 | - 1464 | -Expires: January 1998 [Page 26] 1465 | - 1466 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 1467 | - 1468 | - 1469 | -general protocol extensibility mechanism. 1470 | - 1471 | - int ldap_extended_operation( 1472 | - LDAP *ld, 1473 | - char *exoid, 1474 | - struct berval *exdata, 1475 | - LDAPControl **serverctrls, 1476 | - LDAPControl **clientctrls, 1477 | - int *msgidp 1478 | - ); 1479 | - 1480 | - int ldap_extended_operation_s( 1481 | - LDAP *ld, 1482 | - char *exoid, 1483 | - struct berval *exdata, 1484 | - LDAPControl **serverctrls, 1485 | - LDAPControl **clientctrls, 1486 | - char **retoidp, 1487 | - struct berval **retdatap 1488 | - ); 1489 | - 1490 | -Parameters are: 1491 | - 1492 | -ld The session handle. 1493 | - 1494 | -requestoid The dotted-OID text string naming the request. 1495 | - 1496 | -requestdata The arbitrary data required by the operation (if NULL, no 1497 | - data is sent to the server). 1498 | - 1499 | -serverctrls List of LDAP server controls. 1500 | - 1501 | -clientctrls List of client controls. 1502 | - 1503 | -msgidp This result parameter will be set to the message id of the 1504 | - request if the ldap_extended_operation() call succeeds. 1505 | - 1506 | -retoidp Pointer to a character string that will be set to an allo- 1507 | - cated, dotted-OID text string returned by the server. This 1508 | - string should be disposed of using the ldap_memfree() func- 1509 | - tion. If no OID was returned, *retoidp is set to NULL. 1510 | - 1511 | -retdatap Pointer to a berval structure pointer that will be set an 1512 | - allocated copy of the data returned by the server. This 1513 | - struct berval should be disposed of using ber_bvfree(). If 1514 | - no data is returned, *retdatap is set to NULL. 1515 | - 1516 | -The ldap_extended_operation() function initiates an asynchronous 1517 | - 1518 | - 1519 | - 1520 | -Expires: January 1998 [Page 27] 1521 | - 1522 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 1523 | - 1524 | - 1525 | -extended operation and returns the constant LDAP_SUCCESS if the request 1526 | -was successfully sent, or another LDAP error code if not. See the sec- 1527 | -tion below on error handling for more information about possible errors 1528 | -and how to interpret them. If successful, ldap_extended_operation() 1529 | -places the message id of the request in *msgidp. A subsequent call to 1530 | -ldap_result(), described below, can be used to obtain the result of the 1531 | -extended operation which can be passed to ldap_parse_extended_result() 1532 | -to obtain the OID and data contained in the response. 1533 | - 1534 | -The synchronous ldap_extended_operation_s() function returns the result 1535 | -of the operation, either the constant LDAP_SUCCESS if the operation was 1536 | -successful, or another LDAP error code if it was not. See the section 1537 | -below on error handling for more information about possible errors and 1538 | -how to interpret them. The retoid and retdata parameters are filled in 1539 | -with the OID and data from the response. If no OID or data was 1540 | -returned, these parameters are set to NULL. 1541 | - 1542 | -The ldap_extended_operation() and ldap_extended_operation_s() functions 1543 | -both support LDAPv3 server controls and client controls. 1544 | - 1545 | - 1546 | -8. Abandoning An Operation 1547 | - 1548 | -The following calls are used to abandon an operation in progress: 1549 | - 1550 | - int ldap_abandon_ext( 1551 | - LDAP *ld, 1552 | - int msgid, 1553 | - LDAPControl **serverctrls, 1554 | - LDAPControl **clientctrls 1555 | - ); 1556 | - 1557 | - int ldap_abandon( 1558 | - LDAP *ld, 1559 | - int msgid 1560 | - ); 1561 | - 1562 | - 1563 | -ld The session handle. 1564 | - 1565 | -msgid The message id of the request to be abandoned. 1566 | - 1567 | -serverctrls List of LDAP server controls. 1568 | - 1569 | -clientctrls List of client controls. 1570 | - 1571 | -ldap_abandon_ext() abandons the operation with message id msgid and 1572 | -returns the constant LDAP_SUCCESS if the abandon was successful or 1573 | - 1574 | - 1575 | - 1576 | -Expires: January 1998 [Page 28] 1577 | - 1578 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 1579 | - 1580 | - 1581 | -another LDAP error code if not. See the section below on error handling 1582 | -for more information about possible errors and how to interpret them. 1583 | - 1584 | -ldap_abandon() is identical to ldap_abandon_ext() except that it returns 1585 | -zero if the abandon was successful, -1 otherwise and does not support 1586 | -LDAPv3 server controls or client controls. 1587 | - 1588 | -After a successful call to ldap_abandon() or ldap_abandon_ext(), results 1589 | -with the given message id are never returned from a subsequent call to 1590 | -ldap_result(). There is no server response to LDAP abandon operations. 1591 | - 1592 | - 1593 | -9. Obtaining Results and Peeking Inside LDAP Messages 1594 | - 1595 | -ldap_result() is used to obtain the result of a previous asynchronously 1596 | -initiated operation. Note that depending on how it is called, 1597 | -ldap_result() may actually return a list or "chain" of messages. 1598 | - 1599 | -ldap_msgfree() frees the results obtained from a previous call to 1600 | -ldap_result(), or a synchronous search routine. 1601 | - 1602 | -ldap_msgtype() returns the type of an LDAP message. ldap_msgid() 1603 | -returns the message ID of an LDAP message. 1604 | - 1605 | - int ldap_result( 1606 | - LDAP *ld, 1607 | - int msgid, 1608 | - int all, 1609 | - struct timeval *timeout, 1610 | - LDAPMessage **res 1611 | - ); 1612 | - 1613 | - int ldap_msgfree( LDAPMessage *res ); 1614 | - 1615 | - int ldap_msgtype( LDAPMessage *res ); 1616 | - 1617 | - int ldap_msgid( LDAPMessage *res ); 1618 | - 1619 | -Parameters are: 1620 | - 1621 | -ld The session handle. 1622 | - 1623 | -msgid The message id of the operation whose results are to be 1624 | - returned, or the constant LDAP_RES_ANY (-1) if any result is 1625 | - desired. 1626 | - 1627 | -all Specifies how many messages will be retrieved in a single call 1628 | - to ldap_result(). This parameter only has meaning for search 1629 | - 1630 | - 1631 | - 1632 | -Expires: January 1998 [Page 29] 1633 | - 1634 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 1635 | - 1636 | - 1637 | - results. Pass the constant LDAP_MSG_ONE (0x00) to retrieve one 1638 | - message at a time. Pass LDAP_MSG_ALL (0x01) to request that 1639 | - all results of a search be received before returning all 1640 | - results in a single chain. Pass LDAP_MSG_RECEIVED (0x02) to 1641 | - indicate that all results retrieved so far should be returned 1642 | - in the result chain. 1643 | - 1644 | -timeout A timeout specifying how long to wait for results to be 1645 | - returned. A NULL value causes ldap_result() to block until 1646 | - results are available. A timeout value of zero seconds speci- 1647 | - fies a polling behavior. 1648 | - 1649 | -res For ldap_result(), a result parameter that will contain the 1650 | - result(s) of the operation. For ldap_msgfree(), the result 1651 | - chain to be freed, obtained from a previous call to 1652 | - ldap_result(), ldap_search_s(), or ldap_search_st(). 1653 | - 1654 | -Upon successful completion, ldap_result() returns the type of the first 1655 | -result returned in the res parameter. This will be one of the following 1656 | -constants. 1657 | - 1658 | - LDAP_RES_BIND (0x61) 1659 | - LDAP_RES_SEARCH_ENTRY (0x64) 1660 | - LDAP_RES_SEARCH_REFERENCE (0x73) -- new in LDAPv3 1661 | - LDAP_RES_SEARCH_RESULT (0x65) 1662 | - LDAP_RES_MODIFY (0x67) 1663 | - LDAP_RES_ADD (0x69) 1664 | - LDAP_RES_DELETE (0x6B) 1665 | - LDAP_RES_MODDN (0x6D) 1666 | - LDAP_RES_COMPARE (0x6F) 1667 | - LDAP_RES_EXTENDED (0x78) -- new in LDAPv3 1668 | - 1669 | -ldap_result() returns 0 if the timeout expired and -1 if an error 1670 | -occurs, in which case the error parameters of the LDAP session handle 1671 | -will be set accordingly. 1672 | - 1673 | -ldap_msgfree() frees the result structure pointed to by res and returns 1674 | -the type of the message it freed. 1675 | - 1676 | -ldap_msgtype() returns the type of the LDAP message it is passed as a 1677 | -parameter. The type will be one of the types listed above, or -1 on 1678 | -error. 1679 | - 1680 | -ldap_msgid() returns the message ID associated with the LDAP message 1681 | -passed as a parameter. 1682 | - 1683 | - 1684 | - 1685 | - 1686 | - 1687 | - 1688 | -Expires: January 1998 [Page 30] 1689 | - 1690 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 1691 | - 1692 | - 1693 | -10. Handling Errors and Parsing Results 1694 | - 1695 | -The following calls are used to extract information from results and 1696 | -handle errors returned by other LDAP API routines. 1697 | - 1698 | - int ldap_parse_result( 1699 | - LDAP *ld, 1700 | - LDAPMessage *res, 1701 | - int *errcodep, 1702 | - char **matcheddnp, 1703 | - char **errmsgp, 1704 | - char ***referralsp, 1705 | - LDAPControl ***serverctrlsp, 1706 | - int freeit 1707 | - ); 1708 | - 1709 | - int ldap_parse_sasl_bind_result( 1710 | - LDAP *ld, 1711 | - LDAPMessage *res, 1712 | - struct berval **servercredp, 1713 | - int freeit 1714 | - ); 1715 | - 1716 | - int ldap_parse_extended_result( 1717 | - LDAP *ld, 1718 | - LDAPMessage *res, 1719 | - char **resultoidp, 1720 | - struct berval **resultdata, 1721 | - int freeit 1722 | - ); 1723 | - 1724 | - char *ldap_err2string( int err ); 1725 | - 1726 | - The use of the following routines is deprecated. 1727 | - 1728 | - int ldap_result2error( 1729 | - LDAP *ld, 1730 | - LDAPMessage *res, 1731 | - int freeit 1732 | - ); 1733 | - 1734 | - void ldap_perror( LDAP *ld, char *msg ); 1735 | - 1736 | -Parameters are: 1737 | - 1738 | -ld The session handle. 1739 | - 1740 | -res The result of an LDAP operation as returned by 1741 | - 1742 | - 1743 | - 1744 | -Expires: January 1998 [Page 31] 1745 | - 1746 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 1747 | - 1748 | - 1749 | - ldap_result() or one of the synchronous API operation 1750 | - calls. 1751 | - 1752 | -errcodep This result parameter will be filled in with the LDAP error 1753 | - code field from the LDAPResult message. This is the indi- 1754 | - cation from the server of the outcome of the operation. 1755 | - NULL may be passed to ignore this field. 1756 | - 1757 | -matcheddnp In the case of a return of LDAP_NO_SUCH_OBJECT, this result 1758 | - parameter will be filled in with a DN indicating how much 1759 | - of the name in the request was recognized. NULL may be 1760 | - passed to ignore this field. The matched DN string should 1761 | - be freed by calling ldap_memfree() which is described later 1762 | - in this document. 1763 | - 1764 | -errmsgp This result parameter will be filled in with the contents 1765 | - of the error message field from the LDAPResult message. 1766 | - The error message string should be freed by calling 1767 | - ldap_memfree() which is described later in this document. 1768 | - NULL may be passed to ignore this field. 1769 | - 1770 | -referralsp This result parameter will be filled in with the contents 1771 | - of the referrals field from the LDAPResult message, indi- 1772 | - cating zero or more alternate LDAP servers where the 1773 | - request should be retried. The referrals array should be 1774 | - freed by calling ldap_value_free() which is described later 1775 | - in this document. NULL may be passed to ignore this field. 1776 | - 1777 | -serverctrlsp This result parameter will be filled in with an allocated 1778 | - array of controls copied out of the LDAPResult message. 1779 | - The control array should be freed by calling 1780 | - ldap_controls_free() which was described earlier. 1781 | - 1782 | -freeit A boolean that determines whether the res parameter is 1783 | - disposed of or not. Pass any non-zero value to have these 1784 | - routines free res after extracting the requested informa- 1785 | - tion. This is provided as a convenience; you can also use 1786 | - ldap_msgfree() to free the result later. 1787 | - 1788 | -servercredp For SASL bind results, this result parameter will be filled 1789 | - in with the credentials passed back by the server for 1790 | - mutual authentication, if given. An allocated berval struc- 1791 | - ture is returned that should be disposed of by calling 1792 | - ldap_ber_free(). NULL may be passed to ignore this field. 1793 | - 1794 | -resultoidp For extended results, this result parameter will be filled 1795 | - in with the dotted-OID text representation of the name of 1796 | - the extended operation response. This string should be 1797 | - 1798 | - 1799 | - 1800 | -Expires: January 1998 [Page 32] 1801 | - 1802 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 1803 | - 1804 | - 1805 | - disposed of by calling ldap_memfree(). NULL may be passed 1806 | - to ignore this field. 1807 | - 1808 | -resultdatap For extended results, this result parameter will be filled 1809 | - in with a pointer to a struct berval containing the data in 1810 | - the extended operation response. It should be disposed of 1811 | - by calling ldap_ber_free(). NULL may be passed to ignore 1812 | - this field. 1813 | - 1814 | -err For ldap_err2string(), an LDAP error code, as returned by 1815 | - ldap_result2error() or another LDAP API call. 1816 | - 1817 | -Additional parameters for the deprecated routines are not described. 1818 | -Interested readers are referred to RFC 1823. 1819 | - 1820 | -All of the ldap_parse_*_result() routines skip over messages of type 1821 | -LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_REFERENCE when looking for a 1822 | -result message to parse. They return the constant LDAP_SUCCESS if the 1823 | -result was successfully parsed and another LDAP error code if not. Note 1824 | -that the LDAP error code that indicates the outcome of the operation 1825 | -performed by the server is placed in the errcodep ldap_parse_result() 1826 | -parameter. 1827 | - 1828 | -ldap_err2string() is used to convert a numeric LDAP error code, as 1829 | -returned by one of the ldap_parse_*_result() routines, or one of the 1830 | -synchronous API operation calls, into an informative NULL-terminated 1831 | -character string message describing the error. It returns a pointer to 1832 | -static data. 1833 | - 1834 | - 1835 | -11. Stepping Through a List of Results 1836 | - 1837 | -The ldap_first_message() and ldap_next_message() routines are used to 1838 | -step through the list of messages in a result chain returned by 1839 | -ldap_result(). For search operations, the result chain may actually 1840 | -include referral messages, entry messages, and result messages. 1841 | -ldap_count_messages() is used to count the number of messages returned. 1842 | -The ldap_msgtype() function, described above, can be used to distinguish 1843 | -between the different message types. 1844 | - 1845 | - LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *res ); 1846 | - 1847 | - LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *msg ); 1848 | - 1849 | - int ldap_count_messages( LDAP *ld, LDAPMessage *res ); 1850 | - 1851 | -Parameters are: 1852 | - 1853 | - 1854 | - 1855 | - 1856 | -Expires: January 1998 [Page 33] 1857 | - 1858 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 1859 | - 1860 | - 1861 | -ld The session handle. 1862 | - 1863 | -res The result chain, as obtained by a call to one of the synchronous 1864 | - search routines or ldap_result(). 1865 | - 1866 | -msg The message returned by a previous call to ldap_first_message() 1867 | - or ldap_next_message(). 1868 | - 1869 | -ldap_first_message() and ldap_next_message() will return NULL when no 1870 | -more messages exist in the result set to be returned. NULL is also 1871 | -returned if an error occurs while stepping through the entries, in which 1872 | -case the error parameters in the session handle ld will be set to indi- 1873 | -cate the error. 1874 | - 1875 | -ldap_count_messages() returns the number of messages contained in a 1876 | -chain of results. It can also be used to count the number of messages 1877 | -that remain in a chain if called with a message, entry, or reference 1878 | -returned by ldap_first_message(), ldap_next_message(), 1879 | -ldap_first_entry(), ldap_next_entry(), ldap_first_reference(), 1880 | -ldap_next_reference(). 1881 | - 1882 | - 1883 | -12. Parsing Search Results 1884 | - 1885 | -The following calls are used to parse the entries and references 1886 | -returned by ldap_search() and friends. These results are returned in an 1887 | -opaque structure that should only be accessed by calling the routines 1888 | -described below. Routines are provided to step through the entries and 1889 | -references returned, step through the attributes of an entry, retrieve 1890 | -the name of an entry, and retrieve the values associated with a given 1891 | -attribute in an entry. 1892 | - 1893 | - 1894 | -12.1. Stepping Through a List of Entries 1895 | - 1896 | -The ldap_first_entry() and ldap_next_entry() routines are used to step 1897 | -through and retrieve the list of entries from a search result chain. 1898 | -The ldap_first_reference() and ldap_next_reference() routines are used 1899 | -to step through and retrieve the list of continuation references from a 1900 | -search result chain. ldap_count_entries() is used to count the number 1901 | -of entries returned. ldap_count_references() is used to count the number 1902 | -of references returned. 1903 | - 1904 | - LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *res ); 1905 | - 1906 | - LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry ); 1907 | - 1908 | - LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *res ); 1909 | - 1910 | - 1911 | - 1912 | -Expires: January 1998 [Page 34] 1913 | - 1914 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 1915 | - 1916 | - 1917 | - LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *ref ); 1918 | - 1919 | - int ldap_count_entries( LDAP *ld, LDAPMessage *res ); 1920 | - 1921 | - int ldap_count_references( LDAP *ld, LDAPMessage *res ); 1922 | - 1923 | -Parameters are: 1924 | - 1925 | -ld The session handle. 1926 | - 1927 | -res The search result, as obtained by a call to one of the synchro- 1928 | - nous search routines or ldap_result(). 1929 | - 1930 | -entry The entry returned by a previous call to ldap_first_entry() or 1931 | - ldap_next_entry(). 1932 | - 1933 | -ldap_first_entry() and ldap_next_entry() will return NULL when no more 1934 | -entries or references exist in the result set to be returned. NULL is 1935 | -also returned if an error occurs while stepping through the entries, in 1936 | -which case the error parameters in the session handle ld will be set to 1937 | -indicate the error. 1938 | - 1939 | -ldap_count_entries() returns the number of entries contained in a chain 1940 | -of entries. It can also be used to count the number of entries that 1941 | -remain in a chain if called with a message, entry or reference returned 1942 | -by ldap_first_message(), ldap_next_message(), ldap_first_entry(), 1943 | -ldap_next_entry(), ldap_first_reference(), ldap_next_reference(). 1944 | - 1945 | -ldap_count_references() returns the number of references contained in a 1946 | -chain of search results. It can also be used to count the number of 1947 | -references that remain in a chain. 1948 | - 1949 | - 1950 | -12.2. Stepping Through the Attributes of an Entry 1951 | - 1952 | -The ldap_first_attribute() and ldap_next_attribute() calls are used to 1953 | -step through the list of attribute types returned with an entry. 1954 | - 1955 | - char *ldap_first_attribute( 1956 | - LDAP *ld, 1957 | - LDAPMessage *entry, 1958 | - BerElement **ptr 1959 | - ); 1960 | - 1961 | - char *ldap_next_attribute( 1962 | - LDAP *ld, 1963 | - LDAPMessage *entry, 1964 | - BerElement *ptr 1965 | - 1966 | - 1967 | - 1968 | -Expires: January 1998 [Page 35] 1969 | - 1970 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 1971 | - 1972 | - 1973 | - ); 1974 | - 1975 | - void ldap_memfree( char *mem ); 1976 | - 1977 | -Parameters are: 1978 | - 1979 | -ld The session handle. 1980 | - 1981 | -entry The entry whose attributes are to be stepped through, as returned 1982 | - by ldap_first_entry() or ldap_next_entry(). 1983 | - 1984 | -ptr In ldap_first_attribute(), the address of a pointer used inter- 1985 | - nally to keep track of the current position in the entry. In 1986 | - ldap_next_attribute(), the pointer returned by a previous call to 1987 | - ldap_first_attribute(). 1988 | - 1989 | -mem A pointer to memory allocated by the LDAP library, such as the 1990 | - attribute names returned by ldap_first_attribute() and 1991 | - ldap_next_attribute, or the DN returned by ldap_get_dn(). 1992 | - 1993 | -ldap_first_attribute() and ldap_next_attribute() will return NULL when 1994 | -the end of the attributes is reached, or if there is an error, in which 1995 | -case the error parameters in the session handle ld will be set to indi- 1996 | -cate the error. 1997 | - 1998 | -Both routines return a pointer to an allocated buffer containing the 1999 | -current attribute name. This should be freed when no longer in use by 2000 | -calling ldap_memfree(). 2001 | - 2002 | -ldap_first_attribute() will allocate and return in ptr a pointer to a 2003 | -BerElement used to keep track of the current position. This pointer 2004 | -should be passed in subsequent calls to ldap_next_attribute() to step 2005 | -through the entry's attributes. After a set of calls to 2006 | -ldap_first_attribute() and ldap_next_attibute(), if ptr is non-NULL, it 2007 | -should be freed by calling ldap_ber_free( ptr, 0 ). Note that it is very 2008 | -important to pass the second parameter as 0 (zero) in this call. 2009 | - 2010 | -The attribute names returned are suitable for passing in a call to 2011 | -ldap_get_values() and friends to retrieve the associated values. 2012 | - 2013 | - 2014 | -12.3. Retrieving the Values of an Attribute 2015 | - 2016 | -ldap_get_values() and ldap_get_values_len() are used to retrieve the 2017 | -values of a given attribute from an entry. ldap_count_values() and 2018 | -ldap_count_values_len() are used to count the returned values. 2019 | -ldap_value_free() and ldap_value_free_len() are used to free the values. 2020 | - 2021 | - 2022 | - 2023 | - 2024 | -Expires: January 1998 [Page 36] 2025 | - 2026 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 2027 | - 2028 | - 2029 | - char **ldap_get_values( 2030 | - LDAP *ld, 2031 | - LDAPMessage *entry, 2032 | - char *attr 2033 | - ); 2034 | - 2035 | - struct berval **ldap_get_values_len( 2036 | - LDAP *ld, 2037 | - LDAPMessage *entry, 2038 | - char *attr 2039 | - ); 2040 | - 2041 | - int ldap_count_values( char **vals ); 2042 | - 2043 | - int ldap_count_values_len( struct berval **vals ); 2044 | - 2045 | - int ldap_value_free( char **vals ); 2046 | - 2047 | - int ldap_value_free_len( struct berval **vals ); 2048 | - 2049 | -Parameters are: 2050 | - 2051 | -ld The session handle. 2052 | - 2053 | -entry The entry from which to retrieve values, as returned by 2054 | - ldap_first_entry() or ldap_next_entry(). 2055 | - 2056 | -attr The attribute whose values are to be retrieved, as returned by 2057 | - ldap_first_attribute() or ldap_next_attribute(), or a caller- 2058 | - supplied string (e.g., "mail"). 2059 | - 2060 | -vals The values returned by a previous call to ldap_get_values() or 2061 | - ldap_get_values_len(). 2062 | - 2063 | -Two forms of the various calls are provided. The first form is only 2064 | -suitable for use with non-binary character string data. The second _len 2065 | -form is used with any kind of data. 2066 | - 2067 | -Note that the values returned are dynamically allocated and should be 2068 | -freed by calling either ldap_value_free() or ldap_value_free_len() when 2069 | -no longer in use. 2070 | - 2071 | - 2072 | -12.4. Retrieving the name of an entry 2073 | - 2074 | -ldap_get_dn() is used to retrieve the name of an entry. 2075 | -ldap_explode_dn() and ldap_explode_rdn() are used to break up a name 2076 | -into its component parts. ldap_dn2ufn() is used to convert the name into 2077 | - 2078 | - 2079 | - 2080 | -Expires: January 1998 [Page 37] 2081 | - 2082 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 2083 | - 2084 | - 2085 | -a more "user friendly" format. 2086 | - 2087 | - char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ); 2088 | - 2089 | - char **ldap_explode_dn( char *dn, int notypes ); 2090 | - 2091 | - char **ldap_explode_rdn( char *rdn, int notypes ); 2092 | - 2093 | - char *ldap_dn2ufn( char *dn ); 2094 | - 2095 | -Parameters are: 2096 | - 2097 | -ld The session handle. 2098 | - 2099 | -entry The entry whose name is to be retrieved, as returned by 2100 | - ldap_first_entry() or ldap_next_entry(). 2101 | - 2102 | -dn The dn to explode, such as returned by ldap_get_dn(). 2103 | - 2104 | -rdn The rdn to explode, such as returned in the components of the 2105 | - array returned by ldap_explode_dn(). 2106 | - 2107 | -notypes A boolean parameter, if non-zero indicating that the dn or rdn 2108 | - components should have their type information stripped off 2109 | - (i.e., "cn=Babs" would become "Babs"). 2110 | - 2111 | -ldap_get_dn() will return NULL if there is some error parsing the dn, 2112 | -setting error parameters in the session handle ld to indicate the error. 2113 | -It returns a pointer to malloc'ed space that the caller should free by 2114 | -calling ldap_memfree() when it is no longer in use. Note the format of 2115 | -the DNs returned is given by [4]. 2116 | - 2117 | -ldap_explode_dn() returns a NULL-terminated char * array containing the 2118 | -RDN components of the DN supplied, with or without types as indicated by 2119 | -the notypes parameter. The array returned should be freed when it is no 2120 | -longer in use by calling ldap_value_free(). 2121 | - 2122 | -ldap_explode_rdn() returns a NULL-terminated char * array containing the 2123 | -components of the RDN supplied, with or without types as indicated by 2124 | -the notypes parameter. The array returned should be freed when it is no 2125 | -longer in use by calling ldap_value_free(). 2126 | - 2127 | -ldap_dn2ufn() converts the DN into the user friendly format described in 2128 | -[5]. The UFN returned is malloc'ed space that should be freed by a call 2129 | -to ldap_memfree() when no longer in use. 2130 | - 2131 | - 2132 | - 2133 | - 2134 | - 2135 | - 2136 | -Expires: January 1998 [Page 38] 2137 | - 2138 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 2139 | - 2140 | - 2141 | -13. Encoded ASN.1 Value Manipulation 2142 | - 2143 | -This section describes routines which may be used to encode and decode 2144 | -BER-encoded ASN.1 values, which are often used inside of control and 2145 | -extension values. 2146 | - 2147 | -With the exceptions of two new functions ber_flatten() and ber_init(), 2148 | -these functions are compatible with the University of Michigan LDAP 3.3 2149 | -implementation of BER. 2150 | - 2151 | - 2152 | -13.1. General 2153 | - 2154 | - struct berval { 2155 | - unsigned long bv_len; 2156 | - char *bv_val; 2157 | - }; 2158 | - 2159 | -A struct berval contains a sequence of bytes and an indication of its 2160 | -length. The bv_val is not null terminated. bv_len must always be a 2161 | -nonnegative number. Applications may allocate their own berval struc- 2162 | -tures. 2163 | - 2164 | - typedef struct berelement { 2165 | - /* opaque */ 2166 | - } BerElement; 2167 | - 2168 | -The BerElement structure contains not only a copy of the encoded value, 2169 | -but also state information used in encoding or decoding. Applications 2170 | -cannot allocate their own BerElement structures. The internal state is 2171 | -neither thread-specific nor locked, so two threads should not manipulate 2172 | -the same BerElement value simultaneously. 2173 | - 2174 | -A single BerElement value cannot be used for both encoding and decoding. 2175 | - 2176 | - void ber_bvfree ( struct berval *bv); 2177 | - 2178 | -ber_bvfree() frees a berval returned from this API. Both the bv->bv_val 2179 | -string and the berval itself are freed. Applications should not use 2180 | -ber_bvfree() with bervals which the application has allocated. 2181 | - 2182 | - void ber_bvecfree ( struct berval **bv ); 2183 | - 2184 | -ber_bvecfree() frees an array of bervals returned from this API. Each 2185 | -of the bervals in the array are freed using ber_bvfree(), then the array 2186 | -itself is freed. 2187 | - 2188 | - struct berval *ber_bvdup (struct berval *bv ); 2189 | - 2190 | - 2191 | - 2192 | -Expires: January 1998 [Page 39] 2193 | - 2194 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 2195 | - 2196 | - 2197 | -ber_bvdup() returns a copy of a berval. The bv_val field in the 2198 | -returned berval points to a different area of memory as the bv_val field 2199 | -in the argument berval. The null pointer is returned on error (e.g. out 2200 | -of memory). 2201 | - 2202 | - void ber_free ( BerElement *ber, int fbuf ); 2203 | - 2204 | -ber_free() frees a BerElement which is returned from the API calls 2205 | -ber_alloc_t() or ber_init(). Each BerElement must be freed by the 2206 | -caller. The second argument fbuf should always be set to 1. 2207 | - 2208 | - 2209 | -13.2. Encoding 2210 | - 2211 | - BerElement *ber_alloc_t(int options); 2212 | - 2213 | -ber_alloc_t() constructs and returns BerElement. The null pointer is 2214 | -returned on error. The options field contains a bitwise-or of options 2215 | -which are to be used when generating the encoding of this BerElement. 2216 | -One option is defined and must always be supplied: 2217 | - 2218 | - #define LBER_USE_DER 0x01 2219 | - 2220 | -When this option is present, lengths will always be encoded in the 2221 | -minimum number of octets. Note that this option does not cause values 2222 | -of sets and sequences to be rearranged in tag and byte order, so these 2223 | -functions are not suitable for generating DER output as defined in X.509 2224 | -and X.680. 2225 | - 2226 | -Unrecognized option bits are ignored. 2227 | - 2228 | -The BerElement returned by ber_alloc_t() is initially empty. Calls to 2229 | -ber_printf() will append bytes to the end of the ber_alloc_t(). 2230 | - 2231 | - int ber_printf(BerElement *ber, char *fmt, ... ) 2232 | - 2233 | -The ber_printf() routine is used to encode a BER element in much the 2234 | -same way that sprintf() works. One important difference, though, is 2235 | -that state information is kept in the ber argument so that multiple 2236 | -calls can be made to ber_printf() to append to the end of the BER ele- 2237 | -ment. ber must be a pointer to a BerElement returned by ber_alloc_t(). 2238 | -ber_printf() interprets and formats its arguments according to the for- 2239 | -mat string fmt. ber_printf() returns -1 if there is an error during 2240 | -encoding. As with sprintf(), each character in fmt refers to an argu- 2241 | -ment to ber_printf(). 2242 | - 2243 | -The format string can contain the following format characters: 2244 | - 2245 | - 2246 | - 2247 | - 2248 | -Expires: January 1998 [Page 40] 2249 | - 2250 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 2251 | - 2252 | - 2253 | -'t' Tag. The next argument is an int specifying the tag to override 2254 | - the next element to be written to the ber. This works across 2255 | - calls. The int value must contain the tag class, constructed 2256 | - bit, and tag value. The tag value must fit in a single octet 2257 | - (tag value is less than 32). For example, a tag of "[3]" for a 2258 | - constructed type is 0xA3. 2259 | - 2260 | -'b' Boolean. The next argument is an int, containing either 0 for 2261 | - FALSE or 0xff for TRUE. A boolean element is output. If this 2262 | - format character is not preceded by the 't' format modifier, the 2263 | - tag 0x01 is used for the element. 2264 | - 2265 | -'i' Integer. The next argument is an int, containing the integer in 2266 | - the host's byte order. An integer element is output. If this 2267 | - format character is not preceded by the 't' format modifier, the 2268 | - tag 0x02 is used for the element. 2269 | - 2270 | -'X' Bitstring. The next two arguments are a char * pointer to the 2271 | - start of the bitstring, followed by an int containing the number 2272 | - of bits in the bitstring. A bitstring element is output, in 2273 | - primitive form. If this format character is not preceded by the 2274 | - 't' format modifier, the tag 0x03 is used for the element. 2275 | - 2276 | -'n' Null. No argument is required. An ASN.1 NULL element is out- 2277 | - put. If this format character is not preceded by the 't' format 2278 | - modifier, the tag 0x05 is used for the element. 2279 | - 2280 | -'o' Octet string. The next two arguments are a char *, followed by 2281 | - an int with the length of the string. The string may contain 2282 | - null bytes and need not by null-terminated. An octet string 2283 | - element is output, in primitive form. If this format character 2284 | - is not preceded by the 't' format modifier, the tag 0x04 is used 2285 | - for the element. 2286 | - 2287 | -'s' Octet string. The next argument is a char * pointing to a 2288 | - null-terminated string. An octet string element in primitive 2289 | - form is output, which does not include the trailing ' ' byte. If 2290 | - this format character is not preceded by the 't' format modif- 2291 | - ier, the tag 0x04 is used for the element. 2292 | - 2293 | -'v' Several octet strings. The next argument is a char **, an array 2294 | - of char * pointers to null-terminated strings. The last element 2295 | - in the array must be a null pointer. The octet strings do not 2296 | - include the trailing SEQUENCE OF octet strings. The 't' format 2297 | - modifier cannot be used with this format character. 2298 | - 2299 | -'V' Several octet strings. A null-terminated array of berval *'s is 2300 | - supplied. Note that a construct like '{V}' is required to get an 2301 | - 2302 | - 2303 | - 2304 | -Expires: January 1998 [Page 41] 2305 | - 2306 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 2307 | - 2308 | - 2309 | - actual SEQUENCE OF octet strings. The 't' format modifier cannot 2310 | - be used with this format character. 2311 | - 2312 | -'{' Begin sequence. No argument is required. If this format char- 2313 | - acter is not preceded by the 't' format modifier, the tag 0x30 2314 | - is used. 2315 | - 2316 | -'}' End sequence. No argument is required. The 't' format modifier 2317 | - cannot be used with this format character. 2318 | - 2319 | -'[' Begin set. No argument is required. If this format character 2320 | - is not preceded by the 't' format modifier, the tag 0x31 is 2321 | - used. 2322 | - 2323 | -']' End set. No argument is required. The 't' format modifier can- 2324 | - not be used with this format character. 2325 | - 2326 | -Each use of a '{' format character must be matched by a '}' character, 2327 | -either later in the format string, or in the format string of a subse- 2328 | -quent call to ber_printf() for that BerElement. The same applies to the 2329 | -'[' and 2330 | - 2331 | -Sequences and sets nest, and implementations of this API must maintain 2332 | -internal state to be able to properly calculate the lengths. 2333 | - 2334 | - int ber_flatten (BerElement *ber, struct berval **bvPtr); 2335 | - 2336 | -The ber_flatten routine allocates a struct berval whose contents are a 2337 | -BER encoding taken from the ber argument. The bvPtr pointer points to 2338 | -the returned berval, which must be freed using ber_bvfree(). This rou- 2339 | -tine returns 0 on success and -1 on error. 2340 | - 2341 | -The ber_flatten API call is not present in U-M LDAP 3.3. 2342 | - 2343 | -The use of ber_flatten on a BerElement in which all '{' and '}' format 2344 | -modifiers have not been properly matched can result in a berval whose 2345 | -contents are not a valid BER encoding. 2346 | - 2347 | - 2348 | -13.3. Encoding Example 2349 | - 2350 | -The following is an example of encoding the following ASN.1 data type: 2351 | - 2352 | - Example1Request ::= SEQUENCE { 2353 | - s OCTET STRING, -- must be printable 2354 | - val1 INTEGER, 2355 | - val2 [0] INTEGER DEFAULT 0 2356 | - } 2357 | - 2358 | - 2359 | - 2360 | -Expires: January 1998 [Page 42] 2361 | - 2362 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 2363 | - 2364 | - 2365 | - int encode_example1(char *s,int val1,int val2,struct berval **bvPtr) 2366 | - { 2367 | - BerElement *ber; 2368 | - int rc; 2369 | - 2370 | - ber = ber_alloc_t(LBER_USE_DER); 2371 | - 2372 | - if (ber == NULL) return -1; 2373 | - 2374 | - if (ber_printf(ber,"{si",s,val1) == -1) { 2375 | - ber_free(ber,1); 2376 | - return -1; 2377 | - } 2378 | - 2379 | - if (val2 != 0) { 2380 | - if (ber_printf(ber,"ti",0x80,val2) == -1) { 2381 | - ber_free(ber,1); 2382 | - return -1; 2383 | - } 2384 | - } 2385 | - 2386 | - if (ber_printf(ber,"}") == -1) { 2387 | - ber_free(ber,1); 2388 | - return -1; 2389 | - } 2390 | - 2391 | - rc = ber_flatten(ber,bvPtr); 2392 | - ber_free(ber,1); 2393 | - return -1; 2394 | - } 2395 | - 2396 | - 2397 | -13.4. Decoding 2398 | - 2399 | -The following two symbols are available to applications. 2400 | - 2401 | - #define LBER_ERROR 0xffffffffL 2402 | - #define LBER_DEFAULT 0xffffffffL 2403 | - 2404 | - BerElement *ber_init (struct berval *bv); 2405 | - 2406 | -The ber_init functions construct BerElement and returns a new BerElement 2407 | -containing a copy of the data in the bv argument. ber_init returns the 2408 | -null pointer on error. 2409 | - 2410 | - unsigned long ber_scanf (BerElement *ber, char *fmt, ... ); 2411 | - 2412 | -The ber_scanf() routine is used to decode a BER element in much the same 2413 | - 2414 | - 2415 | - 2416 | -Expires: January 1998 [Page 43] 2417 | - 2418 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 2419 | - 2420 | - 2421 | -way that sscanf() works. One important difference, though, is that some 2422 | -state information is kept with the ber argument so that multiple calls 2423 | -can be made to ber_scanf() to sequentially read from the BER element. 2424 | -The ber argument must be a pointer to a BerElement returned by 2425 | -ber_init(). ber_scanf interprets the bytes according to the format 2426 | -string fmt, and stores the results in its additional arguments. 2427 | -ber_scanf() returns LBER_ERROR on error, and a nonnegative number on 2428 | -success. 2429 | - 2430 | -The format string contains conversion specifications which are used to 2431 | -direct the interpretation of the BER element. The format string can 2432 | -contain the following characters: 2433 | - 2434 | -'a' Octet string. A char ** argument should be supplied. Memory is 2435 | - allocated, filled with the contents of the octet string, null- 2436 | - terminated, and the pointer to the string is stored in the argu- 2437 | - ment. The returned value must be freed using ldap_memfree. The 2438 | - tag of the element must indicate the primitive form (constructed 2439 | - strings are not supported) but is otherwise ignored and dis- 2440 | - carded during the decoding. This format cannot be used with 2441 | - octet strings which could contain null bytes. 2442 | - 2443 | -'O' Octet string. A struct berval ** argument should be supplied, 2444 | - which upon return points to a allocated struct berval containing 2445 | - the octet string and its length. ber_bvfree() must be called to 2446 | - free the allocated memory. The tag of the element must indicate 2447 | - the primitive form (constructed strings are not supported) but 2448 | - is otherwise ignored during the decoding. 2449 | - 2450 | -'b' Boolean. A pointer to an int should be supplied. The int value 2451 | - stored will be 0 for FALSE or nonzero for TRUE. The tag of the 2452 | - element must indicate the primitive form but is otherwise 2453 | - ignored during the decoding. 2454 | - 2455 | -'i' Integer. A pointer to an int should be supplied. The int value 2456 | - stored will be in host byte order. The tag of the element must 2457 | - indicate the primitive form but is otherwise ignored during the 2458 | - decoding. ber_scanf() will return an error if the integer can- 2459 | - not be stored in an int. 2460 | - 2461 | -'B' Bitstring. A char ** argument should be supplied which will 2462 | - point to the allocated bits, followed by an unsigned long * 2463 | - argument, which will point to the length (in bits) of the bit- 2464 | - string returned. ldap_memfree must be called to free the bit- 2465 | - string. The tag of the element must indicate the primitive form 2466 | - (constructed bitstrings are not supported) but is otherwise 2467 | - ignored during the decoding. 2468 | - 2469 | - 2470 | - 2471 | - 2472 | -Expires: January 1998 [Page 44] 2473 | - 2474 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 2475 | - 2476 | - 2477 | -'n' Null. No argument is required. The element is simply skipped 2478 | - if it is recognized as a zero-length element. The tag is 2479 | - ignored. 2480 | - 2481 | -'v' Several octet strings. A char *** argument should be supplied, 2482 | - which upon return points to a allocated null-terminated array of 2483 | - char *'s containing the octet strings. NULL is stored if the 2484 | - sequence is empty. ldap_memfree must be called to free each 2485 | - element of the array and the array itself. The tag of the 2486 | - sequence and of the octet strings are ignored. 2487 | - 2488 | -'V' Several octet strings (which could contain null bytes). A 2489 | - struct berval *** should be supplied, which upon return points 2490 | - to a allocated null-terminated array of struct berval *'s con- 2491 | - taining the octet strings and their lengths. NULL is stored if 2492 | - the sequence is empty. ber_bvecfree() can be called to free the 2493 | - allocated memory. The tag of the sequence and of the octet 2494 | - strings are ignored. 2495 | - 2496 | -'x' Skip element. The next element is skipped. No argument is 2497 | - required. 2498 | - 2499 | -'{' Begin sequence. No argument is required. The initial sequence 2500 | - tag and length are skipped. 2501 | - 2502 | -'}' End sequence. No argument is required. 2503 | - 2504 | -'[' Begin set. No argument is required. The initial set tag and 2505 | - length are skipped. 2506 | - 2507 | -']' End set. No argument is required. 2508 | - 2509 | - unsigned long ber_peek_tag (BerElement *ber, unsigned long *lenPtr); 2510 | - 2511 | -ber_peek_tag() returns the tag of the next element to be parsed in the 2512 | -BerElement argument. The length of this element is stored in the 2513 | -*lenPtr argument. LBER_DEFAULT is returned if there is no further data 2514 | -to be read. The ber argument is not modified. 2515 | - 2516 | - unsigned long ber_skip_tag (BerElement *ber, unsigned long *lenPtr); 2517 | - 2518 | -ber_skip_tag() is similar to ber_peek_tag(), except that the state 2519 | -pointer in the BerElement argument is advanced past the first tag and 2520 | -length, and is pointed to the value part of the next element. This rou- 2521 | -tine should only be used with constructed types and situations when a 2522 | -BER encoding is used as the value of an OCTET STRING. The length of the 2523 | -value is stored in *lenPtr. 2524 | - 2525 | - 2526 | - 2527 | - 2528 | -Expires: January 1998 [Page 45] 2529 | - 2530 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 2531 | - 2532 | - 2533 | - unsigned long ber_first_element(BerElement *ber, 2534 | - unsigned long *lenPtr, char **opaquePtr); 2535 | - 2536 | - unsigned long ber_next_element (BerElement *ber, 2537 | - unsigned long *lenPtr, char *opaque); 2538 | - 2539 | -ber_first_element() and ber_next_element() are used to traverse a SET, 2540 | -SET OF, SEQUENCE or SEQUENCE OF data value. ber_first_element() calls 2541 | -ber_skip_tag(), stores internal information in *lenPtr and *opaquePtr, 2542 | -and calls ber_peek_tag() for the first element inside the constructed 2543 | -value. LBER_DEFAULT is returned if the constructed value is empty. 2544 | -ber_next_element() positions the state at the start of the next element 2545 | -in the constructed type. LBER_DEFAULT is returned if there are no 2546 | -further values. 2547 | - 2548 | -The len and opaque values should not be used by applications other than 2549 | -as arguments to ber_next_element(), as shown in the example below. 2550 | - 2551 | - 2552 | -13.5. Decoding Example 2553 | - 2554 | -The following is an example of decoding an ASN.1 data type: 2555 | - 2556 | - Example2Request ::= SEQUENCE { 2557 | - dn OCTET STRING, -- must be printable 2558 | - scope ENUMERATED { b (0), s (1), w (2) }, 2559 | - ali ENUMERATED { n (0), s (1), f (2), a (3) }, 2560 | - size INTEGER, 2561 | - time INTEGER, 2562 | - tonly BOOLEAN, 2563 | - attrs SEQUENCE OF OCTET STRING, -- must be printable 2564 | - [0] SEQUENCE OF SEQUENCE { 2565 | - type OCTET STRING -- must be printable, 2566 | - crit BOOLEAN DEFAULT FALSE, 2567 | - value OCTET STRING 2568 | - } OPTIONAL } 2569 | - 2570 | - #define LDAP_TAG_CONTROL_LIST 0xA0L /* context specific cons 0 */ 2571 | - 2572 | - int decode_example2(struct berval *bv) 2573 | - { 2574 | - BerElement *ber; 2575 | - unsigned long len; 2576 | - int scope, ali, size, time, tonly; 2577 | - char *dn = NULL, **attrs = NULL; 2578 | - int res,i,rc = 0; 2579 | - 2580 | - ber = ber_init(bv); 2581 | - 2582 | - 2583 | - 2584 | -Expires: January 1998 [Page 46] 2585 | - 2586 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 2587 | - 2588 | - 2589 | - if (ber == NULL) { 2590 | - printf("ERROR ber_init failed0); 2591 | - return -1; 2592 | - } 2593 | - 2594 | - res = ber_scanf(ber,"{aiiiiib{v}",&dn,&scope,&ali, 2595 | - &size,&time,&tonly,&attrs); 2596 | - 2597 | - if (res == -1) { 2598 | - printf("ERROR ber_scanf failed0); 2599 | - ber_free(ber,1); 2600 | - return -1; 2601 | - } 2602 | - 2603 | - /* *** use dn */ 2604 | - ldap_memfree(dn); 2605 | - 2606 | - for (i = 0; attrs != NULL && attrs[i] != NULL; i++) { 2607 | - /* *** use attrs[i] */ 2608 | - ldap_memfree(attrs[i]); 2609 | - } 2610 | - ldap_memfree(attrs); 2611 | - 2612 | - if (ber_peek_tag(ber,&len) == LDAP_TAG_CONTROL_LIST) { 2613 | - char *opaque; 2614 | - unsigned long tag; 2615 | - 2616 | - for (tag = ber_first_element(ber,&len,&opaque); 2617 | - tag != LBER_DEFAULT; 2618 | - tag = ber_next_element (ber,&len,opaque)) { 2619 | - 2620 | - unsigned long ttag, tlen; 2621 | - char *type; 2622 | - int crit; 2623 | - struct berval *value; 2624 | - 2625 | - if (ber_scanf(ber,"{a",&type) == LBER_ERROR) { 2626 | - printf("ERROR cannot parse type0); 2627 | - break; 2628 | - } 2629 | - /* *** use type */ 2630 | - ldap_memfree(type); 2631 | - 2632 | - ttag = ber_peek_tag(ber,&tlen); 2633 | - if (ttag == 0x01) { /* boolean */ 2634 | - if (ber_scanf(ber,"b", 2635 | - &crit) == LBER_ERROR) { 2636 | - printf("ERROR cannot parse crit0); 2637 | - 2638 | - 2639 | - 2640 | -Expires: January 1998 [Page 47] 2641 | - 2642 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 2643 | - 2644 | - 2645 | - rc = -1; 2646 | - break; 2647 | - } 2648 | - } else if (ttag == 0x04) { /* octet string */ 2649 | - crit = 0; 2650 | - } else { 2651 | - printf("ERROR extra field in controls0); 2652 | - break; 2653 | - } 2654 | - 2655 | - if (ber_scanf(ber,"O}",&value) == LBER_ERROR) { 2656 | - printf("ERROR cannot parse value0); 2657 | - rc = -1; 2658 | - break; 2659 | - } 2660 | - /* *** use value */ 2661 | - ldap_bvfree(value); 2662 | - } 2663 | - } 2664 | - 2665 | - ber_scanf(ber,"}"); 2666 | - 2667 | - ber_free(ber,1); 2668 | - 2669 | - return rc; 2670 | - } 2671 | - 2672 | - 2673 | - 2674 | -14. Security Considerations 2675 | - 2676 | -LDAPv2 supports security through protocol-level authentication using 2677 | -clear-text passwords. LDAPv3 adds support for SASL [8] (Simple Authen- 2678 | -tication Security Layer) methods. LDAPv3 also supports operation over a 2679 | -secure transport layer using Transport Layer Security TLS [8]. Readers 2680 | -are referred to the protocol documents for discussion of related secu- 2681 | -rity considerations. 2682 | - 2683 | -Implementations of this API should be cautious when handling authentica- 2684 | -tion credentials. In particular, keeping long-lived copies of creden- 2685 | -tials without the application's knowledge is discouraged. 2686 | - 2687 | - 2688 | -15. Acknowledgements 2689 | - 2690 | -Many members of the IETF ASID working group as well as members of the 2691 | -Internet at large have provided useful comments and suggestions that 2692 | -have been incorporated into this revision. 2693 | - 2694 | - 2695 | - 2696 | -Expires: January 1998 [Page 48] 2697 | - 2698 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 2699 | - 2700 | - 2701 | -This original material upon which this revision is based was based upon 2702 | -work supported by the National Science Foundation under Grant No. NCR- 2703 | -9416667. 2704 | - 2705 | - 2706 | -16. Bibliography 2707 | - 2708 | -[1] The Directory: Selected Attribute Syntaxes. CCITT, Recommendation 2709 | - X.520. 2710 | - 2711 | -[2] M. Wahl, A. Coulbeck, T. Howes, S. Kille, W. Yeong, C. Robbins, 2712 | - "Lightweight Directory Access Protocol Attribute Syntax Defini- 2713 | - tions", INTERNET-DRAFT , 2714 | - 11 July 1997. 2715 | - 2716 | -[3] T. Howes, "A String Representation of LDAP Search Filters," 2717 | - INTERNET-DRAFT , May 1997. 2718 | - 2719 | -[4] S. Kille, M. Wahl, "A UTF-8 String Representation of Distinguished 2720 | - Names", INTERNET-DRAFT , 29 April 2721 | - 1997. 2722 | - 2723 | -[5] S. Kille, "Using the OSI Directory to Achieve User Friendly Nam- 2724 | - ing," RFC 1781, March 1995. 2725 | - 2726 | -[6] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol 2727 | - (v3)", INTERNET-DRAFT , 11 2728 | - July 1997. 2729 | - 2730 | -[7] A. Herron, T. Howes, M. Wahl, "LDAP Control Extension for Server 2731 | - Side Sorting of Search Result," INTERNET-DRAFT , 16 April 1997. 2733 | - 2734 | -[8] J. Meyers, "Simple Authentication and Security Layer", INTERNET- 2735 | - DRAFT , April 1997. 2736 | - 2737 | -[9] "Lightweight Directory Access Protocol (v3) Extension for Transport 2738 | - Layer Security", INTERNET-DRAFT , June 1997. 2740 | - 2741 | -[10] "UTF-8, a transformation format of Unicode and ISO 10646", RFC 2742 | - 2044, October 1996. 2743 | - 2744 | -[11] "IP Version 6 Addressing Architecture,", RFC 1884, December 1995. 2745 | - 2746 | - 2747 | - 2748 | - 2749 | - 2750 | - 2751 | - 2752 | -Expires: January 1998 [Page 49] 2753 | - 2754 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 2755 | - 2756 | - 2757 | -17. Author's Addresses 2758 | - 2759 | - Tim Howes 2760 | - Netscape Communications Corp. 2761 | - 501 E. Middlefield Rd., Mailstop MV068 2762 | - Mountain View, CA 94043 2763 | - USA 2764 | - +1 415 937-3419 2765 | - howes@netscape.com 2766 | - 2767 | - 2768 | - Mark Smith 2769 | - Netscape Communications Corp. 2770 | - 501 E. Middlefield Rd., Mailstop MV068 2771 | - Mountain View, CA 94043 2772 | - USA 2773 | - +1 415 937-3477 2774 | - mcs@netscape.com 2775 | - 2776 | - Andy Herron 2777 | - Microsoft Corp. 2778 | - 1 Microsoft Way 2779 | - Redmond, WA 98052 2780 | - USA 2781 | - +1 425 882-8080 2782 | - andyhe@microsoft.com 2783 | - 2784 | - Chris Weider 2785 | - Microsoft Corp. 2786 | - 1 Microsoft Way 2787 | - Redmond, WA 98052 2788 | - USA 2789 | - +1 425 882-8080 2790 | - cweider@microsoft.com 2791 | - 2792 | - Mark Wahl 2793 | - Critical Angle Inc. 2794 | - 4815 W Braker Lane #502-385 2795 | - Austin, TX 78759 2796 | - USA 2797 | - M.Wahl@critical-angle.com 2798 | - 2799 | - 2800 | -18. Appendix A - Sample LDAP API Code 2801 | - 2802 | - #include 2803 | - 2804 | - main() 2805 | - 2806 | - 2807 | - 2808 | -Expires: January 1998 [Page 50] 2809 | - 2810 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 2811 | - 2812 | - 2813 | - { 2814 | - LDAP *ld; 2815 | - LDAPMessage *res, *e; 2816 | - int i; 2817 | - char *a, *dn; 2818 | - BerElement *ptr; 2819 | - char **vals; 2820 | - 2821 | - /* open an LDAP session */ 2822 | - if ( (ld = ldap_init( "dotted.host.name", LDAP_PORT )) == NULL ) 2823 | - exit( 1 ); 2824 | - 2825 | - /* authenticate as nobody */ 2826 | - if ( ldap_simple_bind_s( ld, NULL, NULL ) != LDAP_SUCCESS ) { 2827 | - ldap_perror( ld, "ldap_simple_bind_s" ); 2828 | - exit( 1 ); 2829 | - } 2830 | - 2831 | - /* search for entries with cn of "Babs Jensen", return all attrs */ 2832 | - if ( ldap_search_s( ld, "o=University of Michigan, c=US", 2833 | - LDAP_SCOPE_SUBTREE, "(cn=Babs Jensen)", NULL, 0, &res ) 2834 | - != LDAP_SUCCESS ) { 2835 | - ldap_perror( ld, "ldap_search_s" ); 2836 | - exit( 1 ); 2837 | - } 2838 | - 2839 | - /* step through each entry returned */ 2840 | - for ( e = ldap_first_entry( ld, res ); e != NULL; 2841 | - e = ldap_next_entry( ld, e ) ) { 2842 | - /* print its name */ 2843 | - dn = ldap_get_dn( ld, e ); 2844 | - printf( "dn: %s\n", dn ); 2845 | - ldap_memfree( dn ); 2846 | - 2847 | - /* print each attribute */ 2848 | - for ( a = ldap_first_attribute( ld, e, &ptr ); a != NULL; 2849 | - a = ldap_next_attribute( ld, e, ptr ) ) { 2850 | - printf( "attribute: %s\n", a ); 2851 | - 2852 | - /* print each value */ 2853 | - vals = ldap_get_values( ld, e, a ); 2854 | - for ( i = 0; vals[i] != NULL; i++ ) { 2855 | - printf( "value: %s\n", vals[i] ); 2856 | - } 2857 | - ldap_value_free( vals ); 2858 | - } 2859 | - if ( ptr != NULL ) { 2860 | - ldap_ber_free( ptr, 0 ); 2861 | - 2862 | - 2863 | - 2864 | -Expires: January 1998 [Page 51] 2865 | - 2866 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 2867 | - 2868 | - 2869 | - } 2870 | - } 2871 | - /* free the search results */ 2872 | - ldap_msgfree( res ); 2873 | - 2874 | - /* close and free connection resources */ 2875 | - ldap_unbind( ld ); 2876 | - } 2877 | - 2878 | - 2879 | - 2880 | -19. Appendix B - Outstanding Issues 2881 | - 2882 | - 2883 | -19.1. Support for multithreaded applications 2884 | - 2885 | -In order to support multithreaded applications in a platform-independent 2886 | -way, some additions to the LDAP API are needed. Different implementors 2887 | -have taken different paths to solve this problem in the past. A common 2888 | -set of thread-related API calls must be defined so that application 2889 | -developers are not unduly burdened. These will be added to a future 2890 | -revision of this specification. 2891 | - 2892 | - 2893 | -19.2. Using Transport Layer Security (TLS) 2894 | - 2895 | -The API calls used to support TLS must be specified. They will be added 2896 | -to a future revision of this specification. 2897 | - 2898 | - 2899 | -19.3. Client control for chasing referrals 2900 | - 2901 | -A client control has been defined that can be used to specify on a per- 2902 | -operation basis whether references and external referrals are automati- 2903 | -cally chased by the client library. This will be added to a future 2904 | -revision of this specification. 2905 | - 2906 | - 2907 | -19.4. Potential confusion between hostname:port and IPv6 addresses 2908 | - 2909 | -String representations of IPv6 network addresses [11] can contain colon 2910 | -characters. The ldap_init() call is specified to take strings of the 2911 | -form "hostname:port" or "ipaddress:port". If IPv6 addresses are used, 2912 | -the latter could be ambiguous. A future revision of this specification 2913 | -will resolve this issue. 2914 | - 2915 | - 2916 | - 2917 | - 2918 | - 2919 | - 2920 | -Expires: January 1998 [Page 52] 2921 | - 2922 | -C LDAP API The C LDAP Application Program Interface 29 July 1997 2923 | - 2924 | - 2925 | -19.5. Need to track SASL API standardization efforts 2926 | - 2927 | -If a standard Simple Authentication and Security Layer API is defined, 2928 | -it may be necessary to modify the LDAP API to accommodate it. 2929 | - 2930 | - 2931 | -19.6. Support for character sets other than UTF-8? 2932 | - 2933 | -Some application developers would prefer to pass string data using a 2934 | -character set other than UTF-8. This could be accommodated by adding a 2935 | -new option to ldap_set_option() that supports choosing a character set. 2936 | -If this feature is added, the number of different character sets sup- 2937 | -ported should definitely be minimized. 2938 | - 2939 | - 2940 | -19.7. Use of UTF-8 with LDAPv2 servers 2941 | - 2942 | -Strings are always passed as UTF-8 in this API but LDAP version 2 2943 | -servers do not support the full range of UTF-8 characters. The expected 2944 | -behavior of this API when using LDAP version 2 with unsupported charac- 2945 | -ters should be specified. 2946 | - 2947 | - 2948 | - 2949 | - 2950 | - 2951 | - 2952 | - 2953 | - 2954 | - 2955 | - 2956 | - 2957 | - 2958 | - 2959 | - 2960 | - 2961 | - 2962 | - 2963 | - 2964 | - 2965 | - 2966 | - 2967 | - 2968 | - 2969 | - 2970 | - 2971 | - 2972 | - 2973 | - 2974 | - 2975 | - 2976 | -Expires: January 1998 [Page 53] 2977 | - 2978 | - 2979 | - 2980 | -1. Status of this Memo............................................1 2981 | -2. Introduction...................................................1 2982 | -3. Overview of the LDAP Model.....................................2 2983 | -4. Overview of LDAP API Use.......................................3 2984 | -5. Common Data Structures.........................................4 2985 | -6. LDAP Error Codes...............................................5 2986 | -7. Performing LDAP Operations.....................................6 2987 | -7.1. Initializing an LDAP Session................................6 2988 | -7.2. LDAP Session Handle Options.................................7 2989 | -7.3. Working with controls.......................................10 2990 | -7.4. Authenticating to the directory.............................11 2991 | -7.5. Closing the session.........................................13 2992 | -7.6. Searching...................................................13 2993 | -7.7. Reading an Entry............................................17 2994 | -7.8. Listing the Children of an Entry............................17 2995 | -7.9. Comparing a Value Against an Entry..........................17 2996 | -7.10. Modifying an entry..........................................19 2997 | -7.11. Modifying the Name of an Entry..............................21 2998 | -7.12. Adding an entry.............................................23 2999 | -7.13. Deleting an entry...........................................25 3000 | -7.14. Extended Operations.........................................26 3001 | -8. Abandoning An Operation........................................28 3002 | -9. Obtaining Results and Peeking Inside LDAP Messages.............29 3003 | -10. Handling Errors and Parsing Results............................31 3004 | -11. Stepping Through a List of Results.............................33 3005 | -12. Parsing Search Results.........................................34 3006 | -12.1. Stepping Through a List of Entries..........................34 3007 | -12.2. Stepping Through the Attributes of an Entry.................35 3008 | -12.3. Retrieving the Values of an Attribute.......................36 3009 | -12.4. Retrieving the name of an entry.............................37 3010 | -13. Encoded ASN.1 Value Manipulation...............................39 3011 | -13.1. General.....................................................39 3012 | -13.2. Encoding....................................................40 3013 | -13.3. Encoding Example............................................42 3014 | -13.4. Decoding....................................................43 3015 | -13.5. Decoding Example............................................46 3016 | -14. Security Considerations........................................48 3017 | -15. Acknowledgements...............................................48 3018 | -16. Bibliography...................................................49 3019 | -17. Author's Addresses.............................................50 3020 | -18. Appendix A - Sample LDAP API Code..............................50 3021 | -19. Appendix B - Outstanding Issues................................52 3022 | -19.1. Support for multithreaded applications......................52 3023 | -19.2. Using Transport Layer Security (TLS)........................52 3024 | -19.3. Client control for chasing referrals........................52 3025 | -19.4. Potential confusion between hostname:port and IPv6 addresses52 3026 | -19.5. Need to track SASL API standardization efforts..............53 3027 | -19.6. Support for character sets other than UTF-8?................53 3028 | -19.7. Use of UTF-8 with LDAPv2 servers............................53 3029 | - 3030 | - 3031 | - 3032 | - 3033 | - 3034 | - 3035 | - 3036 | - 3037 | --------------------------------------------------------------------------------