ldap_get_option.3 20.6 KB
Newer Older
1
2
.TH LDAP_GET_OPTION 3 "RELEASEDATE" "OpenLDAP LDVERSION"
.\" $OpenLDAP$
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
3
.\" Copyright 1998-2020 The OpenLDAP Foundation All Rights Reserved.
4
5
6
7
.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
.SH NAME
ldap_get_option, ldap_set_option \- LDAP option handling routines
.SH LIBRARY
Howard Chu's avatar
Howard Chu committed
8
OpenLDAP LDAP (libldap, \-lldap)
9
10
11
12
.SH SYNOPSIS
.nf
.B #include <ldap.h>
.LP
Pierangelo Masarati's avatar
cleanup    
Pierangelo Masarati committed
13
.BI "int ldap_get_option(LDAP *" ld ", int " option ", void *" outvalue ");"
14
.LP
Pierangelo Masarati's avatar
cleanup    
Pierangelo Masarati committed
15
.BI "int ldap_set_option(LDAP *" ld ", int " option ", const void *" invalue ");"
16
17
18
19
20
21
22
23
24
.SH DESCRIPTION
.LP
These routines provide access to options stored either in a LDAP handle
or as global options, where applicable.
They make use of a neutral interface, where the type of the value
either retrieved by 
.BR ldap_get_option (3)
or set by
.BR ldap_set_option (3)
Pierangelo Masarati's avatar
cleanup    
Pierangelo Masarati committed
25
26
is cast to 
.BR "void *" .
27
28
29
The actual type is determined based on the value of the
.B option
argument.
30
31
32
Global options are set/retrieved by passing a NULL LDAP handle. LDAP handles
inherit their default settings from the global options in effect at the time
the handle is created.
33
.TP
34
35
36
37
38
39
40
.B LDAP_OPT_API_FEATURE_INFO
Fills-in a 
.BR "LDAPAPIFeatureInfo" ;
.BR outvalue 
must be a 
.BR "LDAPAPIFeatureInfo *" ,
pointing to an already allocated struct.
41
42
43
44
45
46
47
The
.B ldapaif_info_version
field of the struct must be initialized to
.B LDAP_FEATURE_INFO_VERSION
before making the call. The
.B ldapaif_name
field must be set to the name of a feature to query.
48
49
This is a read-only option.
.TP
50
51
.B LDAP_OPT_API_INFO
Fills-in a 
Pierangelo Masarati's avatar
Pierangelo Masarati committed
52
.BR "LDAPAPIInfo" ;
53
54
.BR outvalue 
must be a 
Pierangelo Masarati's avatar
Pierangelo Masarati committed
55
.BR "LDAPAPIInfo *" ,
56
57
58
59
60
61
62
63
64
65
66
67
68
69
pointing to an already allocated struct. The
.B ldapai_info_version
field of the struct must be initialized to
.B LDAP_API_INFO_VERSION
before making the call.
If the version passed in does not match the current library
version, the expected version number will be stored in the
struct and the call will fail.
The caller is responsible for freeing the elements of the
.B ldapai_extensions
array and the array itself using
.BR ldap_memfree (3).
The caller must also free the
.BR ldapi_vendor_name .
70
71
This is a read-only option.
.TP
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
.B LDAP_OPT_CLIENT_CONTROLS
Sets/gets the client-side controls to be used for all operations.
This is now deprecated as modern LDAP C API provides replacements
for all main operations which accepts client-side controls as
explicit arguments; see for example
.BR ldap_search_ext (3),
.BR ldap_add_ext (3),
.BR ldap_modify_ext (3)
and so on.
.BR outvalue
must be 
.BR "LDAPControl ***" ,
and the caller is responsible of freeing the returned controls, if any,
by calling 
.BR ldap_controls_free (3),
while
.BR invalue
must be 
Pierangelo Masarati's avatar
Pierangelo Masarati committed
90
.BR "LDAPControl *const *" ;
91
92
93
94
95
the library duplicates the controls passed via
.BR invalue .
.TP
.B LDAP_OPT_CONNECT_ASYNC
Sets/gets the status of the asynchronous connect flag.
Pierangelo Masarati's avatar
Pierangelo Masarati committed
96
97
.BR invalue
should either be
98
99
.BR LDAP_OPT_OFF
or
Pierangelo Masarati's avatar
Pierangelo Masarati committed
100
101
102
103
.BR LDAP_OPT_ON ;
.BR outvalue
must be
.BR "int *" .
104
105
106
When set, the library will call
.BR connect (2)
and return, without waiting for response.
Howard Chu's avatar
Howard Chu committed
107
This leaves the handle in a connecting state.
108
109
110
111
112
113
114
115
116
117
118
Subsequent calls to library routines will poll for completion
of the connect before performing further operations.
As a consequence, library calls that need to establish a connection
with a DSA do not block even for the network timeout
(option
.BR LDAP_OPT_NETWORK_TIMEOUT ).
This option is OpenLDAP specific.
.TP
.B LDAP_OPT_CONNECT_CB
This option allows to set a connect callback.
.B invalue
Pierangelo Masarati's avatar
Pierangelo Masarati committed
119
120
must be a 
.BR "const struct ldap_conncb *" .
121
Callbacks are executed in last in-first served order.
Howard Chu's avatar
Howard Chu committed
122
Handle-specific callbacks are executed first, followed by global ones.
123
Right before freeing the callback structure, the
Pierangelo Masarati's avatar
Pierangelo Masarati committed
124
.B lc_del
125
126
callback handler is passed a 
.B NULL
Pierangelo Masarati's avatar
Pierangelo Masarati committed
127
.BR Sockbuf .
128
129
130
131
132
133
134
135
136
137
Calling
.BR ldap_get_option (3)
for this option removes the callback whose pointer matches
.BR outvalue .
This option is OpenLDAP specific.
.TP
.B LDAP_OPT_DEBUG_LEVEL
Sets/gets the debug level of the client library.
.BR invalue
must be a 
Pierangelo Masarati's avatar
Pierangelo Masarati committed
138
139
140
.BR "const int *" ;
.BR outvalue
must be a
141
.BR "int *" .
Pierangelo Masarati's avatar
Pierangelo Masarati committed
142
143
144
145
146
147
148
149
150
151
Valid debug levels are 
.BR LDAP_DEBUG_ANY ,
.BR LDAP_DEBUG_ARGS ,
.BR LDAP_DEBUG_BER ,
.BR LDAP_DEBUG_CONNS ,
.BR LDAP_DEBUG_NONE ,
.BR LDAP_DEBUG_PACKETS ,
.BR LDAP_DEBUG_PARSE ,
and
.BR LDAP_DEBUG_TRACE .
152
153
154
155
156
157
158
159
160
161
162
163
164
This option is OpenLDAP specific.
.TP
.B LDAP_OPT_DEFBASE
Sets/gets a string containing the DN to be used as default base
for search operations.
.BR outvalue
must be a
.BR "char **" ,
and the caller is responsible of freeing the returned string by calling
.BR ldap_memfree (3),
while
.BR invalue
must be a 
Pierangelo Masarati's avatar
Pierangelo Masarati committed
165
.BR "const char *" ;
166
167
168
169
170
171
172
the library duplicates the corresponding string.
This option is OpenLDAP specific.
.TP
.B LDAP_OPT_DEREF
Sets/gets the value that defines when alias dereferencing must occur.
.BR invalue
must be
Pierangelo Masarati's avatar
Pierangelo Masarati committed
173
174
175
176
177
.BR "const int *" ;
.BR outvalue 
must be
.BR "int *" .
They cannot be NULL.
178
179
180
181
182
183
184
185
186
187
188
189
The value of 
.BR *invalue
should be one of
.BR LDAP_DEREF_NEVER
(the default),
.BR LDAP_DEREF_SEARCHING ,
.BR LDAP_DEREF_FINDING ,
or
.BR LDAP_DEREF_ALWAYS .
Note that this has ever been the only means to determine alias dereferencing
within search operations.
.TP
190
191
192
193
194
195
196
.B LDAP_OPT_DESC
Returns the file descriptor associated to the socket buffer
of the LDAP handle passed in as 
.BR ld ;
.BR outvalue
must be a 
.BR "int *" .
Howard Chu's avatar
Howard Chu committed
197
This is a read-only, handle-specific option.
198
.TP
199
200
201
202
.B LDAP_OPT_DIAGNOSTIC_MESSAGE
Sets/gets a string containing the error string associated to the LDAP handle.
This option was formerly known as 
.BR LDAP_OPT_ERROR_STRING .
203
.BR outvalue
204
205
206
207
208
209
must be a
.BR "char **" ,
and the caller is responsible of freeing the returned string by calling
.BR ldap_memfree (3),
while
.BR invalue
210
must be a 
211
212
.BR "char *" ;
the library duplicates the corresponding string.
213
.TP
214
215
216
217
218
219
.B LDAP_OPT_HOST_NAME
Sets/gets a space-separated list of hosts to be contacted by the library 
when trying to establish a connection.
This is now deprecated in favor of
.BR LDAP_OPT_URI .
.BR outvalue
220
must be a 
221
222
223
224
225
.BR "char **" ,
and the caller is responsible of freeing the resulting string by calling
.BR ldap_memfree (3),
while
.BR invalue
226
must be a 
Pierangelo Masarati's avatar
Pierangelo Masarati committed
227
.BR "const char *" ;
228
229
230
231
232
233
234
235
236
237
238
239
the library duplicates the corresponding string.
.TP
.B LDAP_OPT_MATCHED_DN
Sets/gets a string containing the matched DN associated to the LDAP handle.
.BR outvalue
must be a
.BR "char **" ,
and the caller is responsible of freeing the returned string by calling
.BR ldap_memfree (3),
while
.BR invalue
must be a 
Pierangelo Masarati's avatar
Pierangelo Masarati committed
240
.BR "const char *" ;
241
the library duplicates the corresponding string.
242
243
244
245
246
247
248
.TP
.B LDAP_OPT_NETWORK_TIMEOUT
Sets/gets the network timeout value after which
.BR poll (2)/ select (2) 
following a 
.BR connect (2) 
returns in case of no activity.
249
.B outvalue
250
251
252
253
must be a 
.BR "struct timeval **"
(the caller has to free
.BR *outvalue ) ,
254
255
and
.B invalue
256
must be a 
Pierangelo Masarati's avatar
Pierangelo Masarati committed
257
258
.BR "const struct timeval *" .
They cannot be NULL. Using a struct with seconds set to \-1 results
259
in an infinite timeout, which is the default.
260
This option is OpenLDAP specific.
261
.TP
262
263
264
265
.B LDAP_OPT_PROTOCOL_VERSION
Sets/gets the protocol version.
.BR outvalue
and
266
.BR invalue
267
268
must be 
.BR "int *" .
269
.TP
270
271
272
273
274
275
.B LDAP_OPT_REFERRAL_URLS
Sets/gets an array containing the referral URIs associated to the LDAP handle.
.BR outvalue
must be a
.BR "char ***" ,
and the caller is responsible of freeing the returned string by calling
Pierangelo Masarati's avatar
Pierangelo Masarati committed
276
.BR ldap_memvfree (3),
277
while
278
.BR invalue
279
must be a NULL-terminated
Pierangelo Masarati's avatar
Pierangelo Masarati committed
280
.BR "char *const *" ;
281
282
the library duplicates the corresponding string.
This option is OpenLDAP specific.
283
284
285
286
287
.TP
.B LDAP_OPT_REFERRALS
Determines whether the library should implicitly chase referrals or not.
.BR invalue
must be 
Pierangelo Masarati's avatar
Pierangelo Masarati committed
288
289
.BR "const int *" ;
its value should either be
290
291
292
.BR LDAP_OPT_OFF
or
.BR LDAP_OPT_ON .
Pierangelo Masarati's avatar
Pierangelo Masarati committed
293
294
295
296
297
298
299
.BR outvalue
must be
.BR "int *" .
.\".TP
.\".B LDAP_OPT_REFHOPLIMIT
.\"This option is OpenLDAP specific.
.\"It is not currently implemented.
300
.TP
301
302
303
304
.B LDAP_OPT_RESTART
Determines whether the library should implicitly restart connections (FIXME).
.BR invalue
must be 
Pierangelo Masarati's avatar
Pierangelo Masarati committed
305
306
.BR "const int *" ;
its value should either be
307
308
309
.BR LDAP_OPT_OFF
or
.BR LDAP_OPT_ON .
Pierangelo Masarati's avatar
Pierangelo Masarati committed
310
311
312
.BR outvalue
must be
.BR "int *" .
313
.TP
314
315
316
317
.B LDAP_OPT_RESULT_CODE
Sets/gets the LDAP result code associated to the handle.
This option was formerly known as
.BR LDAP_OPT_ERROR_NUMBER .
318
.BR invalue
319
must be a 
Pierangelo Masarati's avatar
Pierangelo Masarati committed
320
321
322
.BR "const int *" .
.BR outvalue
must be a
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
.BR "int *" .
.TP
.B LDAP_OPT_SERVER_CONTROLS
Sets/gets the server-side controls to be used for all operations.
This is now deprecated as modern LDAP C API provides replacements
for all main operations which accepts server-side controls as
explicit arguments; see for example
.BR ldap_search_ext (3),
.BR ldap_add_ext (3),
.BR ldap_modify_ext (3)
and so on.
.BR outvalue
must be 
.BR "LDAPControl ***" ,
and the caller is responsible of freeing the returned controls, if any,
by calling 
.BR ldap_controls_free (3),
while
.BR invalue
must be 
Pierangelo Masarati's avatar
Pierangelo Masarati committed
343
.BR "LDAPControl *const *" ;
344
345
346
the library duplicates the controls passed via
.BR invalue .
.TP
347
348
349
350
351
352
353
354
355
.B LDAP_OPT_SESSION_REFCNT
Returns the reference count associated with the LDAP handle passed in as
.BR ld ;
.BR outvalue
must be a
.BR "int *" .
This is a read-only, handle-specific option.
This option is OpenLDAP specific.
.TP
356
357
358
.B LDAP_OPT_SIZELIMIT
Sets/gets the value that defines the maximum number of entries
to be returned by a search operation.
359
.BR invalue
360
must be
Pierangelo Masarati's avatar
Pierangelo Masarati committed
361
362
363
364
365
366
.BR "const int *" ,
while
.BR outvalue
must be
.BR "int *" ;
They cannot be NULL.
367
.TP
368
369
370
.B LDAP_OPT_SOCKBUF
Returns a pointer to the socket buffer of the LDAP handle passed in as
.BR ld ;
371
372
.BR outvalue
must be a 
373
.BR "Sockbuf **" .
Howard Chu's avatar
Howard Chu committed
374
This is a read-only, handle-specific option.
375
376
377
378
379
This option is OpenLDAP specific.
.TP
.B LDAP_OPT_TIMELIMIT
Sets/gets the value that defines the time limit after which
a search operation should be terminated by the server.
380
.BR invalue
381
must be
Pierangelo Masarati's avatar
Pierangelo Masarati committed
382
383
384
385
.BR "const int *" ,
while
.BR outvalue
must be
386
387
388
389
390
391
.BR "int *" ,
and they cannot be NULL.
.TP
.B LDAP_OPT_TIMEOUT
Sets/gets a timeout value for the synchronous API calls.
.B outvalue
392
must be a 
393
394
395
396
397
398
399
400
401
402
.BR "struct timeval **"
(the caller has to free
.BR *outvalue ) ,
and
.B invalue
must be a 
.BR "struct timeval *" ,
and they cannot be NULL. Using a struct with seconds set to \-1 results
in an infinite timeout, which is the default.
This option is OpenLDAP specific.
403
404
.TP
.B LDAP_OPT_URI
405
Sets/gets a comma- or space-separated list of URIs to be contacted by the library 
406
407
408
409
410
411
412
413
414
when trying to establish a connection.
.BR outvalue
must be a 
.BR "char **" ,
and the caller is responsible of freeing the resulting string by calling
.BR ldap_memfree (3),
while
.BR invalue
must be a 
Pierangelo Masarati's avatar
Pierangelo Masarati committed
415
.BR "const char *" ;
416
417
418
419
420
the library parses the string into a list of 
.BR LDAPURLDesc
structures, so the invocation of 
.BR ldap_set_option (3)
may fail if URL parsing fails.
421
422
423
424
425
426
427
428
URIs may only contain the
.BR schema ,
the
.BR host ,
and the
.BR port
fields.
This option is OpenLDAP specific.
429
430
431
432
433
434
.TP
.B LDAP_OPT_KEEPCONN
Instructs
.BR ldap_result (3)
to keep the connection open on read error or if Notice of Disconnection is received. In these cases, the connection should be closed by the caller.
This option is OpenLDAP specific.
Pierangelo Masarati's avatar
Pierangelo Masarati committed
435
436
437
.SH SASL OPTIONS
The SASL options are OpenLDAP specific.
.TP
Pierangelo Masarati's avatar
Pierangelo Masarati committed
438
439
.B LDAP_OPT_X_SASL_AUTHCID
Gets the SASL authentication identity;
Pierangelo Masarati's avatar
Pierangelo Masarati committed
440
441
442
.BR outvalue
must be a
.BR "char **" ,
Pierangelo Masarati's avatar
Pierangelo Masarati committed
443
444
its content needs to be freed by the caller using
.BR ldap_memfree (3).
Pierangelo Masarati's avatar
Pierangelo Masarati committed
445
.TP
Pierangelo Masarati's avatar
Pierangelo Masarati committed
446
447
.B LDAP_OPT_X_SASL_AUTHZID
Gets the SASL authorization identity;
Pierangelo Masarati's avatar
Pierangelo Masarati committed
448
449
450
.BR outvalue
must be a
.BR "char **" ,
Pierangelo Masarati's avatar
Pierangelo Masarati committed
451
452
its content needs to be freed by the caller using
.BR ldap_memfree (3).
Pierangelo Masarati's avatar
Pierangelo Masarati committed
453
.TP
Pierangelo Masarati's avatar
Pierangelo Masarati committed
454
455
456
457
458
459
.B LDAP_OPT_X_SASL_MAXBUFSIZE
Gets/sets SASL maximum buffer size;
.BR invalue
must be
.BR "const ber_len_t *" ,
while
Pierangelo Masarati's avatar
Pierangelo Masarati committed
460
.BR outvalue
Pierangelo Masarati's avatar
Pierangelo Masarati committed
461
462
463
464
must be
.BR "ber_len_t *" .
See also
.BR LDAP_OPT_X_SASL_SECPROPS .
Pierangelo Masarati's avatar
Pierangelo Masarati committed
465
.TP
Pierangelo Masarati's avatar
Pierangelo Masarati committed
466
467
.B LDAP_OPT_X_SASL_MECH
Gets the SASL mechanism;
Pierangelo Masarati's avatar
Pierangelo Masarati committed
468
469
470
.BR outvalue
must be a
.BR "char **" ,
Pierangelo Masarati's avatar
Pierangelo Masarati committed
471
472
its content needs to be freed by the caller using
.BR ldap_memfree (3).
Pierangelo Masarati's avatar
Pierangelo Masarati committed
473
.TP
Pierangelo Masarati's avatar
Pierangelo Masarati committed
474
475
476
.B LDAP_OPT_X_SASL_MECHLIST
Gets the list of the available mechanisms,
in form of a NULL-terminated array of strings;
Pierangelo Masarati's avatar
Pierangelo Masarati committed
477
.BR outvalue
Pierangelo Masarati's avatar
Pierangelo Masarati committed
478
479
must be
.BR "char ***" .
Howard Chu's avatar
Howard Chu committed
480
The caller must not free or otherwise muck with it.
Pierangelo Masarati's avatar
Pierangelo Masarati committed
481
.TP
482
.B LDAP_OPT_X_SASL_NOCANON
Pierangelo Masarati's avatar
Pierangelo Masarati committed
483
484
Sets/gets the NOCANON flag.
When unset, the hostname is canonicalized.
Pierangelo Masarati's avatar
Pierangelo Masarati committed
485
486
487
488
.BR invalue
must be
.BR "const int *" ;
its value should either be
Pierangelo Masarati's avatar
Pierangelo Masarati committed
489
490
491
.BR LDAP_OPT_OFF
or
.BR LDAP_OPT_ON .
Pierangelo Masarati's avatar
Pierangelo Masarati committed
492
493
494
.BR outvalue
must be
.BR "int *" .
Pierangelo Masarati's avatar
Pierangelo Masarati committed
495
496
497
498
.TP
.B LDAP_OPT_X_SASL_REALM
Gets the SASL realm;
.BR outvalue
Pierangelo Masarati's avatar
Pierangelo Masarati committed
499
must be a
Pierangelo Masarati's avatar
Pierangelo Masarati committed
500
.BR "char **" ,
Pierangelo Masarati's avatar
Pierangelo Masarati committed
501
502
its content needs to be freed by the caller using
.BR ldap_memfree (3).
Pierangelo Masarati's avatar
Pierangelo Masarati committed
503
504
.TP
.B LDAP_OPT_X_SASL_SECPROPS
Pierangelo Masarati's avatar
Pierangelo Masarati committed
505
Sets the SASL secprops;
Pierangelo Masarati's avatar
Pierangelo Masarati committed
506
507
508
509
510
511
512
513
514
515
516
517
518
519
.BR invalue
must be a
.BR "char *" ,
containing a comma-separated list of properties.
Legal values are:
.BR none ,
.BR nodict ,
.BR noplain ,
.BR noactive ,
.BR passcred ,
.BR forwardsec ,
.BR noanonymous ,
.BR minssf=<minssf> ,
.BR maxssf=<maxssf> ,
Pierangelo Masarati's avatar
Pierangelo Masarati committed
520
.BR maxbufsize=<maxbufsize> .
Pierangelo Masarati's avatar
Pierangelo Masarati committed
521
.TP
Pierangelo Masarati's avatar
Pierangelo Masarati committed
522
523
.B LDAP_OPT_X_SASL_SSF
Gets the SASL SSF;
Pierangelo Masarati's avatar
Pierangelo Masarati committed
524
.BR outvalue
Pierangelo Masarati's avatar
Pierangelo Masarati committed
525
526
527
528
529
530
531
532
must be a
.BR "ber_len_t *" .
.TP
.B LDAP_OPT_X_SASL_SSF_EXTERNAL
Sets the SASL SSF value related to an authentication
performed using an EXTERNAL mechanism;
.BR invalue
must be a
Pierangelo Masarati's avatar
Pierangelo Masarati committed
533
.BR "const ber_len_t *" .
Pierangelo Masarati's avatar
Pierangelo Masarati committed
534
535
536
537
538
539
540
541
542
543
544
545
546
.TP
.B LDAP_OPT_X_SASL_SSF_MAX
Gets/sets SASL maximum SSF;
.BR invalue
must be
.BR "const ber_len_t *" ,
while
.BR outvalue
must be
.BR "ber_len_t *" .
See also
.BR LDAP_OPT_X_SASL_SECPROPS .
.TP
Pierangelo Masarati's avatar
Pierangelo Masarati committed
547
548
.B LDAP_OPT_X_SASL_SSF_MIN
Gets/sets SASL minimum SSF;
Pierangelo Masarati's avatar
Pierangelo Masarati committed
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
.BR invalue
must be
.BR "const ber_len_t *" ,
while
.BR outvalue
must be
.BR "ber_len_t *" .
See also
.BR LDAP_OPT_X_SASL_SECPROPS .
.TP
.B LDAP_OPT_X_SASL_USERNAME
Gets the SASL username;
.BR outvalue
must be a
.BR "char **" .
Pierangelo Masarati's avatar
Pierangelo Masarati committed
564
565
Its content needs to be freed by the caller using
.BR ldap_memfree (3).
566
567
568
569
570
571
.B LDAP_OPT_X_SASL_CBINDING
Sets/gets the channel-binding type to use in SASL,
one of
.BR LDAP_OPT_X_SASL_CBINDING_NONE
(the default),
.BR LDAP_OPT_X_SASL_CBINDING_TLS_UNIQUE
Ryan Tandy's avatar
Ryan Tandy committed
572
the "tls-unique" type from RFC 5929.
573
.BR LDAP_OPT_X_SASL_CBINDING_TLS_ENDPOINT
Ryan Tandy's avatar
Ryan Tandy committed
574
the "tls-server-end-point" from RFC 5929, compatible with Windows.
575
576
577
578
579
580
581
.BR invalue
must be
.BR "const int *" ;
.BR outvalue
must be
.BR "int *" .
.TP
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
.SH TCP OPTIONS
The TCP options are OpenLDAP specific.
Mainly intended for use with Linux, they may not be portable.
.TP
.B LDAP_OPT_X_KEEPALIVE_IDLE
Sets/gets the number of seconds a connection needs to remain idle
before TCP starts sending keepalive probes.
.BR invalue
must be
.BR "const int *" ;
.BR outvalue
must be
.BR "int *" .
.TP
.B LDAP_OPT_X_KEEPALIVE_PROBES
Sets/gets the maximum number of keepalive probes TCP should send
before dropping the connection.
.BR invalue
must be
.BR "const int *" ;
.BR outvalue
must be
.BR "int *" .
.TP
.B LDAP_OPT_X_KEEPALIVE_INTERVAL
Sets/gets the interval in seconds between individual keepalive probes.
.BR invalue
must be
.BR "const int *" ;
.BR outvalue
must be
.BR "int *" .
614
615
.SH TLS OPTIONS
The TLS options are OpenLDAP specific.
Pierangelo Masarati's avatar
Pierangelo Masarati committed
616
617
618
.\".TP
.\".B LDAP_OPT_X_TLS
.\"Sets/gets the TLS mode.
619
.TP
Pierangelo Masarati's avatar
Pierangelo Masarati committed
620
621
622
623
624
625
626
627
.B LDAP_OPT_X_TLS_CACERTDIR
Sets/gets the path of the directory containing CA certificates.
.BR invalue
must be
.BR "const char *" ;
.BR outvalue
must be
.BR "char **" ,
Pierangelo Masarati's avatar
Pierangelo Masarati committed
628
629
and its contents need to be freed by the caller using
.BR ldap_memfree (3).
630
.TP
631
.B LDAP_OPT_X_TLS_CACERTFILE
Howard Chu's avatar
Howard Chu committed
632
Sets/gets the full-path of the CA certificate file.
Pierangelo Masarati's avatar
Pierangelo Masarati committed
633
634
635
636
637
638
.BR invalue
must be
.BR "const char *" ;
.BR outvalue
must be
.BR "char **" ,
Pierangelo Masarati's avatar
Pierangelo Masarati committed
639
640
and its contents need to be freed by the caller using
.BR ldap_memfree (3).
641
.TP
642
.B LDAP_OPT_X_TLS_CERTFILE
Howard Chu's avatar
Howard Chu committed
643
Sets/gets the full-path of the certificate file.
Pierangelo Masarati's avatar
Pierangelo Masarati committed
644
645
646
647
648
649
.BR invalue
must be
.BR "const char *" ;
.BR outvalue
must be
.BR "char **" ,
Pierangelo Masarati's avatar
Pierangelo Masarati committed
650
651
and its contents need to be freed by the caller using
.BR ldap_memfree (3).
652
.TP
653
654
655
656
657
658
659
660
.B LDAP_OPT_X_TLS_CIPHER
Gets the cipher being used on an established TLS session.
.BR outvalue
must be
.BR "char **" ,
and its contents need to be freed by the caller using
.BR ldap_memfree (3).
.TP
661
662
.B LDAP_OPT_X_TLS_CIPHER_SUITE
Sets/gets the allowed cipher suite.
Pierangelo Masarati's avatar
Pierangelo Masarati committed
663
664
665
666
667
668
.BR invalue
must be
.BR "const char *" ;
.BR outvalue
must be
.BR "char **" ,
Pierangelo Masarati's avatar
Pierangelo Masarati committed
669
670
and its contents need to be freed by the caller using
.BR ldap_memfree (3).
671
.TP
Pierangelo Masarati's avatar
Pierangelo Masarati committed
672
673
674
675
676
677
678
679
.B LDAP_OPT_X_TLS_CONNECT_ARG
Sets/gets the connection callback argument.
.BR invalue
must be
.BR "const void *" ;
.BR outvalue
must be
.BR "void **" .
680
.TP
Pierangelo Masarati's avatar
Pierangelo Masarati committed
681
682
683
684
685
686
687
688
.B LDAP_OPT_X_TLS_CONNECT_CB
Sets/gets the connection callback handle.
.BR invalue
must be
.BR "const LDAP_TLS_CONNECT_CB *" ;
.BR outvalue
must be
.BR "LDAP_TLS_CONNECT_CB **" .
689
690
691
692
693
694
695
.TP
.B LDAP_OPT_X_TLS_CRLCHECK
Sets/gets the CRL evaluation strategy, one of
.BR LDAP_OPT_X_TLS_CRL_NONE ,
.BR LDAP_OPT_X_TLS_CRL_PEER ,
or
.BR LDAP_OPT_X_TLS_CRL_ALL .
Pierangelo Masarati's avatar
Pierangelo Masarati committed
696
697
698
699
700
701
.BR invalue
must be
.BR "const int *" ;
.BR outvalue
must be
.BR "int *" .
702
703
Requires OpenSSL.
.TP
Pierangelo Masarati's avatar
Pierangelo Masarati committed
704
705
706
707
708
709
710
711
.B LDAP_OPT_X_TLS_CRLFILE
Sets/gets the full-path of the CRL file.
.BR invalue
must be
.BR "const char *" ;
.BR outvalue
must be
.BR "char **" ,
Pierangelo Masarati's avatar
Pierangelo Masarati committed
712
713
and its contents need to be freed by the caller using
.BR ldap_memfree (3).
Howard Chu's avatar
Howard Chu committed
714
This option is only valid for GnuTLS.
715
.TP
Pierangelo Masarati's avatar
Pierangelo Masarati committed
716
.B LDAP_OPT_X_TLS_CTX
Howard Chu's avatar
Howard Chu committed
717
718
Sets/gets the TLS library context. New TLS sessions will inherit their
default settings from this library context.
Pierangelo Masarati's avatar
Pierangelo Masarati committed
719
720
721
722
723
724
.BR invalue
must be
.BR "const void *" ;
.BR outvalue
must be
.BR "void **" .
725
When using the OpenSSL library this is an SSL_CTX*. When using other
Howard Chu's avatar
Howard Chu committed
726
727
728
crypto libraries this is a pointer to an OpenLDAP private structure.
Applications generally should not use this option or attempt to
manipulate this structure.
729
730
731
732
.TP
.B LDAP_OPT_X_TLS_DHFILE
Gets/sets the full-path of the file containing the parameters
for Diffie-Hellman ephemeral key exchange.
Pierangelo Masarati's avatar
Pierangelo Masarati committed
733
734
735
736
737
738
.BR invalue
must be
.BR "const char *" ;
.BR outvalue
must be
.BR "char **" ,
Pierangelo Masarati's avatar
Pierangelo Masarati committed
739
740
and its contents need to be freed by the caller using
.BR ldap_memfree (3).
741
742
.TP
.B LDAP_OPT_X_TLS_ECNAME
743
Gets/sets the name of the curve(s) used for
744
745
746
747
748
749
750
751
752
elliptic curve key exchanges.
.BR invalue
must be
.BR "const char *" ;
.BR outvalue
must be
.BR "char **" ,
and its contents need to be freed by the caller using
.BR ldap_memfree (3).
753
Ignored by GnuTLS. In GnuTLS a curve may be selected
754
in the cipher suite specification.
755
.TP
Pierangelo Masarati's avatar
Pierangelo Masarati committed
756
.B LDAP_OPT_X_TLS_KEYFILE
Howard Chu's avatar
Howard Chu committed
757
Sets/gets the full-path of the certificate key file.
Pierangelo Masarati's avatar
Pierangelo Masarati committed
758
759
760
761
762
763
.BR invalue
must be
.BR "const char *" ;
.BR outvalue
must be
.BR "char **" ,
Pierangelo Masarati's avatar
Pierangelo Masarati committed
764
765
and its contents need to be freed by the caller using
.BR ldap_memfree (3).
Pierangelo Masarati's avatar
Pierangelo Masarati committed
766
.TP
767
.B LDAP_OPT_X_TLS_NEWCTX
Howard Chu's avatar
Howard Chu committed
768
Instructs the library to create a new TLS library context.
Pierangelo Masarati's avatar
Pierangelo Masarati committed
769
770
771
772
.BR invalue
must be
.BR "const int *" .
A non-zero value pointed to by
773
.BR invalue
Howard Chu's avatar
Howard Chu committed
774
tells the library to create a context for a server.
775
.TP
776
777
778
779
780
781
782
783
.B LDAP_OPT_X_TLS_PEERCERT
Gets the peer's certificate in DER format from an established TLS session.
.BR outvalue
must be
.BR "struct berval *" ,
and the data it returns needs to be freed by the caller using
.BR ldap_memfree (3).
.TP
Pierangelo Masarati's avatar
Pierangelo Masarati committed
784
785
786
787
788
789
790
791
792
793
794
.B LDAP_OPT_X_TLS_PROTOCOL_MIN
Sets/gets the minimum protocol version.
.BR invalue
must be
.BR "const int *" ;
.BR outvalue
must be
.BR "int *" .
.TP
.B LDAP_OPT_X_TLS_RANDOM_FILE
Sets/gets the random file when
Pierangelo Masarati's avatar
Pierangelo Masarati committed
795
.B /dev/random
Pierangelo Masarati's avatar
Pierangelo Masarati committed
796
and
Pierangelo Masarati's avatar
Pierangelo Masarati committed
797
.B /dev/urandom
Pierangelo Masarati's avatar
Pierangelo Masarati committed
798
799
800
801
802
803
804
are not available.
.BR invalue
must be
.BR "const char *" ;
.BR outvalue
must be
.BR "char **" ,
Pierangelo Masarati's avatar
Pierangelo Masarati committed
805
806
and its contents need to be freed by the caller using
.BR ldap_memfree (3).
807
Ignored by GnuTLS older than version 2.2.
Pierangelo Masarati's avatar
Pierangelo Masarati committed
808
809
810
811
812
813
814
815
816
817
.TP
.B LDAP_OPT_X_TLS_REQUIRE_CERT
Sets/gets the peer certificate checking strategy,
one of
.BR LDAP_OPT_X_TLS_NEVER ,
.BR LDAP_OPT_X_TLS_HARD ,
.BR LDAP_OPT_X_TLS_DEMAND ,
.BR LDAP_OPT_X_TLS_ALLOW ,
.BR LDAP_OPT_X_TLS_TRY .
.TP
Howard Chu's avatar
Howard Chu committed
818
819
820
821
822
823
824
825
826
.B LDAP_OPT_X_TLS_REQUIRE_SAN
Sets/gets the peer certificate subjectAlternativeName checking strategy,
one of
.BR LDAP_OPT_X_TLS_NEVER ,
.BR LDAP_OPT_X_TLS_HARD ,
.BR LDAP_OPT_X_TLS_DEMAND ,
.BR LDAP_OPT_X_TLS_ALLOW ,
.BR LDAP_OPT_X_TLS_TRY .
.TP
Pierangelo Masarati's avatar
Pierangelo Masarati committed
827
.B LDAP_OPT_X_TLS_SSL_CTX
Howard Chu's avatar
Howard Chu committed
828
Gets the TLS session context associated with this handle.
Pierangelo Masarati's avatar
Pierangelo Masarati committed
829
830
831
.BR outvalue
must be
.BR "void **" .
832
When using the OpenSSL library this is an SSL*. When using other
Howard Chu's avatar
Howard Chu committed
833
834
crypto libraries this is a pointer to an OpenLDAP private structure.
Applications generally should not use this option.
835
836
837
838
839
840
841
842
.TP
.B LDAP_OPT_X_TLS_VERSION
Gets the TLS version being used on an established TLS session.
.BR outvalue
must be
.BR "char **" ,
and its contents need to be freed by the caller using
.BR ldap_memfree (3).
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
.SH ERRORS
On success, the functions return
.BR LDAP_OPT_SUCCESS ,
while they may return
.B LDAP_OPT_ERROR
to indicate a generic option handling error.
Occasionally, more specific errors can be returned, like
.B LDAP_NO_MEMORY
to indicate a failure in memory allocation.
.SH NOTES
The LDAP libraries with the
.B LDAP_OPT_REFERRALS 
option set to
.B LDAP_OPT_ON
(default value) automatically follow referrals using an anonymous bind.
Application developers are encouraged to either implement consistent
referral chasing features, or explicitly disable referral chasing
by setting that option to
.BR LDAP_OPT_OFF .
862
863
864
865
866
867
868
869
870
871
.P
The protocol version used by the library defaults to LDAPv2 (now historic),
which corresponds to the
.B LDAP_VERSION2
macro.
Application developers are encouraged to explicitly set
.B LDAP_OPT_PROTOCOL_VERSION
to LDAPv3, using the 
.B LDAP_VERSION3
macro, or to allow users to select the protocol version.
872
873
874
875
876
877
.SH SEE ALSO
.BR ldap (3),
.BR ldap_error (3),
.B RFC 4422
(http://www.rfc-editor.org),
.SH ACKNOWLEDGEMENTS
Kurt Zeilenga's avatar
Kurt Zeilenga committed
878
.so ../Project