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.

The manner in which the LDAP option value is specified for the ldap_set_option() routine depends upon the LDAP protocol version option for the LDAP handle. The manner in which the LDAP option value is specified for the ldap_set_option_np() routine is not dependent upon the LDAP protocol version option for the LDAP handle. Note the default LDAP protocol version is 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.
Table 1. How to specify options for the ldap_set_option and ldap_set_option_np routines
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
Example: The 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);
The following LDAP options can be set:
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 a NULL control address. Specify NULL 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 to LDAP_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 the LDAP_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 the LDAP_OPT_UTF8_IO option of the LDAP handle.

The following client controls are supported:
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
For more information about client controls, see Supported client controls.
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 the LDAP_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 as NULL, 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 by ORing 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
Note some of these trace points are applicable only for the LDAP server and do not generate any trace output for the LDAP client. For more information about the LDAP trace options, see Enabling tracing.
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 the LDAP_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 as NULL. 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 the LDAP_LIBASCII compiler variable.

The trace output is written to stdout if the LDAP_OPT_DEBUG_FILENAME option is not set and the LDAP_DEBUG_FILENAME environment variable is not defined. Therefore, the LDAP_OPT_DEBUG_FILENAME option should be set before either the LDAP_OPT_DEBUG or LDAP_OPT_DEBUG_STRING option is set if the trace output is not to be written to the default trace file as specified by the LDAP_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, if LDAP_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 to stdout until a subsequent call is successful in setting the LDAP_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 the LDAP_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 as NULL. 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 the LDAP_LIBASCII compiler variable.
The value for LDAP_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 or X20)
  • 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 the LDAP_OPT_DEBUG_STRING starts with a plus or minus sign. Otherwise, the trace options that are specified by the LDAP_DEBUG environment variable are replaced with the options specified by the LDAP_OPT_DEBUG_STRING option. For more information about the LDAP trace options, see Enabling tracing.

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 either LDAP_OPT_ON or LDAP_OPT_OFF. The default is LDAP_OPT_OFF. A parameter error is returned if the LDAP protocol version is not set to LDAP_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. Specify NULL 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 both LDAP_OPT_EXT_REBIND_FN and LDAP_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.
The LDAP_OPT_IO_CALLBACK option cannot be changed after a connection is established with the LDAP server. Specify NULL for the address of the LDAPIOCallback structure to revert to the normal socket routines. The callback routines are used when following referrals returned by the local LDAP server. The LDAPIOCallback 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 the LDAPIOCallback 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 in errno.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 be 0 for a normal return, or a value that is defined in errno.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 in errno.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 be EAGAIN if the time limit is reached, EINTR if the wait is interrupted by a signal, or 0 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 in errno.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 a SASL 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 to LDAP_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 a SASL 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 to LDAP_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 either LDAP_VERSION2 or LDAP_VERSION3. The default is LDAP_VERSION3 if ldap_init() or ldap_ssl_init() can be used to create the LDAP handle, and LDAP_VERSION2 if ldap_open() can be used to create the LDAP handle. In either case, the LDAP_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 the LDAP_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, the LDAP_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. Specify NULL 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 both LDAP_OPT_EXT_REBIND_FN and LDAP_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 either LDAP_OPT_ON or LDAP_OPT_OFF. The default is LDAP_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 is 10.
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 either LDAP_OPT_ON or LDAP_OPT_OFF. The default is LDAP_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 a NULL control address. Specify NULL 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 to LDAP_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 the LDAP_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 of 0, 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 the SOCKS_CONF and SOCKS_SERVER environment variables and also the LDAP_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 the LDAP_LIBASCII compiler variable. Specify NULL for the option value to cancel the SOCKS configuration that is specified by the SOCKS_CONF or SOCKS_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 the SOCKS_PASSWORD environment variable. The option value is a null-terminated character string in the local EBCDIC code page or UTF-8, as determined by the LDAP_LIBASCII compiler variable. Specify NULL 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 the SOCKS_CONF and SOCKS_SERVER environment variables and also the LDAP_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 the LDAP_LIBASCII compiler variable, and consists of a comma-separated list of SOCKS servers. Each SOCKS server is specified as host: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 to 1080, if it is not specified. Specify NULL for the option value to cancel the SOCKS configuration that is specified by the SOCKS_CONF or SOCKS_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 the SOCKS_USERNAME environment variable. The option value is a null-terminated character string in the local EBCDIC code page or UTF-8, as determined by the LDAP_LIBASCII compiler variable. Specify NULL 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 the SOCKS_VERSION environment variable. The valid values are 4 and 5. The default is 4. 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 the LDAP_OPT_SOCKS_VERSION option to 5 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 the LDAP_OPT_SSL_CIPHER option is not set. The GSK_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 the LDAP_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, specify 04052F.

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 the GSK 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 the LDAP_OPT_SSL_CIPHER_FORMAT option. Also, see the description of the option LDAP_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 the LDAP_OPT_SSL_CIPHER_EXPANDED option is not set. The GSK_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 the LDAP_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, specify 00040005002F.

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, where LDAP_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 the GSK_V3_CIPHER_SPECS environment variable, or from a setting of LDAP_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 the GSK_V3_CIPHER_SPECS_EXPANDED environment variable, or from a setting of LDAP_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 the LDAP_OPT_SSL_TIMEOUT option is not set, the default SSL session timeout of 86400 seconds can be used. The GSK_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. The LDAP_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 of 0, 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 is LDAP_OPT_ON if the LDAP_LIBASCII compiler variable is defined and LDAP_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 the LDAP_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 is LDAP_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.

The following are some common errors for this routine:
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.