ClearBox Server™ v1.2 Developer's Guide

ICommonAuthentication::GetUserPassword

Called by server to request user's password to authenticate him.

IMPORTANT NOTE. Unregistered trial version of ClearBox Server limits the size of password returned in userPassword field of useInf to 4 characters maximum. To remove this limitation, register your copy of ClearBox Server.

HRESULT GetUserPassword(
	[in] long tag,
	[in,out] USERINFO * userInf,
	[out] VARIANT_BOOL * clearTextPassword,
	[out] VARIANT_BOOL * caseSensitive,
	[out] VARIANT_BOOL * ignorePassword,
	[out] VARIANT_BOOL * userExist);

Parameters

tag
[in] Unique value identifying packet (RADIUS or TACACS+) in whose context this method is called.
userInf
[in,out] Describes user whose password is requested. If extension returns password, it must allocate memory for it in userPassword field calling SysAllocString.
clearTextPassword
[out] If user exists but his password is unavailable in clear text, this parameter must be set by extension to VARIANT_TRUE, VARIANT_FALSE otherwise.
caseSensitive
[out] Specifies whether server must perform case-sensitive password check (VARIANT_TRUE) or case-insensitive check (VARIANT_FALSE). Makes sense for ASCII and PAP authentication only when password is checked by the server.
ignorePassword
[out] Specifies whether server must skip user's authentication (VARIANT_TRUE) or authenticate him (VARIANT_TRUE).
userExist
[out] Specifies whether such user name is valid (VARIANT_TRUE) or there's no such user (VARIANT_FALSE).

Return Values

If extension returns error code, it is assumed that user was not found as if userExist was set to VARIANT_FALSE.

Thread Safety

This method is called in context of WORK thread. (See Server Threads Model for details.) You should synchronize data which is shared with other threads.

Memory Management

Server allocates and frees memory for userInf fields (except for userPassword, which is allocated by extension), so extension must not change them.

Remarks

If extension reports that password is unavailable in clear text and server has unencrypted password provided by user, ICommonAuthentication::CheckPassword is called.

If userExist=VARIANT_FALSE, server will reject user (doesn't matter what the values of other parameters are).

If userExist=VARIANT_TRUE and ignorePassword=VARIANT_TRUE, password check is skipped, no matter what clearTextPassword is equal to, but ITACACSAuthentication::CanAuthenticate or IRADIUSAuthentication::CanAuthenticate is called anyway.

Example Code

This code assumes that we know password for the only user John, and server should check it.

STMETHODIMP CTest::GetUserPassword (
	long tag, USERINFO * userInf,
	VARIANT_BOOL * clearTextPassword, VARIANT_BOOL * caseSensitive,
	VARIANT_BOOL * ignorePassword, VARIANT_BOOL * userExist)
{
	// We assume thay there's only one user "John"
	if (wcscmp(userInf->userName,L"John")!=0)
	{
		*userExist=VARIANT_FALSE;
		return S_OK;
	}

	userInf->userPassword=SysAllocString(L"mysuperpassword");
	
	//We know John's password
	*clearTextPassword=VARIANT_TRUE; 
	
	//We allow John to enter passwords like "MySuPerpassWORD"
	*caseSensitive=VARIANT_FALSE; 
	
	//Check John's password
	*ignorePassword=VARIANT_FALSE; 
	*userExist=VARIANT_TRUE;
	
	return S_OK;
}

See Also

ICommonAuthentication, ICommonAuthentication::CheckPassword, IRADIUSAuthentication::CanAuthenticate, ITACACSAuthentication::CanAuthenticate, Common authentication process


© 2001-2003 XPerience Technologies. www.xperiencetech.com

Created by chm2web html help conversion utility.