ldap_get_option, ldap_set_option - LDAP option handling routines
OpenLDAP LDAP (libldap, -lldap)
#include <ldap.h>
int ldap_get_option(LDAP *ld, int option, void *outvalue);
int ldap_set_option(LDAP *ld, int option, const void *invalue);
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
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
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 *.
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
*.
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 *.
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.
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.
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.
ldap(3),
ldap_error(3),
RFC 4422
(
http://www.rfc-editor.org),
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.