`LDAP_SET_OPTION`

Use the ldap_set_option API in an LDAP application to access and set various LDAP session parameters.

Purpose

The ldap_set_option() API in an LDAP application sets the parameters for a secure connection with an LDAP server. The ldap_set_option() API calls the ldap_init(), ldap_ssl_init(), or ldap_open() API to initialize a session with an LDAP server. After the successful initialization, the ldap_set_option() API obtains a pointer to an LDAP structure. You must call this API before you issue a bind or any other operations that connects to the server.

Synopsis

#include <ldap.h>

int ldap_set_option( 
       LDAP *ld, 
       int optionToSet, 
       void *optionValue)

Input parameters

ld: Specifies the LDAP pointer that is returned by a call to ldap_init(), ldap_ssl_init(), or ldap_open().
optionToSet: Identifies the value for the ldap_set_option() call.
optionValue: Specifies the address of the value to set with ldap_set_option().

Session settings

In versions earlier than IBM® Verify Directory, version 6.3, Fix Pack 17, you can set ciphers for SSLv3/TLS 1.0 protocol suite with ldap_set_option(). For IBM Verify Directory, version 6.3, Fix Pack 17 or later, you can set the SSLv3, TLS 1.0, TLS 1.1, or TLS 1.2 protocols and the TLS 1.2 ciphers with ldap_set_option(). You can set the options for an LDAP connection with ldap_set_option().

You can set the following session settings with ldap_set_option():

LDAP_OPT_SSL_CIPHER

Specifies a set of ciphers for the SSLv3, TLS 1.0, or TLS 1.1 protocols.

Table 1. Supported ciphers for the `SSLv3, TLS 1.0`, or `TLS 1.1` protocol
The table lists the supported ciphers for the `SSLv3, TLS 1.0`, or `TLS 1.1` protocol.
Ciphers	Supported by SSLv3 and TLS 1.0	Supported by TLS 1.1
`SLAPD_SSL_RC4_MD5_EX "03"`	Yes	No
`SLAPD_SSL_RC2_MD5_EX "06"`	Yes	No
`SLAPD_SSL_RC4_SHA_US "05"`	Yes	Yes
`SLAPD_SSL_RC4_MD5_US "04"`	Yes	Yes
`SLAPD_SSL_DES_SHA_US "09"`	Yes	Yes
`SLAPD_SSL_3DES_SHA_US "0A"`	Yes	Yes
`SLAPD_SSL_AES_128_SHA_US "2F"`	Yes	Yes
`SLAPD_SSL_AES_256_SHA_US "35"`	Yes	Yes

Note: The ciphers with 03 and 06 hexadecimal values are not supported by the TLS 1.1 protocol.

To set one or more ciphers for the SSLv3, TLS 1.0, or TLS 1.1 protocol, use the following example:

char *setcipher = "352F090A";
ldap_set_option( ld, LDAP_OPT_SSL_CIPHER, setcipher);

LDAP_OPT_SSL_CIPHER_EX

Specifies a set of TLS 1.2 ciphers for the

TLS
1.2

protocol. To specify one or more TLS 1.2 ciphers, separate the ciphers by a comma (,).

The following ciphers are supported by the TLS 1.2 protocol:

TLS_RSA_WITH_RC4_128_SHA
TLS_RSA_WITH_3DES_EDE_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_256_CBC_SHA
TLS_RSA_WITH_AES_128_GCM_SHA256
TLS_RSA_WITH_AES_256_GCM_SHA384
TLS_RSA_WITH_AES_128_CBC_SHA256
TLS_RSA_WITH_AES_256_CBC_SHA256
TLS_ECDHE_RSA_WITH_RC4_128_SHA
TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

To set one or more ciphers for the TLS 1.2 protocol, use the following example:

char *setcipher = "TLS_RSA_WITH_AES_128_CBC_SHA,
                   TLS_RSA_WITH_AES_256_CBC_SHA";
ldap_set_option( ld, LDAP_OPT_SSL_CIPHER_EX, setcipher);

LDAP_OPT_SSL_SECURITY_PROTOCOL

Specifies a set of one or more protocols to use for secure communication with an LDAP server.

The following macros are defined in the ldap.h header file to represent the protocols:

#define LDAP_SECURITY_PROTOCOL_ALL "SSLV3,TLS10,TLS11,TLS12,TLS13"
#define LDAP_SECURITY_PROTOCOL_DEFAULT "TLS12,TLS13"
#define LDAP_SECURITY_PROTOCOL_SSLV3 "SSLV3"
#define LDAP_SECURITY_PROTOCOL_TLSV10 "TLS10"
#define LDAP_SECURITY_PROTOCOL_TLSV11 "TLS11"
#define LDAP_SECURITY_PROTOCOL_TLSV12 "TLS12"
#define LDAP_SECURITY_PROTOCOL_TLSV13 "TLS13"

To set all protocols for secure communication with an LDAP server, use the following example:


ldap_set_option( 
            ld, LDAP_OPT_SSL_SECURITY_PROTOCOL, 
            LDAP_SECURITY_PROTOCOL_ALL);

Errors

The ldap_set_option() AP returns a non-zero value if an error occurs. To obtain a detailed error report, you must run the application in debug mode and check the debug traces.