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.
245 LDAP_OPT_X_SASL_AUTHCID
247 Gets the SASL authentication identity; outvalue must be a char
248 **, its content needs to be freed by the caller using ldap_mem‐
249 free(3).
250 LDAP_OPT_X_SASL_AUTHZID
252 Gets the SASL authorization identity; outvalue must be a char
253 **, its content needs to be freed by the caller using ldap_mem‐
254 free(3).
255 LDAP_OPT_X_SASL_MAXBUFSIZE
257 Gets/sets SASL maximum buffer size; invalue must be const
258 ber_len_t *, while outvalue must be ber_len_t *. See also
259 LDAP_OPT_X_SASL_SECPROPS.
260 LDAP_OPT_X_SASL_MECH
262 Gets the SASL mechanism; outvalue must be a char **, its content
263 needs to be freed by the caller using ldap_memfree(3).
264 LDAP_OPT_X_SASL_MECHLIST
266 Gets the list of the available mechanisms, in form of a NULL-
267 terminated array of strings; outvalue must be char ***. The
268 caller must not free or otherwise muck with it.
269 LDAP_OPT_X_SASL_NOCANON
271 Sets/gets the NOCANON flag. When unset, the hostname is canoni‐
272 calized. invalue must be const int *; its value should either
273 be LDAP_OPT_OFF or LDAP_OPT_ON. outvalue must be int *.
274 LDAP_OPT_X_SASL_REALM
276 Gets the SASL realm; outvalue must be a char **, its content
277 needs to be freed by the caller using ldap_memfree(3).
278 LDAP_OPT_X_SASL_SECPROPS
280 Sets the SASL secprops; invalue must be a char *, containing a
281 comma-separated list of properties. Legal values are: none, no‐
282 dict, noplain, noactive, passcred, forwardsec, noanonymous,
283 minssf=<minssf>, maxssf=<maxssf>, maxbufsize=<maxbufsize>.
284 LDAP_OPT_X_SASL_SSF
286 Gets the SASL SSF; outvalue must be a ber_len_t *.
287 LDAP_OPT_X_SASL_SSF_EXTERNAL
289 Sets the SASL SSF value related to an authentication performed
290 using an EXTERNAL mechanism; invalue must be a const ber_len_t
291 *.
292 LDAP_OPT_X_SASL_SSF_MAX
294 Gets/sets SASL maximum SSF; invalue must be const ber_len_t *,
295 while outvalue must be ber_len_t *. See also
296 LDAP_OPT_X_SASL_SECPROPS.
297 LDAP_OPT_X_SASL_SSF_MIN
299 Gets/sets SASL minimum SSF; invalue must be const ber_len_t *,
300 while outvalue must be ber_len_t *. See also
301 LDAP_OPT_X_SASL_SECPROPS.
302 LDAP_OPT_X_SASL_USERNAME
304 Gets the SASL username; outvalue must be a char **. Its content
305 needs to be freed by the caller using ldap_memfree(3).
306 LDAP_OPT_X_SASL_CBINDING
308 Sets/gets the channel-binding type to use in SASL, one of
309 LDAP_OPT_X_SASL_CBINDING_NONE (the default),
310 LDAP_OPT_X_SASL_CBINDING_TLS_UNIQUE the "tls-unique" type from
311 RFC 5929. LDAP_OPT_X_SASL_CBINDING_TLS_ENDPOINT the "tls-
312 server-end-point" from RFC 5929, compatible with Windows. in‐
313 value must be const int *; outvalue must be int *.
314
316 The TCP options are OpenLDAP specific. Mainly intended for use with
317 Linux, they may not be portable.
318 LDAP_OPT_X_KEEPALIVE_IDLE
320 Sets/gets the number of seconds a connection needs to remain
321 idle before TCP starts sending keepalive probes. invalue must
322 be const int *; outvalue must be int *.
323 LDAP_OPT_X_KEEPALIVE_PROBES
325 Sets/gets the maximum number of keepalive probes TCP should send
326 before dropping the connection. invalue must be const int *;
327 outvalue must be int *.
328 LDAP_OPT_X_KEEPALIVE_INTERVAL
330 Sets/gets the interval in seconds between individual keepalive
331 probes. invalue must be const int *; outvalue must be int *.
332
334 The TLS options are OpenLDAP specific.
335 LDAP_OPT_X_TLS_CACERTDIR
337 Sets/gets the path of the directories containing CA certifi‐
338 cates. Multiple directories may be specified, separated by a
339 semi-colon. invalue must be const char *; outvalue must be char
340 **, and its contents need to be freed by the caller using
341 ldap_memfree(3).
342 LDAP_OPT_X_TLS_CACERTFILE
344 Sets/gets the full-path of the CA certificate file. invalue
345 must be const char *; outvalue must be char **, and its contents
346 need to be freed by the caller using ldap_memfree(3).
347 LDAP_OPT_X_TLS_CERTFILE
349 Sets/gets the full-path of the certificate file. invalue must
350 be const char *; outvalue must be char **, and its contents need
351 to be freed by the caller using ldap_memfree(3).
352 LDAP_OPT_X_TLS_CIPHER
354 Gets the cipher being used on an established TLS session. out‐
355 value must be char **, and its contents need to be freed by the
356 caller using ldap_memfree(3).
357 LDAP_OPT_X_TLS_CIPHER_SUITE
359 Sets/gets the allowed cipher suite. invalue must be const char
360 *; outvalue must be char **, and its contents need to be freed
361 by the caller using ldap_memfree(3).
362 LDAP_OPT_X_TLS_CONNECT_ARG
364 Sets/gets the connection callback argument. invalue must be
365 const void *; outvalue must be void **.
366 LDAP_OPT_X_TLS_CONNECT_CB
368 Sets/gets the connection callback handle. invalue must be const
369 LDAP_TLS_CONNECT_CB *; outvalue must be LDAP_TLS_CONNECT_CB **.
370 LDAP_OPT_X_TLS_CRLCHECK
372 Sets/gets the CRL evaluation strategy, one of
373 LDAP_OPT_X_TLS_CRL_NONE, LDAP_OPT_X_TLS_CRL_PEER, or
374 LDAP_OPT_X_TLS_CRL_ALL. invalue must be const int *; outvalue
375 must be int *. Requires OpenSSL.
376 LDAP_OPT_X_TLS_CRLFILE
378 Sets/gets the full-path of the CRL file. invalue must be const
379 char *; outvalue must be char **, and its contents need to be
380 freed by the caller using ldap_memfree(3). This option is only
381 valid for GnuTLS.
382 LDAP_OPT_X_TLS_CTX
384 Sets/gets the TLS library context. New TLS sessions will inherit
385 their default settings from this library context. invalue must
386 be const void *; outvalue must be void **. When using the
387 OpenSSL library this is an SSL_CTX*. When using other crypto li‐
388 braries this is a pointer to an OpenLDAP private structure. Ap‐
389 plications generally should not use this option or attempt to
390 manipulate this structure.
391 LDAP_OPT_X_TLS_DHFILE
393 Gets/sets the full-path of the file containing the parameters
394 for Diffie-Hellman ephemeral key exchange. invalue must be
395 const char *; outvalue must be char **, and its contents need to
396 be freed by the caller using ldap_memfree(3).
397 LDAP_OPT_X_TLS_ECNAME
399 Gets/sets the name of the curve(s) used for elliptic curve key
400 exchanges. invalue must be const char *; outvalue must be char
401 **, and its contents need to be freed by the caller using
402 ldap_memfree(3). Ignored by GnuTLS. In GnuTLS a curve may be
403 selected in the cipher suite specification.
404 LDAP_OPT_X_TLS_KEYFILE
406 Sets/gets the full-path of the certificate key file. invalue
407 must be const char *; outvalue must be char **, and its contents
408 need to be freed by the caller using ldap_memfree(3).
409 LDAP_OPT_X_TLS_NEWCTX
411 Instructs the library to create a new TLS library context. in‐
412 value must be const int *. A non-zero value pointed to by in‐
413 value tells the library to create a context for a server.
414 LDAP_OPT_X_TLS_PEERCERT
416 Gets the peer's certificate in DER format from an established
417 TLS session. outvalue must be struct berval *, and the data it
418 returns needs to be freed by the caller using ldap_memfree(3).
419 LDAP_OPT_X_TLS_PROTOCOL_MAX
421 Sets/gets the maximum protocol version. invalue must be const
422 int *; outvalue must be int *.
423 LDAP_OPT_X_TLS_PROTOCOL_MIN
425 Sets/gets the minimum protocol version. invalue must be const
426 int *; outvalue must be int *.
427 LDAP_OPT_X_TLS_RANDOM_FILE
429 Sets/gets the random file when /dev/random and /dev/urandom are
430 not available. invalue must be const char *; outvalue must be
431 char **, and its contents need to be freed by the caller using
432 ldap_memfree(3). Ignored by GnuTLS older than version 2.2.
433 LDAP_OPT_X_TLS_REQUIRE_CERT
435 Sets/gets the peer certificate checking strategy, one of
436 LDAP_OPT_X_TLS_NEVER, LDAP_OPT_X_TLS_HARD, LDAP_OPT_X_TLS_DE‐
437 MAND, LDAP_OPT_X_TLS_ALLOW, LDAP_OPT_X_TLS_TRY.
438 LDAP_OPT_X_TLS_REQUIRE_SAN
440 Sets/gets the peer certificate subjectAlternativeName checking
441 strategy, one of LDAP_OPT_X_TLS_NEVER, LDAP_OPT_X_TLS_HARD,
442 LDAP_OPT_X_TLS_DEMAND, LDAP_OPT_X_TLS_ALLOW, LDAP_OPT_X_TLS_TRY.
443 LDAP_OPT_X_TLS_SSL_CTX
445 Gets the TLS session context associated with this handle. out‐
446 value must be void **. When using the OpenSSL library this is
447 an SSL*. When using other crypto libraries this is a pointer to
448 an OpenLDAP private structure. Applications generally should
449 not use this option.
450 LDAP_OPT_X_TLS_VERSION
452 Gets the TLS version being used on an established TLS session.
453 outvalue must be char **, and its contents need to be freed by
454 the caller using ldap_memfree(3).
455 LDAP_OPT_X_TLS_PEERKEY_HASH
457 Sets the (public) key that the application expects the peer to
458 be using. invalue must be const char * containing the base64
459 encoding of the expected peer's key or in the format
460 <hashalg>:<peerkey hash base64 encoded> where as a TLS session
461 is established, the library will hash the peer's key with the
462 provided hash algorithm and compare it with value provided and
463 will only allow the session to continue if they match. This hap‐
464 pens regardless of certificate checking strategy. The list of
465 supported hashalg values depends on the crypto library used,
466 check its documentation to get a list.
467
469 On success, the functions return LDAP_OPT_SUCCESS, while they may re‐
470 turn LDAP_OPT_ERROR to indicate a generic option handling error. Occa‐
471 sionally, more specific errors can be returned, like LDAP_NO_MEMORY to
472 indicate a failure in memory allocation.
473
475 The LDAP libraries with the LDAP_OPT_REFERRALS option set to
476 LDAP_OPT_ON (default value) automatically follow referrals using an
477 anonymous bind. Application developers are encouraged to either imple‐
478 ment consistent referral chasing features, or explicitly disable refer‐
479 ral chasing by setting that option to LDAP_OPT_OFF.
480 The protocol version used by the library defaults to LDAPv2 (now his‐
482 toric), which corresponds to the LDAP_VERSION2 macro. Application de‐
483 velopers are encouraged to explicitly set LDAP_OPT_PROTOCOL_VERSION to
484 LDAPv3, using the LDAP_VERSION3 macro, or to allow users to select the
485 protocol version.
486
488 ldap(3), ldap_error(3), RFC 4422 (http://www.rfc-editor.org),
489
491 OpenLDAP Software is developed and maintained by The OpenLDAP Project
492 <http://www.openldap.org/>. OpenLDAP Software is derived from the Uni‐
493 versity of Michigan LDAP 3.3 Release.
494OpenLDAP 2.6.2 2022/05/04 LDAP_GET_OPTION(3)