|< Windows Access Control Programming 5 | Main | Windows Access Control Programming 7 >|Site Index |Download |

MODULE I2

WINDOWS OS SECURITY

::ACCESS CONTROL STORY::

PART 6

What are in this Module?

1. Privileges

2. Running with Special Privileges

3. Running with Administrator Privileges

4. Asking the User for Credentials

5. Acquiring user credentials

6. Changing Privileges in a Token

7. Enabling and Disabling Privileges

8. Authorization Constants

9. Account Rights Constants

10. Privilege Constants

To get the current LUID that corresponds to one of the string constants, use the LookupPrivilegeValue() function.  Use theLookupPrivilegeName() function to convert a LUID to its corresponding string constant.  The system provides a set of display names that describe each of the privileges.  These are useful when you need to display a description of a privilege to the user.  You can use the LookupPrivilegeDisplayName() function to retrieve a description string that corresponds to the string constant for a privilege.  For example, on systems that use U.S. English, the display name for the SE_SYSTEMTIME_NAME privilege is "Change the system time".  You can use thePrivilegeCheck() function to determine whether an access token holds a specified set of privileges.  This is useful primarily to server applications that are impersonating a client.

A system administrator can use administrative tools, such as User Manager, to add or remove privileges for user and group accounts.  Administrators can programmatically use the LSA functions to work with privileges.  The LsaAddAccountRights() and LsaRemoveAccountRights() functions add or remove privileges from an account.  TheLsaEnumerateAccountRights() function enumerates the privileges held by a specified account.  TheLsaEnumerateAccountsWithUserRight() function enumerates the accounts that hold a specified privilege.  The information for LUID structure is given in the following Table.  Do not manipulate LUID directly.  Applications should use functions and structures to manipulate LUID values.

Running with Special Privileges

Some functions require special privileges to run correctly.  In some cases, the function can only be run by certain users or by members of certain groups.  The most common requirement is that the user be a local administrator.  Other functions require the user's account to have specific privileges enabled.  To reduce the possibility of unauthorized code being able to get control, the system should run with the least privilege necessary.  Applications that need to call functions that require special privileges can leave the system open to attack by hackers.  Such applications should be designed to run for short periods of time and should inform the user of the security implications involved.

Running with Administrator Privileges

The first step in establishing which type of account your application needs to run under is to examine what resources the application will use and what privileged APIs it will call.  You may find that the applications, or large parts of it, do not require administrator privileges.  You can provide the privileges your application needs with less exposure to malicious attack by using one of the following approaches:

1. Run under an account with less privilege.  One way to do this is to use PrivilegeCheck() to determine what privileges are enabled in a token.  If the available privileges are not adequate for the current operation, you can disable that code and ask the user to logon to an account with administrator privileges.

2. Break into a separate application functions that require administrator permissions.  You can provide for the user a shortcut that executes theRunAs command.  Programmatically, you can configure the RunAs command under the AppId registry key for your application.

3. Authenticate the user by callingCredUIPromptForCredentials() (GUI) or CredUICmdLinePromptForCredentials() (command line) to obtain user name and password.

4. Impersonate the user.  A process that starts under a highly privileged account like System can impersonate a user account by callingImpersonateLoggedOnUser() or similar Impersonate functions, thus reducing privilege level.  However, if a call to RevertToSelf() is injected into the thread, the process returns to the original System privileges.

If you have determined that your application must run under an account with administrator privileges and that an administrator password must be stored in the software system.

Asking the User for Credentials

Your application may need to prompt the user for user name and password information to avoid storing an administrator password or to verify that the token holds the appropriate privileges.  However, simply prompting for credentials may train users to supply those to any random, unidentified dialog box that appears on the screen.  The following procedure is recommended to reduce that training effect.

Acquiring user credentials

The recommended steps to properly acquire user credentials:

1. Inform the user, by using a message that is clearly part of your application, that they will see a dialog box that requests their user name and password.  You can also use theCREDUI_INFO structure on the call toCredUIPromptForCredentials() to convey identifying data or a message.

2. CallCredUIPromptForCredentials().  Note that the maximum number of characters specified for user name and password information includes the terminating null character.

3. CallCredUIParseUserName() and CredUIConfirmCredentials() to verify that you obtained appropriate credentials.

The following code portion example shows how to callCredUIPromptForCredentials() to ask the user for a user name and password.  It begins by filling in a CREDUI_INFO structure with information about what prompts to use. Next, the code fills two buffers with zeros.  This is done to ensure that no information gets passed to the function that might reveal an old user name or password to the user.  The call to CredUIPromptForCredentials() brings up the dialog box.  For security reasons, this example uses theCREDUI_FLAGS_DO_NOT_PERSIST flag to prevent the operating system from storing the password because it might then be exposed.  If there are no errors,CredUIPromptForCredentials() fills in the pszName and pszPwd variables and returns zero.  When the application has finished using the credentials, it should put zeros in the buffers to prevent the information from being accidentally revealed.

#include <windows.h>

#include <wincred.h>

 

CREDUI_INFO cui;

TCHAR pszName[CREDUI_MAX_USERNAME_LENGTH+1];

TCHAR pszPwd[CREDUI_MAX_PASSWORD_LENGTH+1];

BOOL fSave;

DWORD dwErr;

 

cui.cbSize = sizeof(CREDUI_INFO);

cui.hwndParent = NULL;

//  Ensure that MessageText and CaptionText identify what credentials to use and which application requires them.

cui.pszMessageText = TEXT("Enter administrator account information");

cui.pszCaptionText = TEXT("CredUITest");

cui.hbmBanner = NULL;

fSave = FALSE;

SecureZeroMemory(pszName, sizeof(pszName));

SecureZeroMemory(pszPwd, sizeof(pszPwd));

dwErr = CredUIPromptForCredentials(

                 &cui,                                      // CREDUI_INFO structure

                 TEXT("TheServer"),           // Target for credentials, usually a server

                 NULL,                                  // Reserved

                 0,                                         // Reason

                 pszName,                          // User name

                 CREDUI_MAX_USERNAME_LENGTH+1,  // Max number of char for user name

                 pszPwd,                            // Password

                 CREDUI_MAX_PASSWORD_LENGTH+1,  // Max number of char for password

                 &fSave,                            // State of save check box

                 CREDUI_FLAGS_GENERIC_CREDENTIALS |  // flags

                 CREDUI_FLAGS_ALWAYS_SHOW_UI |

                 CREDUI_FLAGS_DO_NOT_PERSIST); 

 

if(!dwErr)

{

    //  TODO: Put code that uses the credentials here.

    //  When you have finished using the credentials, erase them from memory.

    SecureZeroMemory(pszName, sizeof(pszName));

    SecureZeroMemory(pszPwd, sizeof(pszPwd));

}

Changing Privileges in a Token

You can change the privileges in either a primary or an impersonation token in two ways:

1. Enable or disable privileges by using theAdjustTokenPrivileges() function.
2. Restrict or remove privileges by using theCreateRestrictedToken() function.

AdjustTokenPrivileges() cannot add or remove privileges from the token.  It can only enable existing privileges that are currently disabled or disable existing privileges that are currently enabled.  CreateRestrictedToken() has more extensive capabilities as follows:

1. Removing a privilege.  Note that removing a privilege is not the same as disabling one.  After a privilege is removed from a token, it cannot be put back.

2. Attaching the deny-only attribute to SIDs in the token.  This has the effect of disallowing specific groups or accounts, for example, denying the Everyone group delete access to a particular file.

3. Specifying a list of restricting SIDs in the token.

Enabling and Disabling Privileges

Enabling a privilege in an access token allows the process to perform system-level actions that it could not previously.  Your application should thoroughly verify that the privilege is appropriate to the type of account, especially for the following powerful privileges:

Before enabling any of these potentially dangerous privileges, determine that functions or operations in your code actually require the privileges.  For example, very few functions in the operating system actually require theSeTchPrivilege.

Authorization Constants

Authorization constants are categorized according to usage as follows:

1. Account Rights Constants.
2. Privilege Constants.

The following account right constants are used to control the logon ability of an account.  TheLogonUser() orLsaLogonUser() functions fail if the account being logged on does not have the account rights required for the type of logon being performed.  TheSE_DENY rights override the corresponding account rights.  An administrator can assign anSE_DENY right to an account to override any logon rights that an account might have as a result of a group membership.  For example, you could assign theSE_NETWORK_LOGON_NAME right to Everyone but assign the SE_DENY_NETWORK_LOGON_NAME right to Administrators to prevent remote administration of computers.

The preceding account right constants are defined as strings in ntsecapi.h.  For example, the SE_INTERACTIVE_LOGON_NAME constant is defined as "SeInteractiveLogonRight".

Privilege Constants

The following privilege constants are defined as strings in winnt.h.  For example, the SE_AUDIT_NAME constant is defined as "SeAuditPrivilege".  The functions that get and adjust the privileges in an access token use the LUID type to identify privileges. Use the LookupPrivilegeValue() function to determine the LUID on the local system that corresponds to a privilege constant.  You can use the LookupPrivilegeName() function to convert a LUID to its corresponding string constant.  The operating system represents a privilege by using the string that follows "User Right" in the Description column of the following table.

The operating system displays the user right strings in the Policy column of the User Rights Assignment node of the Local Security Settings Microsoft Management Console (MMC) snap-in as shown below (Administrative Tools → Local Security Policy).

Figure 1

The following code portion example shows how to enable or disable a privilege in an access token.  The example calls theLookupPrivilegeValue() function to get the LUID that the local system uses to identify the privilege.  Then the example calls the AdjustTokenPrivileges() function, which either enables or disables the privilege that depends on the value of thebEnablePrivilege parameter.

BOOL SetPrivilege(

    HANDLE hToken,          // access token handle

    LPCTSTR lpszPrivilege,  // name of privilege to enable/disable

    BOOL bEnablePrivilege   // to enable or disable privilege

    )

{

 

TOKEN_PRIVILEGES tp;

LUID luid;

lpszPrivilege = "Generate security audits";

 

if(!LookupPrivilegeValue(

        NULL,            // lookup privilege on local system

        lpszPrivilege,   // privilege to lookup

        &luid))        // receives LUID of privilege

{

    printf("LookupPrivilegeValue error: %u\n", GetLastError());

    return FALSE;

}

 

tp.PrivilegeCount = 1;

tp.Privileges[0].Luid = luid;

if(bEnablePrivilege)

    tp.Privileges[0].Attributes = SE_PRIVILEGE_ENABLED;

else

    tp.Privileges[0].Attributes = 0;

 

// Enable the privilege or disable all privileges.

if(!AdjustTokenPrivileges(

       hToken,

       FALSE,

       &tp,

       sizeof(TOKEN_PRIVILEGES),

       (PTOKEN_PRIVILEGES) NULL,

       (PDWORD) NULL))

{

      printf("AdjustTokenPrivileges error: %u\n", GetLastError());

      return FALSE;

}

 

if(GetLastError() == ERROR_NOT_ALL_ASSIGNED)

 

{

      printf("The token does not have the specified privilege. \n");

      return FALSE;

}

 

return TRUE;

}

-------------------------------Windows Access Control Story, Part II---------------------------

Further reading and digging:

1. For Multibytes, Unicode characters and Localization please refer to Locale, wide characters & Unicode (Story) and Windows users & groups programming tutorials (Implementation).

2. Check the best selling C, C++ and Windows books at Amazon.com.

3. Microsoft C references, online MSDN.

4. Microsoft Visual C++, online MSDN.

5. ReactOS - Windows binary compatible OS - C/C++ source code repository, Doxygen.

6. Linux Access Control Lists (ACL) info can be found atAccess Control Lists.

7. Structure, enum, union and typedef story can be foundC/C++ struct, enum, union & typedef.

8. Notation used in MSDN is Hungarian Notation instead of CamelCase and is discussedWindows programming notations.

9. Windows data type information is inWindows data types used in Win32 programming.

|< Windows Access Control Programming 5 | Main | Windows Access Control Programming 7 >|Site Index |Download |