ldap_app_ssl_client_init_np()--Initialize the LDAP Client for a Secure Connection using DCM

 #include <ldap.h>
 #include <ldapssl.h>
 
 int ldap_app_ssl_client_init_np(
                        char *dcm_identifier,
                        int *pSSLReasonCode)

The ldap_app_ssl_client_init_np() is an LDAP V3 function used to initialize the LDAP client using the Digital Certificate Manager (DCM) to control the digital certificate in preparation for making a secure connection (using Secure Sockets Layer (SSL)) to a LDAP server.

ldap_app_ssl_client_init_np() must be called prior to ldap_app_ssl_init_np() to establish a connection, and prior to any kind of ldap_bind(), whether it be an ldap_sasl_bind_s() or an ldap_simple_bind_s(). ldap_app_ssl_client_init_np() must be called only once per job, while multiple ldap_app_ssl_init_np() or secure connections can be done, allowing one (DCM) initialization to be done for many connections. Once the secure connection is established all subsequent LDAP messages that flow over the secure connection are encrypted, including the ldap_bind() parameters, until ldap_unbind() is called.

Either ldap_ssl_client_init() or ldap_app_ssl_client_init_np() (but not both) can be called in an application process. If you are not going to use SSL client authentication (LDAP SASL bind with the EXTERNAL mechanism), use ldap_ssl_client_init().

Authorities and Locks

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

Parameters

dcm_identifier

(Input) An identifier string that corresponds to a secure application registered with DCM. If NULL is used, then the default Directory Services client application ID will be used (QIBM_GLD_DIRSRV_CLIENT).

pSSLReasonCode

(Output) 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_app_ssl_client_init_np() is called). See QSYSINC/H.LDAPSSL for reason codes that can be returned.

Examples

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:

 rc = ldap_app_ssl_client_init_np (dcm_identifier, &reasoncode);
 ld = ldap_app_ssl_init_np(ldaphost, ldapport );
 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 );

The following scenario depicts the calling sequence for multiple connections using one DCM identifier:

 rc = ldap_app_ssl_client_init_np (dcm_identifier, &reasoncode);
 ld = ldap_app_ssl_init_np(ldaphost, ldapport );
 rc = ldap_set_option( ld, LDAP_OPT_SSL_CIPHER, &ciphers);
        rc = ldap_sasl_bind_s( ld, NULL, LDAP_MECHANISM_EXTERNAL, NULL, NULL, NULL );

   /* For multiple secure connections using the same dcm_identifier. */  

 ld1 = ldap_app_ssl_init_np(ldaphost, ldapport );
        rc = ldap_sasl_bind_s( ld, NULL, LDAP_MECHANISM_EXTERNAL, NULL, NULL, NULL );

 ld2 = ldap_app_ssl_init_np(ldaphost, ldapport );
        rc = ldap_sasl_bind_s( ld, NULL, LDAP_MECHANISM_EXTERNAL, NULL, NULL, NULL );

 ...additional LDAP API calls

 rc = ldap_unbind( ld );
 rc = ldap_unbind( ld1 );
 rc = ldap_unbind( ld2 );

Return Value

LDAP_SUCCESS

if the request was successful.

another LDAP error code

if the request was not successful.

Error Conditions

If ldap_app_ssl_client_init_np() is not successful it will return an LDAP error code. See LDAP Client API Error Conditions for possible LDAP error code values.

Error Messages

The following message may be sent from this function.

Related Information

• ldap_app_ssl_init_np() -- Initializes an SSL Connection.
• ldap_app_ssl_start_np() -- Starts a Secure LDAP Connection using DCM.
• ldap_ssl_client_init() -- Initializes the SSL Library.
• ldap_ssl_init() -- Initializes an SSL connection.
• ldap_ssl_start() -- Creates a secure SSL connection (deprecated).
• ldap_bind() -- Bind to the directory server.
• ldap_sasl_bind_s() -- Synchronously bind to the directory using Simple Authentication Security Layer (SASL).
• ldap_unbind() -- Unbind from the LDAP server and close the connection.
• ldap_ssl_environment_init() -- Initializes SSL for a secure connection between client and server.
• ldap_start_tls_s_np() -- Starts a TLS session with a Certificate.
• ldap_start_tls_app_np() -- Starts a TLS session with an Application ID.
• ldap_stop_tls_s_np() -- Ends a TLS session.

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