---
name: "ldap_get_option"
section: "3"
platform: "linux"
package: "libldap"
version: "2.7.2-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux", "macos"]
url: "https://new.carta.tech/ldap_get_option"
---

# ldap\_get\_option(3)

LDAP option handling routines

## NAME

ldap\_get\_option, ldap\_set\_option - LDAP option handling routines

## LIBRARY

OpenLDAP LDAP (libldap, -lldap)

## SYNOPSIS

```
#include <ldap.h>
```

**int ldap\_get\_option(LDAP \****ld***, int** *option***, void \****outvalue***);**

**int ldap\_set\_option(LDAP \****ld***, int** *option***, const void \****invalue***);**

## DESCRIPTION

These routines provide access to options stored either in a LDAP handle or as global options, where applicable. They make use of a neutral interface, where the type of the value either retrieved by  [**ldap\_get\_option**(3)](/ldap_get_option/3.md) or set by [**ldap\_set\_option**(3)](/ldap_set_option/3.md) is cast to  **void \***. The actual type is determined based on the value of the **option** argument. Global options are set/retrieved by passing a NULL LDAP handle. LDAP handles inherit their default settings from the global options in effect at the time the handle is created.

- **LDAP\_OPT\_API\_FEATURE\_INFO**

  Fills-in a  **LDAPAPIFeatureInfo**; **outvalue** must be a  **LDAPAPIFeatureInfo \***, pointing to an already allocated struct. The **ldapaif\_info\_version** field of the struct must be initialized to **LDAP\_FEATURE\_INFO\_VERSION** before making the call. The **ldapaif\_name** field must be set to the name of a feature to query. This is a read-only option.

- **LDAP\_OPT\_API\_INFO**

  Fills-in a  **LDAPAPIInfo**; **outvalue** must be a  **LDAPAPIInfo \***, pointing to an already allocated struct. The **ldapai\_info\_version** field of the struct must be initialized to **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 **ldapai\_extensions** array and the array itself using [**ldap\_memfree**(3)](/ldap_memfree/3.md). The caller must also free the **ldapi\_vendor\_name**. This is a read-only option.

- **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 [**ldap\_search\_ext**(3)](/ldap_search_ext/3.md), [**ldap\_add\_ext**(3)](/ldap_add_ext/3.md), [**ldap\_modify\_ext**(3)](/ldap_modify_ext/3.md) and so on. **outvalue** must be  **LDAPControl \*\*\***, and the caller is responsible of freeing the returned controls, if any, by calling  [**ldap\_controls\_free**(3)](/ldap_controls_free/3.md), while **invalue** must be  **LDAPControl \*const \***; the library duplicates the controls passed via **invalue**.

- **LDAP\_OPT\_CONNECT\_ASYNC**

  Sets/gets the status of the asynchronous connect flag. **invalue** should either be **LDAP\_OPT\_OFF** or **LDAP\_OPT\_ON**; **outvalue** must be **int \***. When set, the library will call [**connect**(2)](/connect/2.md) 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 **LDAP\_OPT\_NETWORK\_TIMEOUT**). This option is OpenLDAP specific.

- **LDAP\_OPT\_CONNECT\_CB**

  This option allows to set a connect callback. **invalue** must be a  **const struct ldap\_conncb \***. Callbacks are executed in last in-first served order. Handle-specific callbacks are executed first, followed by global ones. Right before freeing the callback structure, the **lc\_del** callback handler is passed a  **NULL** **Sockbuf**. Calling [**ldap\_get\_option**(3)](/ldap_get_option/3.md) for this option removes the callback whose pointer matches **outvalue**. This option is OpenLDAP specific.

- **LDAP\_OPT\_DEBUG\_LEVEL**

  Sets/gets the debug level of the client library. **invalue** must be a  **const int \***; **outvalue** must be a **int \***. Valid debug levels are  **LDAP\_DEBUG\_ANY**, **LDAP\_DEBUG\_ARGS**, **LDAP\_DEBUG\_BER**, **LDAP\_DEBUG\_CONNS**, **LDAP\_DEBUG\_NONE**, **LDAP\_DEBUG\_PACKETS**, **LDAP\_DEBUG\_PARSE**, and **LDAP\_DEBUG\_TRACE**. This option is OpenLDAP specific.

- **LDAP\_OPT\_DEFBASE**

  Sets/gets a string containing the DN to be used as default base for search operations. **outvalue** must be a **char \*\***, and the caller is responsible of freeing the returned string by calling [**ldap\_memfree**(3)](/ldap_memfree/3.md), while **invalue** must be a  **const char \***; the library duplicates the corresponding string. This option is OpenLDAP specific.

- **LDAP\_OPT\_DEREF**

  Sets/gets the value that defines when alias dereferencing must occur. **invalue** must be **const int \***; **outvalue** must be **int \***. They cannot be NULL. The value of  **\*invalue** should be one of **LDAP\_DEREF\_NEVER** (the default), **LDAP\_DEREF\_SEARCHING**, **LDAP\_DEREF\_FINDING**, or **LDAP\_DEREF\_ALWAYS**. Note that this has ever been the only means to determine alias dereferencing within search operations.

- **LDAP\_OPT\_DESC**

  Returns the file descriptor associated to the socket buffer of the LDAP handle passed in as  **ld**; **outvalue** must be a  **int \***. This is a read-only, handle-specific option.

- **LDAP\_OPT\_DIAGNOSTIC\_MESSAGE**

  Sets/gets a string containing the error string associated to the LDAP handle. This option was formerly known as  **LDAP\_OPT\_ERROR\_STRING**. **outvalue** must be a **char \*\***, and the caller is responsible of freeing the returned string by calling [**ldap\_memfree**(3)](/ldap_memfree/3.md), while **invalue** must be a  **char \***; the library duplicates the corresponding string.

- **LDAP\_OPT\_HOST\_NAME**

  Sets/gets a space-separated list of hosts to be contacted by the library  when trying to establish a connection. This is now deprecated in favor of **LDAP\_OPT\_URI**. **outvalue** must be a  **char \*\***, and the caller is responsible of freeing the resulting string by calling [**ldap\_memfree**(3)](/ldap_memfree/3.md), while **invalue** must be a  **const char \***; the library duplicates the corresponding string.

- **LDAP\_OPT\_MATCHED\_DN**

  Sets/gets a string containing the matched DN associated to the LDAP handle. **outvalue** must be a **char \*\***, and the caller is responsible of freeing the returned string by calling [**ldap\_memfree**(3)](/ldap_memfree/3.md), while **invalue** must be a  **const char \***; the library duplicates the corresponding string.

- **LDAP\_OPT\_NETWORK\_TIMEOUT**

  Sets/gets the network timeout value after which [**poll**(2)](/poll/2.md)/[**select**(2)](/select/2.md) following a  [**connect**(2)](/connect/2.md) returns in case of no activity. **outvalue** must be a  **struct timeval \*\*** (the caller has to free **\*outvalue** using [**ldap\_memfree**(3)](/ldap_memfree/3.md)), and **invalue** must be a  **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.

- **LDAP\_OPT\_PROTOCOL\_VERSION**

  Sets/gets the protocol version. **outvalue** and **invalue** must be  **int \***.

- **LDAP\_OPT\_REFERRAL\_URLS**

  Sets/gets an array containing the referral URIs associated to the LDAP handle. **outvalue** must be a **char \*\*\***, and the caller is responsible of freeing the returned string by calling [**ldap\_memvfree**(3)](/ldap_memvfree/3.md), while **invalue** must be a NULL-terminated **char \*const \***; the library duplicates the corresponding string. This option is OpenLDAP specific.

- **LDAP\_OPT\_REFERRALS**

  Determines whether the library should implicitly chase referrals or not. **invalue** must be  **const int \***; its value should either be **LDAP\_OPT\_OFF** or **LDAP\_OPT\_ON**. **outvalue** must be **int \***.

- **LDAP\_OPT\_REFHOPLIMIT**

  Set the maximum number of referrals to chase for a request. **invalue** must be **const int \***; **outvalue** must be a **int \***. They cannot be NULL. This option is OpenLDAP specific.

- **LDAP\_OPT\_RESTART**

  Determines whether the library should implicitly restart connections (FIXME). **invalue** must be  **const int \***; its value should either be **LDAP\_OPT\_OFF** or **LDAP\_OPT\_ON**. **outvalue** must be **int \***.

- **LDAP\_OPT\_RESULT\_CODE**

  Sets/gets the LDAP result code associated to the handle. This option was formerly known as **LDAP\_OPT\_ERROR\_NUMBER**. **invalue** must be a  **const int \***. **outvalue** must be a **int \***.

- **LDAP\_OPT\_SERVER\_CONTROLS**

  Sets/gets the server-side controls to be used for all 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 [**ldap\_search\_ext**(3)](/ldap_search_ext/3.md), [**ldap\_add\_ext**(3)](/ldap_add_ext/3.md), [**ldap\_modify\_ext**(3)](/ldap_modify_ext/3.md) and so on. **outvalue** must be  **LDAPControl \*\*\***, and the caller is responsible of freeing the returned controls, if any, by calling  [**ldap\_controls\_free**(3)](/ldap_controls_free/3.md), while **invalue** must be  **LDAPControl \*const \***; the library duplicates the controls passed via **invalue**.

- **LDAP\_OPT\_SESSION\_REFCNT**

  Returns the reference count associated with the LDAP handle passed in as **ld**; **outvalue** must be a **int \***. This is a read-only, handle-specific option. This option is OpenLDAP specific.

- **LDAP\_OPT\_SIZELIMIT**

  Sets/gets the value that defines the maximum number of entries to be returned by a search operation. **invalue** must be **const int \***, while **outvalue** must be **int \***; They cannot be NULL.

- **LDAP\_OPT\_SOCKBUF**

  Returns a pointer to the socket buffer of the LDAP handle passed in as **ld**; **outvalue** must be a  **Sockbuf \*\***. This is a read-only, handle-specific option. This option is OpenLDAP specific.

- **LDAP\_OPT\_SOCKET\_BIND\_ADDRESSES**

  Sets/gets a space-separated list of IP Addresses used as binding interface to remote server when trying to establish a connection. Only one valid IPv4 address and/or one valid IPv6 address are allowed in the list. **outvalue** must be a **char \*\***, and the caller is responsible of freeing the returned string by calling [**ldap\_memfree**(3)](/ldap_memfree/3.md), while **invalue** must be a **const char \***; the library duplicates the corresponding string.

- **LDAP\_OPT\_TIMELIMIT**

  Sets/gets the value that defines the time limit after which a search operation should be terminated by the server. **invalue** must be **const int \***, while **outvalue** must be **int \***, and they cannot be NULL.

- **LDAP\_OPT\_TIMEOUT**

  Sets/gets a timeout value for the synchronous API calls. **outvalue** must be a  **struct timeval \*\*** (the caller has to free **\*outvalue** using [**ldap\_memfree**(3)](/ldap_memfree/3.md)), and **invalue** must be a  **struct timeval \***, and they cannot be NULL. Using a struct with seconds set to -1 results in an infinite timeout, which is the default. This option is OpenLDAP specific.

- **LDAP\_OPT\_URI**

  Sets/gets a comma- or space-separated list of URIs to be contacted by the library  when trying to establish a connection. **outvalue** must be a  **char \*\***, and the caller is responsible of freeing the resulting string by calling [**ldap\_memfree**(3)](/ldap_memfree/3.md), while **invalue** must be a  **const char \***; the library parses the string into a list of  **LDAPURLDesc** structures, so the invocation of  [**ldap\_set\_option**(3)](/ldap_set_option/3.md) may fail if URL parsing fails. URIs may only contain the **schema**, the **host**, and the **port** fields. This option is OpenLDAP specific.

- **LDAP\_OPT\_KEEPCONN**

  Instructs [**ldap\_result**(3)](/ldap_result/3.md) 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.

- **LDAP\_OPT\_TCP\_USER\_TIMEOUT**

  Allows to configure TCP\_USER\_TIMEOUT in milliseconds on the connection, overriding the operating system setting. This option is OpenLDAP specific and supported only on Linux 2.6.37 or higher. **invalue** must be a **const unsigned int \***; **outvalue** must be an **unsigned int \***.

## SASL OPTIONS

The SASL options are OpenLDAP specific and unless otherwise noted, require an LDAP handle to be passed.

- **LDAP\_OPT\_X\_SASL\_AUTHCID**

  Gets the SASL authentication identity; **outvalue** must be a **char \*\***, its content needs to be freed by the caller using [**ldap\_memfree**(3)](/ldap_memfree/3.md).

- **LDAP\_OPT\_X\_SASL\_AUTHZID**

  Gets the SASL authorization identity; **outvalue** must be a **char \*\***, its content needs to be freed by the caller using [**ldap\_memfree**(3)](/ldap_memfree/3.md).

- **LDAP\_OPT\_X\_SASL\_MAXBUFSIZE**

  Gets/sets SASL maximum buffer size; **invalue** must be **const ber\_len\_t \***, while **outvalue** must be **ber\_len\_t \***. See also **LDAP\_OPT\_X\_SASL\_SECPROPS**.

- **LDAP\_OPT\_X\_SASL\_MECH**

  Gets the SASL mechanism; **outvalue** must be a **char \*\***, its content needs to be freed by the caller using [**ldap\_memfree**(3)](/ldap_memfree/3.md).

- **LDAP\_OPT\_X\_SASL\_MECHLIST**

  Gets the list of the available mechanisms, in form of a NULL-terminated array of strings; **outvalue** must be **char \*\*\***. The caller must not free or otherwise muck with it. This option can be used globally.

- **LDAP\_OPT\_X\_SASL\_NOCANON**

  Sets/gets the NOCANON flag. When unset, the hostname is canonicalized. **invalue** must be **const int \***; its value should either be **LDAP\_OPT\_OFF** or **LDAP\_OPT\_ON**. **outvalue** must be **int \***.

- **LDAP\_OPT\_X\_SASL\_REALM**

  Gets the SASL realm; **outvalue** must be a **char \*\***, its content needs to be freed by the caller using [**ldap\_memfree**(3)](/ldap_memfree/3.md).

- **LDAP\_OPT\_X\_SASL\_SECPROPS**

  Sets the SASL secprops; **invalue** must be a **char \***, containing a comma-separated list of properties. Legal values are: **none**, **nodict**, **noplain**, **noactive**, **passcred**, **forwardsec**, **noanonymous**, **nonstdcbind**, **minssf=\<minssf\>**, **maxssf=\<maxssf\>**, **maxbufsize=\<maxbufsize\>**.

- **LDAP\_OPT\_X\_SASL\_SSF**

  Gets the SASL SSF; **outvalue** must be a **ber\_len\_t \***.

- **LDAP\_OPT\_X\_SASL\_SSF\_EXTERNAL**

  Sets the SASL SSF value related to an authentication performed using an EXTERNAL mechanism; **invalue** must be a **const ber\_len\_t \***.

- **LDAP\_OPT\_X\_SASL\_SSF\_MAX**

  Gets/sets SASL maximum SSF; **invalue** must be **const ber\_len\_t \***, while **outvalue** must be **ber\_len\_t \***. See also **LDAP\_OPT\_X\_SASL\_SECPROPS**.

- **LDAP\_OPT\_X\_SASL\_SSF\_MIN**

  Gets/sets SASL minimum SSF; **invalue** must be **const ber\_len\_t \***, while **outvalue** must be **ber\_len\_t \***. See also **LDAP\_OPT\_X\_SASL\_SECPROPS**.

- **LDAP\_OPT\_X\_SASL\_USERNAME**

  Gets the SASL username; **outvalue** must be a **char \*\***. Its content needs to be freed by the caller using [**ldap\_memfree**(3)](/ldap_memfree/3.md).

- **LDAP\_OPT\_X\_SASL\_CBINDING**

  Sets/gets the channel-binding type to use in SASL, one of **LDAP\_OPT\_X\_SASL\_CBINDING\_NONE** (the default), **LDAP\_OPT\_X\_SASL\_CBINDING\_TLS\_UNIQUE** the "tls-unique" type from RFC 5929. **LDAP\_OPT\_X\_SASL\_CBINDING\_TLS\_ENDPOINT** the "tls-server-end-point" from RFC 5929, compatible with Windows. **invalue** must be **const int \***; **outvalue** must be **int \***.

## TCP OPTIONS

The TCP options are OpenLDAP specific. Mainly intended for use with Linux, they may not be portable.

- **LDAP\_OPT\_X\_KEEPALIVE\_IDLE**

  Sets/gets the number of seconds a connection needs to remain idle before TCP starts sending keepalive probes. **invalue** must be **const int \***; **outvalue** must be **int \***.

- **LDAP\_OPT\_X\_KEEPALIVE\_PROBES**

  Sets/gets the maximum number of keepalive probes TCP should send before dropping the connection. **invalue** must be **const int \***; **outvalue** must be **int \***.

- **LDAP\_OPT\_X\_KEEPALIVE\_INTERVAL**

  Sets/gets the interval in seconds between individual keepalive probes. **invalue** must be **const int \***; **outvalue** must be **int \***.

## TLS OPTIONS

The TLS options are OpenLDAP specific.

- **LDAP\_OPT\_X\_TLS\_CACERTDIR**

  Sets/gets the path of the directories containing CA certificates. Multiple directories may be specified, separated by a semi-colon. **invalue** must be **const char \***; **outvalue** must be **char \*\***, and its contents need to be freed by the caller using [**ldap\_memfree**(3)](/ldap_memfree/3.md).

- **LDAP\_OPT\_X\_TLS\_CACERTFILE**

  Sets/gets the full-path of the CA certificate file. **invalue** must be **const char \***; **outvalue** must be **char \*\***, and its contents need to be freed by the caller using [**ldap\_memfree**(3)](/ldap_memfree/3.md).

- **LDAP\_OPT\_X\_TLS\_CACERTURIS**

  Sets/gets an array containing the URIs of CA certificates. The URIs accepted are based on the underlying crypto library. In the case of OpenSSL, the URIs are handled by the provider interface, and a URI without a scheme is treated as a file path. **outvalue** must be a **char \*\*\***, and the caller is responsible of freeing the returned string by calling [**ldap\_memvfree**(3)](/ldap_memvfree/3.md), while **invalue** must be a NULL-terminated **char \*const \***; the library duplicates the corresponding string.

- **LDAP\_OPT\_X\_TLS\_CERTFILE**

  Sets/gets the full-path of the certificate file. **invalue** must be **const char \***; **outvalue** must be **char \*\***, and its contents need to be freed by the caller using [**ldap\_memfree**(3)](/ldap_memfree/3.md).

- **LDAP\_OPT\_X\_TLS\_CIPHER**

  Gets the cipher being used on an established TLS session. **outvalue** must be **char \*\***, and its contents need to be freed by the caller using [**ldap\_memfree**(3)](/ldap_memfree/3.md).

- **LDAP\_OPT\_X\_TLS\_CIPHER\_SUITE**

  Sets/gets the allowed cipher suite. This directive is not supported when using MbedTLS. **invalue** must be **const char \***; **outvalue** must be **char \*\***, and its contents need to be freed by the caller using [**ldap\_memfree**(3)](/ldap_memfree/3.md).

- **LDAP\_OPT\_X\_TLS\_CONNECT\_ARG**

  Sets/gets the connection callback argument. **invalue** must be **const void \***; **outvalue** must be **void \*\***.

- **LDAP\_OPT\_X\_TLS\_CONNECT\_CB**

  Sets/gets the connection callback handle. **invalue** must be **const LDAP\_TLS\_CONNECT\_CB \***; **outvalue** must be **LDAP\_TLS\_CONNECT\_CB \*\***.

- **LDAP\_OPT\_X\_TLS\_CRLCHECK**

  Sets/gets the CRL evaluation strategy, one of **LDAP\_OPT\_X\_TLS\_CRL\_NONE**, **LDAP\_OPT\_X\_TLS\_CRL\_PEER**, or **LDAP\_OPT\_X\_TLS\_CRL\_ALL**. **invalue** must be **const int \***; **outvalue** must be **int \***. Requires OpenSSL.

- **LDAP\_OPT\_X\_TLS\_CRLFILE**

  Sets/gets the full-path of the CRL file. **invalue** must be **const char \***; **outvalue** must be **char \*\***, and its contents need to be freed by the caller using [**ldap\_memfree**(3)](/ldap_memfree/3.md). This option is only valid for GnuTLS.

- **LDAP\_OPT\_X\_TLS\_CTX**

  Sets/gets the TLS library context. New TLS sessions will inherit their default settings from this library context. **invalue** must be **const void \***; **outvalue** must be **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.

- **LDAP\_OPT\_X\_TLS\_DHFILE**

  Gets/sets the full-path of the file containing the parameters for Diffie-Hellman ephemeral key exchange. This directive is not supported when using MbedTLS. **invalue** must be **const char \***; **outvalue** must be **char \*\***, and its contents need to be freed by the caller using [**ldap\_memfree**(3)](/ldap_memfree/3.md).

- **LDAP\_OPT\_X\_TLS\_ECNAME**

  Gets/sets the name of the curve(s) used for elliptic curve key exchanges. **invalue** must be **const char \***; **outvalue** must be **char \*\***, and its contents need to be freed by the caller using [**ldap\_memfree**(3)](/ldap_memfree/3.md). Ignored by GnuTLS. In GnuTLS a curve may be selected in the cipher suite specification.

- **LDAP\_OPT\_X\_TLS\_KEYFILE**

  Sets/gets the full-path of the certificate key file. **invalue** must be **const char \***; **outvalue** must be **char \*\***, and its contents need to be freed by the caller using [**ldap\_memfree**(3)](/ldap_memfree/3.md).

- **LDAP\_OPT\_X\_TLS\_NEWCTX**

  Instructs the library to create a new TLS library context. **invalue** must be **const int \***. A non-zero value pointed to by **invalue** tells the library to create a context for a server.

- **LDAP\_OPT\_X\_TLS\_PEERCERT**

  Gets the peer's certificate in DER format from an established TLS session. **outvalue** must be **struct berval \***, and the data it returns needs to be freed by the caller using [**ldap\_memfree**(3)](/ldap_memfree/3.md).

- **LDAP\_OPT\_X\_TLS\_PROTOCOL\_MAX**

  Sets/gets the maximum protocol version. **invalue** must be **const int \***; **outvalue** must be **int \***.

- **LDAP\_OPT\_X\_TLS\_PROTOCOL\_MIN**

  Sets/gets the minimum protocol version. **invalue** must be **const int \***; **outvalue** must be **int \***.

- **LDAP\_OPT\_X\_TLS\_RANDOM\_FILE**

  Sets/gets the random file when **/dev/random** and **/dev/urandom** are not available. **invalue** must be **const char \***; **outvalue** must be **char \*\***, and its contents need to be freed by the caller using [**ldap\_memfree**(3)](/ldap_memfree/3.md). Ignored by GnuTLS older than version 2.2.

- **LDAP\_OPT\_X\_TLS\_REQUIRE\_CERT**

  Sets/gets the peer certificate checking strategy, one of **LDAP\_OPT\_X\_TLS\_NEVER**, **LDAP\_OPT\_X\_TLS\_HARD**, **LDAP\_OPT\_X\_TLS\_DEMAND**, **LDAP\_OPT\_X\_TLS\_ALLOW**, **LDAP\_OPT\_X\_TLS\_TRY**.

- **LDAP\_OPT\_X\_TLS\_REQUIRE\_SAN**

  Sets/gets the peer certificate subjectAlternativeName checking strategy, one of **LDAP\_OPT\_X\_TLS\_NEVER**, **LDAP\_OPT\_X\_TLS\_HARD**, **LDAP\_OPT\_X\_TLS\_DEMAND**, **LDAP\_OPT\_X\_TLS\_ALLOW**, **LDAP\_OPT\_X\_TLS\_TRY**.

- **LDAP\_OPT\_X\_TLS\_SSL\_CTX**

  Gets the TLS session context associated with this handle. **outvalue** must be **void \*\***. When using the OpenSSL library this is an SSL\*. When using other crypto libraries this is a pointer to an OpenLDAP private structure. Applications generally should not use this option.

- **LDAP\_OPT\_X\_TLS\_URIS**

  Sets/gets an array containing the URIs of certificates, intermediate certificates and keys. The URIs accepted are based on the underlying crypto library. In the case of OpenSSL, the URIs are handled by the provider interface, and a URI without a scheme is treated as a file path. **outvalue** must be a **char \*\*\***, and the caller is responsible of freeing the returned string by calling [**ldap\_memvfree**(3)](/ldap_memvfree/3.md), while **invalue** must be a NULL-terminated **char \*const \***; the library duplicates the corresponding string.

- **LDAP\_OPT\_X\_TLS\_VERSION**

  Gets the TLS version being used on an established TLS session. **outvalue** must be **char \*\***, and its contents need to be freed by the caller using [**ldap\_memfree**(3)](/ldap_memfree/3.md).

- **LDAP\_OPT\_X\_TLS\_PEERKEY\_HASH**

  Sets the (public) key that the application expects the peer to be using. **invalue** must be **const char \*** containing the base64 encoding of the expected peer's key or in the format **\<hashalg\>:\<peerkey hash base64 encoded\>** where as a TLS session is established, the library will hash the peer's key with the provided hash algorithm and compare it with value provided and will only allow the session to continue if they match. This happens regardless of certificate checking strategy. The list of supported **hashalg** values depends on the crypto library used, check its documentation to get a list.

## ERRORS

On success, the functions return **LDAP\_OPT\_SUCCESS**, while they may return **LDAP\_OPT\_ERROR** to indicate a generic option handling error. Occasionally, more specific errors can be returned, like **LDAP\_NO\_MEMORY** to indicate a failure in memory allocation.

## NOTES

The LDAP libraries with the **LDAP\_OPT\_REFERRALS** option set to **LDAP\_OPT\_ON** (default value) automatically follow referrals using an anonymous bind. Application developers are encouraged to either implement consistent referral chasing features, or explicitly disable referral chasing by setting that option to **LDAP\_OPT\_OFF**.

The protocol version used by the library defaults to LDAPv2 (now historic), which corresponds to the **LDAP\_VERSION2** macro. Application developers are encouraged to explicitly set **LDAP\_OPT\_PROTOCOL\_VERSION** to LDAPv3, using the  **LDAP\_VERSION3** macro, or to allow users to select the protocol version.

## SEE ALSO

[**ldap**(3)](/ldap/3.md), [**ldap\_error**(3)](/ldap_error/3.md), **RFC 4422** (http://www.rfc-editor.org),

## ACKNOWLEDGEMENTS

**OpenLDAP Software** is developed and maintained by The OpenLDAP Project \<http://www.openldap.org/\>. **OpenLDAP Software** is derived from the University of Michigan LDAP 3.3 Release.