This supplementary note provides information for functions used in program examples of the Windows Process & Thread 1, Windows Process & Thread 2 and Windows Process & Thread 3. Struct, enum, macro and type are dumped in struct, enum, typedef, macros etc. The information compiled for NT 5 (Windows 2000 and above).
Page Index:
|
|
Item |
Description |
|
Function |
GetKernelObjectSecurity(). |
|
Use |
To retrieve a copy of the security descriptor that protects a kernel object. |
|
Prototype |
BOOL GetKernelObjectSecurity( HANDLE Handle, SECURITY_INFORMATION RequestedInformation, PSECURITY_DESCRIPTOR pSecurityDescriptor, DWORD nLength, LPDWORD lpnLengthNeeded ); |
|
Parameters |
Handle - [in] Handle to a kernel object. RequestedInformation - [in] Specifies a SECURITY_INFORMATION value that identifies the security information being requested. pSecurityDescriptor - [out] Pointer to a buffer the function fills with a copy of the security descriptor of the specified object. The calling process must have the right to view the specified aspects of the object's security status. The SECURITY_DESCRIPTOR structure is returned in self-relative format. nLength - [in] Specifies the size, in bytes, of the buffer pointed to by the pSecurityDescriptor parameter. lpnLengthNeeded - [out] Pointer to a variable that receives the number of bytes required for the buffer pointed to by the pSecurityDescriptor parameter. If this variable's value is greater than the value of the nLength parameter when the function returns, none of the security descriptor is copied to the buffer. |
|
Return value |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
- |
|
Table 1 |
|
SetKernelObjectSecurity()
|
Item |
Description |
|
Function |
SetKernelObjectSecurity(). |
|
Use |
To set the security of a kernel object. For example, this can be a process, thread, or event. |
|
Prototype |
BOOL SetKernelObjectSecurity( HANDLE Handle, SECURITY_INFORMATION SecurityInformation, PSECURITY_DESCRIPTOR SecurityDescriptor ); |
|
Parameters |
See below. |
|
Return value |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
- |
|
Table 2 |
|
Handle - [in] Handle to a kernel object for which security information is set.
SecurityInformation - [in] Specifies the components of the security descriptor to set. This parameter can be a combination of the following values.
|
Value |
Meaning |
|
DACL_SECURITY_INFORMATION |
Sets the object's DACL. The handle must have WRITE_DAC access, or the calling process must be the object's owner. |
|
GROUP_SECURITY_INFORMATION |
Sets the object's primary group SID. The handle must have WRITE_OWNER access, or the calling process must be the object's owner. |
|
OWNER_SECURITY_INFORMATION |
Sets the object's owner SID. The handle must have WRITE_OWNER access. Alternatively, the calling process must be the object's owner or have the SE_TAKE_OWNERSHIP_NAME privilege enabled. |
|
SACL_SECURITY_INFORMATION |
Sets the object's SACL. The handle must have ACCESS_SYSTEM_SECURITY access. The correct way to get this access is to enable the SE_SECURITY_NAME privilege in the caller's current access token, open the handle for ACCESS_SYSTEM_SECURITY access, and then disable the privilege. |
|
Table 3 |
|
SecurityDescriptor - [in] Pointer to a SECURITY_DESCRIPTOR structure containing the new security information.
|
Item |
Description |
|
Function |
PrivilegeCheck(). |
|
Use |
To determine whether a specified set of privileges are enabled in an access token. The PrivilegeCheck() function is typically called by a server application to check the privileges of a client's access token. |
|
Prototype |
BOOL PrivilegeCheck( HANDLE ClientToken, PPRIVILEGE_SET RequiredPrivileges, LPBOOL pfResult ); |
|
Parameters |
ClientToken - [in] Handle to an access token representing a client process. This handle must have been obtained by opening the token of a thread impersonating the client. The token must be open for TOKEN_QUERY access. RequiredPrivileges - [in] Pointer to a PRIVILEGE_SET structure. The Privilege member of this structure is an array of LUID_AND_ATTRIBUTES structures. Before calling PrivilegeCheck(), use the Privilege array to indicate the set of privileges to check. Set the Control member to PRIVILEGE_SET_ALL_NECESSARY if all of the privileges must be enabled; or set it to zero if it is sufficient that any one of the privileges be enabled. When PrivilegeCheck() returns, the Attributes member of each LUID_AND_ATTRIBUTES structure is set to SE_PRIVILEGE_USED_FOR_ACCESS if the corresponding privilege is enabled. pfResult - [out] Pointer to a value the function sets to indicate whether any or all of the specified privileges are enabled in the access token. If the Control member of the PRIVILEGE_SET structure specifies PRIVILEGE_SET_ALL_NECESSARY, this value is TRUE only if all the privileges are enabled; otherwise, this value is TRUE if any of the privileges are enabled. |
|
Return value |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
- |
|
Table 4 |
|
An access token contains a list of the privileges held by the account associated with the token. These privileges can be enabled or disabled; most are disabled by default. The PrivilegeCheck() function checks only for enabled privileges. To get a list of all the enabled and disabled privileges held by an access token, call the GetTokenInformation() function. To enable or disable a set of privileges in an access token, call the AdjustTokenPrivileges() function.
|
Item |
Description |
|
Function |
OpenProcessToken(). |
|
Use |
To open the access token associated with a process. |
|
Prototype |
BOOL OpenProcessToken( HANDLE ProcessHandle, DWORD DesiredAccess, PHANDLE TokenHandle ); |
|
Parameters |
ProcessHandle - [in] Handle to the process whose access token is opened. The process must have the PROCESS_QUERY_INFORMATION access permission. DesiredAccess - [in] Specifies an access mask that specifies the requested types of access to the access token. These requested access types are compared with the DACL of the token to determine which accesses are granted or denied. TokenHandle - [out] Pointer to a handle that identifies the newly opened access token when the function returns. |
|
Return value |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
Close the access token handle returned through the TokenHandle parameter by calling CloseHandle(). |
|
Table 5 |
|
|
Item |
Description |
|
Function |
OpenThreadToken(). |
|
Use |
To open the access token associated with a thread. |
|
Prototype |
BOOL OpenThreadToken( HANDLE ThreadHandle, DWORD DesiredAccess, BOOL OpenAsSelf, PHANDLE TokenHandle ); |
|
Parameters |
ThreadHandle - [in] Handle to the thread whose access token is opened. DesiredAccess - [in] Specifies an access mask that specifies the requested types of access to the access token. These requested access types are reconciled against the token's DACL to determine which accesses are granted or denied. OpenAsSelf - [in] Indicates whether the access check is to be made against the security context of the thread calling the OpenThreadToken() function or against the security context of the process for the calling thread. If this parameter is FALSE, the access check is performed using the security context for the calling thread. If the thread is impersonating a client, this security context can be that of a client process. If this parameter is TRUE, the access check is made using the security context of the process for the calling thread. TokenHandle - [out] Pointer to a variable that receives the handle to the newly opened access token. |
|
Return value |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). If the token has the anonymous impersonation level, the token will not be opened and OpenThreadToken() sets ERROR_CANT_OPEN_ANONYMOUS as the error. |
|
Include file |
<windows.h> |
|
Remark |
Close the access token handle returned through the TokenHandle parameter by calling CloseHandle(). |
|
Table 6 |
|
The OpenAsSelf parameter allows the caller of the API to open the access token of a specified thread when the caller is impersonating a token at SecurityIdentification level. Without this parameter, the calling thread cannot open the access token on the specified thread because it is impossible to open executive-level objects using the SecurityIdentification impersonation level. Tokens with the anonymous impersonation level cannot be opened.
|
Item |
Description |
|
Function |
GetCurrentProcess(). |
|
Use |
To retrieve a pseudo handle for the current process. |
|
Prototype |
HANDLE GetCurrentProcess(void); |
|
Parameters |
This function has no parameters. |
|
Return value |
The return value is a pseudo handle to the current process. |
|
Include file |
<windows.h> |
|
Remark |
|
|
Table 7 |
|
A pseudo handle is a special constant, currently (HANDLE)-1, that is interpreted as the current process handle. For compatibility with future operating systems, it is best to call GetCurrentProcess() instead of hard-coding this constant value. The calling process can use a pseudo handle to specify its own process whenever a process handle is required. Pseudo handles are not inherited by child processes. This handle has the maximum possible access to the process object. For systems that support security descriptors, this is the maximum access allowed by the security descriptor for the calling process. For systems that do not support security descriptors, this is PROCESS_ALL_ACCESS. A process can create a "real" handle to itself that is valid in the context of other processes, or that can be inherited by other processes, by specifying the pseudo handle as the source handle in a call to the DuplicateHandle() function. A process can also use the OpenProcess() function to open a real handle to itself. The pseudo handle need not be closed when it is no longer needed. Calling the CloseHandle() function with a pseudo handle has no effect. If the pseudo handle is duplicated by DuplicateHandle(), the duplicate handle must be closed.
|
Item |
Description |
|
Function |
SetTokenInformation(). |
|
Use |
To set various types of information for a specified access token. The information that this function sets replaces existing information. The calling process must have appropriate access rights to set the information. |
|
Prototype |
BOOL SetTokenInformation( HANDLE TokenHandle, TOKEN_INFORMATION_CLASS TokenInformationClass, LPVOID TokenInformation, DWORD TokenInformationLength ); |
|
Parameters |
TokenHandle - [in] Handle to the access token for which information is to be set. TokenInformationClass - [in] Specifies a value from the TOKEN_INFORMATION_CLASS enumerated type identifying the type of information the function sets. The valid values from TOKEN_INFORMATION_CLASS are described in the TokenInformation parameter. TokenInformation - [in] Pointer to a buffer containing the information set in the access token. The structure of this buffer depends on the type of information specified by the TokenInformationClass parameter. The following values are valid in calls to this function:
TokenInformationLength - [in] Specifies the length, in bytes, of the buffer pointed to by TokenInformation. |
|
Return value |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
- |
|
Table 8 |
|
To set privilege information, an application can call the AdjustTokenPrivileges() function. To set a token's groups, an application can call the AdjustTokenGroups() function. Token-type information can be set only when an access token is created.
|
Item |
Description |
|
Function |
LogonUser(). |
|
Use |
To attempt to log a user on to the local computer. |
|
Prototype |
BOOL LogonUser( LPTSTR lpszUsername, LPTSTR lpszDomain, LPTSTR lpszPassword, DWORD dwLogonType, DWORD dwLogonProvider, PHANDLE phToken ); |
|
Parameters |
See below. |
|
Return value |
If the function succeeds, the function returns nonzero. If the function fails, it returns zero. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
Implemented as Unicode and ANSI versions. |
|
Table 9 |
|
The local computer is the computer from which LogonUser() was called. You cannot use LogonUser() to log on to a remote computer. You specify the user with a user name and domain, and authenticate the user with a plaintext password. If the function succeeds, you receive a handle to a token that represents the logged-on user. You can then use this token handle to impersonate the specified user or, in most cases, to create a process that runs in the context of the specified user.
lpszUsername - [in] Pointer to a null-terminated string that specifies the name of the user. This is the name of the user account to log on to. If you use the user principal name (UPN) format, user@DNS_domain_name, the lpszDomain parameter must be NULL. The user account must have Log On Locally permission on the local computer. This permission is granted to all users on workstations and servers but only to administrators on domain controllers.
lpszDomain - [in] Pointer to a null-terminated string that specifies the name of the domain or server whose account database contains the lpszUsername account. If this parameter is NULL, the user name must be specified in UPN format. If this parameter is ".", the function validates the account using only the local account database.
lpszPassword - [in] Pointer to a null-terminated string that specifies the plaintext password for the user account specified by lpszUsername. When you have finished using the password, clear the password from memory by calling the SecureZeroMemory() function.
dwLogonType - [in] Specifies the type of logon operation to perform. This parameter can be one of the following values.
|
Value |
Meaning |
|
LOGON32_LOGON_BATCH |
This logon type is intended for batch servers, where processes may be executing on behalf of a user without their direct intervention. This type is also for higher performance servers that process many plaintext authentication attempts at a time, such as mail or Web servers. The LogonUser() function does not cache credentials for this logon type. |
|
LOGON32_LOGON_INTERACTIVE |
This logon type is intended for users who will be interactively using the computer, such as a user being logged on by a terminal server, remote shell, or similar process. This logon type has the additional expense of caching logon information for disconnected operations; therefore, it is inappropriate for some client/server applications, such as a mail server. |
|
LOGON32_LOGON_NETWORK |
This logon type is intended for high performance servers to authenticate plaintext passwords. The LogonUser() function does not cache credentials for this logon type. |
|
LOGON32_LOGON_NETWORK_CLEARTEXT |
This logon type preserves the name and password in the authentication package, which allows the server to make connections to other network servers while impersonating the client. A server can accept plaintext credentials from a client, call LogonUser(), verify that the user can access the system across the network, and still communicate with other servers. |
|
LOGON32_LOGON_NEW_CREDENTIALS |
This logon type allows the caller to clone its current token and specify new credentials for outbound connections. The new logon session has the same local identifier but uses different credentials for other network connections. This logon type is supported only by the LOGON32_PROVIDER_WINNT50 logon provider. |
|
LOGON32_LOGON_SERVICE |
Indicates a service-type logon. The account provided must have the service privilege enabled. |
|
LOGON32_LOGON_UNLOCK |
This logon type is for GINA DLLs that log on users who will be interactively using the computer. This logon type can generate a unique audit record that shows when the workstation was unlocked. |
|
Table 10 |
|
GINA
A Graphical Identification and Authentication dynamic-link library (DLL). The GINA is a replaceable DLL component that is loaded by the Winlogon executable. The GINA implements the authentication policy of the interactive logon model and is expected to perform all identification and authentication user interactions.
dwLogonProvider - [in] Specifies the logon provider. This parameter can be one of the following values.
|
Value |
Meaning |
|
LOGON32_PROVIDER_DEFAULT |
Use the standard logon provider for the system. The default security provider is negotiate, unless you pass NULL for the domain name and the user name is not in UPN format. In this case, the default provider is NTLM. For Windows 2000, Windows NT, the default security provider is NTLM. |
|
LOGON32_PROVIDER_WINNT50 |
Use the negotiate logon provider. For Windows NT, this value is not supported. |
|
LOGON32_PROVIDER_WINNT40 |
Use the NTLM logon provider. |
|
LOGON32_PROVIDER_WINNT35 |
Use the Windows NT 3.5 logon provider. |
|
Table 11 |
|
phToken - [out] Pointer to a handle variable that receives a handle to a token that represents the specified user. You can use the returned handle in calls to the ImpersonateLoggedOnUser() function. In most cases, the returned handle is a primary token that you can use in calls to the CreateProcessAsUser() function. However, if you specify the LOGON32_LOGON_NETWORK flag, LogonUser() returns an impersonation token that you cannot use in CreateProcessAsUser() unless you call DuplicateTokenEx() to convert it to a primary token. When you no longer need this handle, close it by calling the CloseHandle() function. The LOGON32_LOGON_NETWORK logon type is fastest, but it has the following limitations:
The function returns an impersonation token, not a primary token. You cannot use this token directly in the CreateProcessAsUser() function. However, you can call the DuplicateTokenEx() function to convert the token to a primary token, and then use it in CreateProcessAsUser().
If you convert the token to a primary token and use it in CreateProcessAsUser() to start a process, the new process cannot access other network resources, such as remote servers or printers, through the redirector. An exception is that if the network resource is not access controlled, then the new process will be able to access it.
The SE_TCB_NAME privilege is not required for this function unless you are logging onto a Passport account. For Windows 2000, the process calling LogonUser() requires the SE_TCB_NAME privilege. If the calling process does not have this privilege, LogonUser() fails and GetLastError() returns ERROR_PRIVILEGE_NOT_HELD. In some cases, the process that calls LogonUser() must also have the SE_CHANGE_NOTIFY_NAME privilege enabled; otherwise, LogonUser() fails and GetLastError() returns ERROR_ACCESS_DENIED. This privilege is not required for the local system account or accounts that are members of the administrators group. By default, SE_CHANGE_NOTIFY_NAME is enabled for all users, but some administrators may disable it for everyone. The account being logged on, that is, the account specified by lpszUsername, must have the necessary account rights. For example, to log on a user with the LOGON32_LOGON_INTERACTIVE flag, the user (or a group to which the user belongs) must have the SE_INTERACTIVE_LOGON_NAME account right. A user is considered logged on if at least one token exists. If you call CreateProcessAsUser() and then close the token, the system considers the user as still logged on until the process (and all child processes) have ended. If the LogonUser() call is successful, the system notifies network providers that the logon occurred by calling the provider's NPLogonNotify entry-point function.
|
Item |
Description |
|
Function |
CreateProcessAsUser(). |
|
Use |
To create a new process and its primary thread. |
|
Prototype |
BOOL CreateProcessAsUser( HANDLE hToken, LPCTSTR lpApplicationName, LPTSTR lpCommandLine, LPSECURITY_ATTRIBUTES lpProcessAttributes, LPSECURITY_ATTRIBUTES lpThreadAttributes, BOOL bInheritHandles, DWORD dwCreationFlags, LPVOID lpEnvironment, LPCTSTR lpCurrentDirectory, LPSTARTUPINFO lpStartupInfo, LPPROCESS_INFORMATION lpProcessInformation ); |
|
Parameters |
See below. |
|
Return value |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
Implemented as Unicode and ANSI versions. |
|
Table 12 |
|
hToken - [in] Handle to a primary token that represents a user. The handle must have the TOKEN_QUERY, TOKEN_DUPLICATE, and TOKEN_ASSIGN_PRIMARY access rights. The user represented by the token must have read and execute access to the application specified by the lpApplicationName or the lpCommandLine parameter. To get a primary token that represents the specified user, call the LogonUser() function. Alternatively, you can call the DuplicateTokenEx() function to convert an impersonation token into a primary token. This allows a server application that is impersonating a client to create a process that has the security context of the client. Terminal Services: The process is run in the session specified in the token. By default, this is the same session that called LogonUser(). To change the session, use the SetTokenInformation() function.
lpApplicationName - [in] Pointer to a null-terminated string that specifies the module to execute. The specified module can be a Windows-based application. It can be some other type of module (for example, MS-DOS or OS/2) if the appropriate subsystem is available on the local computer. The string can specify the full path and file name of the module to execute or it can specify a partial name. In the case of a partial name, the function uses the current drive and current directory to complete the specification. The function will not use the search path. If the file name does not contain an extension, .exe is assumed. Therefore, if the file name extension is .com, this parameter must include the .com extension. The lpApplicationName parameter can be NULL. In that case, the module name must be the first white space-delimited token in the lpCommandLine string. If you are using a long file name that contains a space, use quoted strings to indicate where the file name ends and the arguments begin; otherwise, the file name is ambiguous. For example, consider the string "c:\program files\sub dir\program name". This string can be interpreted in a number of ways. The system tries to interpret the possibilities in the following order:
c:\program.exe files\sub dir\program name
c:\program files\sub.exe dir\program name
c:\program files\sub dir\program.exe name
c:\program files\sub dir\program name.exe
If the executable module is a 16-bit application, lpApplicationName should be NULL, and the string pointed to by lpCommandLine should specify the executable module as well as its arguments. By default, all 16-bit Windows-based applications created by CreateProcessAsUser() are run in a separate VDM (equivalent to CREATE_SEPARATE_WOW_VDM in CreateProcess()).
lpCommandLine - [in] Pointer to a null-terminated string that specifies the command line to execute. The maximum length of this string is 32,000 characters. For Windows 2000: The maximum length of this string is MAX_PATH characters. The Unicode version of this function, CreateProcessAsUserW(), will fail if this parameter is a const string. The lpCommandLine parameter can be NULL. In that case, the function uses the string pointed to by lpApplicationName as the command line. If both lpApplicationName and lpCommandLine are non-NULL, *lpApplicationName specifies the module to execute, and *lpCommandLine specifies the command line. The new process can use GetCommandLine() to retrieve the entire command line. Console processes written in C can use the argc and argv arguments to parse the command line. Because argv[0] is the module name, C programmers generally repeat the module name as the first token in the command line. If lpApplicationName is NULL, the first white-space, delimited token of the command line specifies the module name. If you are using a long file name that contains a space: use quoted strings to indicate where the file name ends and the arguments begin (see the explanation for the lpApplicationName parameter). If the file name does not contain an extension, .exe is appended. Therefore, if the file name extension is .com, this parameter must include the .com extension. If the file name ends in a period (.) with no extension, or if the file name contains a path, .exe is not appended. If the file name does not contain a directory path, the system searches for the executable file in the following sequence:
The directory from which the application loaded.
The current directory for the parent process.
The 32-bit Windows system directory. Use the GetSystemDirectory() function to get the path of this directory.
The 16-bit Windows system directory. There is no function that obtains the path of this directory, but it is searched.
The Windows directory. Use the GetWindowsDirectory() function to get the path of this directory.
The directories that are listed in the PATH environment variable.
The system adds a null character to the command line string to separate the file name from the arguments. This divides the original string into two strings for internal processing.
lpProcessAttributes - [in] Pointer to a SECURITY_ATTRIBUTES structure that specifies a security descriptor for the new process and determines whether child processes can inherit the returned handle. If lpProcessAttributes is NULL or lpSecurityDescriptor is NULL, the process gets a default security descriptor and the handle cannot be inherited. The default security descriptor is that of the user referenced in the hToken parameter. This security descriptor may not allow access for the caller, in which case the process may not be opened again after it is run. The process handle is valid and will continue to have full access rights.
lpThreadAttributes - [in] Pointer to a SECURITY_ATTRIBUTES structure that specifies a security descriptor for the new process and determines whether child processes can inherit the returned handle. If lpThreadAttributes is NULL or lpSecurityDescriptor is NULL, the thread gets a default security descriptor and the handle cannot be inherited. The default security descriptor is that of the user referenced in the hToken parameter. This security descriptor may not allow access for the caller.
bInheritHandles - [in] If this parameter is TRUE, each inheritable handle in the calling process is inherited by the new process. If the parameter is FALSE, the handles are not inherited. Note that inherited handles have the same value and access rights as the original handles. For Terminal Services: You cannot inherit handles across sessions. Additionally, if this parameter is TRUE, you must create the process in the same session as the caller.
dwCreationFlags - [in] Flags that control the priority class and the creation of the process. This parameter also controls the new process's priority class, which is used to determine the scheduling priorities of the process's threads. If none of the priority class flags is specified, the priority class defaults to NORMAL_PRIORITY_CLASS unless the priority class of the creating process is IDLE_PRIORITY_CLASS or BELOW_NORMAL_PRIORITY_CLASS. In this case, the child process receives the default priority class of the calling process.
lpEnvironment - [in] Pointer to an environment block for the new process. If this parameter is NULL, the new process uses the environment of the calling process. An environment block consists of a null-terminated block of null-terminated strings. Each string is in the form: name = value. Because the equal sign is used as a separator, it must not be used in the name of an environment variable. An environment block can contain either Unicode or ANSI characters. If the environment block pointed to by lpEnvironment contains Unicode characters, be sure that dwCreationFlags includes CREATE_UNICODE_ENVIRONMENT. Note that an ANSI environment block is terminated by two zero bytes: one for the last string, one more to terminate the block. A Unicode environment block is terminated by four zero bytes: two for the last string, two more to terminate the block. To retrieve a copy of the environment block for a given user, use the CreateEnvironmentBlock() function.
lpCurrentDirectory - [in] Pointer to a null-terminated string that specifies the full path to the current directory for the process. The string can also specify a UNC path. If this parameter is NULL, the new process will have the same current drive and directory as the calling process (This feature is provided primarily for shells that need to start an application and specify its initial drive and working directory).
lpStartupInfo - [in] Pointer to a STARTUPINFO structure that specifies the window station, desktop, standard handles, and appearance of the main window for the new process.
lpProcessInformation - [out] Pointer to a PROCESS_INFORMATION structure that receives identification information about the new process. Handles in PROCESS_INFORMATION must be closed with CloseHandle() when they are no longer needed. The new process then runs the specified executable file. The CreateProcessAsUser() function is similar to the CreateProcess() function, except that the new process runs in the security context of the user represented by the hToken parameter. By default, the new process is non-interactive, that is, it runs on a desktop that is not visible and cannot receive user input. Also, by default, the new process inherits the environment of the calling process, rather than the environment associated with the specified user. The CreateProcessWithLogonW() and CreateProcessWithTokenW() functions are similar to CreateProcessAsUser(), except that the caller does not need to call the LogonUser() function to authenticate the user and get a token. This function is also similar to the SHCreateProcessAsUserW() function. Typically, the process that calls the CreateProcessAsUser() function must have the SE_ASSIGNPRIMARYTOKEN_NAME and SE_INCREASE_QUOTA_NAME privileges. However, if hToken is a restricted version of the caller's primary token, the SE_ASSIGNPRIMARYTOKEN_NAME privilege is not required. If the necessary privileges are not already enabled, CreateProcessAsUser() enables them for the duration of the call. CreateProcessAsUser() must be able to open the primary token of the calling process with the TOKEN_DUPLICATE and TOKEN_IMPERSONATE access rights. By default, CreateProcessAsUser() creates the new process on a non-interactive window station with a desktop that is not visible and cannot receive user input. To enable user interaction with the new process, you must specify the name of the default interactive window station and desktop, "winsta0\default", in the lpDesktop member of the STARTUPINFO structure. In addition, before calling CreateProcessAsUser(), you must change the discretionary access control list (DACL) of both the default interactive window station and the default desktop. The DACLs for the window station and desktop must grant access to the user or the logon session represented by the hToken parameter. CreateProcessAsUser() does not load the specified user's profile into the HKEY_USERS registry key. Therefore, to access the information in the HKEY_CURRENT_USER registry key, you must load the user's profile information into HKEY_USERS with the LoadUserProfile() function before calling CreateProcessAsUser(). If the lpEnvironment parameter is NULL, the new process inherits the environment of the calling process. CreateProcessAsUser() does not automatically modify the environment block to include environment variables specific to the user represented by hToken. For example, the USERNAME and USERDOMAIN variables are inherited from the calling process if lpEnvironment is NULL. It is your responsibility to prepare the environment block for the new process and specify it in lpEnvironment.
CreateProcessAsUser() allows you to access the specified directory and executable image in the security context of the caller or the target user. By default, CreateProcessAsUser() 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. To access the directory and executable image using the security context of the target user, specify hToken in a call to the ImpersonateLoggedOnUser() function before calling CreateProcessAsUser(). The process is assigned a process identifier. The identifier is valid until the process terminates. It can be used to identify the process, or specified in the OpenProcess() function to open a handle to the process. The initial thread in the process is also assigned a thread identifier. It can be specified in the OpenThread() function to open a handle to the thread. The identifier is valid until the thread terminates and can be used to uniquely identify the thread within the system. These identifiers are returned in the PROCESS_INFORMATION structure. The calling thread can use the WaitForInputIdle() function to wait until the new process has finished its initialization and is waiting for user input with no input pending. This can be useful for synchronization between parent and child processes, because CreateProcessAsUser returns without waiting for the new process to finish its initialization. For example, the creating process would use WaitForInputIdle() before trying to find a window associated with the new process.
The preferred way to shut down a process is by using the ExitProcess() function, because this function sends notification of approaching termination to all DLLs attached to the process. Other means of shutting down a process do not notify the attached DLLs. Note that when a thread calls ExitProcess(), other threads of the process are terminated without an opportunity to execute any additional code (including the thread termination code of attached DLLs).
Security Remarks: The lpApplicationName parameter can be NULL, in which case the executable name must be the first white space-delimited string in lpCommandLine. If the executable or path name has a space in it, there is a risk that a different executable could be run because of the way the function parses spaces. The following example is dangerous because the function will attempt to run "Program.exe", if it exists, instead of "MyApp.exe":
CreateProcessAsUser(hToken, NULL, "C:\\Program Files\\MyApp", ...)
If a malicious user were to create an application called "Program.exe" on a system, any program that incorrectly calls CreateProcessAsUser() using the Program Files directory will run this application instead of the intended application. To avoid this problem, do not pass NULL for lpApplicationName. If you do pass NULL for lpApplicationName, use quotation marks around the executable path in lpCommandLine, as shown in the example below:
CreateProcessAsUser(hToken, NULL, "\"C:\\Program Files\\MyApp.exe\" -L -S", ...)
ConvertStringSecurityDescriptorToSecurityDescriptor()
|
Item |
Description |
|
Function |
ConvertStringSecurityDescriptorToSecurityDescriptor(). |
|
Use |
To convert a string-format security descriptor into a valid, functional security descriptor. This function retrieves a security descriptor that the ConvertSecurityDescriptorToStringSecurityDescriptor() function converted to string format. |
|
Prototype |
BOOL ConvertStringSecurityDescriptorToSecurityDescriptor( LPCTSTR StringSecurityDescriptor, DWORD StringSDRevision, PSECURITY_DESCRIPTOR* SecurityDescriptor, PULONG SecurityDescriptorSize ); |
|
Parameters |
StringSecurityDescriptor - [in] Pointer to a null-terminated string containing the string-format security descriptor to convert. StringSDRevision - [in] Specifies the revision level of the StringSecurityDescriptor string. Currently this value must be SDDL_REVISION_1. SecurityDescriptor - [out] Pointer to a variable that receives a pointer to the converted security descriptor. The returned security descriptor is self-relative. To free the returned buffer, call the LocalFree() function. To convert the security descriptor to an absolute security descriptor, use the MakeAbsoluteSD() function. SecurityDescriptorSize - [out] Pointer to a variable that receives the size, in bytes, of the converted security descriptor. This parameter can be NULL. |
|
Return value |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). GetLastError() may return one of the following error codes:
|
|
Include file |
<sddl.h> |
|
Remark |
If ace_type is ACCESS_ALLOWED_OBJECT_ACE_TYPE and neither object_guid nor inherit_object_guid has a GUID specified, then ConvertStringSecurityDescriptorToSecurityDescriptor() converts ace_type to ACCESS_ALLOWED_ACE_TYPE. Implemented as Unicode and ANSI versions. |
|
Table 13 |
|
ConvertSecurityDescriptorToStringSecurityDescriptor()
|
Item |
Description |
|
Function |
ConvertSecurityDescriptorToStringSecurityDescriptor(). |
|
Use |
To convert a security descriptor to a string format. You can use the string format to store or transmit the security descriptor. To convert the string-format security descriptor back to a valid, functional security descriptor, call the ConvertStringSecurityDescriptorToSecurityDescriptor() function. |
|
Prototype |
BOOL ConvertSecurityDescriptorToStringSecurityDescriptor( PSECURITY_DESCRIPTOR SecurityDescriptor, DWORD RequestedStringSDRevision, SECURITY_INFORMATION SecurityInformation, LPTSTR* StringSecurityDescriptor, PULONG StringSecurityDescriptorLen ); |
|
Parameters |
SecurityDescriptor - [in] Pointer to the security descriptor to convert. The security descriptor can be in absolute or self-relative format. RequestedStringSDRevision - [in] Specifies the revision level of the output StringSecurityDescriptor string. Currently this value must be SDDL_REVISION_1. SecurityInformation - [in] Specifies a combination of the following SECURITY_INFORMATION bit flags to indicate the components of the security descriptor to include in the output string.
StringSecurityDescriptor - [out] Pointer to a variable that receives a pointer to a null-terminated security descriptor string. To free the returned buffer, call the LocalFree() function. StringSecurityDescriptorLen - [out] Pointer to a variable that receives the size, in TCHARs, of the security descriptor string returned in the StringSecurityDescriptor buffer. This parameter can be NULL if you do not need to retrieve the size. |
|
Return value |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). The GetLastError() function may return one of the following error codes:
|
|
Include file |
<sddl.h> |
|
Remark |
If the DACL is NULL, and the SE_DACL_PRESENT control bit is set in the input security descriptor, the function fails. If the DACL is NULL, and the SE_DACL_PRESENT control bit is not set in the input security descriptor, the resulting security descriptor string does not have a D: component. Implemented as Unicode and ANSI versions. |
|
Table 14 |
|
|
Item |
Description |
|
Function |
GlobalAlloc(). |
|
Use |
To allocate the specified number of bytes from the heap. Windows memory management does not provide a separate local heap and global heap. The global functions are slower than other memory management functions and do not provide as many features. Therefore, new applications should use the heap functions. However, the global functions are still used with DDE, the clipboard functions, and OLE data objects. |
|
Prototype |
HGLOBAL GlobalAlloc(UINT uFlags, SIZE_T dwBytes); |
|
Parameters |
See below. |
|
Return value |
If the function succeeds, the return value is a handle to the newly allocated memory object. If the function fails, the return value is NULL. To get extended error information, call GetLastError(). |
|
Include file |
<sddl.h> |
|
Remark |
To free the memory, use the GlobalFree() function. |
|
Table 15 |
|
uFlags - [in] Memory allocation attributes. If zero is specified, the default is GMEM_FIXED. This parameter can be one or more of the following values, except for the incompatible combinations that are specifically noted.
|
Value |
Meaning |
|
GHND |
Combines GMEM_MOVEABLE and GMEM_ZEROINIT. |
|
GMEM_FIXED |
To allocate fixed memory. The return value is a pointer. |
|
GMEM_MOVEABLE |
Allocates movable memory. Memory blocks are never moved in physical memory, but they can be moved within the default heap. The return value is a handle to the memory object. To translate the handle into a pointer, use the GlobalLock() function. This value cannot be combined with GMEM_FIXED. |
|
GMEM_ZEROINIT |
Initializes memory contents to zero. |
|
GPTR |
Combines GMEM_FIXED and GMEM_ZEROINIT. |
|
Table 16 |
|
The following values are obsolete, but are provided for compatibility with 16-bit Windows. They are ignored.
GMEM_DDESHARE
GMEM_DISCARDABLE
GMEM_LOWER
GMEM_NOCOMPACT
GMEM_NODISCARD
GMEM_NOT_BANKED
GMEM_NOTIFY
GMEM_SHARE
dwBytes - [in] Number of bytes to allocate. If this parameter is zero and the uFlags parameter specifies GMEM_MOVEABLE, the function returns a handle to a memory object that is marked as discarded. If this function succeeds, it allocates at least the amount of memory requested. If the actual amount allocated is greater than the amount requested, the process can use the entire amount. To determine the actual number of bytes allocated, use the GlobalSize() function. If the heap does not contain sufficient free space to satisfy the request, GlobalAlloc() returns NULL. Because NULL is used to indicate an error, virtual address zero is never allocated. It is, therefore, easy to detect the use of a NULL pointer. Memory allocated with this function is guaranteed to be aligned on an 8-byte boundary. To execute dynamically generated code, use the VirtualAlloc() function to allocate memory and the VirtualProtect() function to grant PAGE_EXECUTE access.
LocalFree()
|
Item |
Description |
|
Function |
LocalFree(). |
|
Use |
To free the specified local memory object and invalidates its handle. The local functions are slower than other memory management functions and do not provide as many features. Therefore, new applications should use the heap functions. |
|
Prototype |
HLOCAL LocalFree(HLOCAL hMem); |
|
Parameters |
hMem - [in] Handle to the local memory object. This handle is returned by either the LocalAlloc() or LocalReAlloc() function. |
|
Return value |
If the function succeeds, the return value is NULL. If the function fails, the return value is equal to a handle to the local memory object. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
- |
|
Table 17 |
|
If the process tries to examine or modify the memory after it has been freed, heap corruption may occur or an access violation exception (EXCEPTION_ACCESS_VIOLATION) may be generated. If the hMem parameter is NULL, LocalFree() ignores the parameter and returns NULL. The LocalFree() function will free a locked memory object. A locked memory object has a lock count greater than zero. The LocalLock() function locks a local memory object and increments the lock count by one. The LocalUnlock() function unlocks it and decrements the lock count by one. To get the lock count of a local memory object, use the LocalFlags() function. If an application is running under a debug version of the system, LocalFree() will issue a message that tells you that a locked object is being freed. If you are debugging the application, LocalFree() will enter a breakpoint just before freeing a locked object. This allows you to verify the intended behavior, and then continue execution.
LocalReAlloc()
|
Item |
Description |
|
Function |
LocalReAlloc(). |
|
Use |
To change the size or the attributes of a specified local memory object. The size can increase or decrease. |
|
Prototype |
HLOCAL LocalReAlloc( HLOCAL hMem, SIZE_T uBytes, UINT uFlags ); |
|
Parameters |
hMem - [in] Handle to the local memory object to be reallocated. This handle is returned by either the LocalAlloc() or LocalReAlloc() function. uBytes - [in] New size of the memory block, in bytes. If uFlags specifies LMEM_MODIFY, this parameter is ignored. uFlags - [in] If LMEM_MODIFY is specified, this parameter modifies the attributes of the memory object, and the uBytes parameter is ignored. Otherwise, this parameter controls the reallocation of the memory object. If this parameter does not specify LMEM_MODIFY, this parameter can be one or more of the following values:
|
|
Return value |
If the function succeeds, the return value is a handle to the reallocated memory object. If the function fails, the return value is NULL. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
If LocalReAlloc() fails, the original memory is not freed, and the original handle and pointer are still valid. If LocalReAlloc() reallocates a fixed object, the value of the handle returned is the address of the first byte of the memory block. To access the memory, a process can simply cast the return value to a pointer. |
|
Table 18 |
|
LocalAlloc()
|
Item |
Description |
|
Function |
LocalAlloc(). |
|
Use |
To allocate the specified number of bytes from the heap. Windows memory management does not provide a separate local heap and global heap. |
|
Prototype |
HLOCAL LocalAlloc(UINT uFlags, SIZE_T uBytes); |
|
Parameters |
uFlags - [in] Memory allocation attributes. The default is the LMEM_FIXED value. This parameter can be one or more of the following values, except for the incompatible combinations that are specifically noted.
The following values are obsolete, but are provided for compatibility with 16-bit Windows. They are ignored.
uBytes - [in] Number of bytes to allocate. If this parameter is zero and the uFlags parameter specifies LMEM_MOVEABLE, the function returns a handle to a memory object that is marked as discarded. |
|
Return value |
If the function succeeds, the return value is a handle to the newly allocated memory object. If the function fails, the return value is NULL. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
To free the memory, use the LocalFree() function. |
|
Table 19 |
|
If the heap does not contain sufficient free space to satisfy the request, LocalAlloc() returns NULL. Because NULL is used to indicate an error, virtual address zero is never allocated. It is, therefore, easy to detect the use of a NULL pointer. If this function succeeds, it allocates at least the amount requested. If the amount allocated is greater than the amount requested, the process can use the entire amount. To determine the actual number of bytes allocated, use the LocalSize() function.
GetNamedSecurityInfo()
|
Item |
Description |
|
Function |
GetNamedSecurityInfo(). |
|
Use |
To retrieve a copy of the security descriptor for an object specified by name. |
|
Prototype |
DWORD GetNamedSecurityInfo( LPTSTR pObjectName, SE_OBJECT_TYPE ObjectType, SECURITY_INFORMATION SecurityInfo, PSID* ppsidOwner, PSID* ppsidGroup, PACL* ppDacl, PACL* ppSacl, PSECURITY_DESCRIPTOR* ppSecurityDescriptor ); |
|
Parameters |
pObjectName - [in] Pointer to a null-terminated string that specifies the name of the object from which to retrieve security information. ObjectType - [in] Specifies a value from the SE_OBJECT_TYPE enumeration that indicates the type of object named by the pObjectName parameter. SecurityInfo - [in] A set of SECURITY_INFORMATION bit flags that indicate the type of security information to retrieve. This parameter can be a combination of the following values:
ppsidOwner - [out] Pointer to a variable that receives a pointer to the owner SID in the security descriptor returned in ppSecurityDescriptor. The returned pointer is valid only if you set the OWNER_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the owner SID. ppsidGroup - [out] Pointer to a variable that receives a pointer to the primary group SID in the returned security descriptor. The returned pointer is valid only if you set the GROUP_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the group SID. ppDacl - [out] Pointer to a variable that receives a pointer to the DACL in the returned security descriptor. The returned pointer is valid only if you set the DACL_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the DACL. ppSacl - [out] Pointer to a variable that receives a pointer to the SACL in the returned security descriptor. The returned pointer is valid only if you set the SACL_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the SACL. ppSecurityDescriptor - [out] Pointer to a variable that receives a pointer to the security descriptor of the object. When you have finished using the pointer, free the returned buffer by calling the LocalFree() function. |
|
Return value |
If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in winerror.h. |
|
Include file |
<aclapi.h> |
|
Remark |
Implemented as Unicode and ANSI versions. |
|
Table 20 |
|
|
If the ppsidOwner, ppsidGroup, ppDacl, and ppSacl parameters are non-NULL, and the SecurityInfo parameter specifies that they be retrieved from the object, those parameters will point to the corresponding parameters in the security descriptor returned in ppSecurityDescriptor. To read the owner, group, or DACL from the object's security descriptor, the object's DACL must grant READ_CONTROL access to the caller, or the caller must be the owner of the object. To read the system access control list of the object, the SE_SECURITY_NAME privilege must be enabled for the calling process. You can use the GetNamedSecurityInfo() function with the following types of objects:
|
This function does not handle race conditions. If your thread calls this function at the approximate time that another thread changes the object's security descriptor, then this function could fail. This function transfers information in plaintext. The information transferred by this function is signed unless signing has been turned off for the system, but no encryption is performed. For Windows 2000 SP2 and earlier, Windows NT, the information transferred by this function is unsigned.
SetEntriesInAcl()
|
Item |
Description |
|
Function |
SetEntriesInAcl(). |
|
Use |
To create a new access control list (ACL) by merging new access control or audit control information into an existing ACL. |
|
Prototype |
DWORD SetEntriesInAcl( ULONG cCountOfExplicitEntries, PEXPLICIT_ACCESS pListOfExplicitEntries, PACL OldAcl, PACL* NewAcl ); |
|
Parameters |
cCountOfExplicitEntries - [in] Specifies the number of EXPLICIT_ACCESS structures in the pListOfExplicitEntries array. pListOfExplicitEntries - [in] Pointer to an array of EXPLICIT_ACCESS structures that describe the access control information to merge into the existing ACL. OldAcl - [in] Pointer to the existing ACL. This parameter can be NULL, in which case, the function creates a new ACL based on the EXPLICIT_ACCESS entries. NewAcl - [out] Pointer to a variable that receives a pointer to the new ACL. If the function succeeds, you must call the LocalFree() function to free the returned buffer. |
|
Return value |
If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in winerror.h. |
|
Include file |
<aclapi.h> |
|
Remark |
Implemented as Unicode and ANSI versions. |
|
Table 21 |
|
Each entry in the array of EXPLICIT_ACCESS structures specifies access control or audit control information for a specified trustee. A trustee can be a user, group, or other SID value, such as a logon identifier or logon type (for instance, a Windows service or batch job). You can use a name or a security identifier (SID) to identify a trustee. You can use the SetEntriesInAcl() function to modify the list of ACEs in a discretionary access control list (DACL) or a system access control list (SACL). Note that SetEntriesInAcl() does not prevent you from mixing access control and audit control information in the same ACL; however, the resulting ACL will contain meaningless entries. For a DACL, the grfAccessMode member of the EXPLICIT_ACCESS structure specifies whether to allow, deny, or revoke access rights for the trustee. This member can specify one of the following values:
GRANT_ACCESS
SET_ACCESS
DENY_ACCESS
REVOKE_ACCESS
The SetEntriesInAcl() function places any new access-denied ACEs at the beginning of the list of ACEs for the new ACL. This function places any new access-allowed ACEs just before any existing access-allowed ACEs. For a SACL, the grfAccessMode member of the EXPLICIT_ACCESS structure can specify the following values:
REVOKE_ACCESS
SET_AUDIT_FAILURE
SET_AUDIT_SUCCESS
SET_AUDIT_FAILURE and SET_AUDIT_SUCCESS can be combined. The SetEntriesInAcl() function places any new system-audit ACEs at the beginning of the list of ACEs for the new ACL.
SetNamedSecurityInfo()
|
Item |
Description |
|
Function |
SetNamedSecurityInfo(). |
|
Use |
To set specified security information in the security descriptor of a specified object. The caller identifies the object by name. |
|
Prototype |
DWORD SetNamedSecurityInfo( LPTSTR pObjectName, SE_OBJECT_TYPE ObjectType, SECURITY_INFORMATION SecurityInfo, PSID psidOwner, PSID psidGroup, PACL pDacl, PACL pSacl ); |
|
Parameters |
pObjectName - [in] Pointer to a null-terminated string that specifies the name of the object for which to set security information. This can be the name of a local or remote file or directory on an NTFS file system, network share, registry key, semaphore, event, mutex, file mapping, or waitable timer. ObjectType - [in] A value of the SE_OBJECT_TYPE enumeration that indicates the type of object named by the pObjectName parameter. SecurityInfo - [in] A set of SECURITY_INFORMATION bit flags that indicate the type of security information to set. This parameter can be a bitwise-OR combination of the following values:
psidOwner - [in] Pointer to a SID structure that identifies the owner of the object. The SID must be one that can be assigned as the owner SID of a security descriptor. The SecurityInfo parameter must include the OWNER_SECURITY_INFORMATION flag. To set the owner, the caller must have WRITE_OWNER access to the object or have the SE_TAKE_OWNERSHIP_NAME privilege enabled. If you are not setting the owner SID, this parameter can be NULL. psidGroup - [in] Pointer to a SID that identifies the primary group of the object. The SecurityInfo parameter must include the GROUP_SECURITY_INFORMATION flag. If you are not setting the primary group SID, this parameter can be NULL. pDacl -[in] Pointer to the new DACL for the object. The SecurityInfo parameter must include the DACL_SECURITY_INFORMATION flag. The caller must have WRITE_DAC access to the object or be the owner of the object. If you are not setting the DACL, this parameter can be NULL. pSacl - [in] Pointer to the new SACL for the object. The SecurityInfo parameter must include the SACL_SECURITY_INFORMATION flag. The caller must have the SE_SECURITY_NAME privilege enabled. If you are not setting the SACL, this parameter can be NULL. |
|
Return value |
If the function succeeds, the function returns ERROR_SUCCESS. If the function fails, it returns a nonzero error code defined in winerror.h. |
|
Include file |
<aclapi.h> |
|
Remark |
Implemented as Unicode and ANSI versions. |
|
Table 22 |
|
If you are setting the DACL or SACL of an object, the system automatically propagates any inheritable ACEs to existing child objects, according to the rules of inheritance. For Windows NT, the system does not automatically propagate inheritable ACEs to existing child objects. You can use the SetNamedSecurityInfo() function with the following types of objects:
Local or remote files or directories on an NTFS.
Local or remote printers.
Local or remote Windows services.
Network shares.
Registry keys.
Semaphores, events, mutexes, and waitable timers.
File-mapping objects.
Directory service objects.
The SetNamedSecurityInfo() function does not reorder access-allowed or access-denied ACEs based on the preferred order. When propagating inheritable ACEs to existing child objects, SetNamedSecurityInfo() puts inherited ACEs in order after all of the non inherited ACEs in the DACLs of the child objects. This function transfers information in plaintext. The information transferred by this function is signed unless signing has been turned off for the system, but no encryption is performed. For Windows 2000 SP2 and earlier, Windows NT, the information transferred by this function is unsigned.
BuildTrusteeWithSid()
|
Item |
Description |
|
Function |
BuildTrusteeWithSid(). |
|
Use |
To initialize a TRUSTEE structure. The caller specifies the security identifier (SID) of the trustee. The function sets other members of the structure to default values and does not look up the name associated with the SID. |
|
Prototype |
VOID BuildTrusteeWithSid(PTRUSTEE pTrustee, PSID pSid); |
|
Parameters |
pTrustee - [in, out] Pointer to a TRUSTEE structure to initialize. The BuildTrusteeWithSid() function does not allocate any memory. If this parameter is NULL or an invalid pointer, the results are undefined. pSid - [in] Pointer to a SID structure that identifies the trustee. The BuildTrusteeWithSid() function assigns this pointer to the ptstrName member of the TRUSTEE structure. The function sets the other members of the TRUSTEE structure as follows:
|
|
Return value |
This function does not return a value. |
|
Include file |
<aclapi.h> |
|
Remark |
Implemented as Unicode and ANSI versions. |
|
Table 23 |
|
BuildTrusteeWithName()
|
Item |
Description |
|
Function |
BuildTrusteeWithName(). |
|
Use |
To initialize a TRUSTEE structure. The caller specifies the trustee name. The function sets other members of the structure to default values. |
|
Prototype |
VOID BuildTrusteeWithName(PTRUSTEE pTrustee, LPTSTR pName); |
|
Parameters |
pTrustee - [in, out] Pointer to a TRUSTEE structure to initialize. The BuildTrusteeWithName() function does not allocate any memory. If this parameter is NULL or an invalid pointer, the results are undefined. pName - [in] Pointer to a null-terminated string that contains the name of the trustee for the ptstrName member of the TRUSTEE structure. The BuildTrusteeWithName() function sets the other members of the TRUSTEE structure as follows:
|
|
Return value |
This function does not return a value. |
|
Include file |
<aclapi.h> |
|
Remark |
Implemented as Unicode and ANSI versions. |
|
Table 24 |
|
GetTrusteeForm()
|
Item |
Description |
|
Function |
GetTrusteeForm(). |
|
Use |
To retrieve the trustee name from the specified TRUSTEE structure. This value indicates whether the structure uses a name string or a security identifier (SID) to identify the trustee. |
|
Prototype |
TRUSTEE_FORM GetTrusteeForm(PTRUSTEE pTrustee); |
|
Parameters |
pTrustee - [in] Pointer to a TRUSTEE structure. |
|
Return value |
The return value is one of the constants from the TRUSTEE_FORM enumeration. |
|
Include file |
<aclapi.h> |
|
Remark |
Implemented as Unicode and ANSI versions. |
|
Table 25 |
|
GetTrusteeName()
|
Item |
Description |
|
Function |
GetTrusteeName(). |
|
Use |
To retrieve the trustee name from the specified TRUSTEE structure. This function does not allocate any memory. |
|
Prototype |
LPTSTR GetTrusteeName(PTRUSTEE pTrustee); |
|
Parameters |
pTrustee - [in] Pointer to a TRUSTEE structure. |
|
Return value |
If the TrusteeForm() member of the TRUSTEE structure is TRUSTEE_IS_NAME, the return value is the pointer assigned to the ptstrName member of the structure. If the TrusteeForm() member is TRUSTEE_IS_SID, the return value is NULL. The function does not look up the name associated with a security identifier (SID). |
|
Include file |
<aclapi.h> |
|
Remark |
Implemented as Unicode and ANSI versions. |
|
Table 26 |
|
GetTrusteeType()
|
Item |
Description |
|
Function |
GetTrusteeType(). |
|
Use |
To retrieve the trustee type from the specified TRUSTEE structure. This value indicates whether the trustee is a user, a group, or the trustee type is unknown. |
|
Prototype |
TRUSTEE_TYPE GetTrusteeType(PTRUSTEE pTrustee); |
|
Parameters |
pTrustee - [in] Pointer to a TRUSTEE structure. |
|
Return value |
The return value is one of the constants from the TRUSTEE_TYPE enumeration. |
|
Include file |
<aclapi.h> |
|
Remark |
Implemented as Unicode and ANSI versions. |
|
Table 27 |
|
LookupPrivilegeName()
|
Item |
Description |
|
Function |
LookupPrivilegeName(). |
|
Use |
To retrieve the name that corresponds to the privilege represented on a specific system by a specified locally unique identifier (LUID). |
|
Prototype |
BOOL LookupPrivilegeName( LPCTSTR lpSystemName, PLUID lpLuid, LPTSTR lpName, LPDWORD cchName ); |
|
Parameters |
lpSystemName - [in] A pointer to a null-terminated string that specifies the name of the system on which the privilege name is retrieved. If a null string is specified, the function attempts to find the privilege name on the local system. lpLuid - [in] A pointer to the LUID by which the privilege is known on the target system. lpName - [out] A pointer to a buffer that receives a null-terminated string that represents the privilege name. For example, this string could be "SeSecurityPrivilege". cchName - [in, out] A pointer to a variable that specifies the size, in a TCHAR value, of the lpName buffer. When the function returns, this parameter contains the length of the privilege name, not including the terminating null character. If the buffer pointed to by the lpName parameter is too small, this variable contains the required size. |
|
Return value |
If the function succeeds, the function returns nonzero. If the function fails, it returns zero. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
Implemented as Unicode and ANSI versions. So, LookupPrivilegeNameW() is Unicode implementation and LookupPrivilegeNameA() is ANSI implementation. |
|
Table 28 |
|
|
Item |
Description |
|
Function |
LookupPrivilegeValue(). |
|
Use |
To retrieve the locally unique identifier (LUID) used on a specified system to locally represent the specified privilege name. |
|
Prototype |
BOOL LookupPrivilegeValue( LPCTSTR lpSystemName, LPCTSTR lpName, PLUID lpLuid ); |
|
Parameters |
lpSystemName - [in] A pointer to a null-terminated string that specifies the name of the system on which the privilege name is retrieved. If a null string is specified, the function attempts to find the privilege name on the local system. lpName - [in] A pointer to a null-terminated string that specifies the name of the privilege, as defined in the winnt.h header file. For example, this parameter could specify the constant, SE_SECURITY_NAME, or its corresponding string, "SeSecurityPrivilege". lpLuid - [out] A pointer to a variable that receives the LUID by which the privilege is known on the system specified by the lpSystemName parameter. |
|
Return value |
If the function succeeds, the function returns nonzero. If the function fails, it returns zero. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
Implemented as Unicode and ANSI versions. So, Implemented as LookupPrivilegeValueW() for Unicode and LookupPrivilegeValueA() for ANSI. |
|
Table 29 |
|
|
Item |
Description |
|
Function |
LookupPrivilegeDisplayName(). |
|
Use |
To retrieve the display name that represents a specified privilege. |
|
Prototype |
BOOL LookupPrivilegeDisplayName( LPCTSTR lpSystemName, LPCTSTR lpName, LPTSTR lpDisplayName, LPDWORD cchDisplayName, LPDWORD lpLanguageId ); |
|
Parameters |
lpSystemName - [in] Pointer to a null-terminated string that specifies the name of the system on which the privilege name is retrieved. If a null string is specified, the function attempts to find the display name on the local system. lpName- [in] Pointer to a null-terminated string that specifies the name of the privilege, as defined in Winnt.h. For example, this parameter could specify the constant, SE_REMOTE_SHUTDOWN_NAME, or its corresponding string, "SeRemoteShutdownPrivilege". lpDisplayName - [out] Pointer to a buffer that receives a null-terminated string that specifies the privilege display name. For example, if the lpName parameter is SE_REMOTE_SHUTDOWN_NAME, the privilege display name is "Force shutdown from a remote system". cchDisplayName - [in, out] Pointer to a variable that specifies the size, in TCHARs, of the lpDisplayName buffer. When the function returns, this parameter contains the length of the privilege display name, not including the terminating null character. If the buffer pointed to by the lpDisplayName parameter is too small, this variable contains the required size. lpLanguageId - [out] Pointer to a variable that receives the language identifier for the returned display name. |
|
Return value |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
Implemented as Unicode and ANSI versions. So, LookupPrivilegeDisplayNameW() for Unicode and LookupPrivilegeDisplayNameA() for ANSI. |
|
Table 30 |
|
|
Item |
Description |
|
Function |
AdjustTokenPrivileges(). |
|
Use |
To enable or disable privileges in the specified access token. Enabling or disabling privileges in an access token requires TOKEN_ADJUST_PRIVILEGES access. |
|
Prototype |
BOOL AdjustTokenPrivileges( HANDLE TokenHandle, BOOL DisableAllPrivileges, PTOKEN_PRIVILEGES NewState, DWORD BufferLength, PTOKEN_PRIVILEGES PreviousState, PDWORD ReturnLength ); |
|
Parameters |
TokenHandle - [in] Handle to the access token that contains the privileges to be modified. The handle must have TOKEN_ADJUST_PRIVILEGES access to the token. If the PreviousState parameter is not NULL, the handle must also have TOKEN_QUERY access. DisableAllPrivileges- [in] Specifies whether the function disables all of the token's privileges. If this value is TRUE, the function disables all privileges and ignores the NewState parameter. If it is FALSE, the function modifies privileges based on the information pointed to by the NewState parameter. NewState - [in] Pointer to a TOKEN_PRIVILEGES structure that specifies an array of privileges and their attributes. If the DisableAllPrivileges parameter is FALSE, the AdjustTokenPrivileges() function enables, disables, or removes these privileges for the token. The following table describes the action taken by the AdjustTokenPrivileges() function, based on the privilege attribute.
None - The function disables the privilege. If DisableAllPrivileges is TRUE, the function ignores this parameter. BufferLength - [in] Specifies the size, in bytes, of the buffer pointed to by the PreviousState parameter. This parameter can be zero if the PreviousState parameter is NULL. PreviousState - [out] Pointer to a buffer that the function fills with a TOKEN_PRIVILEGES structure that contains the previous state of any privileges that the function modifies. That is, if a privilege has been modified by this function, the privilege and its previous state are contained in the TOKEN_PRIVILEGES structure referenced by PreviousState. If the PrivilegeCount member of TOKEN_PRIVILEGES is zero, then no privileges have been changed by this function. This parameter can be NULL. If you specify a buffer that is too small to receive the complete list of modified privileges, the function fails and does not adjust any privileges. In this case, the function sets the variable pointed to by the ReturnLength parameter to the number of bytes required to hold the complete list of modified privileges. ReturnLength - [out] Pointer to a variable that receives the required size, in bytes, of the buffer pointed to by the PreviousState parameter. This parameter can be NULL if PreviousState is NULL. |
|
Return value |
If the function succeeds, the return value is nonzero. To determine whether the function adjusted all of the specified privileges, call GetLastError(), which returns one of the following values when the function succeeds:
If the function fails, the return value is zero. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
- |
|
Table 31 |
|
The AdjustTokenPrivileges() function cannot add new privileges to the access token. It can only enable or disable the token's existing privileges. To determine the token's privileges, call the GetTokenInformation() function. The NewState parameter can specify privileges that the token does not have, without causing the function to fail. In this case, the function adjusts the privileges that the token does have and ignores the other privileges so that the function succeeds. Call the GetLastError() function to determine whether the function adjusted all of the specified privileges. The PreviousState parameter indicates the privileges that were adjusted. The PreviousState parameter retrieves a TOKEN_PRIVILEGES structure that contains the original state of the adjusted privileges. To restore the original state, pass the PreviousState pointer as the NewState parameter in a subsequent call to the AdjustTokenPrivileges() function.
|
Item |
Description |
|
Function |
GetTokenInformation(). |
|
Use |
To retrieve a specified type of information about an access token. The calling process must have appropriate access rights to obtain the information. To determine if a user is a member of a specific group, use the CheckTokenMembership() function. |
|
Prototype |
BOOL GetTokenInformation( HANDLE TokenHandle, TOKEN_INFORMATION_CLASS TokenInformationClass, LPVOID TokenInformation, DWORD TokenInformationLength, PDWORD ReturnLength ); |
|
Parameters |
TokenHandle - [in] Handle to an access token from which information is retrieved. If TokenInformationClass specifies TokenSource, the handle must have TOKEN_QUERY_SOURCE access. For all other TokenInformationClass values, the handle must have TOKEN_QUERY access. TokenInformationClass - [in] Specifies a value from the TOKEN_INFORMATION_CLASS enumerated type to identify the type of information the function retrieves. TokenInformation - [out] Pointer to a buffer the function fills with the requested information. The structure put into this buffer depends upon the type of information specified by the TokenInformationClass parameter as follows:
TokenInformationLength - [in] Specifies the size, in bytes, of the buffer pointed to by the TokenInformation parameter. If TokenInformation is NULL, this parameter must be zero. ReturnLength - [out] Pointer to a variable that receives the number of bytes needed for the buffer pointed to by the TokenInformation parameter. If this value is larger than the value specified in the TokenInformationLength parameter, the function fails and stores no data in the buffer. If the value of the TokenInformationClass parameter is TokenDefaultDacl and the token has no default DACL, the function sets the variable pointed to by ReturnLength to sizeof(TOKEN_DEFAULT_DACL) and sets the DefaultDacl member of the TOKEN_DEFAULT_DACL structure to NULL. |
|
Return value |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
- |
|
Table 32 |
|
|
Item |
Description |
|
Function |
CheckTokenMembership(). |
|
Use |
To determine whether a specified SID is enabled in an access token. |
|
Prototype |
BOOL CheckTokenMembership( HANDLE TokenHandle, PSID SidToCheck, PBOOL IsMember ); |
|
Parameters |
TokenHandle - [in] Handle to an access token. The handle must have TOKEN_QUERY access to the token. The token must be an impersonation token. If TokenHandle is NULL, CheckTokenMembership() uses the impersonation token of the calling thread. If the thread is not impersonating, the function duplicates the thread's primary token to create an impersonation token. SidToCheck - [in] Pointer to a SID structure. The CheckTokenMembership() function checks for the presence of this SID in the user and group SIDs of the access token. IsMember - [out] Pointer to a variable that receives the results of the check. If the SID is present and has the SE_GROUP_ENABLED attribute, IsMember returns TRUE; otherwise, it returns FALSE. |
|
Return value |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
- |
|
Table 33 |
|
The CheckTokenMembership() function simplifies the process of determining whether a SID is both present and enabled in an access token. Even if a SID is present in the token, the system may not use the SID in an access check. The SID may be disabled or have the SE_GROUP_USE_FOR_DENY_ONLY attribute. The system uses only enabled SIDs to grant access when performing an access check. If TokenHandle is a restricted token, or if TokenHandle is NULL and the current effective token of the calling thread is a restricted token, CheckTokenMembership() also checks whether the SID is present in the list of restricting SIDs.
GetAce()
|
Item |
Description |
|
Function |
GetAce(). |
|
Use |
To obtain a pointer to an ACE in ACL. |
|
Prototype |
BOOL GetAce( PACL pAcl, DWORD dwAceIndex, LPVOID* pAce ); |
|
Parameters |
pAcl - [in] A pointer to an ACL that contains the ACE to be retrieved. dwAceIndex - [in] The index of the ACE to be retrieved. A value of zero corresponds to the first ACE in the ACL, a value of one to the second ACE, and so on. pAce - [out] A pointer to a pointer that the function sets to the address of the ACE. |
|
Return value |
If the function succeeds, the function returns nonzero. If the function fails, it returns zero. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
- |
|
Table 34 |
|
GetAclInformation()
|
Item |
Description |
|
Function |
GetAclInformation(). |
|
Use |
To retrieve information about an ACL. |
|
Prototype |
BOOL GetAclInformation( PACL pAcl, LPVOID pAclInformation, DWORD nAclInformationLength, ACL_INFORMATION_CLASS dwAclInformationClass ); |
|
Parameters |
pAcl - [in] A pointer to an ACL. The function retrieves information about this ACL. If a null value is passed, the function causes an access violation. pAclInformation- [out] A pointer to a buffer to receive the requested information. The structure that is placed into the buffer depends on the information class requested in the dwAclInformationClass parameter. nAclInformationLength - [in] The size, in bytes, of the buffer pointed to by the pAclInformation parameter. dwAclInformationClass- [in] A value of the ACL_INFORMATION_CLASS enumeration that indicates the class of information requested. This parameter can be one of two values from this enumeration:
|
|
Return value |
If the function succeeds, the function returns nonzero. If the function fails, it returns zero. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
- |
|
Table 35 |
|
GetAuditedPermissionsFromAcl()
|
Item |
Description |
|
Function |
GetAuditedPermissionsFromAcl(). |
|
Use |
To retrieve the audited access rights for a specified trustee. The audited rights are based on the ACEs of a specified ACL. The audited access rights indicate the types of access attempts that cause the system to generate an audit record in the system event log. The audited rights include those that the ACL specifies for the trustee or for any groups of which the trustee is a member. In determining the audited rights, the function does not consider the security privileges held by the trustee. |
|
Prototype |
DWORD GetAuditedPermissionsFromAcl( PACL pacl, PTRUSTEE pTrustee, PACCESS_MASK pSuccessfulAuditedRights, PACCESS_MASK pFailedAuditRights ); |
|
Parameters |
pacl - [in] A pointer to an ACL structure from which to get the trustee's audited access rights. pTrustee - [in] A pointer to a TRUSTEE structure that identifies the trustee. A trustee can be a user, group, or program (such as a Windows service). You can use a name or a SID to identify a trustee. pSuccessfulAuditedRights - [out] A pointer to an ACCESS_MASK structure that receives a set of access rights. The system generates an audit record when the trustee successfully uses any of these access rights. pFailedAuditRights - [out] A pointer to an ACCESS_MASK structure that receives a set of access rights based on the ACEs in the specified ACL. The system generates an audit record when the trustee fails in an attempt to use any of these rights. |
|
Return value |
If the function succeeds, the function returns ERROR_SUCCESS. If the function fails, it returns a nonzero error code defined in winerror.h. |
|
Include file |
<aclapi.h> |
|
Remark |
Implemented as Unicode and ANSI versions. GetAuditedPermissionsFromAclW for Unicode and GetAuditedPermissionsFromAclA for ANSI. |
|
Table 36 |
|
The GetAuditedPermissionsFromAcl() function checks all system-audit ACEs in the ACL to determine the audited rights for the trustee. For all ACEs that specify audited rights for a group, GetAuditedPermissionsFromAcl() enumerates the members of the group to determine whether the trustee is a member. The function returns an error if it cannot enumerate the members of a group.
GetFileSecurity()
|
Item |
Description |
|
Function |
GetFileSecurity(). |
|
Use |
To obtain specified information about the security of a file or directory. The information obtained is constrained by the caller's access rights and privileges. The GetNamedSecurityInfo() function provides functionality similar to GetFileSecurity() for files as well as other types of objects. |
|
Prototype |
BOOL GetFileSecurity( LPCTSTR lpFileName, SECURITY_INFORMATION RequestedInformation, PSECURITY_DESCRIPTOR pSecurityDescriptor, DWORD nLength, LPDWORD lpnLengthNeeded ); |
|
Parameters |
lpFileName - [in] Pointer to a null-terminated string that specifies the file or directory for which security information is retrieved. RequestedInformation - [in] A SECURITY_INFORMATION value that identifies the security information being requested. pSecurityDescriptor - [out] Pointer to a buffer that receives a copy of the security descriptor of the object specified by the lpFileName parameter. The calling process must have permission to view the specified aspects of the object's security status. The SECURITY_DESCRIPTOR structure is returned in self-relative format. nLength - [in] Specifies the size, in bytes, of the buffer pointed to by the pSecurityDescriptor parameter. lpnLengthNeeded - [out] Pointer to the variable that receives the number of bytes necessary to store the complete security descriptor. If the returned number of bytes is less than or equal to nLength, the entire security descriptor is returned in the output buffer; otherwise, none of the descriptor is returned. |
|
Return value |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
GetFileSecurityW() for Unicode and GetFileSecurityA() for ANSI. To read the owner, group, or DACL from the security descriptor for the specified file or directory, the DACL for the file or directory must grant READ_CONTROL access to the caller, or the caller must be the owner of the file or directory. To read the SACL of a file or directory, the SE_SECURITY_NAME privilege must be enabled for the calling process. |
|
Table 37 |
|
GetNamedSecurityInfo()
|
Item |
Description |
|
Function |
GetNamedSecurityInfo(). |
|
Use |
To retrieve a copy of the security descriptor for an object specified by name. |
|
Prototype |
DWORD GetNamedSecurityInfo( LPTSTR pObjectName, SE_OBJECT_TYPE ObjectType, SECURITY_INFORMATION SecurityInfo, PSID* ppsidOwner, PSID* ppsidGroup, PACL* ppDacl, PACL* ppSacl, PSECURITY_DESCRIPTOR* ppSecurityDescriptor ); |
|
Parameters |
pObjectName - [in] Pointer to a null-terminated string that specifies the name of the object from which to retrieve security information. ObjectType - [in] Specifies a value from the SE_OBJECT_TYPE enumeration that indicates the type of object named by the pObjectName parameter. SecurityInfo - [in] A set of SECURITY_INFORMATION bit flags that indicate the type of security information to retrieve. This parameter can be a combination of the following values:
ppsidOwner - [out] Pointer to a variable that receives a pointer to the owner SID in the security descriptor returned in ppSecurityDescriptor. The returned pointer is valid only if you set the OWNER_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the owner SID. ppsidGroup - [out] Pointer to a variable that receives a pointer to the primary group SID in the returned security descriptor. The returned pointer is valid only if you set the GROUP_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the group SID. ppDacl - [out] Pointer to a variable that receives a pointer to the DACL in the returned security descriptor. The returned pointer is valid only if you set the DACL_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the DACL. ppSacl - [out] Pointer to a variable that receives a pointer to the SACL in the returned security descriptor. The returned pointer is valid only if you set the SACL_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the SACL. ppSecurityDescriptor - [out] Pointer to a variable that receives a pointer to the security descriptor of the object. When you have finished using the pointer, free the returned buffer by calling the LocalFree() function. |
|
Return value |
If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in winerror.h. |
|
Include file |
<aclapi.h> |
|
Remark |
GetNamedSecurityInfoW() for Unicode and GetNamedSecurityInfoA() for ANSI. |
|
Table 38 |
|
If the ppsidOwner, ppsidGroup, ppDacl, and ppSacl parameters are non-NULL, and the SecurityInfo parameter specifies that they be retrieved from the object, those parameters will point to the corresponding parameters in the security descriptor returned in ppSecurityDescriptor. To read the owner, group, or DACL from the object's security descriptor, the object's DACL must grant READ_CONTROL access to the caller, or the caller must be the owner of the object. To read the system access control list of the object, the SE_SECURITY_NAME privilege must be enabled for the calling process. You can use the GetNamedSecurityInfo() function with the following types of objects:
Local or remote files or directories on an NTFS file system.
Local or remote printers.
Local or remote Windows services.
Network shares.
Registry keys.
Semaphores, events, mutexes, and waitable timers.
File-mapping objects.
Directory service objects.
This function does not handle race conditions. If your thread calls this function at the approximate time that another thread changes the object's security descriptor, then this function could fail. This function transfers information in plaintext. The information transferred by this function is signed unless signing has been turned off for the system, but no encryption is performed. For Windows 2000 SP2 and Windows NT, the information transferred by this function is unsigned.
GetAuditedPermissionsFromAcl()
|
Item |
Description |
|
Function |
GetAuditedPermissionsFromAcl(). |
|
Use |
To retrieve the audited access rights for a specified trustee. The audited rights are based on the ACEs of a specified ACL. The audited access rights indicate the types of access attempts that cause the system to generate an audit record in the system event log. The audited rights include those that the ACL specifies for the trustee or for any groups of which the trustee is a member. In determining the audited rights, the function does not consider the security privileges held by the trustee. |
|
Prototype |
DWORD GetAuditedPermissionsFromAcl( PACL pacl, PTRUSTEE pTrustee, PACCESS_MASK pSuccessfulAuditedRights, PACCESS_MASK pFailedAuditRights ); |
|
Parameters |
pacl - [in] A pointer to an ACL structure from which to get the trustee's audited access rights. pTrustee - [in] A pointer to a TRUSTEE structure that identifies the trustee. A trustee can be a user, group, or program (such as a Windows service). You can use a name or a security identifier (SID) to identify a trustee. pSuccessfulAuditedRights - [out] A pointer to an ACCESS_MASK structure that receives a set of access rights. The system generates an audit record when the trustee successfully uses any of these access rights. pFailedAuditRights - [out] A pointer to an ACCESS_MASK structure that receives a set of access rights based on the ACEs in the specified ACL. The system generates an audit record when the trustee fails in an attempt to use any of these rights. |
|
Return value |
If the function succeeds, the function returns ERROR_SUCCESS. If the function fails, it returns a nonzero error code defined in winerror.h. |
|
Include file |
<aclapi.h> |
|
Remark |
GetAuditedPermissionsFromAclW() for Unicode and GetAuditedPermissionsFromAclA() for ANSI. The GetAuditedPermissionsFromAcl() function checks all system-audit ACEs in the ACL to determine the audited rights for the trustee. For all ACEs that specify audited rights for a group, GetAuditedPermissionsFromAcl() enumerates the members of the group to determine whether the trustee is a member. The function returns an error if it cannot enumerate the members of a group. |
|
Table 39 |
|
GetEffectiveRightsFromAcl()
|
Item |
Description |
|
Function |
GetEffectiveRightsFromAcl(). |
|
Use |
To retrieve the effective access rights that an ACL structure grants to a specified trustee. The trustee's effective access rights are the access rights that the ACL grants to the trustee or to any groups of which the trustee is a member. |
|
Prototype |
DWORD GetEffectiveRightsFromAcl( PACL pacl, PTRUSTEE pTrustee, PACCESS_MASK pAccessRights ); |
|
Parameters |
pacl - [in] A pointer to an ACL structure from which to get the trustee's effective access rights. pTrustee - [in] A pointer to a TRUSTEE structure that identifies the trustee. A trustee can be a user, group, or program (such as a Windows service). You can use a name or a security identifier (SID) to identify a trustee. pAccessRights - [out] A pointer to an ACCESS_MASK variable that receives the effective access rights of the trustee. |
|
Return value |
If the function succeeds, the function returns ERROR_SUCCESS. If the function fails, it returns a nonzero error code defined in winerror.h. |
|
Include file |
<aclapi.h> |
|
Remark |
GetEffectiveRightsFromAclW() for Unicode and GetEffectiveRightsFromAclA() for ANSI. |
|
Table 40 |
|
The GetEffectiveRightsFromAcl() function checks all access-allowed and access-denied ACEs in the ACL to determine the effective rights for the trustee. For all ACEs that allow or deny rights to a group, GetEffectiveRightsFromAcl() enumerates the members of the group to determine whether the trustee is a member. The function returns an error if it cannot enumerate the members of a group. A trustee's group rights are enumerated by GetEffectiveRightsFromAcl() on the local computer, even if the trustee is accessing objects on a remote computer. This function does not evaluate group rights on remote computers. The GetEffectiveRightsFromAcl() function does not consider the following:
Implicitly granted access rights, such as READ_CONTROL and WRITE_DAC, for the owner of an object when determining effective rights.
Privileges held by the trustee when determining effective access rights.
Group rights associated with the logon session, such as interactive, network, authenticated users, and so forth, in determining effective access rights.
Resource manager policy. For example, for file objects, Delete and Read attributes can be provided by the parent even if they have been denied on the object.
GetExplicitEntriesFromAcl()
|
Item |
Description |
|
Function |
GetExplicitEntriesFromAcl(). |
|
Use |
To retrieve an array of structures that describe the ACEs in an ACL. |
|
Prototype |
DWORD GetExplicitEntriesFromAcl( PACL pacl, PULONG pcCountOfExplicitEntries, PEXPLICIT_ACCESS* pListOfExplicitEntries ); |
|
Parameters |
pacl - [in] A pointer to an ACL structure from which to get ACE information. pcCountOfExplicitEntries - [out] A pointer to a variable that receives the number of EXPLICIT_ACCESS structures returned in the pListOfExplicitEntries array. pListOfExplicitEntries - [out] A pointer to a variable that receives a pointer to an array of EXPLICIT_ACCESS structures that describe the ACEs in the ACL. If the function succeeds, you must call the LocalFree() function to free the returned buffer. |
|
Return value |
If the function succeeds, the function returns ERROR_SUCCESS. If the function fails, it returns a nonzero error code defined in winerror.h. |
|
Include file |
<aclapi.h> |
|
Remark |
GetExplicitEntriesFromAclW() for Unicode and GetExplicitEntriesFromAclA() for ANSI. |
|
Table 41 |
|
Each entry in the array of EXPLICIT_ACCESS structures describes access control information from an ACE for a trustee. A trustee can be a user, group, or program (such as a Windows service). For Windows 2000, ACEs that have a flag type of INHERITED_ACE are not returned by this function. A DACL for an object can return zero ACEs if all existing ACEs are flagged as INHERITED_ACE. Each EXPLICIT_ACCESS structure specifies a set of access rights and an access mode flag that indicates whether the ACE allows, denies, or audits the specified rights. For a DACL, the access mode flag can be either GRANT_ACCESS or DENY_ACCESS. For a SACL, the access mode flag can be SET_AUDIT_ACCESS, SET_AUDIT_FAILURE, or both.
GetSecurityDescriptorDacl()
|
Item |
Description |
|
Function |
GetSecurityDescriptorDacl(). |
|
Use |
To retrieve a pointer to the DACL in a specified security descriptor. |
|
Prototype |
BOOL GetSecurityDescriptorDacl( PSECURITY_DESCRIPTOR pSecurityDescriptor, LPBOOL lpbDaclPresent, PACL* pDacl, LPBOOL lpbDaclDefaulted ); |
|
Parameters |
pSecurityDescriptor - [in] A pointer to the SECURITY_DESCRIPTOR structure that contains the DACL. The function retrieves a pointer to it. lpbDaclPresent - [out] A pointer to a value that indicates the presence of a DACL in the specified security descriptor. If lpbDaclPresent is TRUE, the security descriptor contains a DACL, and the remaining output parameters in this function receive valid values. If lpbDaclPresent is FALSE, the security descriptor does not contain a DACL, and the remaining output parameters do not receive valid values. A value of TRUE for lpbDaclPresent does not mean that pDacl is not NULL. That is, lpbDaclPresent can be TRUE while pDacl is NULL, meaning that a NULL DACL is in effect. A NULL DACL implicitly allows all access to an object and is not the same as an empty DACL. An empty DACL permits no access to an object. pDacl - [out] A pointer to a pointer to an ACL. If a DACL exists, the function sets the pointer pointed to by pDacl to the address of the security descriptor's DACL. If a DACL does not exist, no value is stored. If the function stores a NULL value in the pointer pointed to by pDacl, the security descriptor has a NULL DACL. A NULL DACL implicitly allows all access to an object. If an application expects a non-NULL DACL but encounters a NULL DACL, the application should fail securely and not allow access. lpbDaclDefaulted - [out] A pointer to a flag set to the value of the SE_DACL_DEFAULTED flag in the SECURITY_DESCRIPTOR_CONTROL structure if a DACL exists for the security descriptor. If this flag is TRUE, the DACL was retrieved by a default mechanism; if FALSE, the DACL was explicitly specified by a user. |
|
Return value |
If the function succeeds, the function returns nonzero. If the function fails, it returns zero. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
- |
|
Table 42 |
|
GetSecurityDescriptorSacl()
|
Item |
Description |
|
Function |
GetSecurityDescriptorSacl(). |
|
Use |
To retrieve a pointer to the SACL in a specified security descriptor. |
|
Prototype |
BOOL GetSecurityDescriptorSacl( PSECURITY_DESCRIPTOR pSecurityDescriptor, LPBOOL lpbSaclPresent, PACL* pSacl, LPBOOL lpbSaclDefaulted ); |
|
Parameters |
pSecurityDescriptor - [in] A pointer to the SECURITY_DESCRIPTOR structure that contains the SACL to which the function retrieves a pointer. lpbSaclPresent - [out] A pointer to a flag the function sets to indicate the presence of a SACL in the specified security descriptor. If this parameter is TRUE, the security descriptor contains a SACL, and the remaining output parameters in this function receive valid values. If this parameter is FALSE, the security descriptor does not contain a SACL, and the remaining output parameters do not receive valid values. pSacl - [out] A pointer to a pointer to an ACL. If a SACL exists, the function sets the pointer pointed to by pSacl to the address of the security descriptor's SACL. If a SACL does not exist, no value is stored. If the function stores a NULL value in the pointer pointed to by pSacl, the security descriptor has a NULL SACL. lpbSaclDefaulted - [out] A pointer to a flag that is set to the value of the SE_SACL_DEFAULTED flag in the SECURITY_DESCRIPTOR_CONTROL structure if a SACL exists for the security descriptor. |
|
Return value |
If the function succeeds, the function returns nonzero. If the function fails, it returns zero. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
- |
|
Table 43 |
|
GetSecurityInfo()
|
Item |
Description |
|
Function |
GetSecurityInfo(). |
|
Use |
To retrieve a copy of the security descriptor for an object specified by a handle. |
|
Prototype |
DWORD GetSecurityInfo( HANDLE handle, SE_OBJECT_TYPE ObjectType, SECURITY_INFORMATION SecurityInfo, PSID* ppsidOwner, PSID* ppsidGroup, PACL* ppDacl, PACL* ppSacl, PSECURITY_DESCRIPTOR* ppSecurityDescriptor ); |
|
Parameters |
handle - [in] Handle to the object from which to retrieve security information. ObjectType - [in] SE_OBJECT_TYPE enumeration value that indicates the type of object. SecurityInfo - [in] Specifies a set of SECURITY_INFORMATION bit values that indicate the type of security information to retrieve. This parameter can be a combination of the following values:
ppsidOwner - [out] Pointer to a variable that receives a pointer to the owner SID in the security descriptor returned in ppSecurityDescriptor. The returned pointer is valid only if you set the OWNER_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the owner SID. ppsidGroup - [out] Pointer to a variable that receives a pointer to the primary group SID in the returned security descriptor. The returned pointer is valid only if you set the GROUP_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the group SID. ppDacl - [out] Pointer to a variable that receives a pointer to the DACL in the returned security descriptor. The returned pointer is valid only if you set the DACL_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the DACL. ppSacl - [out] Pointer to a variable that receives a pointer to the SACL in the returned security descriptor. The returned pointer is valid only if you set the SACL_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the SACL. ppSecurityDescriptor - [out] Pointer to a variable that receives a pointer to the security descriptor of the object. When you have finished using the pointer, free the returned buffer by calling the LocalFree() function. |
|
Return value |
If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in winerror.h. |
|
Include file |
<aclapi.h> |
|
Remark |
- |
|
Table 44 |
|
If the ppsidOwner, ppsidGroup, ppDacl, and ppSacl parameters are non-NULL, and the SecurityInfo parameter specifies that they be retrieved from the object, those parameters will point to the corresponding parameters in the security descriptor returned in ppSecurityDescriptor. To read the owner, group, or DACL from the object's security descriptor, the calling process must have been granted READ_CONTROL access when the handle was opened. To get READ_CONTROL access, the caller must be the owner of the object or the object's DACL must grant the access. To read the SACL from the security descriptor, the calling process must have been granted ACCESS_SYSTEM_SECURITY access when the handle was opened. The proper way to get this access is to enable the SE_SECURITY_NAME privilege in the caller's current token, open the handle for ACCESS_SYSTEM_SECURITY access, and then disable the privilege. You can use the GetSecurityInfo() function with the following types of objects:
Local or remote files or directories on an NTFS file system.
Named pipes.
Local or remote printers.
Local or remote Windows services.
Network shares.
Registry keys.
Semaphores, events, mutexes, and waitable timers.
Processes, threads, jobs, and file-mapping objects.
Interactive service window stations and desktops.
Directory service objects.
This function does not handle race conditions. If your thread calls this function at the approximate time that another thread changes the object's security descriptor, then this function could fail.
PrivilegeCheck()
|
Item |
Description |
|
Function |
PrivilegeCheck(). |
|
Use |
To determine whether a specified set of privileges are enabled in an access token. The PrivilegeCheck() function is typically called by a server application to check the privileges of a client's access token. |
|
Prototype |
BOOL PrivilegeCheck( HANDLE ClientToken, PPRIVILEGE_SET RequiredPrivileges, LPBOOL pfResult ); |
|
Parameters |
ClientToken - [in] Handle to an access token representing a client process. This handle must have been obtained by opening the token of a thread impersonating the client. The token must be open for TOKEN_QUERY access. RequiredPrivileges - [in] Pointer to a PRIVILEGE_SET structure. The Privilege member of this structure is an array of LUID_AND_ATTRIBUTES structures. Before calling PrivilegeCheck(), use the Privilege array to indicate the set of privileges to check. Set the Control member to PRIVILEGE_SET_ALL_NECESSARY if all of the privileges must be enabled; or set it to zero if it is sufficient that any one of the privileges be enabled. When PrivilegeCheck() returns, the Attributes member of each LUID_AND_ATTRIBUTES structure is set to SE_PRIVILEGE_USED_FOR_ACCESS if the corresponding privilege is enabled. pfResult - [out] Pointer to a value the function sets to indicate whether any or all of the specified privileges are enabled in the access token. If the Control member of the PRIVILEGE_SET structure specifies PRIVILEGE_SET_ALL_NECESSARY, this value is TRUE only if all the privileges are enabled; otherwise, this value is TRUE if any of the privileges are enabled. |
|
Return value |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
- |
|
Table 45 |
|
An access token contains a list of the privileges held by the account associated with the token. These privileges can be enabled or disabled; most are disabled by default. The PrivilegeCheck() function checks only for enabled privileges. To get a list of all the enabled and disabled privileges held by an access token, call the GetTokenInformation() function. To enable or disable a set of privileges in an access token, call the AdjustTokenPrivileges() function.
SetAclInformation()
|
Item |
Description |
|
Function |
SetAclInformation(). |
|
Use |
To set information about an ACL. |
|
Prototype |
BOOL SetAclInformation( PACL pAcl, LPVOID pAclInformation, DWORD nAclInformationLength, ACL_INFORMATION_CLASS dwAclInformationClass ); |
|
Parameters |
pAcl - [in] A pointer to an ACL. The function sets information in this ACL. pAclInformation - [in] A pointer to a buffer that contains the information to be set. This must be a pointer to an ACL_REVISION_INFORMATION structure. nAclInformationLength - [in] The size, in bytes, of the buffer pointed to by the pAclInfo parameter. dwAclInformationClass - [in] An ACL_INFORMATION_CLASS enumerated type that gives the class of information requested. Currently, this parameter can be AclRevisionInformation. This means that the buffer pointed to by the pAclInformation parameter contains an ACL_REVISION_INFORMATION structure. |
|
Return value |
If the function succeeds, the function returns nonzero. If the function fails, it returns zero. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
- |
|
Table 46 |
|
SetEntriesInAcl()
|
Item |
Description |
|
Function |
SetEntriesInAcl(). |
|
Use |
To create a new ACL by merging new access control or audit control information into an existing ACL structure. |
|
Prototype |
DWORD SetEntriesInAcl( ULONG cCountOfExplicitEntries, PEXPLICIT_ACCESS pListOfExplicitEntries, PACL OldAcl, PACL* NewAcl ); |
|
Parameters |
cCountOfExplicitEntries - [in] The number of EXPLICIT_ACCESS structures in the pListOfExplicitEntries array. pListOfExplicitEntries - [in] A pointer to an array of EXPLICIT_ACCESS structures that describe the access control information to merge into the existing ACL. OldAcl - [in] A pointer to the existing ACL. This parameter can be NULL, in which case, the function creates a new ACL based on the EXPLICIT_ACCESS entries. NewAcl - [out] A pointer to a variable that receives a pointer to the new ACL. If the function succeeds, you must call the LocalFree() function to free the returned buffer. |
|
Return value |
If the function succeeds, the function returns ERROR_SUCCESS. If the function fails, it returns a nonzero error code defined in winerror.h. |
|
Include file |
<aclapi.h> |
|
Remark |
SetEntriesInAclW() for Unicode and SetEntriesInAclA() for ANSI. |
|
Table 47 |
|
Each entry in the array of EXPLICIT_ACCESS structures specifies access control or audit control information for a specified trustee. A trustee can be a user, group, or other security identifier (SID) value, such as a logon identifier or logon type (for instance, a Windows service or batch job). You can use a name or a SID to identify a trustee. You can use the SetEntriesInAcl() function to modify the list of ACEs in a DACL or a SACL. Note that SetEntriesInAcl() does not prevent you from mixing access control and audit control information in the same ACL; however, the resulting ACL will contain meaningless entries. For a DACL, the grfAccessMode member of the EXPLICIT_ACCESS structure specifies whether to allow, deny, or revoke access rights for the trustee. This member can specify one of the following values:
GRANT_ACCESS.
SET_ACCESS.
DENY_ACCESS.
REVOKE_ACCESS.
The SetEntriesInAcl() function places any new access-denied ACEs at the beginning of the list of ACEs for the new ACL. This function places any new access-allowed ACEs just before any existing access-allowed ACEs. For a SACL, the grfAccessMode member of the EXPLICIT_ACCESS structure can specify the following values:
REVOKE_ACCESS.
SET_AUDIT_FAILURE.
SET_AUDIT_SUCCESS.
SET_AUDIT_FAILURE and SET_AUDIT_SUCCESS can be combined. The SetEntriesInAcl() function places any new system-audit ACEs at the beginning of the list of ACEs for the new ACL.
|
Item |
Description |
|
Function |
SetTokenInformation(). |
|
Use |
To set various types of information for a specified access token. The information that this function sets replaces existing information. The calling process must have appropriate access rights to set the information. |
|
Prototype |
BOOL SetTokenInformation( HANDLE TokenHandle, TOKEN_INFORMATION_CLASS TokenInformationClass, LPVOID TokenInformation, DWORD TokenInformationLength ); |
|
Parameters |
TokenHandle - [in] A handle to the access token for which information is to be set. TokenInformationClass - [in] A value from the TOKEN_INFORMATION_CLASS enumerated type that identifies the type of information the function sets. The valid values from TOKEN_INFORMATION_CLASS are described in the TokenInformation parameter. TokenInformation - [in] A pointer to a buffer that contains the information set in the access token. The structure of this buffer depends on the type of information specified by the TokenInformationClass parameter. The following values are valid in calls to this function.
TokenInformationLength - [in] Specifies the length, in bytes, of the buffer pointed to by TokenInformation. |
|
Return value |
If the function succeeds, the function returns nonzero. If the function fails, it returns zero. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
- |
|
Table 48 |
|
To set privilege information, an application can call the AdjustTokenPrivileges() function. To set a token's groups, an application can call the AdjustTokenGroups() function. Token-type information can be set only when an access token is created.
|
Item |
Description |
|
Function |
DuplicateToken(). |
|
Use |
To create a new access token that duplicates one already in existence. |
|
Prototype |
BOOL DuplicateToken( HANDLE ExistingTokenHandle, SECURITY_IMPERSONATION_LEVEL ImpersonationLevel, PHANDLE DuplicateTokenHandle ); |
|
Parameters |
ExistingTokenHandle - [in] Handle to an access token opened with TOKEN_DUPLICATE access. ImpersonationLevel - [in] Specifies a SECURITY_IMPERSONATION_LEVEL enumerated type that supplies the impersonation level of the new token. DuplicateTokenHandle - [out] Pointer to a variable that receives a handle to the duplicate token. This handle has TOKEN_IMPERSONATE and TOKEN_QUERY access to the new token. |
|
Return value |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError(). |
|
Include file |
<windows.h> |
|
Remark |
The DuplicateToken() function creates an impersonation token, which you can use in functions such as SetThreadToken() and ImpersonateLoggedOnUser(). The token created by DuplicateToken() cannot be used in the CreateProcessAsUser() function, which requires a primary token. To create a token that you can pass to CreateProcessAsUser(), use the DuplicateTokenEx() function. |
|
Table 49 |
|
|
Item |
Description |
|
Function |
DuplicateTokenEx(). |
|
Use |
To create a new access token that duplicates an existing token. This function can create either a primary token or an impersonation token. |
|
Prototype |
BOOL DuplicateTokenEx( HANDLE hExistingToken, DWORD dwDesiredAccess, LPSECURITY_ATTRIBUTES lpTokenAttributes, SECURITY_IMPERSONATION_LEVEL ImpersonationLevel, TOKEN_TYPE TokenType, PHANDLE phNewToken ); |
|
Parameters |
hExistingToken - [in] Handle to an access token opened with TOKEN_DUPLICATE access. dwDesiredAccess - [in] Specifies the requested access rights for the new token. The DuplicateTokenEx() function compares the requested access rights with the existing token's DACL to determine which rights are granted or denied. To request the same access rights as the existing token, specify zero. To request all access rights that are valid for the caller, specify MAXIMUM_ALLOWED. lpTokenAttributes - [in] Pointer to a SECURITY_ATTRIBUTES structure that specifies a security descriptor for the new token and determines whether child processes can inherit the token. If lpTokenAttributes is NULL, the token gets a default security descriptor and the handle cannot be inherited. If the security descriptor contains a SACL, the token gets ACCESS_SYSTEM_SECURITY access right, even if it was not requested in dwDesiredAccess. ImpersonationLevel - [in] Specifies a value from the SECURITY_IMPERSONATION_LEVEL enumeration that indicates the impersonation level of the new token. TokenType - [in] Specifies one of the following values from the TOKEN_TYPE enumeration:
phNewToken - [out] Pointer to a HANDLE variable that receives the new token. |
|
Return value |