Apache Portable Runtime
apr_ldap.h
Go to the documentation of this file.
1 /* Licensed to the Apache Software Foundation (ASF) under one or more
2  * contributor license agreements. See the NOTICE file distributed with
3  * this work for additional information regarding copyright ownership.
4  * The ASF licenses this file to You under the Apache License, Version 2.0
5  * (the "License"); you may not use this file except in compliance with
6  * the License. You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 /**
18  * @file apr_ldap.h
19  * @brief APR-UTIL LDAP routines
20  */
21 #ifndef APU_LDAP_H
22 #define APU_LDAP_H
23 
24 /**
25  * @defgroup APR_Util_LDAP LDAP routines
26  *
27  * The APR LDAP routines provide a common, cross platform, ability to connect
28  * to and search an LDAP server.
29  *
30  * The goals of the API are:
31  *
32  * - Work within the functionality of APR pools. Requests from different pools
33  * can make LDAP requests of a common connection, and when the connection
34  * pool or the request pool goes away, the connection and/or LDAP requests
35  * are cleaned up gracefully.
36  *
37  * - Offer an asynchronous API that can be used for non blocking access to an
38  * LDAP server. The responses APR_WANT_READ and APR_WANT_WRITE make it clear
39  * whether the API wants to read or write to the LDAP server in the next API
40  * call.
41  *
42  * - Be as simple as possible. Data is returned fully processed in callbacks,
43  * removing the need for API calls to access data, and intermediate data
44  * structures.
45  *
46  * In typical use, the following calls are used:
47  *
48  * - apr_ldap_initialise() - create a handle to keep track of a connection.
49  * - apr_ldap_option_set() - set the URL, or the socket descriptor for the
50  * connextion to the server.
51  * - apr_ldap_connect() - if an URL was specified, connect to the server and
52  * confirm success.
53  * - apr_ldap_bind() - initiate a bind, and specify a callback when done.
54  *
55  * Enter the event loop, where we do the following until the connection is
56  * closed.
57  *
58  * - apr_ldap_process() - when writable, perform tasks that require writing to
59  * the LDAP server.
60  * - apr_ldap_result() - when readable, perform tasks that require reading from
61  * the LDAP server.
62  *
63  * Respond appropriately to callbacks, lining up calls to apr_ldap_compare() and
64  * apr_ldap_search() as needed.
65  *
66  * @ingroup APR
67  * @{
68  */
69 
70 #include "apr.h"
71 
72 /*
73  * Handle the case when LDAP is enabled
74  */
75 #if APR_HAS_LDAP || defined(DOXYGEN)
76 
77 #include "apu.h"
78 #include "apr_poll.h"
79 #include "apr_pools.h"
80 #include "apr_network_io.h"
81 #include "apu_errno.h"
82 #include "apr_escape.h"
83 #include "apr_buffer.h"
84 
85 /*
86  * LDAP URL handling
87  */
88 
89 /**
90  * Individual fields accessible within an LDAP URL.
91  * @see apr_ldap_url_parse */
92 typedef struct apr_ldap_url_desc_t {
93  /** Next URL in a sequence of URLs */
95  /** URL scheme (ldap, ldaps, ldapi) */
96  char *lud_scheme;
97  /** Host part of the URL */
98  char *lud_host;
99  /** Port, if appropriate */
100  int lud_port;
101  /** Base distinguished name of the search */
102  char *lud_dn;
103  /** Attributes to be returned during a search */
104  char **lud_attrs;
105  /** Scope of the search */
107  /** Search filter */
108  char *lud_filter;
109  /** Extensions */
110  char **lud_exts;
111  /** Critical extensions */
114 
115 #ifndef APR_LDAP_URL_SUCCESS
116 /**
117  * URL was successfully parsed.
118  * @see apr_ldap_url_parse()
119  */
120 #define APR_LDAP_URL_SUCCESS 0x00
121 /**
122  * Can't allocate memory space
123  * @see apr_ldap_url_parse()
124  */
125 #define APR_LDAP_URL_ERR_MEM 0x01
126 /**
127  * Parameter is bad
128  * @see apr_ldap_url_parse()
129  */
130 #define APR_LDAP_URL_ERR_PARAM 0x02
131 /**
132  * URL doesn't begin with "ldap[si]://"
133  * @see apr_ldap_url_parse()
134  */
135 #define APR_LDAP_URL_ERR_BADSCHEME 0x03
136 /**
137  * URL is missing trailing ">"
138  * @see apr_ldap_url_parse()
139  */
140 #define APR_LDAP_URL_ERR_BADENCLOSURE 0x04
141 /**
142  * URL is bad
143  * @see apr_ldap_url_parse()
144  */
145 #define APR_LDAP_URL_ERR_BADURL 0x05
146 /**
147  * Host port is bad
148  * @see apr_ldap_url_parse()
149  */
150 #define APR_LDAP_URL_ERR_BADHOST 0x06
151 /**
152  * Bad (or missing) attributes
153  * @see apr_ldap_url_parse()
154  */
155 #define APR_LDAP_URL_ERR_BADATTRS 0x07
156 /**
157  * Scope string is invalid (or missing)
158  * @see apr_ldap_url_parse()
159  */
160 #define APR_LDAP_URL_ERR_BADSCOPE 0x08
161 /**
162  * Bad or missing filter
163  * @see apr_ldap_url_parse()
164  */
165 #define APR_LDAP_URL_ERR_BADFILTER 0x09
166 /**
167  * Bad or missing extensions
168  * @see apr_ldap_url_parse()
169  */
170 #define APR_LDAP_URL_ERR_BADEXTS 0x0a
171 #endif
172 
173 /**
174  * Is this URL an ldap url? ldap://
175  * @param url The url to test
176  */
177 APR_DECLARE(int) apr_ldap_is_ldap_url(const char *url);
178 
179 /**
180  * Is this URL an SSL ldap url? ldaps://
181  * @param url The url to test
182  */
183 APR_DECLARE(int) apr_ldap_is_ldaps_url(const char *url);
184 
185 /**
186  * Is this URL an ldap socket url? ldapi://
187  * @param url The url to test
188  */
189 APR_DECLARE(int) apr_ldap_is_ldapi_url(const char *url);
190 
191 /**
192  * Parse an LDAP URL.
193  * @param pool The pool to use
194  * @param url_in The URL to parse
195  * @param ludpp The structure to return the exploded URL
196  * @param result_err The result structure of the operation
197  */
199  const char *url_in,
200  apr_ldap_url_desc_t **ludpp,
201  apu_err_t **result_err);
202 
203 /**
204  * Parse an LDAP URL.
205  * @param pool The pool to use
206  * @param url_in The URL to parse
207  * @param ludpp The structure to return the exploded URL
208  * @param result_err The result structure of the operation
209  */
211  const char *url_in,
212  apr_ldap_url_desc_t **ludpp,
213  apu_err_t **result_err);
214 
215 
216 
217 
218 
219 
220 
221 
222 
223 /* These symbols are not actually exported in a DSO build, but mapped into
224  * a private exported function array for apr_ldap_stub to bind dynamically.
225  * Rename them appropriately to protect the global namespace.
226  */
227 #if defined(APU_DSO_LDAP_BUILD)
228 
229 #define apr_ldap_info apr__ldap_info
230 #define apr_ldap_initialise apr__ldap_initialise
231 #define apr_ldap_option_get apr__ldap_option_get
232 #define apr_ldap_option_set apr__ldap_option_set
233 #define apr_ldap_connect apr__ldap_connect
234 #define apr_ldap_prepare apr__ldap_prepare
235 #define apr_ldap_process apr__ldap_process
236 #define apr_ldap_result apr__ldap_result
237 #define apr_ldap_poll apr__ldap_poll
238 #define apr_ldap_bind apr__ldap_bind
239 #define apr_ldap_compare apr__ldap_compare
240 #define apr_ldap_search apr__ldap_search
241 #define apr_ldap_unbind apr__ldap_unbind
242 
243 #define APU_DECLARE_LDAP(type) type
244 #else
245 /** @see APR_DECLARE */
246 #define APU_DECLARE_LDAP(type) APR_DECLARE(type)
247 #endif
248 
249 /**
250  * Opaque structure representing the LDAP driver.
251  * @see apr_ldap_get_driver
252  */
253 typedef struct apr_ldap_driver_t apr_ldap_driver_t;
254 
255 
256 /** apr_ldap_get_driver: get the driver struct for a name
257  *
258  * The LDAP driver is unique in that LDAP libraries are almost exclusively
259  * derived from RFC1823 "The LDAP Application Program Interface".
260  *
261  * As a result, unlike other drivers for other subsystems in APR, two
262  * different drivers cannot be loaded at once, as the underlying libraries
263  * share common symbols with one another.
264  *
265  * For this reason we have exactly one driver available at a time.
266  *
267  * This function loads the library, and registers a cleanup with the pool
268  * provided to unload the library.
269  *
270  * This function can be called multiple times by independent code, cleanups
271  * are reference counted so the last pool cleanup unloads the library.
272  *
273  * Calling this function explicitly is optional, and would be done to have
274  * complete control over the lifetime of the driver.
275  *
276  * If this function is not called explicitly, this function will be called
277  * if needed before the apr_ldap_info(), apr_ldap_initialise(),
278  * apr_ldap_option_get(), and apr_ldap_option_set() functions,
279  * registering cleanups in the pools provided to those functions if needed.
280  *
281  * @param pool (process) pool to register cleanup that will unload the
282  * library. Cleanup is reference counted so the driver is
283  * unloaded on last access.
284  * @param driver Pointer to driver struct. Can be NULL.
285  * @param err Human readable error messages
286  * @return APR_SUCCESS for success
287  * @return APR_ENOTIMPL for no driver (when DSO not enabled)
288  * @return APR_EDSOOPEN if DSO driver file can't be opened
289  * @return APR_ESYMNOTFOUND if the driver file doesn't contain a driver
290  */
292  const apr_ldap_driver_t **driver,
293  apu_err_t *err)
294  __attribute__((nonnull(1,3)));
295 
296 
297 
298 /**
299  * Opaque structure tracking the state of an LDAP connection.
300  *
301  * @see apr_ldap_initialise
302  */
303 typedef struct apr_ldap_t apr_ldap_t;
304 
305 
306 /**
307  * APR LDAP info function
308  *
309  * This function returns a string describing the LDAP toolkit
310  * currently in use. The string is placed inside result_err->reason.
311  * @param pool The pool to use
312  * @param result_err The returned result
313  */
315  apu_err_t **result_err)
316  __attribute__((nonnull(1,2)));
317 
318 
319 
320 /**
321  * Ports used by LDAP.
322  */
323 /** ldap:/// default LDAP port */
324 #define APR_LDAP_PORT 389
325 /** ldaps:/// default LDAP over TLS port */
326 #define APR_LDAPS_PORT 636
327 
328 
329 /**
330  * APR LDAP initialise function
331  *
332  * This function is responsible for initialising an LDAP
333  * connection in a toolkit independant way. It does the
334  * job of ldap_initialize() from the C api.
335  *
336  * The setting of the LDAP server to connect is made after
337  * this function returns, using the apr_ldap_option_set()
338  * call with APR_LDAP_OPT_DESC or APR_LDAP_OPT_URI.
339  *
340  * A cleanup for the connection is registered in the given pool.
341  *
342  * @param pool The pool to use
343  * @param ldap The ldap context returned
344  * @param err On error, error details are written to the
345  * structure.
346  * @see apr_ldap_option_set
347  * @see APR_LDAP_OPT_DESC
348  * @see APR_LDAP_OPT_URI
349  */
351  apr_ldap_t **ldap,
352  apu_err_t *err)
353  __attribute__((nonnull(1,2,3)));
354 
355 
356 /*
357  * LDAP options.
358  */
359 
360 /**
361  * Structure returned by passing APR_LDAP_OPT_API_INFO to
362  * apr_ldap_option_get().
363  *
364  * Use to return information about the underlying LDAP API.
365  *
366  * @see apr_ldap_option_get
367  * @see APR_LDAP_OPT_API_INFO
368  */
369 typedef struct apr_ldap_apiinfo_t {
370  /** revision of API supported */
372  /** highest LDAP version supported */
374  /** names of API extensions */
375  const char **extensions;
376  /** name of supplier */
377  const char *vendor_name;
378  /** supplier-specific version * 100 */
381 
382 
383 /**
384  * Structure returned by passing APR_LDAP_OPT_API_FEATURE_INFO to
385  * apr_ldap_option_get().
386  *
387  * Use to return details of extensions supported by the underlying API.
388  *
389  * @see apr_ldap_option_get
390  * @see APR_LDAP_OPT_API_FEATURE_INFO
391  */
393  /** LDAP_API_FEATURE_* (less prefix) */
394  const char *name;
395  /** value of LDAP_API_FEATURE_... */
396  int version;
398 
399 /**
400  * LDAP Protocol Versions.
401  *
402  * @see apr_ldap_option_set
403  * @see APR_LDAP_OPT_PROTOCOL_VERSION
404  */
405 typedef enum {
406  /** LDAP version 1 */
408  /** LDAP version 2 */
410  /** LDAP version 3 */
413 
414 /**
415  * LDAP deref settings
416  *
417  * @see apr_ldap_option_set
418  * @see APR_LDAP_OPT_DEREF
419  */
420 typedef enum {
421  APR_LDAP_DEREF_NEVER = 0, /**< Aliases should never be dereferenced */
422  APR_LDAP_DEREF_SEARCHING = 1, /**< Aliases should be dereferenced during the search, but not when locating the base object of the search. */
423  APR_LDAP_DEREF_FINDING = 2, /**< Aliases should be dereferenced when locating the base object, but not during the search. */
424  APR_LDAP_DEREF_ALWAYS = 3 /**< Aliases should always be dereferenced */
426 
427 /**
428  * LDAP options on or off
429  *
430  * @see apr_ldap_option_set
431  * @see APR_LDAP_OPT_REFERRALS
432  */
433 typedef enum {
434  APR_LDAP_OPT_OFF = 0, /**< Option set off */
435  APR_LDAP_OPT_ON = 1 /**< Option set on */
437 
438 
439 /**
440  * Set SSL mode to one of APR_LDAP_NONE, APR_LDAP_SSL, APR_LDAP_STARTTLS
441  * or APR_LDAP_STOPTLS.
442  * @see apr_ldap_option_set
443  * @see apr_ldap_option_get
444  * @see apr_ldap_tls_e
445  */
446 #define APR_LDAP_OPT_TLS 0x6fff
447 /**
448  * Set zero or more CA certificates, client certificates or private
449  * keys globally, or per connection (where supported).
450  *
451  * @see apr_ldap_option_set
452  * @see apr_ldap_opt_tls_cert_t
453  */
454 #define APR_LDAP_OPT_TLS_CERT 0x6ffe
455 /**
456  * Set the LDAP library to not verify the server certificate. This means
457  * all servers are considered trusted.
458  * @see apr_ldap_option_set
459  * @see apr_ldap_verify_e
460  */
461 #define APR_LDAP_OPT_VERIFY_CERT 0x6ffd
462 /**
463  * Set the LDAP library to indicate if referrals should be chased during
464  * LDAP searches.
465  * @see apr_ldap_option_get
466  * @see apr_ldap_option_set
467  * @see apr_ldap_switch_e
468  */
469 #define APR_LDAP_OPT_REFERRALS 0x6ffc
470 /**
471  * Set the LDAP library to indicate a maximum number of referral hops to
472  * chase before giving up on the search.
473  * @see apr_ldap_option_get
474  * @see apr_ldap_option_set
475  */
476 #define APR_LDAP_OPT_REFHOPLIMIT 0x6ffb
477 /**
478  * Get the underlying native LDAP handle.
479  * @see apr_ldap_option_get
480  */
481 #define APR_LDAP_OPT_HANDLE 0x6ffa
482 /**
483  * Get/Set the LDAP protocol version.
484  * @see apr_ldap_option_get
485  * @see apr_ldap_option_set
486  * @see apr_ldap_protocol_version_e
487  */
488 #define APR_LDAP_OPT_PROTOCOL_VERSION 0x6ff9
489 /**
490  * Get the LDAP API info.
491  * @see apr_ldap_option_get
492  * @see apr_ldap_apiinfo_t
493  */
494 #define APR_LDAP_OPT_API_INFO 0x6ff8
495 /**
496  * Get the LDAP API feature info.
497  * @see apr_ldap_option_get
498  * @see apr_ldap_apifeature_info_t
499  */
500 #define APR_LDAP_OPT_API_FEATURE_INFO 0x6ff7
501 /**
502  * Get the dereference setting.
503  * @see apr_ldap_option_get
504  * @see apr_ldap_option_set
505  * @see apr_ldap_deref_e
506  */
507 #define APR_LDAP_OPT_DEREF 0x6ff6
508 /**
509  * Get the most recent result code.
510  * @see apr_ldap_option_get
511  */
512 #define APR_LDAP_OPT_RESULT_CODE 0x6ff5
513 /**
514  * Get or set the underlying socket.
515  *
516  * Use this to get the underlying socket so as to perform select/poll
517  * before attempting to read or write.
518  *
519  * Note that LDAP libraries like OpenLDAP will successfully return an
520  * invalid socket if a previous attempt to connect failed. In this
521  * case, you will obtain an error the next time you use the socket.
522  *
523  * This option can also be used to set the underlying socket, as an
524  * alternative to specifying a URI. This is typically done to perform
525  * non blocking DNS lookups, or non blocking TLS negotiation, neither
526  * of which is supported natively by LDAP APIs.
527  *
528  * @warning Either APR_LDAP_OPT_DESC or APR_LDAP_OPT_URI must be set
529  * before any other options are set, for the LDAP handle to be
530  * initialised internally.
531  * @see apr_ldap_option_get
532  * @see apr_ldap_option_set
533  * @see apr_socket_t
534  */
535 #define APR_LDAP_OPT_DESC 0x6ff4
536 /**
537  * Set the URI to connect to.
538  *
539  * @warning This option (or APR_LDAP_OPT_DESC) must be set before other options,
540  * as this initialises the underlying LDAP API.
541  * @see apr_ldap_option_set
542  */
543 #define APR_LDAP_OPT_URI 0x5006
544 /**
545  * Get/set the network timeout.
546  * @see apr_ldap_option_get
547  * @see apr_ldap_option_set
548  */
549 #define APR_LDAP_OPT_NETWORK_TIMEOUT 0x5005
550 /**
551  * Get/set the timeout.
552  * @see apr_ldap_option_get
553  * @see apr_ldap_option_set
554  */
555 #define APR_LDAP_OPT_TIMEOUT 0x5002
556 
557 /**
558  * CA certificate type unknown
559  * @see APR_LDAP_OPT_TLS_CERT
560  * @see apr_ldap_opt_tls_cert_t
561  */
562 #define APR_LDAP_CA_TYPE_UNKNOWN 0
563 /**
564  * Binary DER encoded CA certificate
565  * @see APR_LDAP_OPT_TLS_CERT
566  * @see apr_ldap_opt_tls_cert_t
567  */
568 #define APR_LDAP_CA_TYPE_DER 1
569 /**
570  * PEM encoded CA certificate
571  * @see APR_LDAP_OPT_TLS_CERT
572  * @see apr_ldap_opt_tls_cert_t
573  */
574 #define APR_LDAP_CA_TYPE_BASE64 2
575 /**
576  * Openldap directory full of base64-encoded cert
577  * authorities with hashes in corresponding .0 directory
578  * @see APR_LDAP_OPT_TLS_CERT
579  * @see apr_ldap_opt_tls_cert_t
580  */
581 #define APR_LDAP_CA_TYPE_CACERTDIR_BASE64 15
582 /**
583  * CA Certificate at the given URI
584  * @see APR_LDAP_OPT_TLS_CERT
585  * @see apr_ldap_opt_tls_cert_t
586  */
587 #define APR_LDAP_CA_TYPE_URI 18
588 /**
589  * Client certificate type unknown
590  * @see APR_LDAP_OPT_TLS_CERT
591  * @see apr_ldap_opt_tls_cert_t
592  */
593 #define APR_LDAP_CERT_TYPE_UNKNOWN 5
594 /**
595  * Binary DER encoded client certificate
596  * @see APR_LDAP_OPT_TLS_CERT
597  * @see apr_ldap_opt_tls_cert_t
598  */
599 #define APR_LDAP_CERT_TYPE_DER 6
600 /**
601  * PEM encoded client certificate
602  * @see APR_LDAP_OPT_TLS_CERT
603  * @see apr_ldap_opt_tls_cert_t
604  */
605 #define APR_LDAP_CERT_TYPE_BASE64 7
606 /**
607  * PKCS#12 encoded client certificate
608  * @see APR_LDAP_OPT_TLS_CERT
609  * @see apr_ldap_opt_tls_cert_t
610  */
611 #define APR_LDAP_CERT_TYPE_PFX 13
612 /**
613  * Certificate at the given URI
614  * @see APR_LDAP_OPT_TLS_CERT
615  * @see apr_ldap_opt_tls_cert_t
616  */
617 #define APR_LDAP_CERT_TYPE_URI 16
618 /**
619  * Private key type unknown
620  * @see APR_LDAP_OPT_TLS_CERT
621  * @see apr_ldap_opt_tls_cert_t
622  */
623 #define APR_LDAP_KEY_TYPE_UNKNOWN 10
624 /**
625  * Binary DER encoded private key
626  * @see APR_LDAP_OPT_TLS_CERT
627  * @see apr_ldap_opt_tls_cert_t
628  */
629 #define APR_LDAP_KEY_TYPE_DER 11
630 /**
631  * PEM encoded private key
632  * @see APR_LDAP_OPT_TLS_CERT
633  * @see apr_ldap_opt_tls_cert_t
634  */
635 #define APR_LDAP_KEY_TYPE_BASE64 12
636 /**
637  * PKCS#12 encoded private key
638  * @see APR_LDAP_OPT_TLS_CERT
639  * @see apr_ldap_opt_tls_cert_t
640  */
641 #define APR_LDAP_KEY_TYPE_PFX 14
642 /**
643  * Private key at the given URI
644  * @see APR_LDAP_OPT_TLS_CERT
645  * @see apr_ldap_opt_tls_cert_t
646  */
647 #define APR_LDAP_KEY_TYPE_URI 17
648 
649 
650 
651 /**
652  * Certificate structure.
653  *
654  * This structure is used to store certificate details. An array of
655  * these structures is passed to apr_ldap_option_set() with the option
656  * APR_LDAP_OPT_TLS_CERT to set CA and client certificates.
657  *
658  * @see apr_ldap_option_set
659  * @see APR_LDAP_OPT_TLS_CERT
660  */
661 typedef struct apr_ldap_opt_tls_cert_t {
662  /** Type of certificate APR_LDAP_*_TYPE_* */
663  int type;
664  /** Path, file, uri or nickname of the certificate */
665  const char *path;
666  /** Optional password, can be NULL */
667  const char *password;
669 
670 
671 /**
672  * APR_LDAP_OPT_TLS
673  *
674  * This sets the SSL level on the LDAP handle.
675  *
676  * @see APR_LDAP_OPT_TLS
677  * @see apr_ldap_option_set
678  */
679 typedef enum {
680  APR_LDAP_TLS_NONE = 0, /**< No encryption */
681  APR_LDAP_TLS_SSL = 1, /**< SSL encryption (ldaps://) */
682  APR_LDAP_TLS_STARTTLS = 2, /**< TLS encryption (STARTTLS) */
683  APR_LDAP_TLS_STOPTLS = 3 /**< end TLS encryption (STOPTLS) */
685 
686 
687 /**
688  * LDAP TLS verify options
689  *
690  * @see APR_LDAP_OPT_VERIFY_CERT
691  * @see apr_ldap_option_set
692  */
693 typedef enum {
694  /** Disable TLS verification (this is an insecure setting) */
696  /** Enable TLS verification */
699 
700 
701 /**
702  * Union of all possible options to be passed to apr_ldap_option_get()
703  * and apr_ldap_option_set().
704  *
705  * @see apr_ldap_option_set
706  * @see apr_ldap_option_get
707  */
708 typedef union apr_ldap_opt_t {
709  /**
710  * LDAP native handle
711  * @see APR_LDAP_OPT_HANDLE
712  */
713  void *handle;
714  /**
715  * LDAP native option
716  */
717  void *opt;
718  /**
719  * LDAP underlying socket
720  *
721  * @see APR_LDAP_OPT_DESC
722  */
724  /**
725  * LDAP uri
726  *
727  * @see APR_LDAP_OPT_URI
728  */
729  const char *uri;
730  /**
731  * LDAP API information
732  *
733  * @see APR_LDAP_OPT_API_INFO
734  */
736  /**
737  * LDAP API feature information
738  *
739  * @see APR_LDAP_OPT_API_FEATURE_INFO
740  */
742  /**
743  * Protocol version
744  *
745  * @see APR_LDAP_OPT_PROTOCOL_VERSION
746  */
748  /**
749  * TLS certificates
750  *
751  * @see APR_LDAP_OPT_TLS_CERT
752  */
754  /**
755  * Timeouts
756  *
757  * @see APR_LDAP_OPT_NETWORK_TIMEOUT
758  * @see APR_LDAP_OPT_TIMEOUT
759  */
761  /**
762  * TLS on/off/starttls
763  *
764  * @see APR_LDAP_OPT_TLS
765  */
767  /**
768  * TLS verification
769  *
770  * @see APR_LDAP_OPT_VERIFY_CERT
771  */
773  /**
774  * Alias dereference
775  *
776  * @see APR_LDAP_OPT_DEREF
777  */
779  /**
780  * Referrals chased
781  *
782  * @see APR_LDAP_OPT_REFERRALS
783  */
785  /**
786  * Referral hop limit
787  *
788  * @see APR_LDAP_OPT_REFHOPLIMIT
789  */
791  /**
792  * Result code
793  *
794  * @see APR_LDAP_OPT_RESULT_CODE
795  */
796  int result;
798 
799 
800 /**
801  * APR LDAP get option function
802  *
803  * This function gets option values from a given LDAP session if
804  * one was specified. It maps to the native ldap_get_option() function.
805  * @param pool The pool to use where needed
806  * @param ldap The LDAP handle
807  * @param option The LDAP_OPT_* option to return
808  * @param outvalue The value returned (if any)
809  * @param result_err On error, error details are written to the
810  * structure.
811  * @see APR_LDAP_OPT_API_FEATURE_INFO
812  * @see APR_LDAP_OPT_API_INFO
813  * @see APR_LDAP_OPT_DEREF
814  * @see APR_LDAP_OPT_DESC
815  * @see APR_LDAP_OPT_HANDLE
816  * @see APR_LDAP_OPT_NETWORK_TIMEOUT
817  * @see APR_LDAP_OPT_PROTOCOL_VERSION
818  * @see APR_LDAP_OPT_REFERRALS
819  * @see APR_LDAP_OPT_REFHOPLIMIT
820  * @see APR_LDAP_OPT_RESULT_CODE
821  * @see APR_LDAP_OPT_TIMEOUT
822  */
824  int option,
825  apr_ldap_opt_t *outvalue,
826  apu_err_t *result_err)
827  __attribute__((nonnull(1,4,5)));
828 
829 /**
830  * APR LDAP set option function
831  *
832  * This function sets option values to a given LDAP session if
833  * one was specified. It maps to the native ldap_set_option() function.
834  *
835  * Where an option is not supported by an LDAP toolkit, this function
836  * will try and apply legacy functions to achieve the same effect,
837  * depending on the platform.
838  * @param pool The pool to use where needed
839  * @param ldap The LDAP handle
840  * @param option The LDAP_OPT_* option to set
841  * @param invalue The value to set
842  * @param result_err On error, error details are written to the
843  * structure.
844  * @see APR_LDAP_OPT_DEREF
845  * @see APR_LDAP_OPT_DESC
846  * @see APR_LDAP_OPT_NETWORK_TIMEOUT
847  * @see APR_LDAP_OPT_PROTOCOL_VERSION
848  * @see APR_LDAP_OPT_REFERRALS
849  * @see APR_LDAP_OPT_REFHOPLIMIT
850  * @see APR_LDAP_OPT_TIMEOUT
851  * @see APR_LDAP_OPT_TLS
852  * @see APR_LDAP_OPT_TLS_CERT
853  * @see APR_LDAP_OPT_URI
854  * @see APR_LDAP_OPT_VERIFY_CERT
855  */
857  int option,
858  const apr_ldap_opt_t *invalue,
859  apu_err_t *result_err)
860  __attribute__((nonnull(1,5)));
861 
862 /**
863  * LDAP interaction identifiers during LDAP binding
864  *
865  * @see apr_ldap_bind_interact_t
866  * @see apr_ldap_bind
867  */
868 typedef enum {
869  APR_LDAP_INTERACT_DN = 0, /**< Distinguished name to use for simple bind */
870  APR_LDAP_INTERACT_GETREALM = 0x4008, /**< SASL realm for the authentication attempt */
871  APR_LDAP_INTERACT_AUTHNAME = 0x4002, /**< SASL username to authenticate */
872  APR_LDAP_INTERACT_USER = 0x4001, /**< SASL username to use for proxy authorization */
873  APR_LDAP_INTERACT_PASS = 0x4004, /**< SASL password for the provided username / Simple password for a simple bind */
874  APR_LDAP_INTERACT_NOECHOPROMPT = 0x4006, /**< SASL generic prompt for input with input echoing disabled */
875  APR_LDAP_INTERACT_ECHOPROMPT = 0x4005, /**< SASL generic prompt for input with input echoing enabled */
877 
878 
879 /**
880  * During apr_ldap_bind(), a callback is passed this structure
881  * requesting authentication and authorisation details. The callback
882  * is expected to fill the buffer with the information requested.
883  *
884  * This is used to obtain the information needed for SASL binds.
885  *
886  * @see apr_ldap_bind_interact_e
887  * @see apr_ldap_bind
888  */
889 typedef struct apr_ldap_bind_interact_t {
890  /** An enum indicating what information is requested. */
892  /** Presented to user (e.g. OTP challenge) */
893  const char *challenge;
894  /** Presented to user (e.g. "Username: ") */
895  const char *prompt;
896  /** Default result string */
897  const char *defresult;
898  /** Buffer to be filled in by the callback with the information requested */
901 
902 /**
903  * Bind SASL interact callback.
904  *
905  * Depending on the type of SASL mechanism chosen, this callback is called
906  * to request details needed for each bind.
907  *
908  * @see apr_ldap_bind_interact_t
909  * @see apr_ldap_bind
910  */
912  apr_ldap_t *ld, unsigned int flags, apr_ldap_bind_interact_t *interact, void *ctx);
913 
914 
915 
916 
917 
918 #if 0
919 
920 typedef struct apr_ldap_rebind_t {
921  /** presented to user (e.g. OTP challenge) */
922  const char *challenge;
923  /** presented to user (e.g. "Username: ") */
924  const char *prompt;
925 } apr_ldap_rebind_t;
926 
927 typedef apr_status_t (apr_ldap_rebind_proc)(
928  apr_ldap_t *ld, apr_ldap_rebind_t *rebind, void *ctx);
929 
930 #endif
931 
932 
933 
934 /**
935  * LDAP Control structure
936  *
937  * @see apr_ldap_bind_cb
938  * @see apr_ldap_compare_cb
939  * @see apr_ldap_search_result_cb
940  * @see apr_ldap_compare
941  * @see apr_ldap_search
942  */
944 
945 
946 
947 
948 /**
949  * APR LDAP connect function.
950  *
951  * This function makes an attempt to connect to the server initialised
952  * by apr_ldap_initialise().
953  *
954  * While other functions will connect if not connected, use this
955  * function to explicitly handle errors in the connect case.
956  *
957  * This function will synchronously perform DNS lookups and TLS negotiation
958  * and will block if needed.
959  *
960  * If you need asynchronous handling, perform the DNS and TLS handling
961  * yourself, and then pass the socket with APR_LDAP_OPT_DESC.
962  *
963  * @return APR_SUCCESS means that the connection connected successfully.
964  * Other error codes indicate that the connect was not successful.
965  */
967  apr_ldap_t *ldap,
968  apr_interval_time_t timeout,
969  apu_err_t *result_err)
970  __attribute__((nonnull(1,2,4)));
971 
972 /**
973  * Callback to prepare an LDAP request.
974  *
975  * This callback is scheduled to be fired when the LDAP socket is next
976  * writable, from within apr_ldap_process().
977  *
978  * When complete, return APR_SUCCESS to indicate you want to continue, or
979  * a different code if you want the event loop to give up. This code will
980  * be returned from apr_ldap_process().
981  * @see apr_ldap_prepare
982  * @see apr_ldap_process
983  */
985  void *ctx, apu_err_t *err);
986 
987 
988 /**
989  * APR LDAP prepare function
990  *
991  * This function schedules a generic callback, fired the next time the LDAP
992  * socket is writable.
993  *
994  * This callback can be used to prepare the initial LDAP request, or to
995  * prepare additional requests as needed without blocking.
996  *
997  * @param pool The pool that keeps track of the lifetime of the callback.
998  * If this pool is cleaned up, the callback will be will be gracefully
999  * removed without affecting other LDAP requests in progress. This pool need
1000  * not have any relationship with the LDAP connection pool.
1001  * @param ldap The ldap handle
1002  * @param prepare_cb The prepare callback function. When apr_ldap_process() is
1003  * next called this callback will be triggered in the expectation of the next
1004  * LDAP request.
1005  * @param prepare_ctx Context passed to the prepare callback.
1006  * @param err Error structure for reporting detailed results.
1007  *
1008  * @return APR_SUCCESS means the callback was successfully prepared. Other error
1009  * codes indicate that the attept to send the cancellation was not successful.
1010  */
1012  apr_ldap_t *ldap,
1013  apr_ldap_prepare_cb prepare_cb,
1014  void *prepare_ctx)
1015  __attribute__((nonnull(1,2,3)));
1016 
1017 
1018 /**
1019  * APR process function.
1020  *
1021  * This function performs outstanding processing of any LDAP conversations
1022  * currently in progress.
1023  *
1024  * When a request tells you that further processing is needed, schedule this
1025  * call the next time the socket is writable.
1026  *
1027  * Most callbacks are fired from within apr_ldap_process() so that we are
1028  * ready to write the next LDAP query should that be needed.
1029  *
1030  * @param pool The pool to use
1031  * @param ldap The LDAP handle
1032  * @param timeout The timeout to use for writes.
1033  * @param err Error structure for reporting detailed results.
1034  *
1035  * @return APR_WANT_WRITE means that at least one further process is outstanding
1036  * and a further write callback should be scheduled. APR_WANTS_READ indicates
1037  * the a request has been sent and we're waiting for the response. APR_SUCCESS
1038  * means that no further processing is needed. Other error codes indicate that
1039  * the processing of outstanding conversations was not successful.
1040  */
1042  apr_ldap_t *ldap,
1043  apr_interval_time_t timeout,
1044  apu_err_t *err)
1045  __attribute__((nonnull(1,2,4)));
1046 
1047 
1048 /**
1049  * APR result function.
1050  *
1051  * This function returns the result of a previous request, ready for further
1052  * processing.
1053  *
1054  * @param pool The pool to use
1055  * @param ldap The LDAP handle
1056  * @param timeout The timeout to use for writes.
1057  * @param err Error structure for reporting detailed results.
1058  *
1059  * @return APR_WANT_WRITE means that at least one further process is outstanding
1060  * and a further write callback should be scheduled. APR_WANTS_READ indicates
1061  * more responses are expected and we're waiting for the response. APR_SUCCESS
1062  * means that no further processing is needed. Other error codes indicate that
1063  * the processing of outstanding conversations was not successful.
1064  */
1066  apr_ldap_t *ldap,
1067  apr_interval_time_t timeout,
1068  apu_err_t *err)
1069  __attribute__((nonnull(1,2,4)));
1070 
1071 
1072 /**
1073  * APR LDAP poll function.
1074  *
1075  * For applications that need simple set of queries, this function provides
1076  * an event loop that can handle a series of LDAP requests.
1077  *
1078  * This function calls apr_ldap_process() and apr_ldap_result() as needed.
1079  *
1080  * @param pool The pool to use
1081  * @param ldap The LDAP handle
1082  * @param timeout The timeout to use for reads and writes.
1083  * @param err Error structure for reporting detailed results.
1084  *
1085  * @return APR_SUCCESS means that no further processing is needed. Other error
1086  * codes indicate that processing was not successful.
1087  */
1089  apr_ldap_t *ldap,
1090  apr_pollcb_t *poll,
1091  apr_interval_time_t timeout,
1092  apu_err_t *err)
1093  __attribute__((nonnull(1,2,3,5)));
1094 
1095 
1096 /**
1097  * Callback to receive the results of a bind operation.
1098  *
1099  * When a bind is successful, this function is called with a status of
1100  * APR_SUCCESS.
1101  *
1102  * Bind success is returned from within apr_ldap_process(), and therefore
1103  * it can be safely assumed that the underlying socket is writable ready
1104  * for exactly one further LDAP operation like apr_ldap_search() or
1105  * apr_ldap_compare().
1106  *
1107  * If the bind fails, status will carry the error code, and err will return
1108  * the human readable details.
1109  *
1110  * If the underlying LDAP connection has failed, status will return details
1111  * of the error, allowing an opportunity to clean up.
1112  *
1113  * When complete, return APR_SUCCESS to indicate you want to continue, or
1114  * a different code if you want the event loop to give up. This code will
1115  * be returned from apr_ldap_process().
1116  *
1117  * If this callback was called during a pool cleanup, the return value is
1118  * ignored.
1119  * @see apr_ldap_bind
1120  * @see apr_ldap_process
1121  * @see apr_ldap_result
1122  */
1124  const char *matcheddn,
1125  apr_ldap_control_t **serverctrls,
1126  void *ctx, apu_err_t *err);
1127 
1128 
1129 #if 0
1130 /**
1131  * Function called to report cancel results.
1132  */
1133 typedef void (*apr_ldap_cancel_cb)(apr_ldap_t *ldap, apr_ldap_message_t *msg, void *ctx);
1134 
1135 /**
1136  * APR LDAP cancel function
1137  *
1138  * This function cancels a previously sent LDAP operation, identified by
1139  * the callback function and callback context.
1140  *
1141  * Cancellations are attempted asynchronously. The result of the cancellation
1142  * will be retrieved and handled by the apr_ldap_result() function, and the
1143  * outcome is passed to the callback provided.
1144  *
1145  * @return APR_INCOMPLETE means that the cancellation was sent, and the message
1146  * in reply needs to be fetched using apr_ldap_result(). Other error
1147  * codes indicate that the attept to send the cancellation was not successful.
1148  */
1149 APU_DECLARE_LDAP(apr_status_t) apr_ldap_cancel(apr_pool_t *pool,
1150  apr_ldap_t *ldap,
1151  apr_ldap_control_t **serverctrls,
1152  apr_ldap_control_t **clientctrls,
1153  apr_interval_time_t timeout,
1154  apr_ldap_cancel_cb cancel_cb, void *cancel_ctx,
1155  apu_err_t *err)
1156  __attribute__((nonnull(1,2,6,8)));
1157 #endif
1158 
1159 /**
1160  * APR LDAP bind function
1161  *
1162  * This function initiates a bind on a previously initialised LDAP connection
1163  * to the directory.
1164  *
1165  * Pass the required SASL mechanism in mech, or set to NULL for a simple
1166  * bind.
1167  *
1168  * Unlike the native LDAP APIs, this function muct be called just once.
1169  * The job of binding is done inside apr_ldap_process() and apr_ldap_result().
1170  *
1171  * Binds are attempted asynchronously. For non blocking behaviour, this function
1172  * must be called after the underlying socket has indicated that it is ready to
1173  * write.
1174  *
1175  * In the absence of an error, apr_ldap_bind will return APR_WANT_READ to
1176  * indicate that the next message in the conversation be retrieved using
1177  * apr_ldap_result().
1178  *
1179  * The outcome of the bind will be retrieved and handled by the
1180  * apr_ldap_process() function, and the outcome is passed to the
1181  * apr_ldap_bind_cb provided.
1182  *
1183  * @param pool The pool that keeps track of the lifetime of the bind conversation.
1184  * If this pool is cleaned up, the bind conversation will be gracefully
1185  * abandoned without affecting other LDAP requests in progress. This pool need
1186  * not have any relationship with the LDAP connection pool.
1187  * @param ldap The ldap handle
1188  * @param mech The SASL mechanism. Pass NULL for simple bind.
1189  * @param interact_cb The SASL interactive callback function. This function is
1190  * is called to request credentials for the bind, depending on the mechanism.
1191  * @param interact_ctx Context passed to the interactive callback.
1192  * @param timeout The timeout to use for writes.
1193  * @param bind_cb The bind result callback function. When the bind process has
1194  * completed the success or failure of the bind is returned here. The callback
1195  * is triggered from inside apr_ldap_process() so that it is safe to write the
1196  * next LDAP request.
1197  * @param bind_ctx Context passed to the bind callback.
1198  * @param err Error structure for reporting detailed results.
1199  * @return APR_WANT_READ means that processing has occurred, and
1200  * the message in reply needs to be fetched using apr_ldap_result().
1201  * APR_WANT_WRITE means that processing has occurred, and the
1202  * conversation needs to be continued with a call to apr_ldap_process().
1203  * APR_SUCCESS means that the processing is complete, and the bind
1204  * has been successful. Other error codes indicate that the bind
1205  * was not successful.
1206  * @see apr_ldap_bind_interact_cb
1207  * @see apr_ldap_bind_cb
1208  * @see apr_ldap_process
1209  * @see apr_ldap_result
1210  */
1212  const char *mech,
1213  apr_ldap_bind_interact_cb *interact_cb,
1214  void *interact_ctx,
1215  apr_interval_time_t timeout,
1216  apr_ldap_bind_cb bind_cb, void *bind_ctx,
1217  apu_err_t *err)
1218  __attribute__((nonnull(1,2,4,9)));
1219 
1220 
1221 /**
1222  * Callback to receive the results of a compare operation.
1223  *
1224  * When a compare is successful, this function is called with a status of
1225  * APR_COMPARE_TRUE or APR_COMPARE_FALSE.
1226  *
1227  * If the compare fails, status will carry the error code, and err will return
1228  * the human readable details.
1229  *
1230  * If the underlying LDAP connection has failed, status will return details
1231  * of the error, allowing an opportunity to clean up.
1232  *
1233  * When complete, return APR_SUCCESS to indicate you want to continue, or
1234  * a different code if you want the event loop to give up. This code will
1235  * be returned from apr_ldap_result().
1236  *
1237  * If this callback was called during a pool cleanup, the return value is
1238  * ignored.
1239  * @see apr_ldap_compare
1240  * @see apr_ldap_result
1241  */
1243  const char *matcheddn,
1244  apr_ldap_control_t **serverctrls,
1245  void *ctx, apu_err_t *err);
1246 
1247 
1248 
1249 /**
1250  * APR LDAP compare function
1251  *
1252  * This function compares a string or binary value of an attribute
1253  * within an entry described by the given distinguished name against
1254  * a previously initialised LDAP connection to the directory.
1255  *
1256  * Compares are attempted asynchronously. For non blocking behaviour, this function
1257  * must be called after the underlying socket has indicated that it is ready to
1258  * write.
1259  *
1260  * In the absence of an error, apr_ldap_compare will return APR_WANT_READ to
1261  * indicate that the next message in the conversation be retrieved using
1262  * apr_ldap_result().
1263  *
1264  * The outcome of the compare will be retrieved and handled by the
1265  * apr_ldap_process() function, and the outcome is passed to the
1266  * apr_ldap_compare_cb provided.
1267  *
1268  * @param pool The pool that keeps track of the lifetime of the compare conversation.
1269  * If this pool is cleaned up, the compare conversation will be gracefully
1270  * abandoned without affecting other LDAP requests in progress. This pool need
1271  * not have any relationship with the LDAP connection pool.
1272  * @param ldap The ldap handle
1273  * @param dn The distinguished named of the object to compare.
1274  * @param attr The attribute of the object to compare.
1275  * @param val The value to be compared to the attribute. The value can be zero
1276  * terminated text, or binary.
1277  * @param serverctrls NULL terminated array of server controls.
1278  * @param clientctrls NULL terminated array of client controls.
1279  * @param timeout The timeout to use for writes.
1280  * @param compare_cb The compare result callback function. When the compare process has
1281  * completed the success or failure of the compare is returned here. The callback
1282  * is triggered from inside apr_ldap_process() so that it is safe to write the
1283  * next LDAP request.
1284  * @param ctx Context passed to the compare callback.
1285  * @param err Error structure for reporting detailed results.
1286  *
1287  * @return APR_WANT_READ means that processing has occurred, and
1288  * the message in reply needs to be fetched using apr_ldap_result().
1289  * APR_SUCCESS means that the processing is complete, and the bind
1290  * has been successful. Other error codes indicate that the bind
1291  * was not successful.
1292  * @see apr_ldap_compare_cb
1293  * @see apr_ldap_process
1294  * @see apr_ldap_result
1295  */
1297  apr_ldap_t *ldap,
1298  const char *dn,
1299  const char *attr,
1300  const apr_buffer_t *val,
1301  apr_ldap_control_t **serverctrls,
1302  apr_ldap_control_t **clientctrls,
1303  apr_interval_time_t timeout,
1304  apr_ldap_compare_cb compare_cb, void *ctx,
1305  apu_err_t *err)
1306  __attribute__((nonnull(1,2,3,4,5,11)));
1307 
1308 
1309 /**
1310  * APR search scopes
1311  *
1312  * @see apr_ldap_search
1313  */
1314 typedef enum {
1315  /** base object search */
1317  /** one-level search */
1319  /** subtree search */
1321  /** subordinate search */
1324 
1325 
1326 /**
1327  * Callback to receive the results of a search operation.
1328  *
1329  * This callback is fired once for every search.
1330  *
1331  * When a search is complete, this function is called with a status of
1332  * APR_SUCCESS or APR_NO_RESULTS_RETURNED.
1333  *
1334  * If the search fails, status will carry the error code, and err will return
1335  * the human readable details.
1336  *
1337  * If the underlying LDAP connection has failed, status will return details
1338  * of the error, allowing an opportunity to clean up.
1339  *
1340  * When complete, return APR_SUCCESS to indicate you want to continue, or
1341  * a different code if you want the event loop to give up. This code will
1342  * be returned from apr_ldap_result().
1343  *
1344  * If this callback was called during a pool cleanup, the return value is
1345  * ignored.
1346  * @see apr_ldap_search
1347  * @see apr_ldap_result
1348  */
1350  apr_size_t count, const char *matcheddn,
1351  apr_ldap_control_t **serverctrls,
1352  void *ctx, apu_err_t *err);
1353 
1354 /**
1355  * Callback to receive the entries of a search operation.
1356  *
1357  * This callback is fired once for every attribute and value combination,
1358  * and then once for each entry to indicate the entry is complete.
1359  *
1360  * When complete, return APR_SUCCESS to indicate you want to continue, or
1361  * a different code if you want the event loop to give up. This code will
1362  * be returned from apr_ldap_result().
1363  *
1364  * @see apr_ldap_search
1365  * @see apr_ldap_result
1366  */
1367 typedef apr_status_t (*apr_ldap_search_entry_cb)(apr_ldap_t *ldap, const char *dn,
1368  int eidx, int nattrs, int aidx,
1369  const char *attr, int nvals,
1370  int vidx, apr_buffer_t *val, int binary,
1371  void *ctx, apu_err_t *err);
1372 
1373 
1374 /**
1375  * APR LDAP search function
1376  *
1377  * This function searches a previously initialised LDAP connection to the directory.
1378  *
1379  * Searches are attempted asynchronously. For non blocking behaviour, this function
1380  * must be called after the underlying socket has indicated that it is ready to
1381  * write.
1382  *
1383  * In the absence of an error, apr_ldap_search will return APR_WANT_READ to
1384  * indicate that the next message in the conversation be retrieved using
1385  * apr_ldap_result().
1386  *
1387  * The outcome of the search will be retrieved and handled by the
1388  * apr_ldap_result() function as each result arrives.
1389  *
1390  * If one or more results are returned, the apr_ldap_search_entry_cb callback
1391  * is called once for each attribute and value combination.
1392  *
1393  * At the end of each entry, apr_ldap_search_entry_cb will be called with no
1394  * attribute or value, giving code an opportunity to perform any processing only
1395  * possible after all of the entries have been retrieved.
1396  *
1397  * Once all entries have been processed, apr_ldap_search_result_cb is called to
1398  * indicate the final result of the search.
1399  *
1400  * If no entries are returned, only apr_ldap_search_result_cb will be called.
1401  *
1402  * @param pool The pool that keeps track of the lifetime of the search conversation.
1403  * If this pool is cleaned up, the search conversation will be gracefully
1404  * abandoned without affecting other LDAP requests in progress. This pool need
1405  * not have any relationship with the LDAP connection pool.
1406  * @param ldap The ldap handle
1407  * @param dn The base distinguished named of the search.
1408  * @param scope The scope of the search.
1409  * @param filter The search filter string.
1410  * @param attrs NULL terminated array of attributes to return.
1411  * @param attrsonly If on, attributes will be returned without values.
1412  * @param serverctrls NULL terminated array of server controls.
1413  * @param clientctrls NULL terminated array of client controls.
1414  * @param timeout The timeout to use for writes.
1415  * @param sizelimit The maximum number of entries to return in the search.
1416  * @param search_result_cb The search result callback function. When the search
1417  * process has completed the success or failure of the search is returned here.
1418  * The callback is triggered from inside apr_ldap_process() so that it is safe to
1419  * write the next LDAP request.
1420  * @param search_entry_cb The search entry callback function. For each value of
1421  * each attribute of each entry, this callback is called with each value. This
1422  * callback is then fired off one more time at the end of each entry, giving the
1423  * chance to handle that entry. The callback is triggered from inside
1424  * apr_ldap_result().
1425  * @param ctx Context passed to the search result and search entry callbacks.
1426  * @param err Error structure for reporting detailed results.
1427  *
1428  * @return APR_WANT_READ means that processing has occurred, and
1429  * the message in reply needs to be fetched using apr_ldap_result().
1430  * Other error codes indicate that the search attempt was not successful.
1431  * @see apr_ldap_search_entry_cb
1432  * @see apr_ldap_search_result_cb
1433  * @see apr_ldap_result
1434  */
1436  apr_ldap_t *ldap,
1437  const char *dn,
1439  const char *filter,
1440  const char **attrs,
1441  apr_ldap_switch_e attrsonly,
1442  apr_ldap_control_t **serverctrls,
1443  apr_ldap_control_t **clientctrls,
1444  apr_interval_time_t timeout,
1445  apr_ssize_t sizelimit,
1446  apr_ldap_search_result_cb search_result_cb,
1447  apr_ldap_search_entry_cb search_entry_cb,
1448  void *ctx,
1449  apu_err_t *err)
1450  __attribute__((nonnull(1,2,3,15)));
1451 
1452 /**
1453  * APR LDAP unbind function
1454  *
1455  * This function unbinds from the LDAP server, and frees the connection handle.
1456  *
1457  * Calling this function is optional, the same effect can be achieved by cleaning up
1458  * the pool passed to apr_ldap_initialise().
1459  *
1460  * @see apr_ldap_initialise
1461  */
1463  apr_ldap_control_t **serverctrls,
1464  apr_ldap_control_t **clientctrls,
1465  apu_err_t *err)
1466  __attribute__((nonnull(1,4)));
1467 
1468 
1469 #endif /* APU_HAS_LDAP */
1470 /** @} */
1471 #endif /* APU_LDAP_H */
1472 
APR Platform Definitions.
APR-UTIL Buffer.
APR-UTIL Escaping.
APR Network library.
APR Poll interface.
APR memory allocation.
APR-Util Error Codes.
apr_status_t apr_ldap_unbind(apr_ldap_t *ldap, apr_ldap_control_t **serverctrls, apr_ldap_control_t **clientctrls, apu_err_t *err)
apr_status_t(* apr_ldap_search_result_cb)(apr_ldap_t *ldap, apr_status_t status, apr_size_t count, const char *matcheddn, apr_ldap_control_t **serverctrls, void *ctx, apu_err_t *err)
Definition: apr_ldap.h:1349
struct apr_ldap_driver_t apr_ldap_driver_t
Definition: apr_ldap.h:253
#define APU_DECLARE_LDAP(type)
Definition: apr_ldap.h:246
apr_status_t apr_ldap_process(apr_pool_t *pool, apr_ldap_t *ldap, apr_interval_time_t timeout, apu_err_t *err)
struct apr_ldap_apifeature_info_t apr_ldap_apifeature_info_t
apr_status_t apr_ldap_compare(apr_pool_t *pool, apr_ldap_t *ldap, const char *dn, const char *attr, const apr_buffer_t *val, apr_ldap_control_t **serverctrls, apr_ldap_control_t **clientctrls, apr_interval_time_t timeout, apr_ldap_compare_cb compare_cb, void *ctx, apu_err_t *err)
apr_status_t(* apr_ldap_search_entry_cb)(apr_ldap_t *ldap, const char *dn, int eidx, int nattrs, int aidx, const char *attr, int nvals, int vidx, apr_buffer_t *val, int binary, void *ctx, apu_err_t *err)
Definition: apr_ldap.h:1367
struct apr_ldap_apiinfo_t apr_ldap_apiinfo_t
union apr_ldap_opt_t apr_ldap_opt_t
apr_status_t apr_ldap_initialise(apr_pool_t *pool, apr_ldap_t **ldap, apu_err_t *err)
apr_status_t apr_ldap_result(apr_pool_t *pool, apr_ldap_t *ldap, apr_interval_time_t timeout, apu_err_t *err)
apr_status_t apr_ldap_search(apr_pool_t *pool, apr_ldap_t *ldap, const char *dn, apr_ldap_search_scope_e scope, const char *filter, const char **attrs, apr_ldap_switch_e attrsonly, apr_ldap_control_t **serverctrls, apr_ldap_control_t **clientctrls, apr_interval_time_t timeout, apr_ssize_t sizelimit, apr_ldap_search_result_cb search_result_cb, apr_ldap_search_entry_cb search_entry_cb, void *ctx, apu_err_t *err)
int apr_ldap_is_ldap_url(const char *url)
int apr_ldap_is_ldapi_url(const char *url)
apr_ldap_deref_e
Definition: apr_ldap.h:420
apr_status_t apr_ldap_prepare(apr_pool_t *pool, apr_ldap_t *ldap, apr_ldap_prepare_cb prepare_cb, void *prepare_ctx)
apr_ldap_bind_interact_e
Definition: apr_ldap.h:868
apr_ldap_search_scope_e
Definition: apr_ldap.h:1314
apr_status_t() apr_ldap_bind_interact_cb(apr_ldap_t *ld, unsigned int flags, apr_ldap_bind_interact_t *interact, void *ctx)
Definition: apr_ldap.h:911
apr_ldap_verify_e
Definition: apr_ldap.h:693
apr_status_t apr_ldap_get_driver(apr_pool_t *pool, const apr_ldap_driver_t **driver, apu_err_t *err)
apr_status_t apr_ldap_poll(apr_pool_t *pool, apr_ldap_t *ldap, apr_pollcb_t *poll, apr_interval_time_t timeout, apu_err_t *err)
apr_status_t apr_ldap_info(apr_pool_t *pool, apu_err_t **result_err)
int apr_ldap_is_ldaps_url(const char *url)
apr_status_t apr_ldap_bind(apr_pool_t *pool, apr_ldap_t *ldap, const char *mech, apr_ldap_bind_interact_cb *interact_cb, void *interact_ctx, apr_interval_time_t timeout, apr_ldap_bind_cb bind_cb, void *bind_ctx, apu_err_t *err)
int apr_ldap_url_parse_ext(apr_pool_t *pool, const char *url_in, apr_ldap_url_desc_t **ludpp, apu_err_t **result_err)
apr_status_t apr_ldap_option_get(apr_pool_t *pool, apr_ldap_t *ldap, int option, apr_ldap_opt_t *outvalue, apu_err_t *result_err)
apr_status_t apr_ldap_option_set(apr_pool_t *pool, apr_ldap_t *ldap, int option, const apr_ldap_opt_t *invalue, apu_err_t *result_err)
apr_status_t(* apr_ldap_compare_cb)(apr_ldap_t *ldap, apr_status_t status, const char *matcheddn, apr_ldap_control_t **serverctrls, void *ctx, apu_err_t *err)
Definition: apr_ldap.h:1242
apr_status_t apr_ldap_connect(apr_pool_t *pool, apr_ldap_t *ldap, apr_interval_time_t timeout, apu_err_t *result_err)
struct apr_ldap_t apr_ldap_t
Definition: apr_ldap.h:303
struct apr_ldap_url_desc_t apr_ldap_url_desc_t
apr_status_t(* apr_ldap_bind_cb)(apr_ldap_t *ldap, apr_status_t status, const char *matcheddn, apr_ldap_control_t **serverctrls, void *ctx, apu_err_t *err)
Definition: apr_ldap.h:1123
apr_status_t(* apr_ldap_prepare_cb)(apr_ldap_t *ldap, apr_status_t status, void *ctx, apu_err_t *err)
Definition: apr_ldap.h:984
struct apr_ldap_control_t apr_ldap_control_t
Definition: apr_ldap.h:943
apr_ldap_switch_e
Definition: apr_ldap.h:433
apr_ldap_protocol_version_e
Definition: apr_ldap.h:405
apr_ldap_tls_e
Definition: apr_ldap.h:679
int apr_ldap_url_parse(apr_pool_t *pool, const char *url_in, apr_ldap_url_desc_t **ludpp, apu_err_t **result_err)
struct apr_ldap_bind_interact_t apr_ldap_bind_interact_t
struct apr_ldap_opt_tls_cert_t apr_ldap_opt_tls_cert_t
@ APR_LDAP_DEREF_NEVER
Definition: apr_ldap.h:421
@ APR_LDAP_DEREF_SEARCHING
Definition: apr_ldap.h:422
@ APR_LDAP_DEREF_FINDING
Definition: apr_ldap.h:423
@ APR_LDAP_DEREF_ALWAYS
Definition: apr_ldap.h:424
@ APR_LDAP_INTERACT_GETREALM
Definition: apr_ldap.h:870
@ APR_LDAP_INTERACT_AUTHNAME
Definition: apr_ldap.h:871
@ APR_LDAP_INTERACT_USER
Definition: apr_ldap.h:872
@ APR_LDAP_INTERACT_DN
Definition: apr_ldap.h:869
@ APR_LDAP_INTERACT_ECHOPROMPT
Definition: apr_ldap.h:875
@ APR_LDAP_INTERACT_NOECHOPROMPT
Definition: apr_ldap.h:874
@ APR_LDAP_INTERACT_PASS
Definition: apr_ldap.h:873
@ APR_LDAP_SCOPE_ONELEVEL
Definition: apr_ldap.h:1318
@ APR_LDAP_SCOPE_SUBORDINATE
Definition: apr_ldap.h:1322
@ APR_LDAP_SCOPE_SUBTREE
Definition: apr_ldap.h:1320
@ APR_LDAP_SCOPE_BASE
Definition: apr_ldap.h:1316
@ APR_LDAP_VERIFY_OFF
Definition: apr_ldap.h:695
@ APR_LDAP_VERIFY_ON
Definition: apr_ldap.h:697
@ APR_LDAP_OPT_ON
Definition: apr_ldap.h:435
@ APR_LDAP_OPT_OFF
Definition: apr_ldap.h:434
@ APR_LDAP_VERSION1
Definition: apr_ldap.h:407
@ APR_LDAP_VERSION2
Definition: apr_ldap.h:409
@ APR_LDAP_VERSION3
Definition: apr_ldap.h:411
@ APR_LDAP_TLS_STOPTLS
Definition: apr_ldap.h:683
@ APR_LDAP_TLS_NONE
Definition: apr_ldap.h:680
@ APR_LDAP_TLS_SSL
Definition: apr_ldap.h:681
@ APR_LDAP_TLS_STARTTLS
Definition: apr_ldap.h:682
int apr_status_t
Definition: apr_errno.h:44
struct apr_socket_t apr_socket_t
Definition: apr_network_io.h:219
#define APR_DECLARE(type)
Definition: apr.h:516
struct apr_pollcb_t apr_pollcb_t
Definition: apr_poll.h:318
struct apr_pool_t apr_pool_t
Definition: apr_pools.h:60
apr_int64_t apr_interval_time_t
Definition: apr_time.h:55
Definition: apr_tables.h:62
Definition: apr_buffer.h:69
Definition: apr_ldap.h:392
const char * name
Definition: apr_ldap.h:394
int version
Definition: apr_ldap.h:396
Definition: apr_ldap.h:369
int protocol_version
Definition: apr_ldap.h:373
int vendor_version
Definition: apr_ldap.h:379
int api_version
Definition: apr_ldap.h:371
const char * vendor_name
Definition: apr_ldap.h:377
const char ** extensions
Definition: apr_ldap.h:375
Definition: apr_ldap.h:889
const char * defresult
Definition: apr_ldap.h:897
apr_ldap_bind_interact_e id
Definition: apr_ldap.h:891
const char * prompt
Definition: apr_ldap.h:895
apr_buffer_t result
Definition: apr_ldap.h:899
const char * challenge
Definition: apr_ldap.h:893
Definition: apr_ldap.h:661
const char * password
Definition: apr_ldap.h:667
const char * path
Definition: apr_ldap.h:665
int type
Definition: apr_ldap.h:663
Definition: apr_ldap.h:92
char ** lud_exts
Definition: apr_ldap.h:110
int lud_scope
Definition: apr_ldap.h:106
char * lud_host
Definition: apr_ldap.h:98
int lud_crit_exts
Definition: apr_ldap.h:112
char * lud_filter
Definition: apr_ldap.h:108
char * lud_dn
Definition: apr_ldap.h:102
char * lud_scheme
Definition: apr_ldap.h:96
char ** lud_attrs
Definition: apr_ldap.h:104
struct apr_ldap_url_desc_t * lud_next
Definition: apr_ldap.h:94
int lud_port
Definition: apr_ldap.h:100
Definition: apu_errno.h:289
Definition: apr_ldap.h:708
int result
Definition: apr_ldap.h:796
const char * uri
Definition: apr_ldap.h:729
apr_ldap_protocol_version_e pv
Definition: apr_ldap.h:747
apr_ldap_tls_e tls
Definition: apr_ldap.h:766
apr_socket_t * socket
Definition: apr_ldap.h:723
void * handle
Definition: apr_ldap.h:713
apr_ldap_deref_e deref
Definition: apr_ldap.h:778
void * opt
Definition: apr_ldap.h:717
int refhoplimit
Definition: apr_ldap.h:790
apr_interval_time_t timeout
Definition: apr_ldap.h:760
apr_ldap_switch_e refs
Definition: apr_ldap.h:784
apr_ldap_verify_e verify
Definition: apr_ldap.h:772
apr_array_header_t * certs
Definition: apr_ldap.h:753
apr_ldap_apifeature_info_t ldfi
Definition: apr_ldap.h:741
apr_ldap_apiinfo_t info
Definition: apr_ldap.h:735