1LDAP_GET_OPTION(3) Library Functions Manual LDAP_GET_OPTION(3)
2
6 ldap_get_option, ldap_set_option - LDAP option handling routines
7
9 OpenLDAP LDAP (libldap, -lldap)
10
12 #include <ldap.h>
13 int ldap_get_option(LDAP *ld, int option, void *outvalue);
15 int ldap_set_option(LDAP *ld, int option, const void *invalue);
17
19 These routines provide access to options stored either in a LDAP handle
20 or as global options, where applicable. They make use of a neutral in‐
21 terface, where the type of the value either retrieved by ldap_get_op‐
22 tion(3) or set by ldap_set_option(3) is cast to void *. The actual
23 type is determined based on the value of the option argument. Global
24 options are set/retrieved by passing a NULL LDAP handle. LDAP handles
25 inherit their default settings from the global options in effect at the
26 time the handle is created.
27 LDAP_OPT_API_FEATURE_INFO
29 Fills-in a LDAPAPIFeatureInfo; outvalue must be a LDAPAPIFea‐
30 tureInfo *, pointing to an already allocated struct. The lda‐
31 paif_info_version field of the struct must be initialized to
32 LDAP_FEATURE_INFO_VERSION before making the call. The lda‐
33 paif_name field must be set to the name of a feature to query.
34 This is a read-only option.
35 LDAP_OPT_API_INFO
37 Fills-in a LDAPAPIInfo; outvalue must be a LDAPAPIInfo *, point‐
38 ing to an already allocated struct. The ldapai_info_version
39 field of the struct must be initialized to LDAP_API_INFO_VERSION
40 before making the call. If the version passed in does not match
41 the current library version, the expected version number will be
42 stored in the struct and the call will fail. The caller is re‐
43 sponsible for freeing the elements of the ldapai_extensions ar‐
44 ray and the array itself using ldap_memfree(3). The caller must
45 also free the ldapi_vendor_name. This is a read-only option.
46 LDAP_OPT_CLIENT_CONTROLS
48 Sets/gets the client-side controls to be used for all opera‐
49 tions. This is now deprecated as modern LDAP C API provides re‐
50 placements for all main operations which accepts client-side
51 controls as explicit arguments; see for example
52 ldap_search_ext(3), ldap_add_ext(3), ldap_modify_ext(3) and so
53 on. outvalue must be LDAPControl ***, and the caller is respon‐
54 sible of freeing the returned controls, if any, by calling
55 ldap_controls_free(3), while invalue must be LDAPControl *const
56 *; the library duplicates the controls passed via invalue.
57 LDAP_OPT_CONNECT_ASYNC
59 Sets/gets the status of the asynchronous connect flag. invalue
60 should either be LDAP_OPT_OFF or LDAP_OPT_ON; outvalue must be
61 int *. When set, the library will call connect(2) and return,
62 without waiting for response. This leaves the handle in a con‐
63 necting state. Subsequent calls to library routines will poll
64 for completion of the connect before performing further opera‐
65 tions. As a consequence, library calls that need to establish a
66 connection with a DSA do not block even for the network timeout
67 (option LDAP_OPT_NETWORK_TIMEOUT). This option is OpenLDAP spe‐
68 cific.
69 LDAP_OPT_CONNECT_CB
71 This option allows to set a connect callback. invalue must be a
72 const struct ldap_conncb *. Callbacks are executed in last in-
73 first served order. Handle-specific callbacks are executed
74 first, followed by global ones. Right before freeing the call‐
75 back structure, the lc_del callback handler is passed a NULL
76 Sockbuf. Calling ldap_get_option(3) for this option removes the
77 callback whose pointer matches outvalue. This option is OpenL‐
78 DAP specific.
79 LDAP_OPT_DEBUG_LEVEL
81 Sets/gets the debug level of the client library. invalue must
82 be a const int *; outvalue must be a int *. Valid debug levels
83 are LDAP_DEBUG_ANY, LDAP_DEBUG_ARGS, LDAP_DEBUG_BER, LDAP_DE‐
84 BUG_CONNS, LDAP_DEBUG_NONE, LDAP_DEBUG_PACKETS, LDAP_DE‐
85 BUG_PARSE, and LDAP_DEBUG_TRACE. This option is OpenLDAP spe‐
86 cific.
87 LDAP_OPT_DEFBASE
89 Sets/gets a string containing the DN to be used as default base
90 for search operations. outvalue must be a char **, and the
91 caller is responsible of freeing the returned string by calling
92 ldap_memfree(3), while invalue must be a const char *; the li‐
93 brary duplicates the corresponding string. This option is
94 OpenLDAP specific.
95 LDAP_OPT_DEREF
97 Sets/gets the value that defines when alias dereferencing must
98 occur. invalue must be const int *; outvalue must be int *.
99 They cannot be NULL. The value of *invalue should be one of
100 LDAP_DEREF_NEVER (the default), LDAP_DEREF_SEARCHING,
101 LDAP_DEREF_FINDING, or LDAP_DEREF_ALWAYS. Note that this has
102 ever been the only means to determine alias dereferencing within
103 search operations.
104 LDAP_OPT_DESC
106 Returns the file descriptor associated to the socket buffer of
107 the LDAP handle passed in as ld; outvalue must be a int *. This
108 is a read-only, handle-specific option.
109 LDAP_OPT_DIAGNOSTIC_MESSAGE
111 Sets/gets a string containing the error string associated to the
112 LDAP handle. This option was formerly known as LDAP_OPT_ER‐
113 ROR_STRING. outvalue must be a char **, and the caller is re‐
114 sponsible of freeing the returned string by calling ldap_mem‐
115 free(3), while invalue must be a char *; the library duplicates
116 the corresponding string.
117 LDAP_OPT_HOST_NAME
119 Sets/gets a space-separated list of hosts to be contacted by the
120 library when trying to establish a connection. This is now dep‐
121 recated in favor of LDAP_OPT_URI. outvalue must be a char **,
122 and the caller is responsible of freeing the resulting string by
123 calling ldap_memfree(3), while invalue must be a const char *;
124 the library duplicates the corresponding string.
125 LDAP_OPT_MATCHED_DN
127 Sets/gets a string containing the matched DN associated to the
128 LDAP handle. outvalue must be a char **, and the caller is re‐
129 sponsible of freeing the returned string by calling ldap_mem‐
130 free(3), while invalue must be a const char *; the library du‐
131 plicates the corresponding string.
132 LDAP_OPT_NETWORK_TIMEOUT
134 Sets/gets the network timeout value after which poll(2)/se‐
135 lect(2) following a connect(2) returns in case of no activity.
136 outvalue must be a struct timeval ** (the caller has to free
137 *outvalue using ldap_memfree(3)), and invalue must be a const
138 struct timeval *. They cannot be NULL. Using a struct with sec‐
139 onds set to -1 results in an infinite timeout, which is the de‐
140 fault. This option is OpenLDAP specific.
141 LDAP_OPT_PROTOCOL_VERSION
143 Sets/gets the protocol version. outvalue and invalue must be
144 int *.
145 LDAP_OPT_REFERRAL_URLS
147 Sets/gets an array containing the referral URIs associated to
148 the LDAP handle. outvalue must be a char ***, and the caller is
149 responsible of freeing the returned string by calling
150 ldap_memvfree(3), while invalue must be a NULL-terminated char
151 *const *; the library duplicates the corresponding string. This
152 option is OpenLDAP specific.
153 LDAP_OPT_REFERRALS
155 Determines whether the library should implicitly chase referrals
156 or not. invalue must be const int *; its value should either be
157 LDAP_OPT_OFF or LDAP_OPT_ON. outvalue must be int *.
158 LDAP_OPT_RESTART
160 Determines whether the library should implicitly restart connec‐
161 tions (FIXME). invalue must be const int *; its value should
162 either be LDAP_OPT_OFF or LDAP_OPT_ON. outvalue must be int *.
163 LDAP_OPT_RESULT_CODE
165 Sets/gets the LDAP result code associated to the handle. This
166 option was formerly known as LDAP_OPT_ERROR_NUMBER. invalue
167 must be a const int *. outvalue must be a int *.
168 LDAP_OPT_SERVER_CONTROLS
170 Sets/gets the server-side controls to be used for all opera‐
171 tions. This is now deprecated as modern LDAP C API provides re‐
172 placements for all main operations which accepts server-side
173 controls as explicit arguments; see for example
174 ldap_search_ext(3), ldap_add_ext(3), ldap_modify_ext(3) and so
175 on. outvalue must be LDAPControl ***, and the caller is respon‐
176 sible of freeing the returned controls, if any, by calling
177 ldap_controls_free(3), while invalue must be LDAPControl *const
178 *; the library duplicates the controls passed via invalue.
179 LDAP_OPT_SESSION_REFCNT
181 Returns the reference count associated with the LDAP handle
182 passed in as ld; outvalue must be a int *. This is a read-only,
183 handle-specific option. This option is OpenLDAP specific.
184 LDAP_OPT_SIZELIMIT
186 Sets/gets the value that defines the maximum number of entries
187 to be returned by a search operation. invalue must be const int
188 *, while outvalue must be int *; They cannot be NULL.
189 LDAP_OPT_SOCKBUF
191 Returns a pointer to the socket buffer of the LDAP handle passed
192 in as ld; outvalue must be a Sockbuf **. This is a read-only,
193 handle-specific option. This option is OpenLDAP specific.
194 LDAP_OPT_SOCKET_BIND_ADDRESSES
196 Sets/gets a space-separated list of IP Addresses used as binding
197 interface to remote server when trying to establish a connec‐
198 tion. Only one valid IPv4 address and/or one valid IPv6 address
199 are allowed in the list. outvalue must be a char **, and the
200 caller is responsible of freeing the returned string by calling
201 ldap_memfree(3), while invalue must be a const char *; the li‐
202 brary duplicates the corresponding string.
203 LDAP_OPT_TIMELIMIT
205 Sets/gets the value that defines the time limit after which a
206 search operation should be terminated by the server. invalue
207 must be const int *, while outvalue must be int *, and they can‐
208 not be NULL.
209 LDAP_OPT_TIMEOUT
211 Sets/gets a timeout value for the synchronous API calls. out‐
212 value must be a struct timeval ** (the caller has to free *out‐
213 value using ldap_memfree(3)), and invalue must be a struct
214 timeval *, and they cannot be NULL. Using a struct with seconds
215 set to -1 results in an infinite timeout, which is the default.
216 This option is OpenLDAP specific.
217 LDAP_OPT_URI
219 Sets/gets a comma- or space-separated list of URIs to be con‐
220 tacted by the library when trying to establish a connection.
221 outvalue must be a char **, and the caller is responsible of
222 freeing the resulting string by calling ldap_memfree(3), while
223 invalue must be a const char *; the library parses the string
224 into a list of LDAPURLDesc structures, so the invocation of
225 ldap_set_option(3) may fail if URL parsing fails. URIs may only
226 contain the schema, the host, and the port fields. This option
227 is OpenLDAP specific.
228 LDAP_OPT_KEEPCONN
230 Instructs ldap_result(3) to keep the connection open on read er‐
231 ror or if Notice of Disconnection is received. In these cases,
232 the connection should be closed by the caller. This option is
233 OpenLDAP specific.
234 LDAP_OPT_TCP_USER_TIMEOUT
236 Allows to configure TCP_USER_TIMEOUT in milliseconds on the con‐
237 nection, overriding the operating system setting. This option
238 is OpenLDAP specific and supported only on Linux 2.6.37 or
239 higher. invalue must be a const unsigned int *; outvalue must
240 be an unsigned int *.
241
244 The SASL options are OpenLDAP specific and unless otherwise noted, re‐
245 quire an LDAP handle to be passed.
246 LDAP_OPT_X_SASL_AUTHCID
248 Gets the SASL authentication identity; outvalue must be a char
249 **, its content needs to be freed by the caller using ldap_mem‐
250 free(3).
251 LDAP_OPT_X_SASL_AUTHZID
253 Gets the SASL authorization identity; outvalue must be a char
254 **, its content needs to be freed by the caller using ldap_mem‐
255 free(3).
256 LDAP_OPT_X_SASL_MAXBUFSIZE
258 Gets/sets SASL maximum buffer size; invalue must be const
259 ber_len_t *, while outvalue must be ber_len_t *. See also
260 LDAP_OPT_X_SASL_SECPROPS.
261 LDAP_OPT_X_SASL_MECH
263 Gets the SASL mechanism; outvalue must be a char **, its content
264 needs to be freed by the caller using ldap_memfree(3).
265 LDAP_OPT_X_SASL_MECHLIST
267 Gets the list of the available mechanisms, in form of a NULL-
268 terminated array of strings; outvalue must be char ***. The
269 caller must not free or otherwise muck with it. This option can
270 be used globally.
271 LDAP_OPT_X_SASL_NOCANON
273 Sets/gets the NOCANON flag. When unset, the hostname is canoni‐
274 calized. invalue must be const int *; its value should either
275 be LDAP_OPT_OFF or LDAP_OPT_ON. outvalue must be int *.
276 LDAP_OPT_X_SASL_REALM
278 Gets the SASL realm; outvalue must be a char **, its content
279 needs to be freed by the caller using ldap_memfree(3).
280 LDAP_OPT_X_SASL_SECPROPS
282 Sets the SASL secprops; invalue must be a char *, containing a
283 comma-separated list of properties. Legal values are: none, no‐
284 dict, noplain, noactive, passcred, forwardsec, noanonymous,
285 minssf=<minssf>, maxssf=<maxssf>, maxbufsize=<maxbufsize>.
286 LDAP_OPT_X_SASL_SSF
288 Gets the SASL SSF; outvalue must be a ber_len_t *.
289 LDAP_OPT_X_SASL_SSF_EXTERNAL
291 Sets the SASL SSF value related to an authentication performed
292 using an EXTERNAL mechanism; invalue must be a const ber_len_t
293 *.
294 LDAP_OPT_X_SASL_SSF_MAX
296 Gets/sets SASL maximum SSF; invalue must be const ber_len_t *,
297 while outvalue must be ber_len_t *. See also
298 LDAP_OPT_X_SASL_SECPROPS.
299 LDAP_OPT_X_SASL_SSF_MIN
301 Gets/sets SASL minimum SSF; invalue must be const ber_len_t *,
302 while outvalue must be ber_len_t *. See also
303 LDAP_OPT_X_SASL_SECPROPS.
304 LDAP_OPT_X_SASL_USERNAME
306 Gets the SASL username; outvalue must be a char **. Its content
307 needs to be freed by the caller using ldap_memfree(3).
308 LDAP_OPT_X_SASL_CBINDING
310 Sets/gets the channel-binding type to use in SASL, one of
311 LDAP_OPT_X_SASL_CBINDING_NONE (the default),
312 LDAP_OPT_X_SASL_CBINDING_TLS_UNIQUE the "tls-unique" type from
313 RFC 5929. LDAP_OPT_X_SASL_CBINDING_TLS_ENDPOINT the "tls-
314 server-end-point" from RFC 5929, compatible with Windows. in‐
315 value must be const int *; outvalue must be int *.
316
318 The TCP options are OpenLDAP specific. Mainly intended for use with
319 Linux, they may not be portable.
320 LDAP_OPT_X_KEEPALIVE_IDLE
322 Sets/gets the number of seconds a connection needs to remain
323 idle before TCP starts sending keepalive probes. invalue must
324 be const int *; outvalue must be int *.
325 LDAP_OPT_X_KEEPALIVE_PROBES
327 Sets/gets the maximum number of keepalive probes TCP should send
328 before dropping the connection. invalue must be const int *;
329 outvalue must be int *.
330 LDAP_OPT_X_KEEPALIVE_INTERVAL
332 Sets/gets the interval in seconds between individual keepalive
333 probes. invalue must be const int *; outvalue must be int *.
334
336 The TLS options are OpenLDAP specific.
337 LDAP_OPT_X_TLS_CACERTDIR
339 Sets/gets the path of the directories containing CA certifi‐
340 cates. Multiple directories may be specified, separated by a
341 semi-colon. invalue must be const char *; outvalue must be char
342 **, and its contents need to be freed by the caller using
343 ldap_memfree(3).
344 LDAP_OPT_X_TLS_CACERTFILE
346 Sets/gets the full-path of the CA certificate file. invalue
347 must be const char *; outvalue must be char **, and its contents
348 need to be freed by the caller using ldap_memfree(3).
349 LDAP_OPT_X_TLS_CERTFILE
351 Sets/gets the full-path of the certificate file. invalue must
352 be const char *; outvalue must be char **, and its contents need
353 to be freed by the caller using ldap_memfree(3).
354 LDAP_OPT_X_TLS_CIPHER
356 Gets the cipher being used on an established TLS session. out‐
357 value must be char **, and its contents need to be freed by the
358 caller using ldap_memfree(3).
359 LDAP_OPT_X_TLS_CIPHER_SUITE
361 Sets/gets the allowed cipher suite. invalue must be const char
362 *; outvalue must be char **, and its contents need to be freed
363 by the caller using ldap_memfree(3).
364 LDAP_OPT_X_TLS_CONNECT_ARG
366 Sets/gets the connection callback argument. invalue must be
367 const void *; outvalue must be void **.
368 LDAP_OPT_X_TLS_CONNECT_CB
370 Sets/gets the connection callback handle. invalue must be const
371 LDAP_TLS_CONNECT_CB *; outvalue must be LDAP_TLS_CONNECT_CB **.
372 LDAP_OPT_X_TLS_CRLCHECK
374 Sets/gets the CRL evaluation strategy, one of
375 LDAP_OPT_X_TLS_CRL_NONE, LDAP_OPT_X_TLS_CRL_PEER, or
376 LDAP_OPT_X_TLS_CRL_ALL. invalue must be const int *; outvalue
377 must be int *. Requires OpenSSL.
378 LDAP_OPT_X_TLS_CRLFILE
380 Sets/gets the full-path of the CRL file. invalue must be const
381 char *; outvalue must be char **, and its contents need to be
382 freed by the caller using ldap_memfree(3). This option is only
383 valid for GnuTLS.
384 LDAP_OPT_X_TLS_CTX
386 Sets/gets the TLS library context. New TLS sessions will inherit
387 their default settings from this library context. invalue must
388 be const void *; outvalue must be void **. When using the
389 OpenSSL library this is an SSL_CTX*. When using other crypto li‐
390 braries this is a pointer to an OpenLDAP private structure. Ap‐
391 plications generally should not use this option or attempt to
392 manipulate this structure.
393 LDAP_OPT_X_TLS_DHFILE
395 Gets/sets the full-path of the file containing the parameters
396 for Diffie-Hellman ephemeral key exchange. invalue must be
397 const char *; outvalue must be char **, and its contents need to
398 be freed by the caller using ldap_memfree(3).
399 LDAP_OPT_X_TLS_ECNAME
401 Gets/sets the name of the curve(s) used for elliptic curve key
402 exchanges. invalue must be const char *; outvalue must be char
403 **, and its contents need to be freed by the caller using
404 ldap_memfree(3). Ignored by GnuTLS. In GnuTLS a curve may be
405 selected in the cipher suite specification.
406 LDAP_OPT_X_TLS_KEYFILE
408 Sets/gets the full-path of the certificate key file. invalue
409 must be const char *; outvalue must be char **, and its contents
410 need to be freed by the caller using ldap_memfree(3).
411 LDAP_OPT_X_TLS_NEWCTX
413 Instructs the library to create a new TLS library context. in‐
414 value must be const int *. A non-zero value pointed to by in‐
415 value tells the library to create a context for a server.
416 LDAP_OPT_X_TLS_PEERCERT
418 Gets the peer's certificate in DER format from an established
419 TLS session. outvalue must be struct berval *, and the data it
420 returns needs to be freed by the caller using ldap_memfree(3).
421 LDAP_OPT_X_TLS_PROTOCOL_MAX
423 Sets/gets the maximum protocol version. invalue must be const
424 int *; outvalue must be int *.
425 LDAP_OPT_X_TLS_PROTOCOL_MIN
427 Sets/gets the minimum protocol version. invalue must be const
428 int *; outvalue must be int *.
429 LDAP_OPT_X_TLS_RANDOM_FILE
431 Sets/gets the random file when /dev/random and /dev/urandom are
432 not available. invalue must be const char *; outvalue must be
433 char **, and its contents need to be freed by the caller using
434 ldap_memfree(3). Ignored by GnuTLS older than version 2.2.
435 LDAP_OPT_X_TLS_REQUIRE_CERT
437 Sets/gets the peer certificate checking strategy, one of
438 LDAP_OPT_X_TLS_NEVER, LDAP_OPT_X_TLS_HARD, LDAP_OPT_X_TLS_DE‐
439 MAND, LDAP_OPT_X_TLS_ALLOW, LDAP_OPT_X_TLS_TRY.
440 LDAP_OPT_X_TLS_REQUIRE_SAN
442 Sets/gets the peer certificate subjectAlternativeName checking
443 strategy, one of LDAP_OPT_X_TLS_NEVER, LDAP_OPT_X_TLS_HARD,
444 LDAP_OPT_X_TLS_DEMAND, LDAP_OPT_X_TLS_ALLOW, LDAP_OPT_X_TLS_TRY.
445 LDAP_OPT_X_TLS_SSL_CTX
447 Gets the TLS session context associated with this handle. out‐
448 value must be void **. When using the OpenSSL library this is
449 an SSL*. When using other crypto libraries this is a pointer to
450 an OpenLDAP private structure. Applications generally should
451 not use this option.
452 LDAP_OPT_X_TLS_VERSION
454 Gets the TLS version being used on an established TLS session.
455 outvalue must be char **, and its contents need to be freed by
456 the caller using ldap_memfree(3).
457 LDAP_OPT_X_TLS_PEERKEY_HASH
459 Sets the (public) key that the application expects the peer to
460 be using. invalue must be const char * containing the base64
461 encoding of the expected peer's key or in the format
462 <hashalg>:<peerkey hash base64 encoded> where as a TLS session
463 is established, the library will hash the peer's key with the
464 provided hash algorithm and compare it with value provided and
465 will only allow the session to continue if they match. This hap‐
466 pens regardless of certificate checking strategy. The list of
467 supported hashalg values depends on the crypto library used,
468 check its documentation to get a list.
469
471 On success, the functions return LDAP_OPT_SUCCESS, while they may re‐
472 turn LDAP_OPT_ERROR to indicate a generic option handling error. Occa‐
473 sionally, more specific errors can be returned, like LDAP_NO_MEMORY to
474 indicate a failure in memory allocation.
475
477 The LDAP libraries with the LDAP_OPT_REFERRALS option set to
478 LDAP_OPT_ON (default value) automatically follow referrals using an
479 anonymous bind. Application developers are encouraged to either imple‐
480 ment consistent referral chasing features, or explicitly disable refer‐
481 ral chasing by setting that option to LDAP_OPT_OFF.
482 The protocol version used by the library defaults to LDAPv2 (now his‐
484 toric), which corresponds to the LDAP_VERSION2 macro. Application de‐
485 velopers are encouraged to explicitly set LDAP_OPT_PROTOCOL_VERSION to
486 LDAPv3, using the LDAP_VERSION3 macro, or to allow users to select the
487 protocol version.
488
490 ldap(3), ldap_error(3), RFC 4422 (http://www.rfc-editor.org),
491
493 OpenLDAP Software is developed and maintained by The OpenLDAP Project
494 <http://www.openldap.org/>. OpenLDAP Software is derived from the Uni‐
495 versity of Michigan LDAP 3.3 Release.
496OpenLDAP 2.6.6 2023/07/31 LDAP_GET_OPTION(3)