Apache Portable Runtime
Loading...
Searching...
No Matches
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 */
92typedef struct apr_ldap_url_desc_t {
93 /** Next URL in a sequence of URLs */
95 /** URL scheme (ldap, ldaps, ldapi) */
97 /** Host part of the URL */
98 char *lud_host;
99 /** Port, if appropriate */
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 */
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 */
177APR_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 */
183APR_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 */
189APR_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 */
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 */
303typedef 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 */
369typedef 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_... */
398
399/**
400 * LDAP Protocol Versions.
401 *
402 * @see apr_ldap_option_set
403 * @see APR_LDAP_OPT_PROTOCOL_VERSION
404 */
405typedef 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 */
420typedef 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 */
433typedef 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 */
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 */
679typedef 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 */
693typedef 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 */
708typedef 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 */
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 */
868typedef 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 */
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
920typedef 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
927typedef 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 */
1133typedef 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 */
1149APU_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 */
1314typedef 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 */
1367typedef 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_bind_interact_cb(apr_ldap_t *ld, unsigned int flags, apr_ldap_bind_interact_t *interact, void *ctx)
Definition apr_ldap.h:911
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_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