ldap_set_option(), ldap_set_option_np()
Purpose
Set the value for an LDAP option
Format
#include <ldap.h>
int ldap_set_option(
LDAP * ld,
int option,
void * value)
int ldap_set_option_np(
LDAP * ld,
int option,
…)
Parameters
Input
- ld
- Specifies the LDAP handle.
- option
- Specifies the option identifier.
- value
- Specifies the option value.
Usage
The ldap_set_option() and ldap_set_option_np() routines set the value for an LDAP option in the supplied LDAP handle. The routines differ only in the way the third parameter is specified.
2
for LDAP handles created by the ldap_open() routine
and 3
for LDAP handles created by the ldap_init() and ldap_ssl_init() routines. Table 1 summarizes how
to specify the options.Option | ldap_set_option Version 2 |
ldap_set_option Version 3 |
ldap_set_option_np |
---|---|---|---|
LDAP_OPT_CLIENT_CONTROLS |
LDAPControl ** |
LDAPControl ** |
|
LDAP_OPT_DEBUG |
int |
int * |
int |
LDAP_OPT_DEBUG_FILENAME |
char * |
char * |
char * |
LDAP_OPT_DEBUG_STRING |
char * |
char * |
char * |
LDAP_OPT_DELEGATION |
int |
int |
|
LDAP_OPT_DEREF |
int |
int * |
int |
LDAP_OPT_EXT_REBIND_FN |
LDAPExtRebindProc |
LDAPExtRebindProc |
LDAPExtRebindProc |
LDAP_OPT_IO_CALLBACK |
LDAPIOCallback * |
LDAPIOCallback * |
LDAPIOCallback * |
LDAP_OPT_MAX_SASL_LEVEL |
int * |
int |
|
LDAP_OPT_MIN_SASL_LEVEL |
int * |
int |
|
LDAP_OPT_PROTOCOL_VERSION |
int * |
int * |
int |
LDAP_OPT_REBIND_FN |
LDAPRebindProc |
LDAPRebindProc |
LDAPRebindProc |
LDAP_OPT_REFERRALS |
int |
int |
int |
LDAP_OPT_REFHOPLIMIT |
int |
int * |
int |
LDAP_OPT_RESTART |
int |
int |
int |
LDAP_OPT_SERVER_CONTROLS |
LDAPControl ** |
LDAPControl ** |
|
LDAP_OPT_SIZELIMIT |
int |
int * |
int |
LDAP_OPT_SOCKS_CONF |
char * |
char * |
char * |
LDAP_OPT_SOCKS_PASSWORD |
char * |
char * |
char * |
LDAP_OPT_SOCKS_SERVER |
char * |
char * |
char * |
LDAP_OPT_SOCKS_USERNAME |
char * |
char * |
char * |
LDAP_OPT_SOCKS_VERSION |
int |
int * |
int |
LDAP_OPT_SSL_CIPHER |
char * |
char * |
char * |
LDAP_OPT_SSL_CIPHER_EXPANDED |
char * |
char * |
char * |
LDAP_OPT_SSL_CIPHER_FORMAT |
int |
int |
int |
LDAP_OPT_SSL_TIMEOUT |
int |
int * |
int |
LDAP_OPT_TIMELIMIT |
int |
int * |
int |
LDAP_OPT_UTF8_IO |
int |
int |
int |
LDAP_OPT_V2_WIRE_FORMAT |
int |
int |
int |
LDAP_OPT_SIZELIMIT
option is specified as follows: int sizeLimit = 50;
/* Version 2 */
ldap_set_option(ld, LDAP_OPT_SIZELIMIT, (void *)sizeLimit);
/* Version 3 */
ldap_set_option(ld, LDAP_OPT_SIZELIMIT, &sizeLimit);
/* Version 2 or Version 3 */
ldap_set_option_np(ld, LDAP_OPT_SIZELIMIT, sizeLimit);
- LDAP_OPT_CLIENT_CONTROLS
- The
LDAP_OPT_CLIENT_CONTROLS
option specifies a default list of client controls to be processed with each request. The end of the list is indicated by aNULL
control address. SpecifyNULL
for the list address to clear the current client controls list for the LDAP handle. The entire list is rejected if the list includes a critical client control that is not recognized by the LDAP client run time. A parameter error is returned if the LDAP protocol version is not set toLDAP_VERSION3
. The default list can be overridden by specifying a client control, or a list of client controls, on specific API routines. There are no default client controls if theLDAP_OPT_CLIENT_CONTROLS
option is not set.The OID string in the client control is a null-terminated character string in UTF-8 or the local EBCDIC code page, as determined by the
LDAP_OPT_UTF8_IO
option of the LDAP handle. In addition, a client control value that is a character string is in UTF-8 or the local EBCDIC code page, as determined by theLDAP_OPT_UTF8_IO
option of the LDAP handle.The following client controls are supported:
For more information about client controls, see Supported client controls.ibm-saslBindCramRealmName 1.3.18.0.2.10.12 ibm-saslBindCramUserName 1.3.18.0.2.10.13 ibm-saslBindDigestRealmName 1.3.18.0.2.10.12 ibm-saslBindDigestUserName 1.3.18.0.2.10.13 ibm-serverHandledSearchRequest 1.3.18.0.2.10.7
- LDAP_OPT_DEBUG
- The
LDAP_OPT_DEBUG
option specifies a bitmap that indicates the level of debug trace you want for the LDAP client run time and overrides the debug trace level that is set by theLDAP_DEBUG
environment variable. The debug trace level applies to the entire process and not just the LDAP handle. For this reason, the LDAP handle can be specified asNULL
, in which case the ldap_set_option() routine expects the debug trace level to be specified as the address of an integer and the ldap_set_option_np() routine expects the debug trace level to be specified as an integer. If specified, the LDAP handle must be a valid handle.The option value is formed byORing
together one or more of the following debug options:- LDAP_DEBUG_ACL
- Trace ACL processing
- LDAP_DEBUG_ALL
- Enable all debug traces (same as
LDAP_DEBUG_ANY
) - LDAP_DEBUG_ANY
- Enable all debug traces (same as
LDAP_DEBUG_ALL
) - LDAP_DEBUG_ARGS
- Trace request arguments
- LDAP_DEBUG_BE_CAPABILITIES
- Trace backend capabilities
- LDAP_DEBUG_BER
- Trace ASN.1 encode and decode processing
- LDAP_DEBUG_CACHE
- Trace cache activity
- LDAP_DEBUG_CONNS
- Trace connection activity
- LDAP_DEBUG_ERROR
- Trace errors
- LDAP_DEBUG_FILTER
- Trace filter processing
- LDAP_DEBUG_INFO
- Trace informational messages
- LDAP_DEBUG_LDAPBE
- Trace server backend activity
- LDAP_DEBUG_LDBM
- Trace file backend activity
- LDAP_DEBUG_MESSAGE
- Trace message processing
- LDAP_DEBUG_MULTISERVER
- Trace multiple server activity
- LDAP_DEBUG_OFF
- Disable all debug traces
- LDAP_DEBUG_PACKETS
- Trace packet activity
- LDAP_DEBUG_PARSE
- Trace parsing activity
- LDAP_DEBUG_PERFORMANCE
- Trace performance statistics
- LDAP_DEBUG_PLUGIN
- Trace plug-in extension activity
- LDAP_DEBUG_REFERRAL
- Trace referral activity
- LDAP_DEBUG_REPLICATION
- Trace replication activity
- LDAP_DEBUG_SCHEMA
- Trace schema processing
- LDAP_DEBUG_SDBM
- Trace RACF® backend activity
- LDAP_DEBUG_STATS
- Trace operational statistics
- LDAP_DEBUG_STRBUF
- Trace and UTF-8 activity
- LDAP_DEBUG_SYSPLEX
- Trace sysplex activity
- LDAP_DEBUG_TDBM
- Trace TDBM database processing
- LDAP_DEBUG_THREAD
- Trace thread activity
- LDAP_DEBUG_TRACE
- Trace API routine entry and exit
- LDAP_OPT_DEBUG_FILENAME
- The
LDAP_OPT_DEBUG_FILENAME
option specifies the name of the LDAP trace output file and overrides the name that is set by theLDAP_DEBUG_FILENAME
environment variable. The debug file name applies to the entire process and not just the LDAP handle. For this reason, the LDAP handle can be specified asNULL
. If specified, the LDAP handle must be a valid handle. The file name is in the local EBCDIC code page or UTF-8, as determined by theLDAP_LIBASCII
compiler variable.The trace output is written to
stdout
if theLDAP_OPT_DEBUG_FILENAME
option is not set and theLDAP_DEBUG_FILENAME
environment variable is not defined. Therefore, theLDAP_OPT_DEBUG_FILENAME
option should be set before either theLDAP_OPT_DEBUG
orLDAP_OPT_DEBUG_STRING
option is set if the trace output is not to be written to the default trace file as specified by theLDAP_DEBUG_FILENAME
environment variable.The current process identifier is included as part of the trace file name when the name contains a percent sign (
%
). For example, ifLDAP_OPT_DEBUG_FILENAME
is set to/tmp/ldap.%.trc
and the current process identifier is 247, then the trace file name is/tmp/ldap.247.trc
. The trace file name should be unique for each process with LDAP trace enabled because the trace output can be corrupted if multiple processes use the same trace file.LDAP_LOCAL_ERROR
is returned if the specified trace file cannot be opened. In this case, the trace output is written tostdout
until a subsequent call is successful in setting theLDAP_OPT_DEBUG_FILENAME
option. - LDAP_OPT_DEBUG_STRING
- The
LDAP_OPT_DEBUG_STRING
option specifies LDAP trace options as a null-terminated character string and either completely replaces or incrementally modifies the trace options that are set by theLDAP_DEBUG
environment variable. The debug trace level applies to the entire process and not just the LDAP handle. For this reason, the LDAP handle can be specified asNULL
. If specified, the LDAP handle must be a valid handle. The debug string is in the local EBCDIC code page or UTF-8, as determined by theLDAP_LIBASCII
compiler variable.The value forLDAP_OPT_DEBUG_STRING
is a character string that can be specified as follows:- A decimal value (for example,
32
) - A hexadecimal value (for example,
x20
orX20
) - A keyword (for example,
FILTER
) - A construct of these values using plus and minus signs to indicate inclusion or exclusion of a value.
The trace options that are specified by the
LDAP_DEBUG
environment variable are modified if theLDAP_OPT_DEBUG_STRING
starts with a plus or minus sign. Otherwise, the trace options that are specified by theLDAP_DEBUG
environment variable are replaced with the options specified by theLDAP_OPT_DEBUG_STRING
option. For more information about the LDAP trace options, see Enabling tracing. - A decimal value (for example,
- LDAP_OPT_DELEGATION
- The
LDAP_OPT_DELEGATION
option specifies whether the LDAP client passes Kerberos delegated credentials to the LDAP server. It must be set to eitherLDAP_OPT_ON
orLDAP_OPT_OFF
. The default isLDAP_OPT_OFF
. A parameter error is returned if the LDAP protocol version is not set toLDAP_VERSION3
. Use this option if you want to allow the LDAP server to use the client's credentials for requests. Note the server might or might not support this capability. - LDAP_OPT_DEREF
- The
LDAP_OPT_DEREF
option specifies how the LDAP server handles aliases during search request. It must have one of the following values:LDAP_DEREF_ALWAYS
- Dereference aliases both in searching and in locating the base object of the search.
LDAP_DEREF_FINDING
- Dereference aliases in locating the base object of the search but not when searching subordinates of the base object.
LDAP_DEREF_NEVER
- Do not dereference aliases. (This is the default.)
LDAP_DEREF_SEARCHING
- Dereference aliases in subordinates of the base object in searching but not in locating the base object of the search.
- LDAP_OPT_EXT_REBIND_FN
- The
LDAP_OPT_EXT_REBIND_FN
option specifies the routine to be called by the LDAP client run time when it must authenticate a connection with another LDAP server. This can occur when the LDAP client is following a referral returned by the initial LDAP server. If a rebind routine is not defined, referrals are followed using an anonymous bind. For more information about the rebind routine, see Rebinding while following referrals. SpecifyNULL
for the rebind function to stop using a rebind routine.The rebind routine set by the
LDAP_OPT_EXT_REBIND_FN
option can be used if bothLDAP_OPT_EXT_REBIND_FN
andLDAP_OPT_REBIND_FN
are set for the LDAP handle. - LDAP_OPT_IO_CALLBACK
- The
LDAP_OPT_IO_CALLBACK
option specifies routines to be called by the LDAP client run time when it must communicate with the LDAP server. The C/C++ runtime (LE) socket routines, such as socket(), bind(), connect(), getpeername(), send(), select(), recv(), and close(), are used if the application does not provide its own routines.TheLDAP_OPT_IO_CALLBACK
option cannot be changed after a connection is established with the LDAP server. SpecifyNULL
for the address of theLDAPIOCallback
structure to revert to the normal socket routines. The callback routines are used when following referrals returned by the local LDAP server. TheLDAPIOCallback
structure is defined as follows:typedef struct _LDAPIOCallback { void * userData; int (*connect)(const char * host, int port, int * desc, void * userData); int (*getpeer)(int desc, struct sockaddr * addr, size_t size, size_t * length, void * userData); int (*send)(int desc, const void * buffer, size_t length, void * userData); int (*select)(int desc[], struct timeval * timeout, int * rtndesc, void * userData); int (*recv)(int desc, void * buffer, size_t size, size_t * length, void * userData); void (*close)(int desc, void * userData); } LDAPIOCallback;
The fields in theLDAPIOCallback
structure are used as follows:- userData
- The userData value is passed to each of the callback routines.
Specify
NULL
for this field if you do not need to pass anything to the callback routines. - connect
- The connect routine should be called when the LDAP client
run time must establish a connection with the LDAP server. The host and port values are obtained from the ldap_init(), ldap_ssl_init() or ldap_open() routine. If an LDAP
URL was specified, the host parameter contains the host name
that is obtained from the URL. The callback routine can use these
values to establish the connection, or can ignore them and use a different
algorithm to determine the target for the connection. The return value
must be
0
if the connection is successful, or a value that is defined inerrno.h
if the connection is unsuccessful. The desc parameter should be set to a descriptor for the connection if the request is successful. The descriptor can be anything that is meaningful to the application if it is not-1
. The descriptor is passed to the other callback routines. - getpeer
- The getpeer routine should be called to obtain the connection
name for the LDAP server. For a TCP/IP-based connection, this should
be a
struct sockaddr
for the AF_INET or AF_INET6 family. The addr and size parameters identify the address and size of the return buffer. The callback routine should set the length parameter to the actual size of the returned identification. The return value should be0
for a normal return, or a value that is defined inerrno.h
for a failure return. - send
- The send routine should be called to send data to the LDAP
server. The callback routine is responsible for ensuring that all
the data is sent to the LDAP server (that is, this is a blocking send).
The buffer and length parameters identify the data to
be sent. The return value should be
0
if the data is sent, or a value that is defined inerrno.h
if the data cannot be sent. - select
- The select routine should be called to wait for data on
one or more LDAP server connections. The desc parameter is
an array of descriptors with the last entry in the array set to
-1
. The timeout parameter specifies how long to wait for data to become available.NULL
is passed for the timeout parameter if the select routine is to wait indefinitely. The return value should beEAGAIN
if the time limit is reached,EINTR
if the wait is interrupted by a signal, or0
if there is data or status available for a connection. The rtndesc parameter should be set to the descriptor with pending data or status. - recv
- The recv routine should be called to receive data or connection
status from the LDAP server. The callback routine should not return
until it has either data or an error (that is, this is a blocking
receive). The buffer and size parameters identify the
receive buffer address and size. The callback routine should set the length parameter to the actual data length. The return value
should be
0
if data is received,ECONNRESET
if the connection is closed, or a value that is defined inerrno.h
if an error is detected. - close
- The close routine should be called to close the connection to the LDAP server.
- LDAP_OPT_MAX_SASL_LEVEL
- The
LDAP_OPT_MAX_SASL_LEVEL
option specifies the maximum SASL protection level for the LDAP handle. This is the highest SASL protection level that can be negotiated during a bind using aSASL
mechanism. The negotiated protection level cannot be greater than this level even if the server offers a higher protection level.LDAP_PARAM_ERROR
is returned if the LDAP protocol version is not set toLDAP_VERSION3
.The SASL protection levels, in increasing level of protection, are:LDAP_SASL_LEVEL_NONE
- No integrity or confidentiality protection.
LDAP_SASL_LEVEL_INTEG
- Integrity protection.
LDAP_SASL_LEVEL_CONF
- Integrity and confidentiality protection. (This is the default.)
- LDAP_OPT_MIN_SASL_LEVEL
- The
LDAP_OPT_MIN_SASL_LEVEL
option specifies the minimum SASL protection level for the LDAP handle. This is the lowest SASL protection level that can be negotiated during a bind using aSASL
mechanism. The bind fails if the server does not offer at least this protection level.LDAP_PARAM_ERROR
is returned if the LDAP protocol version is not set toLDAP_VERSION3
.The SASL protection levels, in increasing level of protection, are:LDAP_SASL_LEVEL_NONE
- No integrity or confidentiality protection. (This is the default.)
LDAP_SASL_LEVEL_INTEG
- Integrity protection.
LDAP_SASL_LEVEL_CONF
- Integrity and confidentiality protection.
- LDAP_OPT_PROTOCOL_VERSION
- The
LDAP_OPT_PROTOCOL_VERSION
option specifies the LDAP protocol version that is used by the LDAP client when connecting to an LDAP server. It must be set to eitherLDAP_VERSION2
orLDAP_VERSION3
. The default isLDAP_VERSION3
if ldap_init() or ldap_ssl_init() can be used to create the LDAP handle, andLDAP_VERSION2
if ldap_open() can be used to create the LDAP handle. In either case, theLDAP_OPT_PROTOCOL_VERSION
option can be used to change the default protocol version. The protocol version must be set before the client binds to an LDAP server as a result of calling ldap_bind(), ldap_bind_s(), ldap_sasl_bind(), ldap_sasl_bind_s(), ldap_simple_bind(), ldap_simple_bind_s(), or any routine that causes an implicit bind. An error is returned if theLDAP_OPT_PROTOCOL_VERSION
option is specified after a connection is established with the LDAP server.Note: The LDAP protocol version affects the way parameters are specified for the ldap_set_option() routine. Therefore, theLDAP_OPT_PROTOCOL_VERSION
option should be set before any other LDAP options are set. - LDAP_OPT_REBIND_FN
- The
LDAP_OPT_REBIND_FN
option specifies the routine to be called by the LDAP client run time when it must authenticate a connection with another LDAP server. This can occur when the LDAP client is following a referral that is returned by the initial LDAP server. If a rebind routine is not defined, referrals are followed using an anonymous bind. For more information about the rebind routine, see Rebinding while following referrals. SpecifyNULL
for the rebind function to stop using a rebind routine.The rebind routine set by the
LDAP_OPT_EXT_REBIND_FN
option can be used if bothLDAP_OPT_EXT_REBIND_FN
andLDAP_OPT_REBIND_FN
are set for the LDAP handle. - LDAP_OPT_REFERRALS
- The
LDAP_OPT_REFERRALS
option specifies whether the LDAP client follows referrals that are returned by the LDAP server. It must be set to eitherLDAP_OPT_ON
orLDAP_OPT_OFF
. The default isLDAP_OPT_ON
. - LDAP_OPT_REFHOPLIMIT
- The
LDAP_OPT_REFHOPLIMIT
option specifies the maximum number of LDAP servers to contact when following a referral. For subtree searches, this is the limit on the depth of nested search references, so the number of servers that are contacted might actually exceed this value. The default is10
. - LDAP_OPT_RESTART
- The
LDAP_OPT_RESTART
option specifies whether the select() system call should be restarted when it is interrupted by the system. It must be set to eitherLDAP_OPT_ON
orLDAP_OPT_OFF
. The default isLDAP_OPT_OFF
. - LDAP_OPT_SERVER_CONTROLS
- The
LDAP_OPT_SERVER_CONTROLS
option specifies a default list of server controls to be sent with each request. The end of the list is indicated by aNULL
control address. SpecifyNULL
for the list address to clear the current server controls list for the LDAP handle. A parameter error is returned if the LDAP protocol version is not set toLDAP_VERSION3
. The default list can be overridden by specifying a server control, or a list of server controls, on specific API routines. There are no default server controls if theLDAP_OPT_SERVER_CONTROLS
option is not set.The OID string in the server control is a null-terminated character string in UTF-8 or the local EBCDIC code page, as determined by the LDAP handle. The OID value is assumed to already be in the correct format for transmission to the server and the LDAP client does not modify it.
- LDAP_OPT_SIZELIMIT
- The
LDAP_OPT_SIZELIMIT
option specifies the maximum number of entries that can be returned for a search request. The LDAP server can also provide a size limit on the number of entries returned. For information about the server's size limit and how it interacts with the client size limit, see the documentation for your LDAP server. For the IBM® Tivoli® Directory Server for z/OS®, see the description of the sizeLimit configuration file option (Customizing the LDAP server configuration) in z/OS IBM Tivoli Directory Server Administration and Use for z/OS. The default size limit for the client, which is specified by a value of0
, indicates that the maximum number of entries is limited only by the LDAP server limit. - LDAP_OPT_SOCKS_CONF
- The
LDAP_OPT_SOCKS_CONF
option specifies the name of the SOCKS configuration file to be used when connecting to the LDAP server, and overrides theSOCKS_CONF
andSOCKS_SERVER
environment variables and also theLDAP_OPT_SOCKS_SERVER
option. The option value is a null-terminated character string in the local EBCDIC code page or UTF-8, as determined by theLDAP_LIBASCII
compiler variable. SpecifyNULL
for the option value to cancel the SOCKS configuration that is specified by theSOCKS_CONF
orSOCKS_SERVER
environment variable and use a direct connection to the LDAP server. - LDAP_OPT_SOCKS_PASSWORD
- The
LDAP_OPT_SOCKS_PASSWORD
option specifies the SOCKS password to be used when connecting to the LDAP server through a SOCKS server, and overrides theSOCKS_PASSWORD
environment variable. The option value is a null-terminated character string in the local EBCDIC code page or UTF-8, as determined by theLDAP_LIBASCII
compiler variable. SpecifyNULL
for the option value to indicate that no password is to be used.A SOCKS user name and password are required when using the SOCKS version 5 protocol and the SOCKS server is configured to require user authentication. An unauthenticated SOCKS connection can be used if the SOCKS user name and password are not set. Note authentication for the SOCKS connection is separate from the bind authentication for the LDAP server. The SOCKS user name and password are not used for the SOCKS version 4 protocol.
- LDAP_OPT_SOCKS_SERVER
- The
LDAP_OPT_SOCKS_SERVER
option specifies the SOCKS servers to be used when connecting to the LDAP server, and overrides theSOCKS_CONF
andSOCKS_SERVER
environment variables and also theLDAP_OPT_SOCKS_CONF
option. The option value is a null-terminated character string in the local EBCDIC code page or UTF-8, as determined by theLDAP_LIBASCII
compiler variable, and consists of a comma-separated list of SOCKS servers. Each SOCKS server is specified ashost:port
. The host is a DNS name, an IPv4 address in dotted decimal format, or an IPv6 address in colon-separated format that is enclosed in square brackets. The port defaults to1080
, if it is not specified. SpecifyNULL
for the option value to cancel the SOCKS configuration that is specified by theSOCKS_CONF
orSOCKS_SERVER
environment variable and use a direct connection to the LDAP server. - LDAP_OPT_SOCKS_USERNAME
- The
LDAP_OPT_SOCKS_USERNAME
option specifies the SOCKS user name to be used when connecting to the LDAP server through a SOCKS server. It overrides theSOCKS_USERNAME
environment variable. The option value is a null-terminated character string in the local EBCDIC code page or UTF-8, as determined by theLDAP_LIBASCII
compiler variable. SpecifyNULL
for the option value to indicate that no user name is to be used.A SOCKS user name and password are required when using the SOCKS version 5 protocol and the SOCKS server is configured to require user authentication. An unauthenticated SOCKS connection can be used if the SOCKS user name and password are not set. Note authentication for the SOCKS connection is separate from the bind authentication for the LDAP server. The SOCKS user name and password are not used for the SOCKS version 4 protocol.
- LDAP_OPT_SOCKS_VERSION
- The
LDAP_OPT_SOCKS_VERSION
option specifies the SOCKS protocol version, and overrides theSOCKS_VERSION
environment variable. The valid values are4
and5
. The default is4
. However, the SOCKS version 5 protocol is always used when the LDAP server address is an IPv6 address because the SOCKS version 4 protocol does not support IPv6 addresses. You can set theLDAP_OPT_SOCKS_VERSION
option to5
to cause the LDAP client run time to always use the SOCKS version 5 protocol. - LDAP_OPT_SSL_CIPHER
- This option is pertinent if 2-byte
SSL ciphers are currently in effect, which is based on the setting of the environment variable
LDAP_SSL_CIPHER_FORMAT or the LDAP_OPT_SSL_CIPHER_FORMAT option. Also see the description of the
option
LDAP_OPT_SSL_CIPHER_EXPANDED
. Only one of these settings are pertinent at one time.The
LDAP_OPT_SSL_CIPHER
option specifies one or more cipher suites to be used when negotiating an SSL connection with the LDAP server. The default SSL cipher suites are used if theLDAP_OPT_SSL_CIPHER
option is not set. TheGSK_V3_CIPHER_SPECS
environment variable can be used to change the default cipher suites. The option value is a null-terminated character string in the local EBCDIC code page or UTF-8, as determined by theLDAP_LIBASCII
compiler variable. The string consists of the cipher suites you want as two hexadecimal digits per cipher suite. For example, to choose from RC4-MD5-US, RC4-SHA-1, and AES-128-SHA-1, specify04052F
.For compatibility with prior releases, the
ldap.h
include file provides definitions for 2-byte cipher suites that are supported in SSL V3 and TLS V1.0 as a coding convenience. The definitions are summarized in Table 3. The mnemonics ending in_EX
are always available. The other mnemonics are available only when the SSL Security Level 3 FMID is installed. For newer cipher suites supported in later TLS protocols, use the two hexadecimal digit forms for each cipher suite you want. For more information about theGSK V3_CIPHER_SPECS
environment variable and SSL cipher suites, see Environment variables and Cipher suite definitions in z/OS Cryptographic Services System SSL Programming. The SSL cipher list must be set before an SSL connection is established to the LDAP server. - LDAP_OPT_SSL_CIPHER_EXPANDED
- This option is pertinent provided
4-byte SSL ciphers are currently in effect, which is based on the setting of the environment
variable
LDAP_SSL_CIPHER_FORMAT
or theLDAP_OPT_SSL_CIPHER_FORMAT
option. Also, see the description of the optionLDAP_OPT_SSL_CIPHER
above. Only one of these two settings are pertinent at one time.The
LDAP_OPT_SSL_CIPHER
option specifies one or more cipher suites to be used when negotiating an SSL connection with the LDAP server. The default SSL cipher suites are used if theLDAP_OPT_SSL_CIPHER_EXPANDED
option is not set. TheGSK_V3_CIPHER_SPECS_EXPANDED
environment variable can be used to change the default cipher suites. The option value is a null-terminated character string in the local EBCDIC code page or UTF-8, as determined by theLDAP_LIBASCII
compiler variable. The string consists of the cipher suites you want as four hexadecimal digits per cipher suite. For example, to choose from RC4-MD5-US, RC4-SHA-1, and AES-128-SHA-1, specify00040005002F
.For more information about the
GSK_V3_CIPHER_SPECS_EXPANDED
environment variable and SSL cipher suites, see Environment variables and Cipher suite definitions in z/OS Cryptographic Services System SSL Programming. The SSL cipher list must be set before an SSL connection is established to the LDAP server. - LDAP_OPT_SSL_CIPHER_FORMAT
- This option indicates the length of SSL cipher specifications to
be used. Valid values are
LDAP_SSL_CIPHER_FORMAT_CHAR2 and LDAP_SSL_CIPHER_FORMAT_CHAR4
, whereLDAP_SSL_CIPHER_FORMAT_CHAR2
is the default setting.A value of
LDAP_SSL_CIPHER_FORMAT_CHAR2
indicates the cipher suites in use come from either SSL defaults, as determined from theGSK_V3_CIPHER_SPECS
environment variable, or from a setting ofLDAP_OPT_SSL_CIPHER
, by way of the ldap_set_option() routine.A value of
LDAP_SSL_CIPHER_FORMAT_CHAR4
indicates the cipher suites in use come from either SSL defaults, as determined from theGSK_V3_CIPHER_SPECS_EXPANDED
environment variable, or from a setting ofLDAP_OPT_SSL_CIPHER_EXPANDED
, by way of the ldap_set_option() routine.The SSL cipher list must be set before an SSL connection is established to the LDAP server.
- LDAP_OPT_SSL_TIMEOUT
- The
LDAP_OPT_SSL_TIMEOUT
option specifies the SSL session timeout value in seconds. Cached SSL sessions are discarded after the specified number of seconds. Cached SSL sessions can be reused and improve performance by eliminating the need for a full SSL handshake when reconnecting to an LDAP server. SSL sessions are not cached if the timeout value is zero. If theLDAP_OPT_SSL_TIMEOUT
option is not set, the default SSL session timeout of86400
seconds can be used. TheGSK_V3_SESSION_TIMEOUT
environment variable can be used to change the default SSL session timeout value. The SSL timeout value must be set before an SSL connection is established to the LDAP server. TheLDAP_OPT_SSL_TIMEOUT
option is ignored if the ldap_ssl_client_init() routine should be called to initialize the SSL environment. - LDAP_OPT_TIMELIMIT
- The
LDAP_OPT_TIMELIMIT
option specifies the number of seconds to wait for search results. The LDAP server can also provide a limit on the search time. For information about the server's search time limit and how it interacts with the client time limit, see the documentation for your LDAP server. For the IBM Tivoli Directory Server for z/OS, see the description of the timeLimit configuration file option (Customizing the LDAP server configuration) in z/OS IBM Tivoli Directory Server Administration and Use for z/OS. The default time limit for the client, which is specified by a value of0
, indicates that there is no client time limit and that the maximum number of seconds is limited only by the LDAP server limit. - LDAP_OPT_UTF8_IO
- The
LDAP_OPT_UTF8_IO
option specifies the format of text data that is provided as input to an LDAP API routine or returned as output by an LDAP API routine.LDAP_OPT_ON
indicates text data is in the UTF-8 code set.LDAP_OPT_OFF
indicates text data is in the code set of the current locale. The default isLDAP_OPT_ON
if theLDAP_LIBASCII
compiler variable is defined andLDAP_OPT_OFF
otherwise.The
LDAP_OPT_UTF8_IO
option applies to all LDAP API routines that accept an LDAP handle as an input parameter, unless noted otherwise in the description of the API routine. Text data for LDAP API routines that do not accept an LDAP handle as an input parameter is in the local EBCDIC code page or UTF-8, as determined by theLDAP_LIBASCII
compiler variable. - LDAP_OPT_V2_WIRE_FORMAT
- The
LDAP_OPT_V2_WIRE_FORMAT
option specifies the format of attribute values that are exchanged between the LDAP client and the LDAP server using the LDAP version 2 protocol. (Attribute values that are exchanged by using the LDAP version 3 protocol are always in UTF-8.)LDAP_OPT_V2_WIRE_FORMAT_ISO8859_1
indicates attribute values are exchanged using the ISO8859-1 code page.LDAP_OPT_V2_WIRE_FORMAT_UTF8
indicates attribute values are exchanged using UTF-8. The default isLDAP_OPT_V2_WIRE_FORMAT_UTF8
.
Function return value
The function return
value is LDAP_SUCCESS
if no error is detected. Otherwise,
it is one of the LDAP error codes that are listed in the ldap.h
include file.
LDAP_INVALID_STATE
- The LDAP handle is not in the correct state for the requested operation.
LDAP_LOCAL_ERROR
- A system routine returned an error.
LDAP_NO_MEMORY
- Insufficient storage is available.
LDAP_PARAM_ERROR
- A parameter is not valid or the LDAP protocol version is not correct for the requested option.
LDAP_UNAVAILABLE_CRITICAL_EXTENSION
- A critical client control is not recognized.