Microsoft KB Archive/142790

{|
 * width="100%"|

HOWTO: Extract the Profile Path from a Gina in Windows NT

 * }

Q142790

-

The information in this article applies to:


 * Microsoft Win32 Software Development Kit (SDK), used with:
 * the operating system: Microsoft Windows NT, versions 3.5, 3.51
 * the operating system: Microsoft Windows 2000

-

SUMMARY
This article explains how to get a profile path to return from a GINA in Windows NT.

MORE INFORMATION
In a standard Windows NT system, interactively logged-on users are given a profile. A profile is a registry hive that is tailored to a particular user. The profile is typically used to save user-specific information such as screen appearance, mouse click speeds, whether there is a screen saver, whether the screen saver is secure, and so on. This profile, referenced using the special registry key HKEY_CURRENT_USER, is loaded by Winlogon during the interactive boot process.

The interface between Winlogon and GINA DLLs includes information passed back from GINA that allows Winlogon to locate and load the logged-on user's profile. The WlxLoggedOutSAS pProfile parameter is used to return a pointer to a structure of type WLX_PROFILE_V1_0.

The WLX_PROFILE_V1_0 structure is currently used to support remote and mandatory profiles, which can be configured with User Manager for Domains (usrmgr) | User properties | Profile | User Profile Path. This action can be performed programmatically through the Windows NT LAN Manager API NetUserSetInfo at info-level 3.

If a NULL pointer is returned from WlxLoggedOutSAS as the pProfile parameter, Winlogon will handle the loading (and creation) of the user profile. In this case, the optional, administrator-defined profile path will be ignored for the logon.

Step-by-Step Procedure
Based on the supplied username and domain name, the following steps can be used to determine if and what the administrator-defined profile path is set to:

 Determine the current domain name, with a call to the Windows NT LAN Manager API NetUserModalsGet at info level 2. The returned USER_MODALS_INFO_2 structure member usrmod2_domain_name will contain the domain name. This call need only be made once, during the first logon attempt. Store the result of the first call in a global variable. The current domain name is needed for comparison against the logon domain name, in order to determine where to look up account information. If the supplied domain name is not equal to the current domain name, get the computer name of the domain controller associated with the supplied domain. Use the Win32 API lstrcmpiW for string comparison and the Windows NT LAN Manager API NetGetDCName to obtain the computer name of the domain controller. Use the Windows NT LAN Manager API NetUserGetInfo at info-level 3 to acquire the user account information for the specified user. When calling NetUserGetInfo, target the approriate machine -- either the local machine by way of NULL, or the domain controller computer name acquired from NetGetDCName. If the USER_INFO_3 structure member usri3_profile returned by NetUserGetInfo is an empty string, no profile was defined by an administrator. In this case, WlxLoggedOutSAS can return a NULL pointer as the pProfile parameter, and no further actions need to be performed; otherwise continue.  Copy the USER_INFO_3 structure member usri3_profile to storage allocated by HeapAlloc(GetProcessHeap...). The following source code illustrates this point:

  HeapAlloc( GetProcessHeap, 0,      (lstrlenW(usri3_profile) + 1) * sizeof(WCHAR) // string + NULL      );   Allocate a block of memory of size WLX_PROFILE_V1_0. The following source code illustrates this point:

 HeapAlloc( GetProcessHeap, 0, sizeof(WLX_PROFILE_V1_0) );  Set the dwType member of the WLX_PROFILE_V1_0 structure to WLX_PROFILE_TYPE_V1_0.</li> Set the pszProfile member of the WLX_PROFILE_V1_0 structure to point to the copy of the USER_INFO_3 usri3_profile structure member.</li> Return a pointer to the allocated WLX_PROFILE_V1_0 structure from WlxLoggedOutSAS as the pProfile parameter.</li></ol>

NOTE: The Windows NT LAN Manager APIs are Unicode only. Strings passed to these API must be in Unicode form. Gina is also Unicode only, so this is not usually an issue.

NOTE: It is important to free buffers allocated by the Windows NT LAN Manager API. The Windows NT Lan Manager API NetApiBufferFree can be used for this purpose.

Windows NT Version Specific Information
In Windows NT 3.51 and above, Microsoft recommends that you call the Win32 API LogonUser to obtain an access token representing the supplied username and domain name. This API does not return information specific to any authentication package, such as the user profile path. For this reason, it is necessary to follow the steps outlined in this article.

In Windows NT 3.5, the LsaLogonUser must be used to obtain an access token representing the supplied username and domain name. This API does return a profile path, so the steps outlined in this article do not apply. However, the interface to LsaLogonUser is subject to change in future versions of Windows NT; LogonUser should be used when possible.

Sample Code
<pre class="CODESAMP">  /* The following function illustrates a WlxLoggedOutSAS which obtains the user profile path, and returns the result if a profile path is   found. This function is a modified version of WlxLoggedOutSAS taken from the Win32 SDK version 3.51 gina sample, found in   Mstools/Samples/Win32/Winnt/Gina on the MSDN CD-ROM. */

int WINAPI WlxLoggedOutSAS(      PVOID                   pWlxContext,       DWORD                   dwSasType,       PLUID                   pAuthenticationId,       PSID                    pLogonSid,       PDWORD                  pdwOptions,       PHANDLE                 phToken,       PWLX_MPR_NOTIFY_INFO    pMprNotifyInfo,       PVOID *                 pProfile       ) {      int         result; PWLX_PROFILE_V1_0  pWlxProfile; PWSTR szProfile; // PMiniAccount   pAccount; PGlobals       pGlobals;

pGlobals = (PGlobals) pWlxContext;

result = pWlxFuncs->WlxDialogBoxParam(                  hGlobalWlx,                   hDllInstance,                   (LPTSTR) MAKEINTRESOURCE(IDD_LOGON_DIALOG),                   NULL,                   LogonDlgProc,                   (LPARAM) pGlobals );

if (result == WLX_SAS_ACTION_LOGON) {          result = AttemptLogon(pGlobals, pGlobals->pAccount,                                   pLogonSid, pAuthenticationId);

if (result == WLX_SAS_ACTION_LOGON) {              *pdwOptions = 0; *phToken = pGlobals->hUserToken;

if(!GetUserProfilePath( pGlobals->pAccount->pszUsername, pGlobals->pAccount->pszDomain, &szProfile )) {                  //                    // error occurred acquiring profile path. Log error // here if appropriate. Default is to not provide // profile information as szProfile will be NULL // which causes *pProfile to be set to NULL //               }

//               // if no profile is specified in the userinfo, let winlogon // handle locating the registry hive //               if(szProfile == NULL) { *pProfile = NULL; }              else { pWlxProfile = (PWLX_PROFILE_V1_0)HeapAlloc(                      GetProcessHeap, 0, sizeof(WLX_PROFILE_V1_0) );

if(pWlxProfile == NULL) { //                       // error occurred allocating memory. Log error // here if appropriate. Free memory associated // with the acquired profile path. Default is to                      // not provide profile information by supplying // NULL as pProfile. //                       HeapFree(GetProcessHeap, 0, szProfile); *pProfile = NULL; }                  else { //                       // the allocation succeeded -- fill in the profile // information //                       pWlxProfile->dwType = WLX_PROFILE_TYPE_V1_0; pWlxProfile->pszProfile = szProfile; *pProfile = pWlxProfile; }              }

pMprNotifyInfo->pszUserName = DupString(pGlobals->pAccount->pszUsername); pMprNotifyInfo->pszDomain = DupString(pGlobals->pAccount->pszDomain); pMprNotifyInfo->pszPassword = DupString(pGlobals->pAccount->pszPassword); pMprNotifyInfo->pszOldPassword = NULL; }      }       return(result); }

/*   The following function obtains the profile path for the supplied user on the supplied domain.

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the ProfilePath is set to NULL.

If no profile path exists for the supplied user, the ProfilePath parameter will be set to NULL. If ProfilePath is non-NULL, the caller is responsible for freeing the string via HeapFree(GetProcessHeap...).

This source code relies on the lm.h header file and the netapi32.lib import library. */   BOOL GetUserProfilePath(      IN LPWSTR UserName,     // UserName to retrieve profile path       IN LPWSTR Domain,       // Domain user resides on       OUT LPWSTR *ProfilePath // result profile path.  NULL == no profile       ) {      LPWSTR wTargetComputer; PUSER_INFO_3 ui3 = NULL; PUSER_MODALS_INFO_2 umi2 = NULL; NET_API_STATUS nas; BOOL bSuccess = FALSE; // assume this function will fail

*ProfilePath = NULL;

//       // get the local domain name. // NOTE: in a gina, it would be wise to retrieve this only once, // in DllMain during DLL_PROCESS_ATTACH. The pointer could be      // saved in a global variable and then compared against below. //       nas=NetUserModalsGet(NULL, 2, (LPBYTE *)&umi2); if(nas != NO_ERROR) { return FALSE; }

__try {

//       // determine if you need to look up at the domain controller //       if(lstrcmpiW(Domain, umi2->usrmod2_domain_name) == 0) { //           // target computer is local machine //           wTargetComputer = NULL; }      else { //           // target computer is the PDC computer name for the specified // domain //           nas=NetGetDCName(NULL, Domain, (LPBYTE *)&wTargetComputer); if(nas != NO_ERROR) { __leave; }      }

//       // fetch the info for the user on the appropriate machine //       nas=NetUserGetInfo(           wTargetComputer,           UserName,            // user name           3,                   // info-level           (LPBYTE *) &ui3           );

if(nas != NO_ERROR) { __leave; }

//       // if there is no profile, indicate success. // Note that *ProfilePath will be a NULL pointer //       if(*ui3->usri3_profile == L'\0') { bSuccess = TRUE; __leave; }

//       // allocate storage for profile string //       *ProfilePath = HeapAlloc(GetProcessHeap, 0,           (lstrlenW(ui3->usri3_profile) + 1) * sizeof(WCHAR) );

if(*ProfilePath == NULL) __leave;

//       // copy the appropriate structure memory to allocated storage //       if(lstrcpyW(*ProfilePath, ui3->usri3_profile) != NULL) bSuccess = TRUE; // indicate success if the copy succeeded

} // try __finally {

//       // free the allocated buffers //       if(umi2 != NULL) NetApiBufferFree(umi2);

if(ui3 != NULL) NetApiBufferFree(ui3);

if(wTargetComputer != NULL) NetApiBufferFree(wTargetComputer);

if(!bSuccess) { if(*ProfilePath != NULL) { HeapFree(GetProcessHeap, 0, *ProfilePath); *ProfilePath = NULL; }      }

} // finally

return bSuccess; } Additional query words: LogonUser LsaLogonUser

Keywords : _IK kbnetwork kbGINA kbKernBase kbOSWin2000 kbSDKPlatform kbSecurity kbNetAPI kbCodeSam kbGrpDSNet

Issue type : kbhowto

Technology : kbWin32SDKSearch kbAudDeveloper kbSDKSearch kbWin32sSearch