Microsoft KB Archive/316908

= DOC: Improper Argument in VERIFYSERVERCERT Function =

Article ID: 316908

Article Last Modified on 2/12/2007

-

APPLIES TO


 * Microsoft Windows 2000 Standard Edition

-



This article was previously published under Q316908



SUMMARY
The MSDN documentation for the VERIFYSERVERCERT callback function is incorrect. The second parameter in the current documentation is a pointer to a session handle. This is incorrect.

The second parameter should be a pointer to a pointer to a session handle, not a pointer to a session handle. If the second parameter is incorrectly a pointer to a session handle, the pServerCert structure will be empty. The &quot;More Information&quot; section of this article shows you how the documentation should look.



MORE INFORMATION
The following example shows you how the MSDN documentation for the VERIFYSERVERCERT function should look.

VERIFYSERVERCERT
VERIFYSERVERCERT is a callback function that allows a client to evaluate the certificate chain of the server to which it is connected.

BOOLEAN _cdecl VERIFYSERVERCERT( PLDAP Connection,   PCCERT_CONTEXT* ppServerCert ); Parameters

Connection

The session handle.

ppServerCert

A pointer to a pointer to the server's certificate.

Return Values

If the function succeeds (the client approves the server certificate), the return value is TRUE.

If the function fails; the return value is FALSE and the secure connection is torn down.

Remarks

The VERIFYSERVERCERT callback function allows the client to verify the certificate of the server. The client registers a callback which is invoked after the secure connection is set up. The server certificate context is presented to the callback function, where it can be verified as acceptable or not. To register this callback, call ldap_set_option (conn, LDAP_OPT_SERVER_CERTIFICATE, &CertRoutine) where CertRoutine is the address of your callback function.

The server calls VERIFYSERVERCERT after the secure connection has been established. The server's certificate context is supplied for examination by the client.

As noted in the parameter description, there is a mistake in the pServerCert parameter. What is actually passed back to this parameter is a pointer to a pointer to the CERT_CONTEXT. Even though VERIFYSERVERCERT is declared as receiving a PCCERT_CONTEXT, it in fact receives a PCCERT_CONTEXT*. So an application should use it as: PCCERT_CONTEXT* ppServerCert = (PCCERT_CONTEXT*)pServerCert; Then ppServerCert can be used to verify the certificate. CertFreeCertificateContext should be called before this function returns. Because of the mistake in the pServerCert parameter, the call to this function should be made as follows CertFreeCertificateContext(*ppServerCert); Alternatively, the function can be: CertFreeCertificateContext(*((PCCERT_CONTEXT*)pServerCert));

Requirements

Windows NT, Windows 2000, Windows XP: Included in Windows 2000 and later.

Redistributable:

Requires Active Directory Client Extension on Windows NT 4.0 SP6a and Windows 95, Windows 98, Windows Millennium Edition (Me).

Header: Declared in Winldap.h.

See Also

Functions, ldap_set_option

Keywords: kbdocerr kbinfo KB316908

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.