ldap_get_option(3) — Linux manual page

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | SASL OPTIONS | TCP OPTIONS | TLS OPTIONS | ERRORS | NOTES | SEE ALSO | ACKNOWLEDGEMENTS | COLOPHON

LDAP_GET_OPTION(3)      Library Functions Manual      LDAP_GET_OPTION(3)

NAME         top

       ldap_get_option, ldap_set_option - LDAP option handling routines

LIBRARY         top

       OpenLDAP LDAP (libldap, -lldap)

SYNOPSIS         top

       #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         top

       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         top

       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, nonstdcbind, 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         top

       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         top

       The TLS options are OpenLDAP specific.

       LDAP_OPT_X_TLS_CACERTDIR
              Sets/gets the path of the directories containing CA
              certificates.  Multiple directories may be specified,
              separated by a semi-colon.  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.  This directive is not
              supported when using MbedTLS.  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.
              This directive is not supported when using MbedTLS.
              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         top

       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         top

       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         top

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

ACKNOWLEDGEMENTS         top

       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.

COLOPHON         top

       This page is part of the OpenLDAP (an open source implementation
       of the Lightweight Directory Access Protocol) project.
       Information about the project can be found at 
       ⟨http://www.openldap.org/⟩.  If you have a bug report for this
       manual page, see ⟨http://www.openldap.org/its/⟩.  This page was
       obtained from the project's upstream Git repository
       ⟨https://git.openldap.org/openldap/openldap.git⟩ on 2024-06-14.
       (At that time, the date of the most recent commit that was found
       in the repository was 2024-06-13.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       [email protected]

OpenLDAP LDVERSION             RELEASEDATE            LDAP_GET_OPTION(3)

Pages that refer to this page: lber-sockbuf(3)ldap(3)ldap_bind(3)ldap_error(3)ldap_get_option(3)ldap_open(3)ldap_result(3)ldap.conf(5)