git.sur5r.net Git - openldap/blob - doc/man/man3/ldap_get_option.3

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