ldap_ssl_start()--Start a Secure LDAP Connection

 #include <ldap.h>
 #include <ldapssl.h>
 
 int ldap_ssl_start(
                LDAP  *ld,
                char  *keyring,
                char  *keyring_pw,
                char  *name )

The ldap_ssl_start() function is used to start a secure connection (using Secure Sockets Layer (SSL)) to an LDAP server. ldap_ssl_start() accepts the ld from an ldap_open() and performs an SSL handshake to a server. ldap_ssl_start() must be called after ldap_open() and prior to ldap_bind(). Once the secure connection is established for the ld, all subsequent LDAP messages that flow over the secure connection are encrypted, including the ldap_bind() parameters, until ldap_unbind() is called.

Although still supported, the use of the ldap_ssl_start() API is now deprecated. The ldap_ssl_client_init() and ldap_ssl_init() or ldap_app_ssl_client_init_np() and ldap_app_ssl_init() APIs should be used instead.

Authorities and Locks

Read, *R, authority is needed to the selected Certificate Store and Execute, *X, to the associated directories.

Parameters

ld

(Input) Specifies the LDAP pointer returned by a previous call to ldap_init(), ldap_ssl_init(), or ldap_open().

keyring

(Input) Specifies the name of a key database file (with "kdb" extension). The key database file typically contains one or more certificates of certification authorities (CAs) that are trusted by the client. These types of X.509 certificates are also known as trusted roots. A key database can also be used to store the client's private key(s) and associated client certificate(s). A private key and associated client certificate are required only if the LDAP server is configured to require client and server authentication. If the LDAP server is configured to provide only server authentication, a private key and client certificate are not required.

Note: Although still supported, use of the ldap_ssl_start() is discouraged (its use has been deprecated). Any application using the ldap_ssl_start() API should only use a single key database (per application process).

A fully-qualified path and filename is recommended. If a filename without a fully-qualified path is specified, the LDAP library will look in the current directory for the file. The key database file specified here must have been created using Digital Certificate Manager, DCM. If a key database is not supplied, the default roots are used for trusted Certification Authorities (CAs).

keyring_pw

(Input) Specifies the password that is used to protect the contents of the key database. This password is important since it protects the private key stored in the key database. The password was specified when the key database was initially created. A NULL pointer is accepted.

name

(Input) Specifies the name, or label, associated with the client private key/certificate pair in the key database. It is used to uniquely identify a private key/certificate pair, as stored in the key database.

If the LDAP server is configured to perform Server Authentication, a client certificate is not required (and name can be set to null). If the LDAP server is configured to perform Client and Server Authentication, a client certificate is required. name can be set to null if a default certificate/private key pair has been designated as the default (using Using DCM). Similarly, name can be set to null if there is a single certificate/private key pair in the designated key database.

Return Value

Skit error code

if the request was successful.

-1

if ld is not set (NULL).

Error Conditions

If ld is not NULL, ldap_ssl_start() returns Skit error code, otherwise it returns -1. See gskssl.h for possible values of skit error codes.

Error Messages

The following message may be sent from this function.

Related Information

• ldap_ssl_init() -- Initializes an SSL connection.
• ldap_ssl_client_init() -- Initializes the SSL library.
• ldap_ssl_environment_init() --Initialize SSL for a secure connection between client and server.
• ldap_start_tls_app_np() --Start a TLS session with an Application ID.
• ldap_start_tls_s_np() --Start a TLS session with a Certificate.
• ldap_stop_tls_s_np() --End a TLS session.

The ldap_ssl_start() API includes RSA software. RSA is a trademark of RSA Data Security, Inc.