ldap_ssl_client_init --Initialize the SSL Library

 #include <ldap.h>
 #include <ldapssl.h>
 
 int ldap_ssl_client_init(
       char       *keyring,
       char       *keyring_pw,
       int         ssl_timeout,
       int        *pSSLReasonCode)

The ldap_ssl_client_init() routine is used to initialize the SSL protocol stack for an application process. It should be called once, prior to making any other LDAP calls. Once ldap_ssl_client_init() has been successfully called, any subsequent invocations will return a return code of LDAP_SSL_ALREADY_INITIALIZED.

A related API, ldap_app_ssl_client_init_np() is available for using Digital Certificate Manager (DCM) Application IDs when authenticating the client to the server. Either ldap_ssl_client_init() or ldap_app_ssl_client_init_np() (but not both) can be called in an application process.

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_np() 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

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.

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 the Digital Certificate Manager (DCM). If a key database is not supplied, keyring is null, the *SYSTEM Certificate Store is used.

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 to the password is accepted.

ssl_timeout

(Input) Specifies the SSL timeout value in seconds. The timeout value controls the frequency with which the SSL protocol stack regenerates session keys. If ssl_timeout is set to 0, the default value SSLV3_CLIENT_TIMEOUT will be used. Otherwise, the value supplied will be used, provided it is less than or equal to 86,400. If ssl_timeout is greater than 86,400, LDAP_PARAM_ERROR is returned.

pSSLReasonCode

(Input) Specifies a pointer to the SSL Reason Code, which provides additional information in the event that an error occurs during initialization of the SSL stack (when ldap_ssl_client_init() is called). See QSYSINC/H.LDAPSSL for reason codes that can be returned.

Example

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

The following scenario depicts the recommended calling sequence where the entire set of LDAP transactions are "protected" by using a secure SSL connection, including the dn and password that flow on the ldap_simple_bind():

 rc = ldap_ssl_client_init(keyfile, keyfile_pw, timeout, &sslrc);
 ld = ldap_ssl_init(ldaphost, ldapport, label );
 rc = ldap_set_option( ld, LDAP_OPT_SSL_CIPHER, &ciphers);
 rc = ldap_simple_bind_s(ld, binddn, passwd);

 ...additional LDAP API calls

 rc = ldap_unbind( ld );

The following scenario depicts using the SASL EXTERNAL mechanism for authenticating the client to the server using the credentials in the SSL certificate:

 rc = ldap_ssl_client_init(keyfile, keyfile_pw, timeout, &sslrc);
 ld = ldap_ssl_init(ldaphost, ldapport, label );
 rc = ldap_set_option( ld, LDAP_OPT_SSL_CIPHER, &ciphers);
 rc = ldap_sasl_bind_s( ld, NULL, LDAP_MECHANISM_EXTERNAL, NULL, NULL, NULL ); 

 ...additional LDAP API calls

 rc = ldap_unbind( ld );

Note that the sequence of calls for the deprecated APIs is ldap_open/init(), ldap_ssl_start(), followed by ldap_bind().

The following ciphers are attempted for the SSL handshake by default, in the order shown.

    (Export Version)
  
      RC4_MD5_EXPORT
      RC2_MD5_EXPORT
  
    (Non-export Version)
  
      RC4_SHA_US
      RC4_MD5_US
      DES_SHA_US
      3DES_SHA_US
      RC4_MD5_EXPORT
      RC2_MD5_EXPORT

See ldap_get/set_option() for more information about setting the ciphers to be used.

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

Return Value

LDAP_SUCCESS

if the request was successful.

another LDAP error

if the request was not successful.

Error Conditions

If ldap_ssl_client_init() is not successful, it returns an LDAP error code. See LDAP Client API Error Conditions for possible values for the error codes.

Error Messages

The following message may be sent from this function.

Related Information

• ldap_app_ssl_client_init_np() -- Initialize the LDAP Client for a secure connection using DCM.
• ldap_ssl_init() -- Initializes an SSL connection.
• 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.
• ldap_ssl_start() -- Creates a secure SSL connection (deprecated).

[ Back to top | LDAP APIs | APIs by category ]