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), and invalue must be a const struct timeval *. They
138 cannot be NULL. Using a struct with seconds set to -1 results in
139 an infinite timeout, which is the default. This option is
140 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_TIMELIMIT
196 Sets/gets the value that defines the time limit after which a
197 search operation should be terminated by the server. invalue
198 must be const int *, while outvalue must be int *, and they can‐
199 not be NULL.
200 LDAP_OPT_TIMEOUT
202 Sets/gets a timeout value for the synchronous API calls. out‐
203 value must be a struct timeval ** (the caller has to free *out‐
204 value), and invalue must be a struct timeval *, and they cannot
205 be NULL. Using a struct with seconds set to -1 results in an in‐
206 finite timeout, which is the default. This option is OpenLDAP
207 specific.
208 LDAP_OPT_URI
210 Sets/gets a comma- or space-separated list of URIs to be con‐
211 tacted by the library when trying to establish a connection.
212 outvalue must be a char **, and the caller is responsible of
213 freeing the resulting string by calling ldap_memfree(3), while
214 invalue must be a const char *; the library parses the string
215 into a list of LDAPURLDesc structures, so the invocation of
216 ldap_set_option(3) may fail if URL parsing fails. URIs may only
217 contain the schema, the host, and the port fields. This option
218 is OpenLDAP specific.
219
221 The SASL options are OpenLDAP specific.
222 LDAP_OPT_X_SASL_AUTHCID
224 Gets the SASL authentication identity; outvalue must be a char
225 **, its content needs to be freed by the caller using ldap_mem‐
226 free(3).
227 LDAP_OPT_X_SASL_AUTHZID
229 Gets the SASL authorization identity; outvalue must be a char
230 **, its content needs to be freed by the caller using ldap_mem‐
231 free(3).
232 LDAP_OPT_X_SASL_MAXBUFSIZE
234 Gets/sets SASL maximum buffer size; invalue must be const
235 ber_len_t *, while outvalue must be ber_len_t *. See also
236 LDAP_OPT_X_SASL_SECPROPS.
237 LDAP_OPT_X_SASL_MECH
239 Gets the SASL mechanism; outvalue must be a char **, its content
240 needs to be freed by the caller using ldap_memfree(3).
241 LDAP_OPT_X_SASL_MECHLIST
243 Gets the list of the available mechanisms, in form of a NULL-
244 terminated array of strings; outvalue must be char ***. The
245 caller must not free or otherwise muck with it.
246 LDAP_OPT_X_SASL_NOCANON
248 Sets/gets the NOCANON flag. When unset, the hostname is canoni‐
249 calized. invalue must be const int *; its value should either
250 be LDAP_OPT_OFF or LDAP_OPT_ON. outvalue must be int *.
251 LDAP_OPT_X_SASL_REALM
253 Gets the SASL realm; outvalue must be a char **, its content
254 needs to be freed by the caller using ldap_memfree(3).
255 LDAP_OPT_X_SASL_SECPROPS
257 Sets the SASL secprops; invalue must be a char *, containing a
258 comma-separated list of properties. Legal values are: none, no‐
259 dict, noplain, noactive, passcred, forwardsec, noanonymous,
260 minssf=<minssf>, maxssf=<maxssf>, maxbufsize=<maxbufsize>.
261 LDAP_OPT_X_SASL_SSF
263 Gets the SASL SSF; outvalue must be a ber_len_t *.
264 LDAP_OPT_X_SASL_SSF_EXTERNAL
266 Sets the SASL SSF value related to an authentication performed
267 using an EXTERNAL mechanism; invalue must be a const ber_len_t
268 *.
269 LDAP_OPT_X_SASL_SSF_MAX
271 Gets/sets SASL maximum SSF; invalue must be const ber_len_t *,
272 while outvalue must be ber_len_t *. See also
273 LDAP_OPT_X_SASL_SECPROPS.
274 LDAP_OPT_X_SASL_SSF_MIN
276 Gets/sets SASL minimum SSF; invalue must be const ber_len_t *,
277 while outvalue must be ber_len_t *. See also
278 LDAP_OPT_X_SASL_SECPROPS.
279 LDAP_OPT_X_SASL_USERNAME
281 Gets the SASL username; outvalue must be a char **. Its content
282 needs to be freed by the caller using ldap_memfree(3).
283 LDAP_OPT_X_SASL_CBINDING Sets/gets the channel-binding type to
284 use in SASL, one of LDAP_OPT_X_SASL_CBINDING_NONE (the default),
285 LDAP_OPT_X_SASL_CBINDING_TLS_UNIQUE the "tls-unique" type from
286 RCF 5929. LDAP_OPT_X_SASL_CBINDING_TLS_ENDPOINT the "tls-
287 server-end-point" from RCF 5929, compatible with Windows. in‐
288 value must be const int *; outvalue must be int *.
289 TCP OPTIONS
292 The TCP options are OpenLDAP specific. Mainly intended for use
293 with Linux, they may not be portable.
294 LDAP_OPT_X_KEEPALIVE_IDLE
296 Sets/gets the number of seconds a connection needs to remain
297 idle before TCP starts sending keepalive probes. invalue must
298 be const int *; outvalue must be int *.
299 LDAP_OPT_X_KEEPALIVE_PROBES
301 Sets/gets the maximum number of keepalive probes TCP should send
302 before dropping the connection. invalue must be const int *;
303 outvalue must be int *.
304 LDAP_OPT_X_KEEPALIVE_INTERVAL
306 Sets/gets the interval in seconds between individual keepalive
307 probes. invalue must be const int *; outvalue must be int *.
308
310 The TLS options are OpenLDAP specific.
311 LDAP_OPT_X_TLS_CACERTDIR
313 Sets/gets the path of the directory containing CA certificates.
314 invalue must be const char *; outvalue must be char **, and its
315 contents need to be freed by the caller using ldap_memfree(3).
316 LDAP_OPT_X_TLS_CACERTFILE
318 Sets/gets the full-path of the CA certificate file. invalue
319 must be const char *; outvalue must be char **, and its contents
320 need to be freed by the caller using ldap_memfree(3).
321 LDAP_OPT_X_TLS_CERTFILE
323 Sets/gets the full-path of the certificate file. invalue must
324 be const char *; outvalue must be char **, and its contents need
325 to be freed by the caller using ldap_memfree(3).
326 LDAP_OPT_X_TLS_CIPHER_SUITE
328 Sets/gets the allowed cipher suite. invalue must be const char
329 *; outvalue must be char **, and its contents need to be freed
330 by the caller using ldap_memfree(3).
331 LDAP_OPT_X_TLS_CONNECT_ARG
333 Sets/gets the connection callback argument. invalue must be
334 const void *; outvalue must be void **.
335 LDAP_OPT_X_TLS_CONNECT_CB
337 Sets/gets the connection callback handle. invalue must be const
338 LDAP_TLS_CONNECT_CB *; outvalue must be LDAP_TLS_CONNECT_CB **.
339 LDAP_OPT_X_TLS_CRLCHECK
341 Sets/gets the CRL evaluation strategy, one of
342 LDAP_OPT_X_TLS_CRL_NONE, LDAP_OPT_X_TLS_CRL_PEER, or
343 LDAP_OPT_X_TLS_CRL_ALL. invalue must be const int *; outvalue
344 must be int *. Requires OpenSSL.
345 LDAP_OPT_X_TLS_CRLFILE
347 Sets/gets the full-path of the CRL file. invalue must be const
348 char *; outvalue must be char **, and its contents need to be
349 freed by the caller using ldap_memfree(3). This option is only
350 valid for GnuTLS.
351 LDAP_OPT_X_TLS_CTX
353 Sets/gets the TLS library context. New TLS sessions will inherit
354 their default settings from this library context. invalue must
355 be const void *; outvalue must be void **. When using the
356 OpenSSL library this is an SSL_CTX*. When using other crypto li‐
357 braries this is a pointer to an OpenLDAP private structure. Ap‐
358 plications generally should not use this option or attempt to
359 manipulate this structure.
360 LDAP_OPT_X_TLS_DHFILE
362 Gets/sets the full-path of the file containing the parameters
363 for Diffie-Hellman ephemeral key exchange. invalue must be
364 const char *; outvalue must be char **, and its contents need to
365 be freed by the caller using ldap_memfree(3). Ignored by GnuTLS
366 and Mozilla NSS.
367 LDAP_OPT_X_TLS_ECNAME
369 Gets/sets the name of the curve(s) used for elliptic curve key
370 exchanges. invalue must be const char *; outvalue must be char
371 **, and its contents need to be freed by the caller using
372 ldap_memfree(3). Ignored by GnuTLS and Mozilla NSS. In GnuTLS a
373 curve may be selected in the cipher suite specification.
374 LDAP_OPT_X_TLS_KEYFILE
376 Sets/gets the full-path of the certificate key file. invalue
377 must be const char *; outvalue must be char **, and its contents
378 need to be freed by the caller using ldap_memfree(3).
379 LDAP_OPT_X_TLS_NEWCTX
381 Instructs the library to create a new TLS library context. in‐
382 value must be const int *. A non-zero value pointed to by in‐
383 value tells the library to create a context for a server.
384 LDAP_OPT_X_TLS_PEERCERT
386 Gets the peer's certificate in DER format from an established
387 TLS session. outvalue must be struct berval *, and the data it
388 returns needs to be freed by the caller using ldap_memfree(3).
389 LDAP_OPT_X_TLS_PROTOCOL_MIN
391 Sets/gets the minimum protocol version. invalue must be const
392 int *; outvalue must be int *.
393 LDAP_OPT_X_TLS_RANDOM_FILE
395 Sets/gets the random file when /dev/random and /dev/urandom are
396 not available. invalue must be const char *; outvalue must be
397 char **, and its contents need to be freed by the caller using
398 ldap_memfree(3). Ignored by GnuTLS older than version 2.2. Ig‐
399 nored by Mozilla NSS.
400 LDAP_OPT_X_TLS_REQUIRE_CERT
402 Sets/gets the peer certificate checking strategy, one of
403 LDAP_OPT_X_TLS_NEVER, LDAP_OPT_X_TLS_HARD, LDAP_OPT_X_TLS_DE‐
404 MAND, LDAP_OPT_X_TLS_ALLOW, LDAP_OPT_X_TLS_TRY.
405 LDAP_OPT_X_TLS_REQUIRE_SAN
407 Sets/gets the peer certificate subjectAlternativeName checking
408 strategy, one of LDAP_OPT_X_TLS_NEVER, LDAP_OPT_X_TLS_HARD,
409 LDAP_OPT_X_TLS_DEMAND, LDAP_OPT_X_TLS_ALLOW, LDAP_OPT_X_TLS_TRY.
410 LDAP_OPT_X_TLS_SSL_CTX
412 Gets the TLS session context associated with this handle. out‐
413 value must be void **. When using the OpenSSL library this is
414 an SSL*. When using other crypto libraries this is a pointer to
415 an OpenLDAP private structure. Applications generally should
416 not use this option.
417
419 On success, the functions return LDAP_OPT_SUCCESS, while they may re‐
420 turn LDAP_OPT_ERROR to indicate a generic option handling error. Occa‐
421 sionally, more specific errors can be returned, like LDAP_NO_MEMORY to
422 indicate a failure in memory allocation.
423
425 The LDAP libraries with the LDAP_OPT_REFERRALS option set to
426 LDAP_OPT_ON (default value) automatically follow referrals using an
427 anonymous bind. Application developers are encouraged to either imple‐
428 ment consistent referral chasing features, or explicitly disable refer‐
429 ral chasing by setting that option to LDAP_OPT_OFF.
430 The protocol version used by the library defaults to LDAPv2 (now his‐
432 toric), which corresponds to the LDAP_VERSION2 macro. Application de‐
433 velopers are encouraged to explicitly set LDAP_OPT_PROTOCOL_VERSION to
434 LDAPv3, using the LDAP_VERSION3 macro, or to allow users to select the
435 protocol version.
436
438 ldap(3), ldap_error(3), RFC 4422 (http://www.rfc-editor.org),
439
441 OpenLDAP Software is developed and maintained by The OpenLDAP Project
442 <http://www.openldap.org/>. OpenLDAP Software is derived from the Uni‐
443 versity of Michigan LDAP 3.3 Release.
444OpenLDAP 2021/06/03 LDAP_GET_OPTION(3)