Provided by: libldap-dev_2.5.18+dfsg-0ubuntu0.22.04.2_amd64 bug

NAME

       ldap_get_option, ldap_set_option - LDAP option handling routines

LIBRARY

       OpenLDAP LDAP (libldap, -lldap)

SYNOPSIS

       #include <ldap.h>

       int ldap_get_option(LDAP *ld, int option, void *outvalue);

       int ldap_set_option(LDAP *ld, int option, const void *invalue);

DESCRIPTION

       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
       ldap_get_option(3)  or  set by ldap_set_option(3) is cast to void *.  The actual type is determined based
       on the value of the option argument.  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.

       LDAP_OPT_API_FEATURE_INFO
              Fills-in a LDAPAPIFeatureInfo; outvalue must be a LDAPAPIFeatureInfo *,  pointing  to  an  already
              allocated   struct.   The  ldapaif_info_version  field  of  the  struct  must  be  initialized  to
              LDAP_FEATURE_INFO_VERSION before making the call. The ldapaif_name field must be set to  the  name
              of a feature to query.  This is a read-only option.

       LDAP_OPT_API_INFO
              Fills-in a LDAPAPIInfo; outvalue must be a LDAPAPIInfo *, pointing to an already allocated struct.
              The ldapai_info_version field of the struct must be initialized  to  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 ldapai_extensions array and the array itself using
              ldap_memfree(3).  The caller must also free the ldapi_vendor_name.  This is a read-only option.

       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 ldap_search_ext(3), ldap_add_ext(3), ldap_modify_ext(3) and
              so  on.   outvalue  must be LDAPControl ***, and the caller is responsible of freeing the returned
              controls, if any, by calling ldap_controls_free(3), while invalue must be  LDAPControl  *const  *;
              the library duplicates the controls passed via invalue.

       LDAP_OPT_CONNECT_ASYNC
              Sets/gets  the  status of the asynchronous connect flag.  invalue should either be LDAP_OPT_OFF or
              LDAP_OPT_ON; outvalue must be int *.  When set, the  library  will  call  connect(2)  and  return,
              without  waiting for response.  This leaves the handle in a connecting state.  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 LDAP_OPT_NETWORK_TIMEOUT).  This option is OpenLDAP specific.

       LDAP_OPT_CONNECT_CB
              This option allows to set a connect callback.  invalue must  be  a  const  struct  ldap_conncb  *.
              Callbacks  are  executed  in  last  in-first served order.  Handle-specific callbacks are executed
              first, followed by global ones.  Right before freeing the callback structure, the lc_del  callback
              handler is passed a NULL Sockbuf.  Calling ldap_get_option(3) for this option removes the callback
              whose pointer matches outvalue.  This option is OpenLDAP specific.

       LDAP_OPT_DEBUG_LEVEL
              Sets/gets the debug level of the client library.  invalue must be a const int *; outvalue must  be
              a   int   *.    Valid   debug   levels   are   LDAP_DEBUG_ANY,   LDAP_DEBUG_ARGS,  LDAP_DEBUG_BER,
              LDAP_DEBUG_CONNS, LDAP_DEBUG_NONE,  LDAP_DEBUG_PACKETS,  LDAP_DEBUG_PARSE,  and  LDAP_DEBUG_TRACE.
              This option is OpenLDAP specific.

       LDAP_OPT_DEFBASE
              Sets/gets  a  string containing the DN to be used as default base for search operations.  outvalue
              must be a char **, and the caller is  responsible  of  freeing  the  returned  string  by  calling
              ldap_memfree(3),  while  invalue  must be a const char *; the library duplicates the corresponding
              string.  This option is OpenLDAP specific.

       LDAP_OPT_DEREF
              Sets/gets the value that defines when alias dereferencing must occur.  invalue must be  const  int
              *;  outvalue  must  be  int  *.   They  cannot  be  NULL.   The value of *invalue should be one of
              LDAP_DEREF_NEVER (the default), LDAP_DEREF_SEARCHING,  LDAP_DEREF_FINDING,  or  LDAP_DEREF_ALWAYS.
              Note  that  this  has  ever  been  the  only  means to determine alias dereferencing within search
              operations.

       LDAP_OPT_DESC
              Returns the file descriptor associated to the socket buffer of the LDAP handle passed  in  as  ld;
              outvalue must be a int *.  This is a read-only, handle-specific option.

       LDAP_OPT_DIAGNOSTIC_MESSAGE
              Sets/gets  a  string  containing  the error string associated to the LDAP handle.  This option was
              formerly known as  LDAP_OPT_ERROR_STRING.   outvalue  must  be  a  char  **,  and  the  caller  is
              responsible  of  freeing  the  returned string by calling ldap_memfree(3), while invalue must be a
              char *; the library duplicates the corresponding string.

       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 LDAP_OPT_URI.  outvalue must be a char **, and
              the caller is responsible of freeing  the  resulting  string  by  calling  ldap_memfree(3),  while
              invalue must be a const char *; the library duplicates the corresponding string.

       LDAP_OPT_MATCHED_DN
              Sets/gets  a  string  containing the matched DN associated to the LDAP handle.  outvalue must be a
              char **, and the caller is responsible of freeing the returned string by calling  ldap_memfree(3),
              while invalue must be a const char *; the library duplicates the corresponding string.

       LDAP_OPT_NETWORK_TIMEOUT
              Sets/gets  the  network timeout value after which poll(2)/select(2) following a connect(2) returns
              in case of no activity.  outvalue must be a struct timeval ** (the caller has  to  free  *outvalue
              using  ldap_memfree(3)), and invalue must be a const struct timeval *.  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.

       LDAP_OPT_PROTOCOL_VERSION
              Sets/gets the protocol version.  outvalue and invalue must be int *.

       LDAP_OPT_REFERRAL_URLS
              Sets/gets an array containing the referral URIs associated to the LDAP handle.  outvalue must be a
              char  ***,  and  the  caller  is  responsible  of  freeing  the   returned   string   by   calling
              ldap_memvfree(3),  while  invalue  must be a NULL-terminated char *const *; the library duplicates
              the corresponding string.  This option is OpenLDAP specific.

       LDAP_OPT_REFERRALS
              Determines whether the library should implicitly chase referrals or not.  invalue  must  be  const
              int *; its value should either be LDAP_OPT_OFF or LDAP_OPT_ON.  outvalue must be int *.

       LDAP_OPT_RESTART
              Determines  whether  the  library  should implicitly restart connections (FIXME).  invalue must be
              const int *; its value should either be LDAP_OPT_OFF or LDAP_OPT_ON.  outvalue must be int *.

       LDAP_OPT_RESULT_CODE
              Sets/gets the LDAP result code associated to the  handle.   This  option  was  formerly  known  as
              LDAP_OPT_ERROR_NUMBER.  invalue must be a const int *.  outvalue must be a int *.

       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 ldap_search_ext(3), ldap_add_ext(3), ldap_modify_ext(3) and
              so on.  outvalue must be LDAPControl ***, and the caller is responsible of  freeing  the  returned
              controls,  if  any,  by calling ldap_controls_free(3), while invalue must be LDAPControl *const *;
              the library duplicates the controls passed via invalue.

       LDAP_OPT_SESSION_REFCNT
              Returns the reference count associated with the LDAP handle passed in as ld; outvalue  must  be  a
              int *.  This is a read-only, handle-specific option.  This option is OpenLDAP specific.

       LDAP_OPT_SIZELIMIT
              Sets/gets  the  value  that  defines  the  maximum  number  of  entries to be returned by a search
              operation.  invalue must be const int *, while outvalue must be int *; They cannot be NULL.

       LDAP_OPT_SOCKBUF
              Returns a pointer to the socket buffer of the LDAP handle passed in as  ld;  outvalue  must  be  a
              Sockbuf **.  This is a read-only, handle-specific option.  This option is OpenLDAP specific.

       LDAP_OPT_SOCKET_BIND_ADDRESSES
              Sets/gets  a  space-separated list of IP Addresses used as binding interface to remote server when
              trying to establish a connection. Only one valid IPv4 address and/or one valid  IPv6  address  are
              allowed  in  the  list.   outvalue must be a char **, and the caller is responsible of freeing the
              returned string by calling ldap_memfree(3), while invalue must be a  const  char  *;  the  library
              duplicates the corresponding string.

       LDAP_OPT_TIMELIMIT
              Sets/gets  the  value  that  defines  the  time  limit  after  which  a search operation should be
              terminated by the server.  invalue must be const int *, while outvalue must be  int  *,  and  they
              cannot be NULL.

       LDAP_OPT_TIMEOUT
              Sets/gets  a  timeout  value  for the synchronous API calls.  outvalue must be a struct timeval **
              (the caller has to free *outvalue using ldap_memfree(3)), and invalue must be a 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.

       LDAP_OPT_URI
              Sets/gets a comma- or space-separated list of URIs to be contacted by the library when  trying  to
              establish  a connection.  outvalue must be a char **, and the caller is responsible of freeing the
              resulting string by calling ldap_memfree(3), while invalue must be a const  char  *;  the  library
              parses  the  string into a list of LDAPURLDesc structures, so the invocation of ldap_set_option(3)
              may fail if URL parsing fails.  URIs may only contain the schema, the host, and the  port  fields.
              This option is OpenLDAP specific.

       LDAP_OPT_KEEPCONN
              Instructs  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.

       LDAP_OPT_TCP_USER_TIMEOUT
              Allows  to  configure TCP_USER_TIMEOUT in milliseconds on the connection, overriding the operating
              system setting.  This option is OpenLDAP specific and supported only on Linux  2.6.37  or  higher.
              invalue must be a const unsigned int *; outvalue must be an unsigned int *.

SASL OPTIONS

       The SASL options are OpenLDAP specific and unless otherwise noted, require an LDAP handle to be passed.

       LDAP_OPT_X_SASL_AUTHCID
              Gets  the  SASL authentication identity; outvalue must be a char **, its content needs to be freed
              by the caller using ldap_memfree(3).

       LDAP_OPT_X_SASL_AUTHZID
              Gets the SASL authorization identity; outvalue must be a char **, its content needs to be freed by
              the caller using ldap_memfree(3).

       LDAP_OPT_X_SASL_MAXBUFSIZE
              Gets/sets  SASL  maximum  buffer  size;  invalue must be const ber_len_t *, while outvalue must be
              ber_len_t *.  See also LDAP_OPT_X_SASL_SECPROPS.

       LDAP_OPT_X_SASL_MECH
              Gets the SASL mechanism; outvalue must be a char **, its content needs to be freed by  the  caller
              using ldap_memfree(3).

       LDAP_OPT_X_SASL_MECHLIST
              Gets the list of the available mechanisms, in form of a NULL-terminated array of strings; outvalue
              must be char ***.  The caller must not free or otherwise muck with it. This  option  can  be  used
              globally.

       LDAP_OPT_X_SASL_NOCANON
              Sets/gets the NOCANON flag.  When unset, the hostname is canonicalized.  invalue must be const int
              *; its value should either be LDAP_OPT_OFF or LDAP_OPT_ON.  outvalue must be int *.

       LDAP_OPT_X_SASL_REALM
              Gets the SASL realm; outvalue must be a char **, its content needs to be freed by the caller using
              ldap_memfree(3).

       LDAP_OPT_X_SASL_SECPROPS
              Sets the SASL secprops; invalue must be a char *, containing a comma-separated list of properties.
              Legal  values  are:  none,  nodict,  noplain,   noactive,   passcred,   forwardsec,   noanonymous,
              minssf=<minssf>, maxssf=<maxssf>, maxbufsize=<maxbufsize>.

       LDAP_OPT_X_SASL_SSF
              Gets the SASL SSF; outvalue must be a ber_len_t *.

       LDAP_OPT_X_SASL_SSF_EXTERNAL
              Sets  the  SASL  SSF  value  related  to  an authentication performed using an EXTERNAL mechanism;
              invalue must be a const ber_len_t *.

       LDAP_OPT_X_SASL_SSF_MAX
              Gets/sets SASL maximum SSF; invalue must be const ber_len_t *, while outvalue must be ber_len_t *.
              See also LDAP_OPT_X_SASL_SECPROPS.

       LDAP_OPT_X_SASL_SSF_MIN
              Gets/sets SASL minimum SSF; invalue must be const ber_len_t *, while outvalue must be ber_len_t *.
              See also LDAP_OPT_X_SASL_SECPROPS.

       LDAP_OPT_X_SASL_USERNAME
              Gets the SASL username; outvalue must be a char **.  Its content needs to be freed by  the  caller
              using ldap_memfree(3).

       LDAP_OPT_X_SASL_CBINDING
              Sets/gets  the  channel-binding  type  to  use  in SASL, one of LDAP_OPT_X_SASL_CBINDING_NONE (the
              default),   LDAP_OPT_X_SASL_CBINDING_TLS_UNIQUE   the   "tls-unique"   type   from    RFC    5929.
              LDAP_OPT_X_SASL_CBINDING_TLS_ENDPOINT  the  "tls-server-end-point"  from RFC 5929, compatible with
              Windows.  invalue must be const int *; outvalue must be int *.

TCP OPTIONS

       The TCP options are OpenLDAP specific.  Mainly intended for use with Linux, they may not be portable.

       LDAP_OPT_X_KEEPALIVE_IDLE
              Sets/gets the number of seconds a connection needs  to  remain  idle  before  TCP  starts  sending
              keepalive probes.  invalue must be const int *; outvalue must be int *.

       LDAP_OPT_X_KEEPALIVE_PROBES
              Sets/gets  the  maximum number of keepalive probes TCP should send before dropping the connection.
              invalue must be const int *; outvalue must be int *.

       LDAP_OPT_X_KEEPALIVE_INTERVAL
              Sets/gets the interval in seconds between individual keepalive probes.  invalue must be const  int
              *; outvalue must be int *.

TLS OPTIONS

       The TLS options are OpenLDAP specific.

       LDAP_OPT_X_TLS_CACERTDIR
              Sets/gets  the  path  of  the directory containing CA certificates.  invalue must be const char *;
              outvalue must be char **, and its contents need to be freed by the caller using ldap_memfree(3).

       LDAP_OPT_X_TLS_CACERTFILE
              Sets/gets the full-path of the CA certificate file.  invalue must be const char *;  outvalue  must
              be char **, and its contents need to be freed by the caller using ldap_memfree(3).

       LDAP_OPT_X_TLS_CERTFILE
              Sets/gets  the  full-path of the certificate file.  invalue must be const char *; outvalue must be
              char **, and its contents need to be freed by the caller using ldap_memfree(3).

       LDAP_OPT_X_TLS_CIPHER
              Gets the cipher being used on an established TLS session.  outvalue  must  be  char  **,  and  its
              contents need to be freed by the caller using ldap_memfree(3).

       LDAP_OPT_X_TLS_CIPHER_SUITE
              Sets/gets  the  allowed cipher suite.  invalue must be const char *; outvalue must be char **, and
              its contents need to be freed by the caller using ldap_memfree(3).

       LDAP_OPT_X_TLS_CONNECT_ARG
              Sets/gets the connection callback argument.  invalue must be const void *; outvalue must  be  void
              **.

       LDAP_OPT_X_TLS_CONNECT_CB
              Sets/gets  the  connection callback handle.  invalue must be const LDAP_TLS_CONNECT_CB *; outvalue
              must be LDAP_TLS_CONNECT_CB **.

       LDAP_OPT_X_TLS_CRLCHECK
              Sets/gets the CRL evaluation strategy, one of LDAP_OPT_X_TLS_CRL_NONE, LDAP_OPT_X_TLS_CRL_PEER, or
              LDAP_OPT_X_TLS_CRL_ALL.  invalue must be const int *; outvalue must be int *.  Requires OpenSSL.

       LDAP_OPT_X_TLS_CRLFILE
              Sets/gets  the full-path of the CRL file.  invalue must be const char *; outvalue must be char **,
              and its contents need to be freed by the caller using ldap_memfree(3).  This option is only  valid
              for GnuTLS.

       LDAP_OPT_X_TLS_CTX
              Sets/gets  the TLS library context. New TLS sessions will inherit their default settings from this
              library context.  invalue must be const void *; outvalue must be void **.  When using the  OpenSSL
              library  this  is  an SSL_CTX*. When using other crypto libraries this is a pointer to an OpenLDAP
              private structure.  Applications generally should not use this option  or  attempt  to  manipulate
              this structure.

       LDAP_OPT_X_TLS_DHFILE
              Gets/sets  the  full-path  of  the file containing the parameters for Diffie-Hellman ephemeral key
              exchange.  invalue must be const char *; outvalue must be char **, and its  contents  need  to  be
              freed by the caller using ldap_memfree(3).

       LDAP_OPT_X_TLS_ECNAME
              Gets/sets  the  name of the curve(s) used for elliptic curve key exchanges.  invalue must be const
              char *; outvalue must be char **,  and  its  contents  need  to  be  freed  by  the  caller  using
              ldap_memfree(3).   Ignored  by  GnuTLS.  In  GnuTLS  a  curve  may be selected in the cipher suite
              specification.

       LDAP_OPT_X_TLS_KEYFILE
              Sets/gets the full-path of the certificate key file.  invalue must be const char *; outvalue  must
              be char **, and its contents need to be freed by the caller using ldap_memfree(3).

       LDAP_OPT_X_TLS_NEWCTX
              Instructs  the  library to create a new TLS library context.  invalue must be const int *.  A non-
              zero value pointed to by invalue tells the library to create a context for a server.

       LDAP_OPT_X_TLS_PEERCERT
              Gets the peer's certificate in DER format from an  established  TLS  session.   outvalue  must  be
              struct berval *, and the data it returns needs to be freed by the caller using ldap_memfree(3).

       LDAP_OPT_X_TLS_PROTOCOL_MAX
              Sets/gets the maximum protocol version.  invalue must be const int *; outvalue must be int *.

       LDAP_OPT_X_TLS_PROTOCOL_MIN
              Sets/gets the minimum protocol version.  invalue must be const int *; outvalue must be int *.

       LDAP_OPT_X_TLS_RANDOM_FILE
              Sets/gets  the  random  file when /dev/random and /dev/urandom are not available.  invalue must be
              const char *; outvalue must be char **, and its contents need to be  freed  by  the  caller  using
              ldap_memfree(3).  Ignored by GnuTLS older than version 2.2.

       LDAP_OPT_X_TLS_REQUIRE_CERT
              Sets/gets    the    peer    certificate    checking   strategy,   one   of   LDAP_OPT_X_TLS_NEVER,
              LDAP_OPT_X_TLS_HARD, LDAP_OPT_X_TLS_DEMAND, LDAP_OPT_X_TLS_ALLOW, LDAP_OPT_X_TLS_TRY.

       LDAP_OPT_X_TLS_REQUIRE_SAN
              Sets/gets   the   peer   certificate   subjectAlternativeName   checking    strategy,    one    of
              LDAP_OPT_X_TLS_NEVER,     LDAP_OPT_X_TLS_HARD,     LDAP_OPT_X_TLS_DEMAND,    LDAP_OPT_X_TLS_ALLOW,
              LDAP_OPT_X_TLS_TRY.

       LDAP_OPT_X_TLS_SSL_CTX
              Gets the TLS session context associated with this handle.  outvalue must be void **.   When  using
              the  OpenSSL  library  this  is an SSL*. When using other crypto libraries this is a pointer to an
              OpenLDAP private structure.  Applications generally should not use this option.

       LDAP_OPT_X_TLS_VERSION
              Gets the TLS version being used on an established TLS session.  outvalue must be char **, and  its
              contents need to be freed by the caller using ldap_memfree(3).

       LDAP_OPT_X_TLS_PEERKEY_HASH
              Sets  the  (public)  key that the application expects the peer to be using.  invalue must be const
              char  *  containing  the  base64  encoding  of  the  expected  peer's  key  or   in   the   format
              <hashalg>:<peerkey  hash  base64  encoded> where as a TLS session is established, the library will
              hash the peer's key with the provided hash algorithm and compare it with value provided  and  will
              only  allow the session to continue if they match. This happens regardless of certificate checking
              strategy. The list of supported hashalg values depends on  the  crypto  library  used,  check  its
              documentation to get a list.

ERRORS

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

NOTES

       The  LDAP  libraries  with the LDAP_OPT_REFERRALS option set to 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
       LDAP_OPT_OFF.

       The protocol version used by the library defaults to LDAPv2 (now  historic),  which  corresponds  to  the
       LDAP_VERSION2  macro.   Application developers are encouraged to explicitly set LDAP_OPT_PROTOCOL_VERSION
       to LDAPv3, using the LDAP_VERSION3 macro, or to allow users to select the protocol version.

SEE ALSO

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

ACKNOWLEDGEMENTS

       OpenLDAP Software is  developed  and  maintained  by  The  OpenLDAP  Project  <http://www.openldap.org/>.
       OpenLDAP Software is derived from the University of Michigan LDAP 3.3 Release.