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_OPT_API_FEATURE_INFO
Fills-in a LDAPAPIFeatureInfo; outvalue must be a LDAPAPIFea-
tureInfo *, pointing to an already allocated struct. This is a
read-only option.
LDAP_OPT_API_INFO
Fills-in a LDAPAPIInfo; outvalue must be a LDAPAPIInfo *, point-
ing to an already allocated struct. This is a read-only option.
LDAP_OPT_CLIENT_CONTROLS
Sets/gets the client-side controls to be used for all opera-
tions. 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 respon-
sible 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 con-
necting state. Subsequent calls to library routines will poll
for completion of the connect before performing further opera-
tions. 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 spe-
cific.
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-
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 dep-
recated 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_mem-
free(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), and invalue must be a const struct timeval
*. They cannot be NULL. Using a struct with seconds set to -1
*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 connec-
tions (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 opera-
tions. 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 respon-
sible 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_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_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 can-
not be NULL.
LDAP_OPT_TIMEOUT
Sets/gets a timeout value for the synchronous API calls. out-
value must be a struct timeval ** (the caller has to free *out-
value), 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
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_mem-
free(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_mem-
free(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.
LDAP_OPT_X_SASL_NOCANON
Sets/gets the NOCANON flag. When unset, the hostname is canoni-
calized. 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
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_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
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). ignored by
GnuTLS.
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_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_SSL_CTX
Gets the TLS session context associated with this handle. out-
value 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.
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 imple-
ment consistent referral chasing features, or explicitly disable refer-
ral chasing by setting that option to LDAP_OPT_OFF.
The protocol version used by the library defaults to LDAPv2 (now his-
toric), which corresponds to the LDAP_VERSION2 macro. Application
|
