Southsoftware.com
.:Pricing
Home
Products
Downloads
Support
Contacts
Site Map
.:RunAsUser DLL
About product
Download trial
Purchase license
View screenshot
Online manual
FAQ & Support
.:Follow us
Follow us on Facebook Follow us on Twitter Follow us on YouTube
   

Functions

Include file: runasuser.h
Note: All structures in this file are 4-byte aligned.

Main functions
Main functions and structures to be used in this implementation.

RunAsUser_GetVersion
SUMMARY:
Current version of the library.
DECLARATION:
DWORD WINAPI RunAsUser_GetVersion(void);
RETURN VALUE:
MAKELONG(minor, major).

RunAsUser_Initialize
SUMMARY:
Initialization interface. Must be called in the main function when program starts.
ARGUMENTS:
lprunasuser - pointer to the configuration structure.
DECLARATION:
BOOL WINAPI RunAsUser_Initialize(LPRUNASUSERCONFIGURATION lprunasuser);
RETURN VALUE:
If TRUE then initialization has been succeeded.

RunAsUser_CommandLine
SUMMARY:
Checks command line arguments and executes internal tasks if necessary. Must be called in the main function when program starts.
ARGUMENTS:
lpszCommandLine - command line to examine;
pdwExitCode - if return value is TRUE then this value contains process exit code.
DECLARATION:
BOOL WINAPI RunAsUser_CommandLine(LPCTSTR lpszCommandLine, LPDWORD pdwExitCode);
RETURN VALUE:
If TRUE, process must be terminated with the returned exit code.

RunAsUser_CreateProcess
SUMMARY:
Creates a new process and its primary thread. The new process runs in the security context of the specified user account.
ARGUMENTS:
runasType - type of authorization (RUNASTYPE_ constants);
pszEXE - the name of the module to be executed;
pszCmdLine - the command line to be executed;
pszDomainName - the domain or server whose account database contains the user account;
pszUserName - the name of the user;
pszPassword - the clear-text password for the user account specified by pszUserName;
pszDesktop - the name of the desktop (Default desktop: "WinSta0\Default"). The desktop must exist at the moment of the function call;
pszStartIn - the full path to the current directory of the process;
nCmdShow - the window show state. Can be any of the SW_ constants defined in WINUSER.H;
dwSession - the identifier of the session in which the process to be created;
fImpersonate - impersonate user before calling the CreateProcessAsUser() function;
fElevate - create process with highest privileges (Windows Vista and later);
lpfnRunAsUser_State - callback function that receives the execution status and extended error log. This parameter cannot be NULL;
lpfnRunAsUser_Wait - callback function that receives handle and identifier of the created process. In this function you can communicate with the created process in any way. This parameter can be NULL;
lParam - a user-defined value that will be passed to lpfnRunAsUser_State and lpfnRunAsUser_Wait callback functions.
DECLARATION:
BOOL WINAPI RunAsUser_CreateProcess(
  RUNASTYPE runasType,
  LPCTSTR pszEXE,
  LPCTSTR pszCmdLine,
  LPCTSTR pszDomainName,
  LPCTSTR pszUserName,
  LPCTSTR pszPassword,
  LPCTSTR pszDesktop,
  LPCTSTR pszStartIn,
  UINT nCmdShow,
  DWORD dwSession,
  BOOL fImpersonate,
  BOOL fElevate,
  RunAsUser_StateFn lpfnRunAsUser_State,
  RunAsUser_WaitFn lpfnRunAsUser_Wait,
  LPARAM lParam);
REMARKS:
If the process is started with RUNASTYPE_LOGONLOCALLYUSER or RUNASTYPE_PASSWORDLESSUSER type, this function does not return until started process is terminated. It is very important to wait until the process is terminated before exiting this function because it is necessary to unload user profile. Make sure your application is not terminated in the lpfnRunAsUser_State or lpfnRunAsUser_Wait function. If it does then user profile will remain loaded.

Desktop: Although, in earlier versions of Windows the program can be run on the desktop that appears after you start the computer (when the system asks for the username and password necessary to log in), starting from Windows XP, Logon and Screen saver desktops are secure. However, it is still possible to start a process when there is no logged on user. To do so, your process must be running as service, pszDesktop must be "Service-0x0-3e7$\Default" and dwSession must be 0 - the process will be started on the hidden desktop.

Impersonation: RunAsUser_CreateProcess allows you to access the specified directory and executable image in the security context of the caller or the target user. If fImpersonate is FALSE then RunAsUser_CreateProcess accesses the directory and executable image in the security context of the caller. In this case, if the caller does not have access to the directory and executable image, the function fails. Specify TRUE to access the directory and executable image in the security context of the target user.

Elevation: On Windows Vista and later, this option allows creating process with highest privileges. Set this option to TRUE, if your process fails to start with error 740 (ERROR_ELEVATION_REQUIRED).

RUNASTYPE_CURRENTUSER: When Terminal Services is running, the process will be started as user that is logged on in the dwSession session. If Terminal Services is not running then process will be started as user that is working in the system for the moment.

RUNASTYPE_LOGONLOCALLYUSER: Because of clear-text password is used for this function, you may wish to clear the password from memory by calling the SecureZeroMemory function.

If you wish to logon a user with blank password, then you will need to disable the restriction against logging on to the network without a password. You can do so by Local Security Policy: Control Panel\Administrative Tools\Local Security Policy\Security Settings\Local Policies\Security Options. The name of the policy is Accounts: Limit local account use of blank passwords to console logon only. By default, this option is enabled.

This example shows how to start process with RUNASTYPE_CURRENTUSER type:
RunAsUser_CreateProcess(
  RUNASTYPE_CURRENTUSER,
  _T("cmd.exe"),
  _T("/C dir"),
  _T(""),
  _T(""),
  _T(""),
  _T("WinSta0\\Default"),
  _T("c:\\"),
  SW_SHOWNORMAL,
  dwSessionId,
  FALSE, FALSE,
  RunAsUser_State,
  RunAsUser_Wait,
  NULL);
This example shows how to start process with RUNASTYPE_THISPROCESSUSER type:
RunAsUser_CreateProcess(
  RUNASTYPE_THISPROCESSUSER,
  _T("cmd.exe"),
  _T("/C dir"),
  _T(""),
  _T(""),
  _T(""),
  _T("WinSta0\\Default"),
  _T("c:\\"),
  SW_SHOWNORMAL,
  dwSessionId,
  FALSE, FALSE,
  RunAsUser_State,
  RunAsUser_Wait,
  NULL);
This example shows how to start process with RUNASTYPE_LOGONLOCALLYUSER type:
RunAsUser_CreateProcess(
  RUNASTYPE_LOGONLOCALLYUSER,
  _T("cmd.exe"),
  _T("/C dir"),
  szDomainName,
  szUserName,
  szPassword,
  _T("WinSta0\\Default"),
  _T("c:\\"),
  SW_SHOWNORMAL,
  dwSessionId,
  FALSE, FALSE,
  RunAsUser_State,
  RunAsUser_Wait,
  NULL);
This example shows how to start process with RUNASTYPE_PASSWORDLESSUSER type:
RunAsUser_CreateProcess(
  RUNASTYPE_PASSWORDLESSUSER,
  _T("cmd.exe"),
  _T("/C dir"),
  szDomainName,
  szUserName,
  _T(""),
  _T("WinSta0\\Default"),
  _T("c:\\"),
  SW_SHOWNORMAL,
  dwSessionId,
  FALSE, FALSE,
  RunAsUser_State,
  RunAsUser_Wait,
  NULL);
This example shows how to start process with RUNASTYPE_LOCALSYSTEM type:
RunAsUser_CreateProcess(
  RUNASTYPE_LOCALSYSTEM,
  _T("cmd.exe"),
  _T("/C dir"),
  _T(""),
  _T(""),
  _T(""),
  _T("WinSta0\\Default"),
  _T("c:\\"),
  SW_SHOWNORMAL,
  dwSessionId,
  FALSE, FALSE,
  RunAsUser_State,
  RunAsUser_Wait,
  NULL);
RETURN VALUE:
Returns TRUE if function succeeded, otherwise returns FALSE.
GetLastError() can be used for extended error information.

Extra functions
Extra common functions that we made available from this implementation.

RunAsUser_CreateUUID
SUMMARY:
Create a Universally Unique Identifier (UUID). A UUID is a 16-octet (128-bit) number represented by 32 hexadecimal digits, displayed in five groups separated by hyphens, in the following form: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
ARGUMENTS:
lpszUuid - buffer for UUID string;
cUuid - size, in TCHARs, of the lpszUuid buffer.
DECLARATION:
BOOL WINAPI RunAsUser_CreateUUID(LPTSTR lpszUuid, DWORD cUuid);
RETURN VALUE:
Returns TRUE if function succeeded, otherwise returns FALSE.
GetLastError() can be used for extended error information.

RunAsUser_GetCurrentUserNonWTS
SUMMARY:
Get current user and domain name (when Terminal Services is not running).
ARGUMENTS:
pszSamUserName - buffer for the SAM (Windows NT) account name;
dwBufferLen - size, in TCHARs, of the pszSamUserName buffer.
DECLARATION:
BOOL WINAPI RunAsUser_GetCurrentUserNonWTS(LPTSTR pszSamUserName, DWORD dwBufferLen);
RETURN VALUE:
Returns TRUE if function succeeded, otherwise returns FALSE.
GetLastError() can be used for extended error information.

RunAsUser_SDDL2SID
SUMMARY:
Converts a string-format SID into a valid, functional security descriptor.
ARGUMENTS:
pszSidStr - pointer to a null-terminated string containing the SID to convert;
pSid - pointer to a variable that receives a pointer to the converted SID.
DECLARATION:
BOOL WINAPI RunAsUser_SDDL2SID(LPCTSTR pszSidStr, PSID *pSid);
RETURN VALUE:
Returns TRUE if function succeeded, otherwise returns FALSE.
GetLastError() can be used for extended error information.
To free pSid, call the FreeSid() function.

RunAsUser_SDDL2SAM
SUMMARY:
Converts a string-format SID into an account name.
ARGUMENTS:
pszSidStr - pointer to a null-terminated string containing the SID to convert;
pszTarget - the domain or server whose account database contains the user account;
pszAccountName - pointer to a variable that receives an user account name.
dwBufferLen - size, in TCHARs, of the pszAccountName buffer.
DECLARATION:
BOOL WINAPI RunAsUser_SDDL2SAM(LPCTSTR pszSidStr, LPCTSTR pszTarget, LPTSTR pszAccountName, DWORD dwBufferLen);
RETURN VALUE:
Returns TRUE if function succeeded, otherwise returns FALSE.
GetLastError() can be used for extended error information.

RunAsUser_SID2SDDL
SUMMARY:
Converts a SID to a string format.
ARGUMENTS:
pSid - pointer to the security descriptor to convert;
pszSidStr - pointer to a variable that receives a null-terminated SID string;
dwBufferLen - size, in TCHARs, of the pszSidStr buffer.
DECLARATION:
BOOL WINAPI RunAsUser_SID2SDDL(PSID pSid, LPTSTR pszSidStr, DWORD dwBufferLen);
RETURN VALUE:
Returns TRUE if function succeeded, otherwise returns FALSE.
GetLastError() can be used for extended error information.

RunAsUser_Name2SID
SUMMARY:
Converts an account name to a binary SID.
ARGUMENTS:
pszUserName - the name of the user;
pszDomainName - the domain or server whose account database contains the user account;
DECLARATION:
PSID WINAPI RunAsUser_Name2SID(LPCTSTR pszUserName, LPCTSTR pszDomainName);
RETURN VALUE:
Returns pointer to a binary SID if function succeeded, otherwise returns NULL.
GetLastError() can be used for extended error information.
To free the returned SID, call the LocalFree() function.

RunAsUser_AdjustPrivilege
SUMMARY:
Enables or disables a privilege for the calling process.
ARGUMENTS:
pszPrivilege - name of the privilege;
dwNewState - can be a combination of SE_PRIVILEGE_ constants defined in WINNT.H.
pdwOldState - receives the previous state of the privilege. This parameter can be NULL.
DECLARATION:
BOOL WINAPI RunAsUser_AdjustPrivilege(LPCTSTR pszPrivilege, DWORD dwNewState, LPDWORD pdwOldState);
RETURN VALUE:
Returns TRUE if function succeeded, otherwise returns FALSE.
GetLastError() can be used for extended error information.

Back to contents

   
About us   Privacy policy   Terms of use   Link to us
Current Version: 1.08
Buy RunAsUser DLL now for only $ 199.95 USD. We accept variety of payment options: Credit Cards, Checks, Wire Transfers, PayPal. Payments can be made Online, by PO, Fax, Mail or Phone.
.:Requirements
Computer: Minimum required by operating system you are running.
Disk Space: Under 4 MB
Operating System: RunAsUser DLL requires a Microsoft Windows NT 4.0 / 2000 / XP / Server 2003 / Server 2008 / Vista / 7 / Server 2012 / 8 Desktop 32 or 64-bit operating system.