Example Code for Establishing a Session over SSL

Establishing a secure LDAP connection using SSL, now called Transport Layer Security (TLS), requires that the server support the proper Certificate Authorities before the connection is attempted, and that the client can supply an appropriate client certificate to the server when the SSL handshake is initiated by the connection attempt.

If the client application must determine if a particular connection is protected by SSL at run-time, the ldap_get_option function can be used with LDAP_OPT_SSL to return this data. The encryption strength can then be returned using the LDAP_OPT_SSL_INFO option. Active Directory requires a 128-bit cipher strength to allow user passwords to be modified by client applications using the LDAP provider over an SSL connection.

The following code example shows how to bind to a server using ldap_sslinit, and then queries the server for the cipher strength.

• Retrieves a host name.
• Initializes a session using ldap_sslinit.
• Specifies LDAP version 3.
• Verifies that the host supports SSL.
• Connects to the server.
• Binds to the server with current credentials.
• Retrieves the SSL cipher strength.

// CHECKSSL: Run the following code example by passing the server name as a
// command line parameter. Example:
//
//	checkssl.exe myserver.fabrikam.com
//
#include <windows.h>
#include <ntldap.h>
#include <winldap.h>
#include <schnlsp.h>
#include <stdio.h>

int main(int argc, char* argv[])
{
	LDAP* ld = NULL;
	INT iRtn = 0; 
	INT connectSuccess = 0;
	PCHAR pHost = NULL;
	ULONG version = LDAP_VERSION3;
	SecPkgContext_ConnectionInfo sslInfo;
	LONG lv = 0;

	// Verify that the user passed in a hostname.
	if (argc > 1)
	{
		pHost = argv[1];
}
	else
	{
		printf("\nSyntax: CHECKSSL <hostname>\n");
		goto FatalExit;
}

	// Create an LDAP session.
	printf("\nConnecting to host \"%s\" ...\n",pHost);
	ld = ldap_sslinit(pHost,LDAP_SSL_PORT,1);
	if (ld == NULL)
	{
		printf( "ldap_sslinit failed with 0x%x.\n",GetLastError());
		return -1;
}

	// Specify VERSION3; the default is version 2.
	printf("Setting Protocol version to 3.\n");
	iRtn = ldap_set_option(ld,
						 LDAP_OPT_PROTOCOL_VERSION,
						 (void*)&version);
	if (iRtn != LDAP_SUCCESS)
		goto FatalExit;

	// Verify that SSL is enabled on the connection.
	// (returns LDAP_OPT_ON/_OFF).
	printf("Checking if SSL is enabled\n");
	iRtn = ldap_get_option(ld,LDAP_OPT_SSL,(void*)&lv);
	if (iRtn != LDAP_SUCCESS)
		goto FatalExit;

	// If SSL is not enabled, enable it.
	if ((void*)lv == LDAP_OPT_ON)
		printf("SSL is enabled\n");
	else
	{
		printf("SSL not enabled.\n SSL being enabled...\n");
		iRtn = ldap_set_option(ld,LDAP_OPT_SSL,LDAP_OPT_ON);
		if (iRtn != LDAP_SUCCESS)
			goto FatalExit;
}

	// Connect to the server.
	connectSuccess = ldap_connect(ld, NULL);

	if(connectSuccess == LDAP_SUCCESS)
		printf("ldap_connect succeeded \n");
	else
	{
		printf("ldap_connect failed with 0x%x.\n",connectSuccess);
		goto FatalExit;
}

	// Bind with current credentials. 
	printf("Binding ...\n");
	iRtn = ldap_bind_s(ld,NULL,NULL,LDAP_AUTH_NEGOTIATE);
	if (iRtn != LDAP_SUCCESS)
		goto FatalExit;

	// Retrieve the SSL cipher strength.
	printf("Getting SSL info\n");
	iRtn = ldap_get_option(ld,LDAP_OPT_SSL_INFO,&sslInfo);
	if (iRtn != LDAP_SUCCESS)
		goto FatalExit;

	printf("SSL cipher strength = %d bits\n",sslInfo.dwCipherStrength);

	goto NormalExit;

	// Cleanup.
NormalExit:
	if (ld != NULL)
		ldap_unbind_s(ld);
	return 0;

	// Cleanup after an error.
FatalExit:
	if( ld != NULL )
		ldap_unbind_s(ld);
	printf( "\n\nERROR: 0x%x\n", iRtn);
	return iRtn;
}

The Microsoft LDAP server software enables the SChannel security package to select the server certificate used to authenticate an SSL connection. SChannel uses the first valid certificate it locates that has all of the following properties:

• Has the "server auth" EKU.
• Contains the FQDN of the server computer, either in the subject CN field or in the subject alt name extension.
• Is located in the local computer personal certificate store, which is known programmatically as the MY certificate store.
• Was issued from a CA that is trusted, within the scope of the computer or the computer domain.

Enabling SSL from the server side is host-dependent and should be detailed in the host administration guide. The following is an outline of requirements for setting up SSL on a Windows 2000 Domain Controller using the Microsoft Enterprise Certificate Authority:

1. Install an Enterprise Certificate Authority on a Windows 2000 Domain Controller, which installs a certificate on a server, or install a 3rd party certificate on the Domain Controller.
2. Open the Default Domain Controller Policy using the Group Policy Editor.
3. Select Windows Settings under Computer Configuration.
4. Select Security Settings, and then select Public Key Policies.
5. Select Automatic Certificate Request Settings.
6. Use the wizard to add a policy for Domain Controllers.

When these steps are completed, all domain controllers request a certificate and support LDAP over SSL using port 636.

If a third-party certificate is required for LDAP SSL connections, then it is important that the Microsoft Enterprise Certificate Authority not be installed on the LDAP server; this sets the Enterprise CA certificate as the default certificate for SSL validation.