ldap_start_tls_s_np()

Purpose

Start TLS for a connection

Format

#include <ldap.h> 

int ldap_start_tls_s_np(
    LDAP *                  ld,
    const char *            label)

Parameters

Input

ld: Specifies the LDAP handle.
label: Specifies the label for the client certificate as a null-terminated character string in the local EBCDIC code page or UTF-8, as determined by the LDAP_OPT_UTF8_IO option for the LDAP handle. Specify NULL for this parameter to use the GSK_KEY_LABEL environment variable. If you specify NULL for this parameter and the GSK_KEY_LABEL environment variable is not defined, the default certificate for the SSL key database, SAF key ring, or PKCS #11 token can be used. A client certificate is needed only when the LDAP server is configured for client authentication.

Usage

The ldap_start_tls_s_np() routine initiates Transport Layer Security (TLS) for an existing connection with an LDAP server. An error is returned if TLS is already being used by the connection or if there are outstanding requests. Any existing authentication for the connection remains unchanged. If the application wants to use the client certificate for authentication, it should call the ldap_sasl_bind() or ldap_sasl_bind_s() routine after calling ldap_start_tls_s_np() and specify EXTERNAL as the SASL authentication method.

The ldap_ssl_client_init() routine must be called to initialize the SSL environment before calling the ldap_start_tls_s_np() routine.

The certificate presented by the LDAP server must contain the DNS host name as either the common name (CN) portion of the certificate subject name or as a subject alternate name. The DNS host name is the name specified when the ldap_init() or ldap_ssl_init() routine was called. An error is returned if the server certificate does not contain a matching host name.

Function return value

The function return value is LDAP_SUCCESS if no error is detected. Otherwise, it is one of the LDAP error codes listed in the ldap.h include file.

The following are some common errors for this routine:

LDAP_INAPPROPRIATE_AUTH: The server certificate does not contain the DNS host name for the connection.
LDAP_NO_MEMORY: Insufficient storage is available.
LDAP_OPERATIONS_ERROR: TLS is already active or there are outstanding requests for the connection.
LDAP_PARAM_ERROR: A parameter is not valid.
LDAP_PROTOCOL_ERROR: The Start TLS extended operation is not supported.
LDAP_SSL_CLIENT_INIT_NOT_CALLED: The ldap_ssl_client_init() routine has not been called.
LDAP_UNAVAILABLE: TLS support is not available or the server is stopping.