Description of the requirements and of the troubleshooting methods that you can use to enable an LDAP client to communicate with an LDAP server over SSL (290483)

INTRODUCTION

This article describes how to setup a Microsoft Windows Lightweight Directory Access Protocol (LDAP) client to communicate with an LDAP server over Secure Sockets Layer (SSL). This article also describes the troubleshooting methods that you can use if you experience problems.

LDAP clients include any process that uses Wldap32.dll, such as the following processes:

• A process that uses calls to Active Directory Services Interfaces (ADSI).
• A process that uses LDAP from the Windows Address Book (WAB). This process is launched by using Microsoft Outlook Express or by using a Search dialog box.

Because Wldap32.dll is the underlying technology, code samples will demonstrate how to use the function calls. This is referred to as the LDAP API.

back to the top

Acquire an SSL connection

This section describes how to acquire an SSL connection. The LDAP API has to open an IP connection to a port on the LDAP server that support SSL traffic. Typically, this is TCP port 636. After this connection is made, the LDAP API initiates a handshake and then tries to authenticate the server. If this handshake is successful, the server certificate is used to negotiate a session key. The session key is used to encrypt the rest of the LDAP operations over that connection.

The SSL handshake is performed by the Microsoft TLS/SSL security provider that is named SChannel. This is the same security provider that handles SSL handshakes for other protocols, such as the following:

• HTTP
• Routing and Remote Access

For additional information about how the SChannel security provider performs the SSL handshake, click the following article number to view the article in the Microsoft Knowledge Base: When the LDAP API performs the handshake, client authentication is not done unless the QUERYCLIENTCERT function is set by using the connection options. Typically, the handshake only involves identifying the server. For additional information about identifying the server, click the following article number to view the article in the Microsoft Knowledge Base: If any one of the steps in the previous article fails, the SSL handshake fails, and the LDAP connection is not created.

You can use the following LDAP API sample code to create an SSL connection:

// Link with Wldap32.lib.
#include <windows.h>
#include <winldap.h>
#include <stdio.h>


int main(int argc, char* argv[])
{
	LDAP *ldapConnection = NULL;
	INT err = 0;
	PCHAR pHost = "Host_Name";  // Change this value to the HostName that you want.
	ULONG ulPort = LDAP_SSL_PORT; // Change this value to the port that you want.

	ldapConnection = ldap_sslinit(pHost,ulPort, 1);
	if ( ldapConnection == NULL ) {
		printf( "ldap_sslinit failed with 0x%x.\n", GetLastError() );
		return 0;
	}

	err = ldap_connect(ldapConnection,0);
	if (err != LDAP_SUCCESS )
		goto FatalExit;
	// Do LDAP work here.

FatalExit:

	if (ldapConnection)
		ldap_unbind_s(ldapConnection);
	printf("\n\n Error return : 0x%x\n",err);
	return err;
}

If the LDAP connection fails, you may receive the following error message:Because the ldap_connect() function call is the first function call that is made that contacts the directory server, you cannot configure the code to work around this problem. If the ldap_connect() function call succeeds, but later the LDAP call fails, this may indicate a programming problem and not an SSL issue.

back to the top

Troubleshooting

You can use the following methods to troubleshoot connection problems.

back to the top

Method 1: Verify that there is not a problem with how the functions are called or with the development environment

Try using a pre-built Windows LDAP client to perform a search. If your development computer is a Windows 2000-based computer, use the Ldp.exe support tool. If your development computer is not a Windows 2000-based computer, use the WAB. If the LDAP server accepts standard LDAP requests, try this also. Typically, the standard LDAP port is TCP port 389. If you cannot connect over the standard LDAP port, the SSL handshake may not be the problem.

For additional information about configuring the WAB, click the following article number to view the article in the Microsoft Knowledge Base: When you try to use a pre-built Windows LDAP client, and it is not successful, but the other Windows LDAP client is successful, this indicates that there is a problem that is specific to your application. You must verify that your development environment is set up correctly and that the function calls are being made correctly. For additional information about possible causes, click the following article number to view the article in the Microsoft Knowledge Base: If the other Windows LDAP client fails, see Method 2.

back to the top

Method 2: Check the event log for errors

The SChannel security provider logs errors to the system log in Microsoft Window 2000 and in Microsoft Windows NT 4.0. By default, error logging is enabled if you are using a Windows 2000 client. For additional information about how to enable logging for a Windows NT 4.0 client, click the following article number to view the article in the Microsoft Knowledge Base: After you complete the steps in the previous article, you have to restart your computer and then try Method 1 again.

You must also determine what the error description is when the error is logged. For additional information about how to find the error description, click the following article number to view the article in the Microsoft Knowledge Base: If no error is logged, try to enable "log for success" events. For additional information about "log for success" events, click the following article number to view the article in the Microsoft Knowledge Base: If your log indicates that you are generating a client context, and that the SSL handshake succeeds, this indicates that the problem is occurring after the SSL connection is created.

If no logging is generated, the connection may have failed for other reasons. In this case, use Telnet to connect to the host on the port that you want. If this fails, the server may not be available, or the correct port may not be specified.

back to the top

Method 3: Use Microsoft Internet Explorer

You can use Internet Explorer to troubleshoot an LDAP SSL connection by entering the URL in the form that is at https://Hostname.corp.com:636. Internet Explorer tries to negotiate the SSL handshake. If Internet Explorer is successful, Internet Explorer then does an HTTP Get request that fails, and you may receive the following error message: If there are server verification problems, Internet Explorer displays the problems and then provides suggestions.

Internet Explorer does not behave exactly like LDAP API behaves when the server is verified. However, Internet Explorer is useful to eliminate common problems.

back to the top

Method 4: Use the WebClient sample in the Microsoft Platform SDK

You can use the sample that is in the following Platform software development kit (SDK) instead of using LDAP:After installation, you can find the sample at the following location:

\Microsoft SDK\Samples\security\SSPI\SSL\WebClient\webclient.c

To more closely mimic the calls that LDAP makes to the SChannel security provider, you have to modify the source code. Change the fifth parameter of the AcquireCredentialHandle function to NULL. The dwSSPIFlags variable must include a ISC_REQ_MUTUAL_AUTH flag that is similar to the following:

    dwSSPIFlags = ISC_REQ_SEQUENCE_DETECT   |
                  ISC_REQ_REPLAY_DETECT     |
                  ISC_REQ_CONFIDENTIALITY   | 
                  ISC_RET_EXTENDED_ERROR    |
                  ISC_REQ_ALLOCATE_MEMORY   |
                  ISC_REQ_STREAM |
		  ISC_REQ_MUTUAL_AUTH ;

You may have to make this change in several places in the code.

If an error is generated, examine the code to determine the following:

• What is the function that generated the error?
• What is the error?

back to the top

Method 5: Put the server name in the Hosts file on the local computer

You can put the server name in the Hosts file on the local computer. The Hosts file is at the following location:

\%SystemRoot%\system32\drivers\etc\

back to the top