mirror of
https://git.openldap.org/openldap/openldap.git
synced 2024-12-21 03:10:25 +08:00
879 lines
21 KiB
Groff
879 lines
21 KiB
Groff
.TH LDAP_GET_OPTION 3 "RELEASEDATE" "OpenLDAP LDVERSION"
|
|
.\" $OpenLDAP$
|
|
.\" Copyright 1998-2021 The OpenLDAP Foundation All Rights Reserved.
|
|
.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
|
|
.SH NAME
|
|
ldap_get_option, ldap_set_option \- LDAP option handling routines
|
|
.SH LIBRARY
|
|
OpenLDAP LDAP (libldap, \-lldap)
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <ldap.h>
|
|
.LP
|
|
.BI "int ldap_get_option(LDAP *" ld ", int " option ", void *" outvalue ");"
|
|
.LP
|
|
.BI "int ldap_set_option(LDAP *" ld ", int " option ", const void *" invalue ");"
|
|
.SH DESCRIPTION
|
|
.LP
|
|
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
|
|
.BR ldap_get_option (3)
|
|
or set by
|
|
.BR ldap_set_option (3)
|
|
is cast to
|
|
.BR "void *" .
|
|
The actual type is determined based on the value of the
|
|
.B 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.
|
|
.TP
|
|
.B LDAP_OPT_API_FEATURE_INFO
|
|
Fills-in a
|
|
.BR "LDAPAPIFeatureInfo" ;
|
|
.BR outvalue
|
|
must be a
|
|
.BR "LDAPAPIFeatureInfo *" ,
|
|
pointing to an already allocated struct.
|
|
The
|
|
.B ldapaif_info_version
|
|
field of the struct must be initialized to
|
|
.B LDAP_FEATURE_INFO_VERSION
|
|
before making the call. The
|
|
.B ldapaif_name
|
|
field must be set to the name of a feature to query.
|
|
This is a read-only option.
|
|
.TP
|
|
.B LDAP_OPT_API_INFO
|
|
Fills-in a
|
|
.BR "LDAPAPIInfo" ;
|
|
.BR outvalue
|
|
must be a
|
|
.BR "LDAPAPIInfo *" ,
|
|
pointing to an already allocated struct. The
|
|
.B ldapai_info_version
|
|
field of the struct must be initialized to
|
|
.B 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
|
|
.B ldapai_extensions
|
|
array and the array itself using
|
|
.BR ldap_memfree (3).
|
|
The caller must also free the
|
|
.BR ldapi_vendor_name .
|
|
This is a read-only option.
|
|
.TP
|
|
.B 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
|
|
.BR ldap_search_ext (3),
|
|
.BR ldap_add_ext (3),
|
|
.BR ldap_modify_ext (3)
|
|
and so on.
|
|
.BR outvalue
|
|
must be
|
|
.BR "LDAPControl ***" ,
|
|
and the caller is responsible of freeing the returned controls, if any,
|
|
by calling
|
|
.BR ldap_controls_free (3),
|
|
while
|
|
.BR invalue
|
|
must be
|
|
.BR "LDAPControl *const *" ;
|
|
the library duplicates the controls passed via
|
|
.BR invalue .
|
|
.TP
|
|
.B LDAP_OPT_CONNECT_ASYNC
|
|
Sets/gets the status of the asynchronous connect flag.
|
|
.BR invalue
|
|
should either be
|
|
.BR LDAP_OPT_OFF
|
|
or
|
|
.BR LDAP_OPT_ON ;
|
|
.BR outvalue
|
|
must be
|
|
.BR "int *" .
|
|
When set, the library will call
|
|
.BR 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
|
|
.BR LDAP_OPT_NETWORK_TIMEOUT ).
|
|
This option is OpenLDAP specific.
|
|
.TP
|
|
.B LDAP_OPT_CONNECT_CB
|
|
This option allows to set a connect callback.
|
|
.B invalue
|
|
must be a
|
|
.BR "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
|
|
.B lc_del
|
|
callback handler is passed a
|
|
.B NULL
|
|
.BR Sockbuf .
|
|
Calling
|
|
.BR ldap_get_option (3)
|
|
for this option removes the callback whose pointer matches
|
|
.BR outvalue .
|
|
This option is OpenLDAP specific.
|
|
.TP
|
|
.B LDAP_OPT_DEBUG_LEVEL
|
|
Sets/gets the debug level of the client library.
|
|
.BR invalue
|
|
must be a
|
|
.BR "const int *" ;
|
|
.BR outvalue
|
|
must be a
|
|
.BR "int *" .
|
|
Valid debug levels are
|
|
.BR LDAP_DEBUG_ANY ,
|
|
.BR LDAP_DEBUG_ARGS ,
|
|
.BR LDAP_DEBUG_BER ,
|
|
.BR LDAP_DEBUG_CONNS ,
|
|
.BR LDAP_DEBUG_NONE ,
|
|
.BR LDAP_DEBUG_PACKETS ,
|
|
.BR LDAP_DEBUG_PARSE ,
|
|
and
|
|
.BR LDAP_DEBUG_TRACE .
|
|
This option is OpenLDAP specific.
|
|
.TP
|
|
.B LDAP_OPT_DEFBASE
|
|
Sets/gets a string containing the DN to be used as default base
|
|
for search operations.
|
|
.BR outvalue
|
|
must be a
|
|
.BR "char **" ,
|
|
and the caller is responsible of freeing the returned string by calling
|
|
.BR ldap_memfree (3),
|
|
while
|
|
.BR invalue
|
|
must be a
|
|
.BR "const char *" ;
|
|
the library duplicates the corresponding string.
|
|
This option is OpenLDAP specific.
|
|
.TP
|
|
.B LDAP_OPT_DEREF
|
|
Sets/gets the value that defines when alias dereferencing must occur.
|
|
.BR invalue
|
|
must be
|
|
.BR "const int *" ;
|
|
.BR outvalue
|
|
must be
|
|
.BR "int *" .
|
|
They cannot be NULL.
|
|
The value of
|
|
.BR *invalue
|
|
should be one of
|
|
.BR LDAP_DEREF_NEVER
|
|
(the default),
|
|
.BR LDAP_DEREF_SEARCHING ,
|
|
.BR LDAP_DEREF_FINDING ,
|
|
or
|
|
.BR LDAP_DEREF_ALWAYS .
|
|
Note that this has ever been the only means to determine alias dereferencing
|
|
within search operations.
|
|
.TP
|
|
.B LDAP_OPT_DESC
|
|
Returns the file descriptor associated to the socket buffer
|
|
of the LDAP handle passed in as
|
|
.BR ld ;
|
|
.BR outvalue
|
|
must be a
|
|
.BR "int *" .
|
|
This is a read-only, handle-specific option.
|
|
.TP
|
|
.B LDAP_OPT_DIAGNOSTIC_MESSAGE
|
|
Sets/gets a string containing the error string associated to the LDAP handle.
|
|
This option was formerly known as
|
|
.BR LDAP_OPT_ERROR_STRING .
|
|
.BR outvalue
|
|
must be a
|
|
.BR "char **" ,
|
|
and the caller is responsible of freeing the returned string by calling
|
|
.BR ldap_memfree (3),
|
|
while
|
|
.BR invalue
|
|
must be a
|
|
.BR "char *" ;
|
|
the library duplicates the corresponding string.
|
|
.TP
|
|
.B 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
|
|
.BR LDAP_OPT_URI .
|
|
.BR outvalue
|
|
must be a
|
|
.BR "char **" ,
|
|
and the caller is responsible of freeing the resulting string by calling
|
|
.BR ldap_memfree (3),
|
|
while
|
|
.BR invalue
|
|
must be a
|
|
.BR "const char *" ;
|
|
the library duplicates the corresponding string.
|
|
.TP
|
|
.B LDAP_OPT_MATCHED_DN
|
|
Sets/gets a string containing the matched DN associated to the LDAP handle.
|
|
.BR outvalue
|
|
must be a
|
|
.BR "char **" ,
|
|
and the caller is responsible of freeing the returned string by calling
|
|
.BR ldap_memfree (3),
|
|
while
|
|
.BR invalue
|
|
must be a
|
|
.BR "const char *" ;
|
|
the library duplicates the corresponding string.
|
|
.TP
|
|
.B LDAP_OPT_NETWORK_TIMEOUT
|
|
Sets/gets the network timeout value after which
|
|
.BR poll (2)/ select (2)
|
|
following a
|
|
.BR connect (2)
|
|
returns in case of no activity.
|
|
.B outvalue
|
|
must be a
|
|
.BR "struct timeval **"
|
|
(the caller has to free
|
|
.BR *outvalue ) ,
|
|
and
|
|
.B invalue
|
|
must be a
|
|
.BR "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.
|
|
.TP
|
|
.B LDAP_OPT_PROTOCOL_VERSION
|
|
Sets/gets the protocol version.
|
|
.BR outvalue
|
|
and
|
|
.BR invalue
|
|
must be
|
|
.BR "int *" .
|
|
.TP
|
|
.B LDAP_OPT_REFERRAL_URLS
|
|
Sets/gets an array containing the referral URIs associated to the LDAP handle.
|
|
.BR outvalue
|
|
must be a
|
|
.BR "char ***" ,
|
|
and the caller is responsible of freeing the returned string by calling
|
|
.BR ldap_memvfree (3),
|
|
while
|
|
.BR invalue
|
|
must be a NULL-terminated
|
|
.BR "char *const *" ;
|
|
the library duplicates the corresponding string.
|
|
This option is OpenLDAP specific.
|
|
.TP
|
|
.B LDAP_OPT_REFERRALS
|
|
Determines whether the library should implicitly chase referrals or not.
|
|
.BR invalue
|
|
must be
|
|
.BR "const int *" ;
|
|
its value should either be
|
|
.BR LDAP_OPT_OFF
|
|
or
|
|
.BR LDAP_OPT_ON .
|
|
.BR outvalue
|
|
must be
|
|
.BR "int *" .
|
|
.\".TP
|
|
.\".B LDAP_OPT_REFHOPLIMIT
|
|
.\"This option is OpenLDAP specific.
|
|
.\"It is not currently implemented.
|
|
.TP
|
|
.B LDAP_OPT_RESTART
|
|
Determines whether the library should implicitly restart connections (FIXME).
|
|
.BR invalue
|
|
must be
|
|
.BR "const int *" ;
|
|
its value should either be
|
|
.BR LDAP_OPT_OFF
|
|
or
|
|
.BR LDAP_OPT_ON .
|
|
.BR outvalue
|
|
must be
|
|
.BR "int *" .
|
|
.TP
|
|
.B LDAP_OPT_RESULT_CODE
|
|
Sets/gets the LDAP result code associated to the handle.
|
|
This option was formerly known as
|
|
.BR LDAP_OPT_ERROR_NUMBER .
|
|
.BR invalue
|
|
must be a
|
|
.BR "const int *" .
|
|
.BR outvalue
|
|
must be a
|
|
.BR "int *" .
|
|
.TP
|
|
.B 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
|
|
.BR ldap_search_ext (3),
|
|
.BR ldap_add_ext (3),
|
|
.BR ldap_modify_ext (3)
|
|
and so on.
|
|
.BR outvalue
|
|
must be
|
|
.BR "LDAPControl ***" ,
|
|
and the caller is responsible of freeing the returned controls, if any,
|
|
by calling
|
|
.BR ldap_controls_free (3),
|
|
while
|
|
.BR invalue
|
|
must be
|
|
.BR "LDAPControl *const *" ;
|
|
the library duplicates the controls passed via
|
|
.BR invalue .
|
|
.TP
|
|
.B LDAP_OPT_SESSION_REFCNT
|
|
Returns the reference count associated with the LDAP handle passed in as
|
|
.BR ld ;
|
|
.BR outvalue
|
|
must be a
|
|
.BR "int *" .
|
|
This is a read-only, handle-specific option.
|
|
This option is OpenLDAP specific.
|
|
.TP
|
|
.B LDAP_OPT_SIZELIMIT
|
|
Sets/gets the value that defines the maximum number of entries
|
|
to be returned by a search operation.
|
|
.BR invalue
|
|
must be
|
|
.BR "const int *" ,
|
|
while
|
|
.BR outvalue
|
|
must be
|
|
.BR "int *" ;
|
|
They cannot be NULL.
|
|
.TP
|
|
.B LDAP_OPT_SOCKBUF
|
|
Returns a pointer to the socket buffer of the LDAP handle passed in as
|
|
.BR ld ;
|
|
.BR outvalue
|
|
must be a
|
|
.BR "Sockbuf **" .
|
|
This is a read-only, handle-specific option.
|
|
This option is OpenLDAP specific.
|
|
.TP
|
|
.B LDAP_OPT_TIMELIMIT
|
|
Sets/gets the value that defines the time limit after which
|
|
a search operation should be terminated by the server.
|
|
.BR invalue
|
|
must be
|
|
.BR "const int *" ,
|
|
while
|
|
.BR outvalue
|
|
must be
|
|
.BR "int *" ,
|
|
and they cannot be NULL.
|
|
.TP
|
|
.B LDAP_OPT_TIMEOUT
|
|
Sets/gets a timeout value for the synchronous API calls.
|
|
.B outvalue
|
|
must be a
|
|
.BR "struct timeval **"
|
|
(the caller has to free
|
|
.BR *outvalue ) ,
|
|
and
|
|
.B invalue
|
|
must be a
|
|
.BR "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.
|
|
.TP
|
|
.B 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.
|
|
.BR outvalue
|
|
must be a
|
|
.BR "char **" ,
|
|
and the caller is responsible of freeing the resulting string by calling
|
|
.BR ldap_memfree (3),
|
|
while
|
|
.BR invalue
|
|
must be a
|
|
.BR "const char *" ;
|
|
the library parses the string into a list of
|
|
.BR LDAPURLDesc
|
|
structures, so the invocation of
|
|
.BR ldap_set_option (3)
|
|
may fail if URL parsing fails.
|
|
URIs may only contain the
|
|
.BR schema ,
|
|
the
|
|
.BR host ,
|
|
and the
|
|
.BR port
|
|
fields.
|
|
This option is OpenLDAP specific.
|
|
.TP
|
|
.B LDAP_OPT_KEEPCONN
|
|
Instructs
|
|
.BR 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.
|
|
.SH SASL OPTIONS
|
|
The SASL options are OpenLDAP specific.
|
|
.TP
|
|
.B LDAP_OPT_X_SASL_AUTHCID
|
|
Gets the SASL authentication identity;
|
|
.BR outvalue
|
|
must be a
|
|
.BR "char **" ,
|
|
its content needs to be freed by the caller using
|
|
.BR ldap_memfree (3).
|
|
.TP
|
|
.B LDAP_OPT_X_SASL_AUTHZID
|
|
Gets the SASL authorization identity;
|
|
.BR outvalue
|
|
must be a
|
|
.BR "char **" ,
|
|
its content needs to be freed by the caller using
|
|
.BR ldap_memfree (3).
|
|
.TP
|
|
.B LDAP_OPT_X_SASL_MAXBUFSIZE
|
|
Gets/sets SASL maximum buffer size;
|
|
.BR invalue
|
|
must be
|
|
.BR "const ber_len_t *" ,
|
|
while
|
|
.BR outvalue
|
|
must be
|
|
.BR "ber_len_t *" .
|
|
See also
|
|
.BR LDAP_OPT_X_SASL_SECPROPS .
|
|
.TP
|
|
.B LDAP_OPT_X_SASL_MECH
|
|
Gets the SASL mechanism;
|
|
.BR outvalue
|
|
must be a
|
|
.BR "char **" ,
|
|
its content needs to be freed by the caller using
|
|
.BR ldap_memfree (3).
|
|
.TP
|
|
.B LDAP_OPT_X_SASL_MECHLIST
|
|
Gets the list of the available mechanisms,
|
|
in form of a NULL-terminated array of strings;
|
|
.BR outvalue
|
|
must be
|
|
.BR "char ***" .
|
|
The caller must not free or otherwise muck with it.
|
|
.TP
|
|
.B LDAP_OPT_X_SASL_NOCANON
|
|
Sets/gets the NOCANON flag.
|
|
When unset, the hostname is canonicalized.
|
|
.BR invalue
|
|
must be
|
|
.BR "const int *" ;
|
|
its value should either be
|
|
.BR LDAP_OPT_OFF
|
|
or
|
|
.BR LDAP_OPT_ON .
|
|
.BR outvalue
|
|
must be
|
|
.BR "int *" .
|
|
.TP
|
|
.B LDAP_OPT_X_SASL_REALM
|
|
Gets the SASL realm;
|
|
.BR outvalue
|
|
must be a
|
|
.BR "char **" ,
|
|
its content needs to be freed by the caller using
|
|
.BR ldap_memfree (3).
|
|
.TP
|
|
.B LDAP_OPT_X_SASL_SECPROPS
|
|
Sets the SASL secprops;
|
|
.BR invalue
|
|
must be a
|
|
.BR "char *" ,
|
|
containing a comma-separated list of properties.
|
|
Legal values are:
|
|
.BR none ,
|
|
.BR nodict ,
|
|
.BR noplain ,
|
|
.BR noactive ,
|
|
.BR passcred ,
|
|
.BR forwardsec ,
|
|
.BR noanonymous ,
|
|
.BR minssf=<minssf> ,
|
|
.BR maxssf=<maxssf> ,
|
|
.BR maxbufsize=<maxbufsize> .
|
|
.TP
|
|
.B LDAP_OPT_X_SASL_SSF
|
|
Gets the SASL SSF;
|
|
.BR outvalue
|
|
must be a
|
|
.BR "ber_len_t *" .
|
|
.TP
|
|
.B LDAP_OPT_X_SASL_SSF_EXTERNAL
|
|
Sets the SASL SSF value related to an authentication
|
|
performed using an EXTERNAL mechanism;
|
|
.BR invalue
|
|
must be a
|
|
.BR "const ber_len_t *" .
|
|
.TP
|
|
.B LDAP_OPT_X_SASL_SSF_MAX
|
|
Gets/sets SASL maximum SSF;
|
|
.BR invalue
|
|
must be
|
|
.BR "const ber_len_t *" ,
|
|
while
|
|
.BR outvalue
|
|
must be
|
|
.BR "ber_len_t *" .
|
|
See also
|
|
.BR LDAP_OPT_X_SASL_SECPROPS .
|
|
.TP
|
|
.B LDAP_OPT_X_SASL_SSF_MIN
|
|
Gets/sets SASL minimum SSF;
|
|
.BR invalue
|
|
must be
|
|
.BR "const ber_len_t *" ,
|
|
while
|
|
.BR outvalue
|
|
must be
|
|
.BR "ber_len_t *" .
|
|
See also
|
|
.BR LDAP_OPT_X_SASL_SECPROPS .
|
|
.TP
|
|
.B LDAP_OPT_X_SASL_USERNAME
|
|
Gets the SASL username;
|
|
.BR outvalue
|
|
must be a
|
|
.BR "char **" .
|
|
Its content needs to be freed by the caller using
|
|
.BR ldap_memfree (3).
|
|
.B LDAP_OPT_X_SASL_CBINDING
|
|
Sets/gets the channel-binding type to use in SASL,
|
|
one of
|
|
.BR LDAP_OPT_X_SASL_CBINDING_NONE
|
|
(the default),
|
|
.BR LDAP_OPT_X_SASL_CBINDING_TLS_UNIQUE
|
|
the "tls-unique" type from RFC 5929.
|
|
.BR LDAP_OPT_X_SASL_CBINDING_TLS_ENDPOINT
|
|
the "tls-server-end-point" from RFC 5929, compatible with Windows.
|
|
.BR invalue
|
|
must be
|
|
.BR "const int *" ;
|
|
.BR outvalue
|
|
must be
|
|
.BR "int *" .
|
|
.TP
|
|
.SH TCP OPTIONS
|
|
The TCP options are OpenLDAP specific.
|
|
Mainly intended for use with Linux, they may not be portable.
|
|
.TP
|
|
.B LDAP_OPT_X_KEEPALIVE_IDLE
|
|
Sets/gets the number of seconds a connection needs to remain idle
|
|
before TCP starts sending keepalive probes.
|
|
.BR invalue
|
|
must be
|
|
.BR "const int *" ;
|
|
.BR outvalue
|
|
must be
|
|
.BR "int *" .
|
|
.TP
|
|
.B LDAP_OPT_X_KEEPALIVE_PROBES
|
|
Sets/gets the maximum number of keepalive probes TCP should send
|
|
before dropping the connection.
|
|
.BR invalue
|
|
must be
|
|
.BR "const int *" ;
|
|
.BR outvalue
|
|
must be
|
|
.BR "int *" .
|
|
.TP
|
|
.B LDAP_OPT_X_KEEPALIVE_INTERVAL
|
|
Sets/gets the interval in seconds between individual keepalive probes.
|
|
.BR invalue
|
|
must be
|
|
.BR "const int *" ;
|
|
.BR outvalue
|
|
must be
|
|
.BR "int *" .
|
|
.SH TLS OPTIONS
|
|
The TLS options are OpenLDAP specific.
|
|
.\".TP
|
|
.\".B LDAP_OPT_X_TLS
|
|
.\"Sets/gets the TLS mode.
|
|
.TP
|
|
.B LDAP_OPT_X_TLS_CACERTDIR
|
|
Sets/gets the path of the directory containing CA certificates.
|
|
.BR invalue
|
|
must be
|
|
.BR "const char *" ;
|
|
.BR outvalue
|
|
must be
|
|
.BR "char **" ,
|
|
and its contents need to be freed by the caller using
|
|
.BR ldap_memfree (3).
|
|
.TP
|
|
.B LDAP_OPT_X_TLS_CACERTFILE
|
|
Sets/gets the full-path of the CA certificate file.
|
|
.BR invalue
|
|
must be
|
|
.BR "const char *" ;
|
|
.BR outvalue
|
|
must be
|
|
.BR "char **" ,
|
|
and its contents need to be freed by the caller using
|
|
.BR ldap_memfree (3).
|
|
.TP
|
|
.B LDAP_OPT_X_TLS_CERTFILE
|
|
Sets/gets the full-path of the certificate file.
|
|
.BR invalue
|
|
must be
|
|
.BR "const char *" ;
|
|
.BR outvalue
|
|
must be
|
|
.BR "char **" ,
|
|
and its contents need to be freed by the caller using
|
|
.BR ldap_memfree (3).
|
|
.TP
|
|
.B LDAP_OPT_X_TLS_CIPHER
|
|
Gets the cipher being used on an established TLS session.
|
|
.BR outvalue
|
|
must be
|
|
.BR "char **" ,
|
|
and its contents need to be freed by the caller using
|
|
.BR ldap_memfree (3).
|
|
.TP
|
|
.B LDAP_OPT_X_TLS_CIPHER_SUITE
|
|
Sets/gets the allowed cipher suite.
|
|
.BR invalue
|
|
must be
|
|
.BR "const char *" ;
|
|
.BR outvalue
|
|
must be
|
|
.BR "char **" ,
|
|
and its contents need to be freed by the caller using
|
|
.BR ldap_memfree (3).
|
|
.TP
|
|
.B LDAP_OPT_X_TLS_CONNECT_ARG
|
|
Sets/gets the connection callback argument.
|
|
.BR invalue
|
|
must be
|
|
.BR "const void *" ;
|
|
.BR outvalue
|
|
must be
|
|
.BR "void **" .
|
|
.TP
|
|
.B LDAP_OPT_X_TLS_CONNECT_CB
|
|
Sets/gets the connection callback handle.
|
|
.BR invalue
|
|
must be
|
|
.BR "const LDAP_TLS_CONNECT_CB *" ;
|
|
.BR outvalue
|
|
must be
|
|
.BR "LDAP_TLS_CONNECT_CB **" .
|
|
.TP
|
|
.B LDAP_OPT_X_TLS_CRLCHECK
|
|
Sets/gets the CRL evaluation strategy, one of
|
|
.BR LDAP_OPT_X_TLS_CRL_NONE ,
|
|
.BR LDAP_OPT_X_TLS_CRL_PEER ,
|
|
or
|
|
.BR LDAP_OPT_X_TLS_CRL_ALL .
|
|
.BR invalue
|
|
must be
|
|
.BR "const int *" ;
|
|
.BR outvalue
|
|
must be
|
|
.BR "int *" .
|
|
Requires OpenSSL.
|
|
.TP
|
|
.B LDAP_OPT_X_TLS_CRLFILE
|
|
Sets/gets the full-path of the CRL file.
|
|
.BR invalue
|
|
must be
|
|
.BR "const char *" ;
|
|
.BR outvalue
|
|
must be
|
|
.BR "char **" ,
|
|
and its contents need to be freed by the caller using
|
|
.BR ldap_memfree (3).
|
|
This option is only valid for GnuTLS.
|
|
.TP
|
|
.B LDAP_OPT_X_TLS_CTX
|
|
Sets/gets the TLS library context. New TLS sessions will inherit their
|
|
default settings from this library context.
|
|
.BR invalue
|
|
must be
|
|
.BR "const void *" ;
|
|
.BR outvalue
|
|
must be
|
|
.BR "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.
|
|
.TP
|
|
.B LDAP_OPT_X_TLS_DHFILE
|
|
Gets/sets the full-path of the file containing the parameters
|
|
for Diffie-Hellman ephemeral key exchange.
|
|
.BR invalue
|
|
must be
|
|
.BR "const char *" ;
|
|
.BR outvalue
|
|
must be
|
|
.BR "char **" ,
|
|
and its contents need to be freed by the caller using
|
|
.BR ldap_memfree (3).
|
|
.TP
|
|
.B LDAP_OPT_X_TLS_ECNAME
|
|
Gets/sets the name of the curve(s) used for
|
|
elliptic curve key exchanges.
|
|
.BR invalue
|
|
must be
|
|
.BR "const char *" ;
|
|
.BR outvalue
|
|
must be
|
|
.BR "char **" ,
|
|
and its contents need to be freed by the caller using
|
|
.BR ldap_memfree (3).
|
|
Ignored by GnuTLS. In GnuTLS a curve may be selected
|
|
in the cipher suite specification.
|
|
.TP
|
|
.B LDAP_OPT_X_TLS_KEYFILE
|
|
Sets/gets the full-path of the certificate key file.
|
|
.BR invalue
|
|
must be
|
|
.BR "const char *" ;
|
|
.BR outvalue
|
|
must be
|
|
.BR "char **" ,
|
|
and its contents need to be freed by the caller using
|
|
.BR ldap_memfree (3).
|
|
.TP
|
|
.B LDAP_OPT_X_TLS_NEWCTX
|
|
Instructs the library to create a new TLS library context.
|
|
.BR invalue
|
|
must be
|
|
.BR "const int *" .
|
|
A non-zero value pointed to by
|
|
.BR invalue
|
|
tells the library to create a context for a server.
|
|
.TP
|
|
.B LDAP_OPT_X_TLS_PEERCERT
|
|
Gets the peer's certificate in DER format from an established TLS session.
|
|
.BR outvalue
|
|
must be
|
|
.BR "struct berval *" ,
|
|
and the data it returns needs to be freed by the caller using
|
|
.BR ldap_memfree (3).
|
|
.TP
|
|
.B LDAP_OPT_X_TLS_PROTOCOL_MIN
|
|
Sets/gets the minimum protocol version.
|
|
.BR invalue
|
|
must be
|
|
.BR "const int *" ;
|
|
.BR outvalue
|
|
must be
|
|
.BR "int *" .
|
|
.TP
|
|
.B LDAP_OPT_X_TLS_RANDOM_FILE
|
|
Sets/gets the random file when
|
|
.B /dev/random
|
|
and
|
|
.B /dev/urandom
|
|
are not available.
|
|
.BR invalue
|
|
must be
|
|
.BR "const char *" ;
|
|
.BR outvalue
|
|
must be
|
|
.BR "char **" ,
|
|
and its contents need to be freed by the caller using
|
|
.BR ldap_memfree (3).
|
|
Ignored by GnuTLS older than version 2.2.
|
|
.TP
|
|
.B LDAP_OPT_X_TLS_REQUIRE_CERT
|
|
Sets/gets the peer certificate checking strategy,
|
|
one of
|
|
.BR LDAP_OPT_X_TLS_NEVER ,
|
|
.BR LDAP_OPT_X_TLS_HARD ,
|
|
.BR LDAP_OPT_X_TLS_DEMAND ,
|
|
.BR LDAP_OPT_X_TLS_ALLOW ,
|
|
.BR LDAP_OPT_X_TLS_TRY .
|
|
.TP
|
|
.B LDAP_OPT_X_TLS_REQUIRE_SAN
|
|
Sets/gets the peer certificate subjectAlternativeName checking strategy,
|
|
one of
|
|
.BR LDAP_OPT_X_TLS_NEVER ,
|
|
.BR LDAP_OPT_X_TLS_HARD ,
|
|
.BR LDAP_OPT_X_TLS_DEMAND ,
|
|
.BR LDAP_OPT_X_TLS_ALLOW ,
|
|
.BR LDAP_OPT_X_TLS_TRY .
|
|
.TP
|
|
.B LDAP_OPT_X_TLS_SSL_CTX
|
|
Gets the TLS session context associated with this handle.
|
|
.BR outvalue
|
|
must be
|
|
.BR "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.
|
|
.TP
|
|
.B LDAP_OPT_X_TLS_VERSION
|
|
Gets the TLS version being used on an established TLS session.
|
|
.BR outvalue
|
|
must be
|
|
.BR "char **" ,
|
|
and its contents need to be freed by the caller using
|
|
.BR ldap_memfree (3).
|
|
.SH ERRORS
|
|
On success, the functions return
|
|
.BR LDAP_OPT_SUCCESS ,
|
|
while they may return
|
|
.B LDAP_OPT_ERROR
|
|
to indicate a generic option handling error.
|
|
Occasionally, more specific errors can be returned, like
|
|
.B LDAP_NO_MEMORY
|
|
to indicate a failure in memory allocation.
|
|
.SH NOTES
|
|
The LDAP libraries with the
|
|
.B LDAP_OPT_REFERRALS
|
|
option set to
|
|
.B 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
|
|
.BR LDAP_OPT_OFF .
|
|
.P
|
|
The protocol version used by the library defaults to LDAPv2 (now historic),
|
|
which corresponds to the
|
|
.B LDAP_VERSION2
|
|
macro.
|
|
Application developers are encouraged to explicitly set
|
|
.B LDAP_OPT_PROTOCOL_VERSION
|
|
to LDAPv3, using the
|
|
.B LDAP_VERSION3
|
|
macro, or to allow users to select the protocol version.
|
|
.SH SEE ALSO
|
|
.BR ldap (3),
|
|
.BR ldap_error (3),
|
|
.B RFC 4422
|
|
(http://www.rfc-editor.org),
|
|
.SH ACKNOWLEDGEMENTS
|
|
.so ../Project
|