1LDAP_GET_OPTION(3)         Library Functions Manual         LDAP_GET_OPTION(3)
2
3
4

NAME

6       ldap_get_option, ldap_set_option - LDAP option handling routines
7

LIBRARY

9       OpenLDAP LDAP (libldap, -lldap)
10

SYNOPSIS

12       #include <ldap.h>
13
14       int ldap_get_option(LDAP *ld, int option, void *outvalue);
15
16       int ldap_set_option(LDAP *ld, int option, const void *invalue);
17

DESCRIPTION

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
21       interface,   where   the   type   of  the  value  either  retrieved  by
22       ldap_get_option(3) or set by ldap_set_option(3) is cast to void *.  The
23       actual  type  is  determined based on the value of the option argument.
24       Global options are set/retrieved by passing a NULL  LDAP  handle.  LDAP
25       handles  inherit  their  default  settings  from  the global options in
26       effect at the time the handle is created.
27
28       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
36       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
43              responsible  for  freeing  the elements of the ldapai_extensions
44              array and the array itself using  ldap_memfree(3).   The  caller
45              must  also  free  the  ldapi_vendor_name.   This  is a read-only
46              option.
47
48       LDAP_OPT_CLIENT_CONTROLS
49              Sets/gets the client-side controls to be  used  for  all  opera‐
50              tions.   This  is  now  deprecated as modern LDAP C API provides
51              replacements for all main operations which  accepts  client-side
52              controls    as    explicit    arguments;    see    for   example
53              ldap_search_ext(3), ldap_add_ext(3), ldap_modify_ext(3)  and  so
54              on.  outvalue must be LDAPControl ***, and the caller is respon‐
55              sible of freeing the  returned  controls,  if  any,  by  calling
56              ldap_controls_free(3),  while invalue must be LDAPControl *const
57              *; the library duplicates the controls passed via invalue.
58
59       LDAP_OPT_CONNECT_ASYNC
60              Sets/gets the status of the asynchronous connect flag.   invalue
61              should  either  be LDAP_OPT_OFF or LDAP_OPT_ON; outvalue must be
62              int *.  When set, the library will call connect(2)  and  return,
63              without  waiting for response.  This leaves the handle in a con‐
64              necting state.  Subsequent calls to library routines  will  poll
65              for  completion  of the connect before performing further opera‐
66              tions.  As a consequence, library calls that need to establish a
67              connection  with a DSA do not block even for the network timeout
68              (option LDAP_OPT_NETWORK_TIMEOUT).  This option is OpenLDAP spe‐
69              cific.
70
71       LDAP_OPT_CONNECT_CB
72              This option allows to set a connect callback.  invalue must be a
73              const struct ldap_conncb *.  Callbacks are executed in last  in-
74              first  served  order.   Handle-specific  callbacks  are executed
75              first, followed by global ones.  Right before freeing the  call‐
76              back  structure,  the  lc_del  callback handler is passed a NULL
77              Sockbuf.  Calling ldap_get_option(3) for this option removes the
78              callback  whose pointer matches outvalue.  This option is OpenL‐
79              DAP specific.
80
81       LDAP_OPT_DEBUG_LEVEL
82              Sets/gets the debug level of the client library.   invalue  must
83              be  a const int *; outvalue must be a int *.  Valid debug levels
84              are     LDAP_DEBUG_ANY,     LDAP_DEBUG_ARGS,     LDAP_DEBUG_BER,
85              LDAP_DEBUG_CONNS,      LDAP_DEBUG_NONE,      LDAP_DEBUG_PACKETS,
86              LDAP_DEBUG_PARSE, and LDAP_DEBUG_TRACE.  This option is OpenLDAP
87              specific.
88
89       LDAP_OPT_DEFBASE
90              Sets/gets  a string containing the DN to be used as default base
91              for search operations.  outvalue must be  a  char  **,  and  the
92              caller  is responsible of freeing the returned string by calling
93              ldap_memfree(3), while invalue must  be  a  const  char  *;  the
94              library  duplicates  the  corresponding  string.  This option is
95              OpenLDAP specific.
96
97       LDAP_OPT_DEREF
98              Sets/gets the value that defines when alias  dereferencing  must
99              occur.   invalue  must  be  const int *; outvalue must be int *.
100              They cannot be NULL.  The value of *invalue  should  be  one  of
101              LDAP_DEREF_NEVER     (the     default),    LDAP_DEREF_SEARCHING,
102              LDAP_DEREF_FINDING, or LDAP_DEREF_ALWAYS.  Note  that  this  has
103              ever been the only means to determine alias dereferencing within
104              search operations.
105
106       LDAP_OPT_DESC
107              Returns the file descriptor associated to the socket  buffer  of
108              the LDAP handle passed in as ld; outvalue must be a int *.  This
109              is a read-only, handle-specific option.
110
111       LDAP_OPT_DIAGNOSTIC_MESSAGE
112              Sets/gets a string containing the error string associated to the
113              LDAP    handle.     This    option   was   formerly   known   as
114              LDAP_OPT_ERROR_STRING.  outvalue must be  a  char  **,  and  the
115              caller  is responsible of freeing the returned string by calling
116              ldap_memfree(3), while invalue must be a  char  *;  the  library
117              duplicates the corresponding string.
118
119       LDAP_OPT_HOST_NAME
120              Sets/gets a space-separated list of hosts to be contacted by the
121              library when trying to establish a connection.  This is now dep‐
122              recated  in  favor of LDAP_OPT_URI.  outvalue must be a char **,
123              and the caller is responsible of freeing the resulting string by
124              calling  ldap_memfree(3),  while invalue must be a const char *;
125              the library duplicates the corresponding string.
126
127       LDAP_OPT_MATCHED_DN
128              Sets/gets a string containing the matched DN associated  to  the
129              LDAP  handle.   outvalue  must  be  a char **, and the caller is
130              responsible of freeing the returned string by calling  ldap_mem‐
131              free(3),  while  invalue  must  be  a  const char *; the library
132              duplicates the corresponding string.
133
134       LDAP_OPT_NETWORK_TIMEOUT
135              Sets/gets   the    network    timeout    value    after    which
136              poll(2)/select(2)  following  a connect(2) returns in case of no
137              activity.  outvalue must be a struct timeval ** (the caller  has
138              to  free  *outvalue), and invalue must be a const struct timeval
139              *.  They cannot be NULL. Using a struct with seconds set  to  -1
140              results  in  an  infinite  timeout,  which is the default.  This
141              option is OpenLDAP specific.
142
143       LDAP_OPT_PROTOCOL_VERSION
144              Sets/gets the protocol version.  outvalue and  invalue  must  be
145              int *.
146
147       LDAP_OPT_REFERRAL_URLS
148              Sets/gets  an  array  containing the referral URIs associated to
149              the LDAP handle.  outvalue must be a char ***, and the caller is
150              responsible   of   freeing   the   returned  string  by  calling
151              ldap_memvfree(3), while invalue must be a  NULL-terminated  char
152              *const *; the library duplicates the corresponding string.  This
153              option is OpenLDAP specific.
154
155       LDAP_OPT_REFERRALS
156              Determines whether the library should implicitly chase referrals
157              or not.  invalue must be const int *; its value should either be
158              LDAP_OPT_OFF or LDAP_OPT_ON.  outvalue must be int *.
159
160       LDAP_OPT_RESTART
161              Determines whether the library should implicitly restart connec‐
162              tions  (FIXME).   invalue  must be const int *; its value should
163              either be LDAP_OPT_OFF or LDAP_OPT_ON.  outvalue must be int *.
164
165       LDAP_OPT_RESULT_CODE
166              Sets/gets the LDAP result code associated to the  handle.   This
167              option  was  formerly  known  as LDAP_OPT_ERROR_NUMBER.  invalue
168              must be a const int *.  outvalue must be a int *.
169
170       LDAP_OPT_SERVER_CONTROLS
171              Sets/gets the server-side controls to be  used  for  all  opera‐
172              tions.   This  is  now  deprecated as modern LDAP C API provides
173              replacements for all main operations which  accepts  server-side
174              controls    as    explicit    arguments;    see    for   example
175              ldap_search_ext(3), ldap_add_ext(3), ldap_modify_ext(3)  and  so
176              on.  outvalue must be LDAPControl ***, and the caller is respon‐
177              sible of freeing the  returned  controls,  if  any,  by  calling
178              ldap_controls_free(3),  while invalue must be LDAPControl *const
179              *; the library duplicates the controls passed via invalue.
180
181       LDAP_OPT_SESSION_REFCNT
182              Returns the reference count  associated  with  the  LDAP  handle
183              passed in as ld; outvalue must be a int *.  This is a read-only,
184              handle-specific option.  This option is OpenLDAP specific.
185
186       LDAP_OPT_SIZELIMIT
187              Sets/gets the value that defines the maximum number  of  entries
188              to be returned by a search operation.  invalue must be const int
189              *, while outvalue must be int *; They cannot be NULL.
190
191       LDAP_OPT_SOCKBUF
192              Returns a pointer to the socket buffer of the LDAP handle passed
193              in  as  ld; outvalue must be a Sockbuf **.  This is a read-only,
194              handle-specific option.  This option is OpenLDAP specific.
195
196       LDAP_OPT_TIMELIMIT
197              Sets/gets the value that defines the time limit  after  which  a
198              search  operation  should  be terminated by the server.  invalue
199              must be const int *, while outvalue must be int *, and they can‐
200              not be NULL.
201
202       LDAP_OPT_TIMEOUT
203              Sets/gets  a  timeout value for the synchronous API calls.  out‐
204              value must be a struct timeval ** (the caller has to free  *out‐
205              value),  and invalue must be a struct timeval *, and they cannot
206              be NULL. Using a struct with seconds set to  -1  results  in  an
207              infinite timeout, which is the default.  This option is OpenLDAP
208              specific.
209
210       LDAP_OPT_URI
211              Sets/gets a comma- or space-separated list of URIs  to  be  con‐
212              tacted  by  the  library  when trying to establish a connection.
213              outvalue must be a char **, and the  caller  is  responsible  of
214              freeing  the  resulting string by calling ldap_memfree(3), while
215              invalue must be a const char *; the library  parses  the  string
216              into  a  list  of  LDAPURLDesc  structures, so the invocation of
217              ldap_set_option(3) may fail if URL parsing fails.  URIs may only
218              contain  the schema, the host, and the port fields.  This option
219              is OpenLDAP specific.
220

SASL OPTIONS

222       The SASL options are OpenLDAP specific.
223
224       LDAP_OPT_X_SASL_AUTHCID
225              Gets the SASL authentication identity; outvalue must be  a  char
226              **,  its content needs to be freed by the caller using ldap_mem‐
227              free(3).
228
229       LDAP_OPT_X_SASL_AUTHZID
230              Gets the SASL authorization identity; outvalue must  be  a  char
231              **,  its content needs to be freed by the caller using ldap_mem‐
232              free(3).
233
234       LDAP_OPT_X_SASL_MAXBUFSIZE
235              Gets/sets SASL  maximum  buffer  size;  invalue  must  be  const
236              ber_len_t  *,  while  outvalue  must  be  ber_len_t *.  See also
237              LDAP_OPT_X_SASL_SECPROPS.
238
239       LDAP_OPT_X_SASL_MECH
240              Gets the SASL mechanism; outvalue must be a char **, its content
241              needs to be freed by the caller using ldap_memfree(3).
242
243       LDAP_OPT_X_SASL_MECHLIST
244              Gets  the  list  of the available mechanisms, in form of a NULL-
245              terminated array of strings; outvalue must  be  char  ***.   The
246              caller must not free or otherwise muck with it.
247
248       LDAP_OPT_X_SASL_NOCANON
249              Sets/gets the NOCANON flag.  When unset, the hostname is canoni‐
250              calized.  invalue must be const int *; its value  should  either
251              be LDAP_OPT_OFF or LDAP_OPT_ON.  outvalue must be int *.
252
253       LDAP_OPT_X_SASL_REALM
254              Gets  the  SASL  realm;  outvalue must be a char **, its content
255              needs to be freed by the caller using ldap_memfree(3).
256
257       LDAP_OPT_X_SASL_SECPROPS
258              Sets the SASL secprops; invalue must be a char *,  containing  a
259              comma-separated  list  of  properties.   Legal values are: none,
260              nodict, noplain, noactive,  passcred,  forwardsec,  noanonymous,
261              minssf=<minssf>, maxssf=<maxssf>, maxbufsize=<maxbufsize>.
262
263       LDAP_OPT_X_SASL_SSF
264              Gets the SASL SSF; outvalue must be a ber_len_t *.
265
266       LDAP_OPT_X_SASL_SSF_EXTERNAL
267              Sets  the  SASL SSF value related to an authentication performed
268              using an EXTERNAL mechanism; invalue must be a  const  ber_len_t
269              *.
270
271       LDAP_OPT_X_SASL_SSF_MAX
272              Gets/sets  SASL  maximum SSF; invalue must be const ber_len_t *,
273              while   outvalue   must    be    ber_len_t    *.     See    also
274              LDAP_OPT_X_SASL_SECPROPS.
275
276       LDAP_OPT_X_SASL_SSF_MIN
277              Gets/sets  SASL  minimum SSF; invalue must be const ber_len_t *,
278              while   outvalue   must    be    ber_len_t    *.     See    also
279              LDAP_OPT_X_SASL_SECPROPS.
280
281       LDAP_OPT_X_SASL_USERNAME
282              Gets the SASL username; outvalue must be a char **.  Its content
283              needs to be freed by the caller using ldap_memfree(3).
284

TCP OPTIONS

286       The TCP options are OpenLDAP specific.  Mainly intended  for  use  with
287       Linux, they may not be portable.
288
289       LDAP_OPT_X_KEEPALIVE_IDLE
290              Sets/gets  the  number  of  seconds a connection needs to remain
291              idle before TCP starts sending keepalive probes.   invalue  must
292              be const int *; outvalue must be int *.
293
294       LDAP_OPT_X_KEEPALIVE_PROBES
295              Sets/gets the maximum number of keepalive probes TCP should send
296              before dropping the connection.  invalue must be  const  int  *;
297              outvalue must be int *.
298
299       LDAP_OPT_X_KEEPALIVE_INTERVAL
300              Sets/gets  the  interval in seconds between individual keepalive
301              probes.  invalue must be const int *; outvalue must be int *.
302

TLS OPTIONS

304       The TLS options are OpenLDAP specific.
305
306       LDAP_OPT_X_TLS_CACERTDIR
307              Sets/gets the path of the directory containing CA  certificates.
308              invalue  must be const char *; outvalue must be char **, and its
309              contents need to be freed by the caller using ldap_memfree(3).
310
311       LDAP_OPT_X_TLS_CACERTFILE
312              Sets/gets the full-path of the  CA  certificate  file.   invalue
313              must be const char *; outvalue must be char **, and its contents
314              need to be freed by the caller using ldap_memfree(3).
315
316       LDAP_OPT_X_TLS_CERTFILE
317              Sets/gets the full-path of the certificate file.   invalue  must
318              be const char *; outvalue must be char **, and its contents need
319              to be freed by the caller using ldap_memfree(3).
320
321       LDAP_OPT_X_TLS_CIPHER_SUITE
322              Sets/gets the allowed cipher suite.  invalue must be const  char
323              *;  outvalue  must be char **, and its contents need to be freed
324              by the caller using ldap_memfree(3).
325
326       LDAP_OPT_X_TLS_CONNECT_ARG
327              Sets/gets the connection callback  argument.   invalue  must  be
328              const void *; outvalue must be void **.
329
330       LDAP_OPT_X_TLS_CONNECT_CB
331              Sets/gets the connection callback handle.  invalue must be const
332              LDAP_TLS_CONNECT_CB *; outvalue must be LDAP_TLS_CONNECT_CB **.
333
334       LDAP_OPT_X_TLS_CRLCHECK
335              Sets/gets    the    CRL    evaluation    strategy,    one     of
336              LDAP_OPT_X_TLS_CRL_NONE,       LDAP_OPT_X_TLS_CRL_PEER,       or
337              LDAP_OPT_X_TLS_CRL_ALL.  invalue must be const int  *;  outvalue
338              must be int *.  Requires OpenSSL.
339
340       LDAP_OPT_X_TLS_CRLFILE
341              Sets/gets  the full-path of the CRL file.  invalue must be const
342              char *; outvalue must be char **, and its contents  need  to  be
343              freed  by the caller using ldap_memfree(3).  This option is only
344              valid for GnuTLS.
345
346       LDAP_OPT_X_TLS_CTX
347              Sets/gets the TLS library context. New TLS sessions will inherit
348              their  default settings from this library context.  invalue must
349              be const void *; outvalue must  be  void  **.   When  using  the
350              OpenSSL  library  this  is  an SSL_CTX*. When using other crypto
351              libraries this is a pointer to an  OpenLDAP  private  structure.
352              Applications  generally should not use this option or attempt to
353              manipulate this structure.
354
355       LDAP_OPT_X_TLS_DHFILE
356              Gets/sets the full-path of the file  containing  the  parameters
357              for  Diffie-Hellman  ephemeral  key  exchange.   invalue must be
358              const char *; outvalue must be char **, and its contents need to
359              be freed by the caller using ldap_memfree(3).  Ignored by GnuTLS
360              and Mozilla NSS.
361
362       LDAP_OPT_X_TLS_KEYFILE
363              Sets/gets the full-path of the certificate  key  file.   invalue
364              must be const char *; outvalue must be char **, and its contents
365              need to be freed by the caller using ldap_memfree(3).
366
367       LDAP_OPT_X_TLS_NEWCTX
368              Instructs the library to  create  a  new  TLS  library  context.
369              invalue  must  be  const  int *.  A non-zero value pointed to by
370              invalue tells the library to create a context for a server.
371
372       LDAP_OPT_X_TLS_PROTOCOL_MIN
373              Sets/gets the minimum protocol version.  invalue must  be  const
374              int *; outvalue must be int *.
375
376       LDAP_OPT_X_TLS_RANDOM_FILE
377              Sets/gets  the random file when /dev/random and /dev/urandom are
378              not available.  invalue must be const char *; outvalue  must  be
379              char  **,  and its contents need to be freed by the caller using
380              ldap_memfree(3).  Ignored by  GnuTLS  older  than  version  2.2.
381              Ignored by Mozilla NSS.
382
383       LDAP_OPT_X_TLS_REQUIRE_CERT
384              Sets/gets   the  peer  certificate  checking  strategy,  one  of
385              LDAP_OPT_X_TLS_NEVER,                       LDAP_OPT_X_TLS_HARD,
386              LDAP_OPT_X_TLS_DEMAND, LDAP_OPT_X_TLS_ALLOW, LDAP_OPT_X_TLS_TRY.
387
388       LDAP_OPT_X_TLS_SSL_CTX
389              Gets  the TLS session context associated with this handle.  out‐
390              value must be void **.  When using the OpenSSL library  this  is
391              an  SSL*. When using other crypto libraries this is a pointer to
392              an OpenLDAP private structure.   Applications  generally  should
393              not use this option.
394

ERRORS

396       On  success,  the  functions  return  LDAP_OPT_SUCCESS,  while they may
397       return LDAP_OPT_ERROR to indicate  a  generic  option  handling  error.
398       Occasionally, more specific errors can be returned, like LDAP_NO_MEMORY
399       to indicate a failure in memory allocation.
400

NOTES

402       The  LDAP  libraries  with  the  LDAP_OPT_REFERRALS   option   set   to
403       LDAP_OPT_ON  (default  value)  automatically  follow referrals using an
404       anonymous bind.  Application developers are encouraged to either imple‐
405       ment consistent referral chasing features, or explicitly disable refer‐
406       ral chasing by setting that option to LDAP_OPT_OFF.
407
408       The protocol version used by the library defaults to LDAPv2  (now  his‐
409       toric),  which  corresponds  to  the  LDAP_VERSION2 macro.  Application
410       developers are encouraged to explicitly  set  LDAP_OPT_PROTOCOL_VERSION
411       to  LDAPv3,  using the LDAP_VERSION3 macro, or to allow users to select
412       the protocol version.
413

SEE ALSO

415       ldap(3), ldap_error(3), RFC 4422 (http://www.rfc-editor.org),
416

ACKNOWLEDGEMENTS

418       OpenLDAP Software is developed and maintained by The  OpenLDAP  Project
419       <http://www.openldap.org/>.  OpenLDAP Software is derived from the Uni‐
420       versity of Michigan LDAP 3.3 Release.
421
422
423
424OpenLDAP 2.4.47                   2018/12/19                LDAP_GET_OPTION(3)
Impressum