JP's homepage

NSIS UserMgr plug-in

From NSIS Wiki


Author: hgerstung (talk, contrib)
Edited by: jpderuiter


Contents

Links

UserMgr.zip (50 KB)

Find the original plugin of the author (15.8.2006) at http://www.meinberg.de/download/utils/UserMgr.zip

UserMgr thread on NSIS Discussion forum

Description

I needed to create a user account in my installer, running a service with restricted rights is something we all should try to do whenever possible.

In order to get this functionality, I used the UserInfo plugin as a starter and created a number of functions dealing with user accounts, privileges and groups.

Please note: This plugin and its functions are only useful for Windows NT/2K/XP target systems.
You should check the type of system in your installer script before trying to call one of the functions of this DLL. I did not test what happens when someone tries to use UserMgr on a Win95/Win98 system.

As I am currently the only one using this, I consider it in beta state and appreciate any comments and feedback, e.g. "Yes, it runs on Winxyz" or "No, no chance on Win87 etc. etc.).

You can reach me via PM, my forum account is hgerstung, so do not hesitate to contact me if you are experiencing difficulties.

Please note: NSIS v2.42 or higher is required for this plugin to run properly.

Known Issues

Windows 9x support
Untested on Windows 9x; structure is different, so probably not going to work.
Any help in resolving these issues (submitting a patch, etc) is appreciated.


Plugin Command Reference

Here's a list of functions the DLL exports including the necessary parameters.

UserMgr::CreateAccount "USERID" "PASSWORD" "COMMENT"
creates a new user account, returns status string
UserMgr::CreateAccountEx "USERID" "PASSWORD" "COMMENT" "FULLNAME" "USERCOMMENT" "FLAGS"
creates a new user account, including the Fullname (Shown in the Welcome screen), returns status string
where "FLAGS" can be one of the following:
UF_ACCOUNTDISABLE
The user's account is disabled.
UF_PASSWD_NOTREQD
No password is required.
UF_PASSWD_CANT_CHANGE
The user cannot change the password.
UF_DONT_EXPIRE_PASSWD
The password will never expire on the account.
UserMgr::GetCurrentUserName
returns the username of the currently logged in user
UserMgr::GetCurrentDomain
returns the domainname of the currently logged in user
UserMgr::BuiltAccountEnv "USERID" "PASSWORD"
builds the User environment of the user (Registry hive, Documents and settings etc.), returns status string
UserMgr::RegLoadUserHive "USERID"
loads the User Registry hive in HKEY_USERS\{USERID}, returns status string
UserMgr::RegUnLoadUserHive "USERID"
unloads the User Registry hive, returns status string
UserMgr::DeleteAccount "USERID"
deletes a user account, returns status string
UserMgr::AddToGroup "USERID" "GROUPID"
adds a user to a group, returns status string
UserMgr::RemoveFromGroup "USERID" "GROUPID"
removes group membership from a user, returns status string
UserMgr::IsMemberOfGroup ''USERID" "GROUPID''
returns "TRUE" if the user is a member of the specified group, else returns "FALSE"
UserMgr::AddPrivilege "USERID" "PRIVILEGE"
adds a privilege to the user account, returns status string. You can find a list of privileges below.
UserMgr::RemovePrivilege "USERID" "PRIVILEGE"
removes a privilege from an account, returns status string. You can find a list of privileges below.
UserMgr::HasPrivilege "USERID" "PRIVILEGE"
returns "TRUE" if the user is has the specified privilege, else returns "FALSE"
UserMgr::CreateGroup "GROUPID" "COMMENT"
creates a new user group, returns status string
UserMgr::DeleteGroup "GROUPID"
deletes a user group, returns status string
UserMgr::GetUserInfo "USERID" "FIELD"
returns a specific information for the given user-ID
where "FIELD" can be one of the following:
EXISTS
returns "OK", if the user exists on the system, otherwise an error is returned (string "ERROR xxxx")
NAME
returns the user name
FULLNAME
returns the full user name (e.g. firstname surname)
HOMEDIR
returns the path to the users home directory
COMMENT
returns a comment stored for the user
PASSWD_STATUS
returns the Password status for the user (either NEVEREXPIRES or CANTCHANGE)
UserMgr::SetUserInfo "USERID" "FIELD" "VALUE"
sets a specific information for the given user-ID
where "FIELD" can be one of the following:
NAME
sets the user name
FULLNAME
sets the full user name (e.g. firstname surname)
HOMEDIR
sets the path to the users home directory
COMMENT
sets a comment stored for the user
PASSWD_NEVER_EXPIRES ["YES"/"NO"]
enables/disables password expiration
PASSWORD
sets the user password (Admin rights required)
UserMgr::ChangeUserPassword "USERID" "OLDPASSWORD" "NEWPASSWORD""
changes the user password (Admin rights not required)
UserMgr::GetLocalizedStdAccountName "STDACCOUNTSID"
returns the localized Standard Account name
(e.g. "NT AUTHORITY\SYSTEM" for "S-1-5-18" on a English system
and "NT-AUTORITÄT\NETZWERKDIENST" for "S-1-5-20" on a German system)
The most often used SID's are defined in the included SpecialGroupsSIDs.nsh
UserMgr::GetUserNameFromSID "SID"
returns the username for the specified SID
(returns both domain and username: "{domain}\{username}")
UserMgr::GetSIDFromUserName "DOMAIN" "USERID"
returns the SID for the specified USERID and DOMAIN
(use an empty string for the domain for a local user)
UserMgr::SetRegKeyAccess "USERID" "ROOTKEY" "REGKEY" "ACCESSMASK"
adds/sets/revokes/denies access rights for registry keys
where "ROOTKEY" can be one of these: HKLM, HKU, HKCU, HKCR
where "ACCESSMASK" starts with a '+' to grant rights, "-" to deny rights, "=" to set rights, afterwards the rights can be listed: 'r' for read access, 'w' for write access, 'x' for execute access, 'a' for full access.
BEWARE
If ACCESSMASK is empty, all of the the users access rights will be removed! This is used to delete an access list entry from a registry key.
example:
 UserMgr::SetRegKeyAccess "myuser" "HKLM" "SYSTEM\CurrentControlSet\Services\Blabla" "=a"
grants full access for "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Blabla" to user "myuser"

Return value

A status string can look like this:

"OK"
Function has been completed successfully
"ERROR xxxx"
An error occurred. Please see MSDN or the LMERR.H file (comes with Visual Studio) to find out about possible error codes. You may also find the Network Management page on MSDN to be useful.

Example

Here is a short example of how to use the functions in an Installer script:

Name "UserMgr.dll Sample Installation Script"
 
OutFile "usermgr-sample.exe"
 
#
# Be careful when using these functions, especially the "Remove" and "Delete"
# commands!!!
#
 
Function .onInit
        # the plugins dir is automatically deleted when the installer exits
        InitPluginsDir
	
	UserMgr::CreateAccount "myuser" "mypassword" "A test user created by the UserMgr plugin"
	Pop $0
        MessageBox MB_OK "CreateUser Result : $0"
 
	UserMgr::AddToGroup  "myuser" "Administrators"
	Pop $0
        MessageBox MB_OK "AddToGroup Result : $0"
 
	UserMgr::SetRegKeyAccess "myuser" "HKLM" "SYSTEM\CurrentControlSet\Services\EventLog\Application\NTP" "=a"
	Pop $0
        MessageBox MB_OK "GrantAccess Result : $0"
 
	UserMgr::SetRegKeyAccess "myuser" "HKLM" "SYSTEM\CurrentControlSet\Services\EventLog\Application\NTP" "=r"
	Pop $0
        MessageBox MB_OK "RevokeWriteAccess Result : $0"
 
	UserMgr::SetRegKeyAccess "myuser" "HKLM" "SYSTEM\CurrentControlSet\Services\EventLog\Application\NTP" ""
	Pop $0
        MessageBox MB_OK "RevokeAccess Result : $0"
 
	UserMgr::DeleteAccount "myuser"
	Pop $0
        MessageBox MB_OK "DeleteUser Result: $0"
        
        #######################################################################
 
	UserMgr::CreateAccountEx "myuserA" "mypassword" "A test user created by the UserMgr plugin" "My User A" "A test user created by the UserMgr plugin" "UF_PASSWD_NOTREQD|UF_DONT_EXPIRE_PASSWD"
	Pop $0
        MessageBox MB_OK "CreateUser Result : $0"
 
	UserMgr::BuiltAccountEnv "myuserA" "mypassword"
	Pop $0
        MessageBox MB_OK "BuiltAccountEnv Result : $0"
 
	UserMgr::RegLoadUserHive "myuserA"
	Pop $0
        MessageBox MB_OK "RegLoadUserHive Result : $0"
 
        WriteRegStr HKEY_USERS "myuserA\Software\My Company\My Software" "String Value" "dead beef"
 
	UserMgr::RegUnLoadUserHive "myuserA"
	Pop $0
        MessageBox MB_OK "RegUnLoadUserHive Result : $0"
 
	UserMgr::ChangeUserPassword "myuserA" "mypassword" "mypasswordb"
	Pop $0
        MessageBox MB_OK "ChangeUserPassword Result : $0"
 
	UserMgr::SetUserInfo "myuserA" "PASSWORD" "mypasswordc"
	Pop $0
        MessageBox MB_OK "SetUserInfo PASSWORD Result : $0"
 
	UserMgr::DeleteAccount "myuserA"
	Pop $0
        MessageBox MB_OK "DeleteUser Result: $0"
 
        ####################################################################### 
 
	UserMgr::GetCurrentUserName
	Pop $0 
        MessageBox MB_OK "GetCurrentUserName Result: $0" 
 
	UserMgr::GetSIDFromUserName "" "$0" 
	Pop $0 
        MessageBox MB_OK "GetSIDFromUserName Result: $0" 
 
	UserMgr::GetUserNameFromSID "$0" 
	Pop $0 
        MessageBox MB_OK "GetUserNameFromSID Result: $0" 
 
 
FunctionEnd
 
Section
SectionEnd

Incomplete List of Account Privileges

This list was taken from a web site and surely is not complete. You may have to ask Google or whoever to find out about certain privileges.

Side note: On my machine I needed to "grant" a user the SeDenyInteractiveLogonRight to deny the account to log in interactively - although it did not possess the SeInteractiveLogonRight privilege and was not a a member of any group. This is the same with SeDenyBatchLogonRight, SeDenyNetworkLogonRight and SeDenyServiceLogonRight. You can clearly see that the "i" in Micro$oft stands for "inconsistency" :-)

SeAssignPrimaryTokenPrivilege 
Replace a process level token
SeAuditPrivilege 
Generate security audits
SeBackupPrivilege 
Back up files and directories
SeBatchLogonRight 
Log on as a batch job
SeChangeNotifyPrivilege 
Bypass traverse checking
SeCreatePagefilePrivilege 
Create a pagefile
SeCreatePermanentPrivilege 
Create permanent shared objects
SeCreateTokenPrivilege 
Create a token object
SeDebugPrivilege 
Debug programs
SeIncreaseBasePriorityPrivilege 
Increase scheduling priority
SeIncreaseQuotaPrivilege 
Increase quotas
SeInteractiveLogonRight 
Log on locally
SeLoadDriverPrivilege 
Load and unload device drivers
SeLockMemoryPrivilege 
Lock pages in memory
SeMachineAccountPrivilege 
Add workstations to domain
SeNetworkLogonRight 
Access this computer from the network
SeProfileSingleProcessPrivilege 
Profile single process
SeRemoteShutdownPrivilege 
Force shutdown from a remote system
SeRestorePrivilege 
Restore files and directories
SeSecurityPrivilege 
Manage auditing and security log
SeServiceLogonRight 
Log on as a service
SeShutdownPrivilege 
Shut down the system
SeSystemEnvironmentPrivilege 
Modify firmware environment values
SeSystemProfilePrivilege 
Profile system performance
SeSystemtimePrivilege 
Change the system time
SeTakeOwnershipPrivilege 
Take ownership of files or other objects
SeTcbPrivilege 
Act as part of the operating system
SeUnsolicitedInputPrivilege 
Read unsolicited input from a terminal device

Changes

JPR 01 Jan 2008:

UserMgr010108.zip (31 KB)

  • NetLocalGroupAddMembers used instead of NetGroupAddUser in the AddToGroup function to make it work. (Thanks to the article of CancerFace (http://nsis.sourceforge.net/User_Management_using_API_calls))
  • PASSWORD added as possible FIELD for the SetUserInfo function. With this field the user password can be changed
  • The function ChangeUserPassword is added to be able to change a user password
  • The function CreateAccountEx is added to be able to add a fullname of a user (Shown in the Welcome Screen) and add flags to the user (Password never expires etc.)
  • The function BuiltAccountEnv is added. This function creates the User Environment (Documents and settings\{User} folder, User Registry Hive etc. to be able to do something there without the need to login as the new created user first
  • The function RegLoadUserHive is added. This function loads the User Registry hive in HKEY_USERS\{USERID} to be able to add keys and values to the HKEY_CURRENT_USER of this user
  • The function RegUnLoadUserHive is added. This function unloads the User Registry hive

JPR 14 Jan 2008:

UserMgr011408.zip (33 KB)

  • Fixed a small bug in GetUserInfo function
  • Fixed 2 small bugs in SetUserInfo function
  • Added GetCurrentUserName function
  • Added GetLocalizedStdAccountName function
  • Added IsMemberOfGroup function

JPR 15 Jan 2008:

UserMgr011508.zip (33 KB)

  • Fixed a small bug in RegLoadUserHive function

JPR 01 Feb 2008:

UserMgr020108.zip (33 KB)

  • Fixed a bug in SetUserInfo function when using for "FULLNAME"
  • Added HasPrivilege function

JPR 22 Jan 2009:

UserMgr012209.zip (42 KB)

  • Added GetCurrentDomain function

JPR 23 Jan 2009:

UserMgr012309.zip (45 KB)

  • Fixed a bug crashing the installer

JPR 25 Jan 2009:

UserMgr012509.zip (47 KB)

  • Return errorcode (WinError if available, else NTStatus) for LsaEnumerateAccountRights in function HasPrivilege
  • Return FALSE if user has no privileges in function HasPrivilege

JPR 2 Sep 2009:

  • Added GetUserNameFromSID function
  • Added GetSIDFromUserName function
  • Fixed a problem in the RegLoadUserHive function when a user was deleted and then recreated