| Previous | Main | Next | Site Index | Download | Disclaimer | Privacy |


 

 

 

 

 

WINDOWS PROCESS & THREADS: A SUPPLEMENTARY NOTE

 

 

 

 

 

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).

 

The Page Index

  1. GetKernelObjectSecurity()

  2. SetKernelObjectSecurity()

  3. PrivilegeCheck()

  4. OpenProcessToken()

  5. OpenThreadToken()

  6. GetCurrentProcess()

  7. SetTokenInformation()

  8. LogonUser()

  9. CreateProcessAsUser()

  10. ConvertStringSecurityDescriptorToSecurityDescriptor()

  11. ConvertSecurityDescriptorToStringSecurityDescriptor()

  12. GlobalAlloc()

  13. LocalFree()

  14. LocalReAlloc()

  15. LocalAlloc()

  16. GetNamedSecurityInfo()

  17. SetEntriesInAcl()

  18. SetNamedSecurityInfo()

  19. BuildTrusteeWithSid()

  20. BuildTrusteeWithName()

  21. GetTrusteeForm()

  22. GetTrusteeName()

  23. GetTrusteeType()

  24. LookupPrivilegeName()

  25. LookupPrivilegeValue()

  26. LookupPrivilegeDisplayName()

  27. AdjustTokenPrivileges()

  28. GetTokenInformation()

  29. CheckTokenMembership()

  30. GetAce()

  31. GetAclInformation()

  32. GetAuditedPermissionsFromAcl()

  33. GetFileSecurity()

  34. GetNamedSecurityInfo()

  35. GetAuditedPermissionsFromAcl()

  36. GetEffectiveRightsFromAcl()

  37. GetExplicitEntriesFromAcl()

  38. GetSecurityDescriptorDacl()

  39. GetSecurityDescriptorSacl()

  40. GetSecurityInfo()

  41. PrivilegeCheck()

  42. SetAclInformation()

  43. SetEntriesInAcl()

  44. SetTokenInformation()

  45. DuplicateToken()

  46. DuplicateTokenEx()

  47. ImpersonateLoggedOnUser()

  48. ImpersonateSelf()

  49. ImpersonateAnonymousToken()

  50. ImpersonateNamedPipeClient()

  51. RevertToSelf()

  52. AddAuditAccessObjectAce()

  53. GetExplicitEntriesFromAcl()

  54. BuildExplicitAccessWithName()

  55. BuildSecurityDescriptor()

  56. AllocateAndInitializeSid()

  57. FreeSid()

  58. CreateWellKnownSid()

  59. IsWellKnownSid()

  60. SecureZeroMemory()

  61. RegCreateKeyEx()

  62. HeapAlloc()

  63. HeapFree()

  64. HeapSize()

  65. HeapReAlloc()

  66. AccessCheck()

  67. InitializeSecurityDescriptor()

 

 

 

 

 

 

 

 

 

 

GetKernelObjectSecurity()

 

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.

 

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 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.

 

OpenProcessToken()

 

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

 

OpenThreadToken()

 

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.

 

GetCurrentProcess()

 

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.

 

SetTokenInformation()

 

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:

  1. TokenDefaultDacl - Specifies a TOKEN_DEFAULT_DACL structure.  The TOKEN_ADJUST_DEFAULT access right is needed to set information in the default DACL.  The ACL structure provided as a new default DACL is not validated for correctness or consistency.  If the TokenInformation parameter is NULL, the current default DACL is removed and no replacement is established.

  2. TokenOrigin - Specifies a TOKEN_ORIGIN structure, with the OriginatingLogonSession member of TOKEN_ORIGIN set to a LUID that represents the token origin.  The token origin can be set only if it has not previously been set.  The SE_TCB_NAME privilege is needed to set the token origin.

  3. TokenOwner - Specifies a TOKEN_OWNER structure.  The TOKEN_ADJUST_DEFAULT access right is needed to set owner information.  A valid owner value is a user or group identifier with an attribute allowing assignment as the owner of objects.

  4. TokenPrimaryGroup - Specifies a TOKEN_PRIMARY_GROUP structure.  The TOKEN_ADJUST_DEFAULT access right is needed to set primary group information.

  5. TokenSessionId - The buffer receives a DWORD value that indicates the Terminal Services session identifier associated with the token.  If the token is associated with the Terminal Server console session, the session identifier is zero.  A nonzero session identifier indicates a Terminal Services client session. In a non-Terminal Services environment, the session identifier is zero.  The process must have the SE_TCB_NAME privilege and must be enabled to set the session ID in a token. For Windows 2000 Server, this value is supported only if Terminal Services is enabled.

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.

 

LogonUser()

 

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.

 

Parameters

 

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:

  1. 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().

  2. 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.

 

CreateProcessAsUser()

 

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:

  1. c:\program.exe files\sub dir\program name

  2. c:\program files\sub.exe dir\program name

  3. c:\program files\sub dir\program.exe name

  4. 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:

 

  1. The directory from which the application loaded.

  2. The current directory for the parent process.

  3. The 32-bit Windows system directory.  Use the GetSystemDirectory() function to get the path of this directory.

  4. The 16-bit Windows system directory.  There is no function that obtains the path of this directory, but it is searched.

  5. The Windows directory.  Use the GetWindowsDirectory() function to get the path of this directory.

  6. 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:

  1. ERROR_INVALID_PARAMETER - Invalid parameter.

  2. ERROR_UNKNOWN_REVISION - The SDDL revision level is invalid.

  3. ERROR_NONE_MAPPED - A SID in the input security descriptor string could not be found in an account lookup operation.

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.

  1. OWNER_SECURITY_INFORMATION - Include the owner.

  2. GROUP_SECURITY_INFORMATION - Include the primary group.

  3. DACL_SECURITY_INFORMATION - Include the DACL.

  4. SACL_SECURITY_INFORMATION - Include the SACL.

 

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:

  1. ERROR_INVALID_PARAMETER - Invalid parameter.

  2. ERROR_UNKNOWN_REVISION - The revision level is invalid.

  3. ERROR_NONE_MAPPED - A SID in the input security descriptor could not be found in an account lookup operation.

  4. ERROR_INVALID_ACL - Invalid ACL.  This error is returned if the SE_DACL_PRESENT flag is set in the input security descriptor and the DACL is NULL.

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

 

GlobalAlloc()

 

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.

  1. GMEM_DDESHARE

  2. GMEM_DISCARDABLE

  3. GMEM_LOWER

  4. GMEM_NOCOMPACT

  5. GMEM_NODISCARD

  6. GMEM_NOT_BANKED

  7. GMEM_NOTIFY

  8. 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:

  1. LMEM_MOVEABLE - Allocates fixed or movable memory, depending on how the memory was originally allocated with LocalAlloc().  If LocalAlloc() was called with LMEM_MOVEABLE, the return value is a handle to the memory object.  To convert the handle to a pointer, use the LocalLock() function.  If LocalAlloc() was called with LMEM_FIXED, the return value is a pointer to the memory object.

  2. LMEM_ZEROINIT - Causes the additional memory contents to be initialized to zero if the memory object is growing in size.

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.

  1. LHND - Combines LMEM_MOVEABLE and LMEM_ZEROINIT.

  2. LMEM_FIXED - Allocates fixed memory.  The return value is a pointer to the memory object.

  3. LMEM_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 to a pointer, use the LocalLock() function.  This value cannot be combined with LMEM_FIXED.

  4. LMEM_ZEROINIT - Initializes memory contents to zero.

  5. LPTR - Combines LMEM_FIXED and LMEM_ZEROINIT.

  6. NONZEROLHND - Same as LMEM_MOVEABLE.

  7. NONZEROLPTR - Same as LMEM_FIXED.

 

The following values are obsolete, but are provided for compatibility with 16-bit Windows.  They are ignored.

  1. LMEM_DISCARDABLE

  2. LMEM_NOCOMPACT

  3. LMEM_NODISCARD

 

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:

  1. DACL_SECURITY_INFORMATION - If this flag is set, the ppDacl parameter receives the object's DACL.

  2. GROUP_SECURITY_INFORMATION - If this flag is set, the ppsidGroup parameter receives the SID of the object's primary group.

  3. OWNER_SECURITY_INFORMATION - If this flag is set, the ppsidOwner parameter receives the SID of the object's owner.

  4. SACL_SECURITY_INFORMATION - If this flag is set, the ppSacl parameter receives the object's SACL.

 

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:

  1. Local or remote files or directories on an NTFS file system.

  2. Local or remote printers.

  3. Local or remote Windows services.

  4. Network shares.

  5. Registry keys.

  6. Semaphores, events, mutexes, and waitable timers.

  7. File-mapping objects.

  8. 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 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:

  1. GRANT_ACCESS

  2. SET_ACCESS

  3. DENY_ACCESS

  4. 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:

  1. REVOKE_ACCESS

  2. SET_AUDIT_FAILURE

  3. 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:

  1. DACL_SECURITY_INFORMATION - Sets the DACL in the security descriptor of the object.  The pDacl parameter is a pointer to the new DACL.  If neither PROTECTED_DACL_SECURITY_INFORMATION nor UNPROTECTED_DACL_SECURITY_INFORMATION is set, the current inheritance settings are preserved.

  2. GROUP_SECURITY_INFORMATION - Sets the primary group SID in the security descriptor of the object.  The psidGroup parameter is a pointer to the new SID.

  3. OWNER_SECURITY_INFORMATION - Sets the owner SID in the security descriptor of the object.  The psidOwner parameter is a pointer to the new SID.

  4. PROTECTED_DACL_SECURITY_INFORMATION - Protects the DACL from inheriting ACEs.  This value is ignored unless DACL_SECURITY_INFORMATION is also used.

  5. PROTECTED_SACL_SECURITY_INFORMATION - Protects the SACL from inheriting ACEs.  This value is ignored unless SACL_SECURITY_INFORMATION is also used.

  6. SACL_SECURITY_INFORMATION - Sets the SACL in the security descriptor of the object.  The pSacl parameter is a pointer to the new SACL.  If neither PROTECTED_SACL_SECURITY_INFORMATION nor UNPROTECTED_SACL_SECURITY_INFORMATION is set, the current inheritance settings are preserved.

  7. UNPROTECTED_DACL_SECURITY_INFORMATION - Inherits ACEs from the parent whenever applicable.  This value is ignored unless DACL_SECURITY_INFORMATION is also used.

  8. UNPROTECTED_SACL_SECURITY_INFORMATION - Inherits ACEs from the parent whenever applicable.  This value is ignored unless SACL_SECURITY_INFORMATION is also used.

 

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:

  1. Local or remote files or directories on an NTFS.

  2. Local or remote printers.

  3. Local or remote Windows services.

  4. Network shares.

  5. Registry keys.

  6. Semaphores, events, mutexes, and waitable timers.

  7. File-mapping objects.

  8. 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:

  1. pMultipleTrustee NULL

  2. MultipleTrusteeOperation - NO_MULTIPLE_TRUSTEE

  3. TrusteeForm - TRUSTEE_IS_SID

  4. TrusteeType - TRUSTEE_IS_UNKNOWN

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:

  1. pMultipleTrustee NULL

  2. MultipleTrusteeOperation - NO_MULTIPLE_TRUSTEE

  3. TrusteeForm - TRUSTEE_IS_NAME

  4. TrusteeType - TRUSTEE_IS_UNKNOWN

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

 

LookupPrivilegeValue()

 

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

 

LookupPrivilegeDisplayName()

 

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

 

AdjustTokenPrivileges()

 

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.

  1. SE_PRIVILEGE_ENABLED - The function enables the privilege.

  2. SE_PRIVILEGE_REMOVED - The privilege is removed from the list of privileges in the token.  The other privileges in the list are reordered to remain contiguous. SE_PRIVILEGE_REMOVED supersedes SE_PRIVILEGE_ENABLED. Because the privilege has been removed from the token, attempts to re enable the privilege result in the warning ERROR_NOT_ALL_ASSIGNED as if the privilege had never existed.  Attempting to remove a privilege that does not exist in the token results in ERROR_NOT_ALL_ASSIGNED being returned.  Privilege checks for removed privileges result in STATUS_PRIVILEGE_NOT_HELD.  Failed privilege check auditing occurs as normal.  The removal of the privilege is irreversible, so the name of the removed privilege is not included in the PreviousState parameter after a call to AdjustTokenPrivilege().

 

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:

  1. ERROR_SUCCESS - The function adjusted all specified privileges.

  2. ERROR_NOT_ALL_ASSIGNED - The token does not have one or more of the privileges specified in the NewState parameter.  The function may succeed with this error value even if no privileges were adjusted.  The PreviousState parameter indicates the privileges that were adjusted.

 

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.

 

GetTokenInformation()

 

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:

  1. NULL - The function returns ERROR_INSUFFICIENT_BUFFER and stores the size required for the buffer in ReturnLength.  The caller can then allocate a buffer with the required size and pass the address of the buffer as TokenInformation in another call to this function.

  2. TokenDefaultDacl - The buffer receives a TOKEN_DEFAULT_DACL structure containing the default DACL for newly created objects.

  3. TokenGroups - The buffer receives a TOKEN_GROUPS structure containing the group accounts associated with the token.

  4. TokenGroupsAndPrivileges - The buffer receives a TOKEN_GROUPS_AND_PRIVILEGES structure containing the user SID, the group accounts, the restricted SIDs, and the authentication ID associated with the token.

  5. TokenImpersonationLevel - The buffer receives a SECURITY_IMPERSONATION_LEVEL value indicating the impersonation level of the token.  If the access token is not an impersonation token, the function fails.

  6. TokenOrigin - The buffer receives a TOKEN_ORIGIN value that contains information about the logon session ID.

  7. TokenOwner - The buffer receives a TOKEN_OWNER structure containing the default owner SID for newly created objects.

  8. TokenPrimaryGroup - The buffer receives a TOKEN_PRIMARY_GROUP structure containing the default primary group SID for newly created objects.

  9. TokenPrivileges - The buffer receives a TOKEN_PRIVILEGES structure containing the token's privileges.

  10. TokenRestrictedSids - The buffer receives a TOKEN_GROUPS structure containing the list of restricting SIDs in a restricted token.

  11. TokenSandBoxInert - The buffer receives a DWORD value that is nonzero if the token includes the SANDBOX_INERT flag.

  12. TokenSessionId - The buffer receives a DWORD value that contains the Terminal Services session identifier associated with the token.  If the token is associated with the Terminal Server console session, the session identifier is zero.  A nonzero session identifier indicates a Terminal Services client session.  In a non-Terminal Services environment, the session identifier is zero.

  13. TokenSource - The buffer receives a TOKEN_SOURCE structure containing the source of the token. TOKEN_QUERY_SOURCE access is needed to retrieve this information.

  14. TokenStatistics - The buffer receives a TOKEN_STATISTICS structure containing various token statistics.

  15. TokenType - The buffer receives a TOKEN_TYPE value indicating whether the token is a primary or impersonation token.

  16. TokenUser - The buffer receives a TOKEN_USER structure containing the token's user account.

 

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

 

CheckTokenMembership()

 

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:

If the value is AclRevisionInformation, the function fills the buffer pointed to by the pAclInformation parameter with an ACL_REVISION_INFORMATION structure. If the value is AclSizeInformation, the function fills the buffer pointed to by the pAclInformation parameter with an ACL_SIZE_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 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:

  1. DACL_SECURITY_INFORMATION - If this flag is set, the ppDacl parameter receives the object's DACL.

  2. GROUP_SECURITY_INFORMATION - If this flag is set, the ppsidGroup parameter receives the security identifier (SID) of the object's primary group.

  3. OWNER_SECURITY_INFORMATION - If this flag is set, the ppsidOwner parameter receives the SID of the object's owner.

  4. SACL_SECURITY_INFORMATION - If this flag is set, the ppSacl parameter receives the object's SACL.

 

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:

  1. Local or remote files or directories on an NTFS file system.

  2. Local or remote printers.

  3. Local or remote Windows services.

  4. Network shares.

  5. Registry keys.

  6. Semaphores, events, mutexes, and waitable timers.

  7. File-mapping objects.

  8. 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:

  1. Implicitly granted access rights, such as READ_CONTROL and WRITE_DAC, for the owner of an object when determining effective rights.

  2. Privileges held by the trustee when determining effective access rights.

  3. Group rights associated with the logon session, such as interactive, network, authenticated users, and so forth, in determining effective access rights.

  4. 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:

  1. DACL_SECURITY_INFORMATION - If this flag is set, the ppDacl parameter receives the object's DACL.

  2. GROUP_SECURITY_INFORMATION - If this flag is set, the ppsidGroup parameter receives the security identifier (SID) of the object's primary group.

  3. OWNER_SECURITY_INFORMATION - If this flag is set, the ppsidOwner parameter receives the SID of the object's owner.

  4. SACL_SECURITY_INFORMATION - If this flag is set, the ppSacl parameter receives the object's SACL.

 

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:

  1. Local or remote files or directories on an NTFS file system.

  2. Named pipes.

  3. Local or remote printers.

  4. Local or remote Windows services.

  5. Network shares.

  6. Registry keys.

  7. Semaphores, events, mutexes, and waitable timers.

  8. Processes, threads, jobs, and file-mapping objects.

  9. Interactive service window stations and desktops.

  10. 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:

  1. GRANT_ACCESS.

  2. SET_ACCESS.

  3. DENY_ACCESS.

  4. 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:

  1. REVOKE_ACCESS.

  2. SET_AUDIT_FAILURE.

  3. 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.

 

SetTokenInformation()

 

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.

  1. TokenDefaultDacl - Specifies a TOKEN_DEFAULT_DACL structure. The TOKEN_ADJUST_DEFAULT access right is needed to set information in the default DACL.  The ACL structure provided as a new default DACL is not validated for correctness or consistency.  If the TokenInformation parameter is NULL, the current default DACL is removed and no replacement is established.

  2. TokenOrigin - Specifies a TOKEN_ORIGIN structure, with the OriginatingLogonSession() member of TOKEN_ORIGIN set to a LUID that represents the token origin.  The token origin can be set only if it has not previously been set.  The SE_TCB_NAME privilege is needed to set the token origin.

  3. TokenOwner - Specifies a TOKEN_OWNER structure.  The TOKEN_ADJUST_DEFAULT access right is needed to set owner information.  A valid owner value is a user or group identifier with an attribute allowing assignment as the owner of objects.

  4. TokenPrimaryGroup - Specifies a TOKEN_PRIMARY_GROUP structure.  The TOKEN_ADJUST_DEFAULT access right is needed to set primary group information.

  5. TokenSessionId - The buffer receives a DWORD value that indicates the Terminal Services session identifier associated with the token.  If the token is associated with the Terminal Server console session, the session identifier is zero.  A nonzero session identifier indicates a Terminal Services client session.  In a non-Terminal Services environment, the session identifier is zero.  The process must have the SE_TCB_NAME privilege and must be enabled to set the session ID in a token.  For Windows 2000 Server, this value is supported only if Terminal Services is enabled.

 

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.

 

DuplicateToken()

 

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

 

DuplicateTokenEx()

 

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:

  1. TokenPrimary - The new token is a primary token that you can use in the CreateProcessAsUser() function.

  2. TokenImpersonation - The new token is an impersonation token.

 

phNewToken - [out] Pointer to a HANDLE variable that receives the new token.

Return value

If the function succeeds, the function returns a nonzero value.  If the function fails, it returns zero.  To get extended error information, call GetLastError().

Include file

<windows.h>

Remark

-

 

Table 50

 

The DuplicateTokenEx() function allows you to create a primary token that you can use in the CreateProcessAsUser() function.  This allows a server application that is impersonating a client to create a process that has the security context of the client.  Note that the DuplicateToken() function can create only impersonation tokens, which are not valid for CreateProcessAsUser().  The following is a typical scenario for using DuplicateTokenEx() to create a primary token.  A server application creates a thread that calls one of the impersonation functions, such as ImpersonateNamedPipeClient(), to impersonate a client.  The impersonating thread then calls the OpenThreadToken() function to get its own token, which is an impersonation token that has the security context of the client.  The thread specifies this impersonation token in a call to DuplicateTokenEx(), specifying the TokenPrimary flag.  The DuplicateTokenEx() function creates a primary token that has the security context of the client.  When you have finished using the new token, call the CloseHandle() function to close the token handle.

 

ImpersonateLoggedOnUser()

 

Item

Description

Function

ImpersonateLoggedOnUser().

Use

To let the calling thread impersonates the security context of a logged-on user.  The user is represented by a token handle.

Prototype

BOOL ImpersonateLoggedOnUser(HANDLE  hToken);

Parameters

hToken - [in] Handle to a primary or impersonation access token that represents a logged-on user.  This can be a token handle returned by a call to LogonUser(), CreateRestrictedToken(), DuplicateToken(), DuplicateTokenEx(), OpenProcessToken(), or OpenThreadToken() functions.  If hToken is a primary token, it must have TOKEN_QUERY and TOKEN_DUPLICATE access.  If hToken is an impersonation token, it must have TOKEN_QUERY and TOKEN_IMPERSONATE access.

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 51

 

The impersonation lasts until the thread exits or until it calls RevertToSelf().  The calling thread does not need to have any particular privileges to call ImpersonateLoggedOnUser().  If the call to ImpersonateLoggedOnUser() fails, the client connection is not impersonated and the client request is made in the security context of the process.  If the process is running as a highly privileged account, such as LocalSystem, or as a member of an administrative group, the user may be able to perform actions they would otherwise be disallowed.  Therefore, it is important to always check the return value of the call, and if it fails, raise an error; do not continue execution of the client request.  All impersonate functions, including ImpersonateLoggedOnUser(), check to determine if the caller has the SeImpersonatePrivilege privilege.  If the caller has the SeImpersonatePrivilege privilege, or if the authenticated identity is the same as the caller, then the requested impersonation is allowed.  Otherwise, the impersonation succeeds at Identify level only.

 

ImpersonateSelf()

 

Item

Description

Function

ImpersonateSelf().

Use

To obtain an access token that impersonates the security context of the calling process.  The token is assigned to the calling thread.

Prototype

BOOL ImpersonateSelf( SECURITY_IMPERSONATION_LEVEL ImpersonationLevel );

Parameters

ImpersonationLevel - [in] Specifies a SECURITY_IMPERSONATION_LEVEL enumerated type that supplies the impersonation level of 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

-

 

Table 52

 

The ImpersonateSelf() function is used for tasks such as enabling a privilege for a single thread rather than for the entire process or for changing the default discretionary DACL for a single thread.  The server can call the RevertToSelf() function when the impersonation is complete.  For this function to succeed, the DACL protecting the process token must grant the TOKEN_DUPLICATE right to itself.

 

ImpersonateAnonymousToken()

 

Item

Description

Function

ImpersonateAnonymousToken().

Use

To enable the specified thread to impersonate the system's anonymous logon token. To ensure that a token matches the operating system's concept of anonymous access, this function should be called before attempting network access to generate an anonymous token on the remote server.

Prototype

BOOL ImpersonateAnonymousToken(HANDLE ThreadHandle);

Parameters

ThreadHandle - [in] Handle to the thread to impersonate the system's anonymous logon 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(). An error of ACCESS_DENIED may indicate that the token is for a restricted process.  Use OpenProcessToken() and IsTokenRestricted() to check if the process is restricted.

Include file

<windows.h>

Remark

-

 

Table 53

 

Anonymous tokens do not include the Everyone Group SID unless the system default has been overridden by setting the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\EveryoneIncludesAnonymous registry value to DWORD = 1.  For Windows 2000, an anonymous token includes the Everyone group SID.  To cancel the impersonation call RevertToSelf().  All impersonate functions, including ImpersonateAnonymousToken(), check to determine if the caller has the SeImpersonatePrivilege privilege.  If the caller has the SeImpersonatePrivilege privilege, or if the authenticated identity is the same as the caller, then the requested impersonation is allowed otherwise, the impersonation succeeds at Identify level only.

 

ImpersonateNamedPipeClient()

 

Item

Description

Function

ImpersonateNamedPipeClient().

Use

To  impersonate a named-pipe client application.

Prototype

BOOL ImpersonateNamedPipeClient(HANDLE hNamedPipe);

Parameters

hNamedPipe - [in] Handle to a named pipe.

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 54

 

The ImpersonateNamedPipeClient() function allows the server end of a named pipe to impersonate the client end. When this function is called, the named-pipe file system changes the thread of the calling process to start impersonating the security context of the last message read from the pipe.  Only the server end of the pipe can call this function.  The server can call the RevertToSelf() function when the impersonation is complete.  Important:  If the ImpersonateNamedPipeClient() function fails, the client is not impersonated, and all subsequent client requests are made in the security context of the process that called the function.  If the calling process is running as a privileged account, it can perform actions that the client would not be allowed to perform.  To avoid security risks, the calling process should always check the return value.  If the return value indicates that the function call failed, no client requests should be executed.  All impersonate functions, including ImpersonateNamedPipeClient(), check to determine if the caller has the SeImpersonatePrivilege privilege.  If the caller has the SeImpersonatePrivilege privilege, or if the authenticated identity is the same as the caller, then the requested impersonation is allowed otherwise, the impersonation succeeds at Identify level only.

 

RevertToSelf()

 

Item

Description

Function

RevertToSelf().

Use

To terminate the impersonation of a client application.

Prototype

BOOL RevertToSelf(void);

Parameters

This function has no parameters.

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 55

 

A process should call the RevertToSelf() function after finishing any impersonation begun by using the DdeImpersonateClient(), ImpersonateDdeClientWindow(), ImpersonateLoggedOnUser(), ImpersonateNamedPipeClient(), ImpersonateSelf(), ImpersonateAnonymousToken() or SetThreadToken() function.  An RPC server that used the RpcImpersonateClient() function to impersonate a client must call the RpcRevertToSelf() or RpcRevertToSelfEx() to end the impersonation.

If RevertToSelf() fails, your application continues to run in the context of the client, which is not appropriate. You should shut down the process if RevertToSelf() fails.

 

AddAuditAccessObjectAce()

 

Item

Description

Function

AddAuditAccessObjectAce().

Use

To add a system-audit ACE to the end of a SACL.  The new ACE can audit access to an object, or to a property set or property on an object.  You can also use AddAuditAccessObjectAce() to add an ACE that only a specified type of child object can inherit.

Prototype

BOOL AddAuditAccessObjectAce( PACL pAcl, DWORD dwAceRevision, DWORD AceFlags, DWORD AccessMask, GUID* ObjectTypeGuid, GUID* InheritedObjectTypeGuid, PSID pSid, BOOL bAuditSuccess, BOOL bAuditFailure );

Parameters

See below.

Return value

See below.

Include file

<windows.h>

Remark

-

 

Table 56

 

pAcl - [in, out] Pointer to a SACL.  The AddAuditAccessObjectAce function adds a system-audit ACE to the end of this SACL.  The ACE is in the form of a SYSTEM_AUDIT_OBJECT_ACE structure.

dwAceRevision - [in] Specifies the revision level of the SACL being modified.  This value must be ACL_REVISION_DS.  If the SACL's revision level is lower than ACL_REVISION_DS, the function changes it to ACL_REVISION_DS.

AceFlags - [in] A set of bit flags that control ACE inheritance and the type of access attempts to audit.  The function sets these flags in the AceFlags member of the ACE_HEADER structure of the new ACE.  This parameter can be a combination of the following values.

 

Value

Meaning

CONTAINER_INHERIT_ACE

The ACE is inherited by container objects.

FAILED_ACCESS_ACE_FLAG

If you set this flag or specify TRUE for the bAuditFailure parameter, failed attempts to use the specified access rights cause the system to generate an audit record in the security event log.

INHERIT_ONLY_ACE

The ACE does not apply to the object to which the ACL is assigned, but it can be inherited by child objects.

INHERITED_ACE

Indicates an inherited ACE. This flag allows operations that change the security on a tree of objects to modify inherited ACEs, while not changing ACEs that were directly applied to the object.

NO_PROPAGATE_INHERIT_ACE

The OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE bits are not propagated to an inherited ACE.

OBJECT_INHERIT_ACE

The ACE is inherited by non container objects.

SUCCESSFUL_ACCESS_ACE_FLAG

If you set this flag or specify TRUE for the bAuditSuccess parameter, successful uses of the specified access rights cause the system to generate an audit record in the security event log.

 

Table 57

 

AccessMask - [in] An ACCESS_MASK that specifies the access rights that the new ACE audits for the specified SID.

ObjectTypeGuid - [in] Pointer to a GUID structure that identifies the type of object, property set, or property protected by the new ACE.  If this parameter is NULL, the new ACE protects the object to which the ACL is assigned.

InheritedObjectTypeGuid - [in] Pointer to a GUID structure that identifies the type of object that can inherit the new ACE.  If this parameter is non-NULL, only the specified object type can inherit the ACE.  If NULL, any type of child object can inherit the ACE.  In either case, inheritance is also controlled by the value of the AceFlags parameter, as well as by any protection against inheritance placed on the child objects.

pSid - [in] Pointer to a SID that identifies the user, group, or logon session for which the new ACE audits access.

bAuditSuccess - [in] Specifies whether successful uses of the specified access rights cause the system to generate an audit record in the security event log.  If this flag is TRUE or if the AceFlags parameter specifies the SUCCESSFUL_ACCESS_ACE_FLAG flag, the system records successful access attempts; otherwise, it does not.

bAuditFailure - [in] Specifies whether failed attempts to use the specified access rights cause the system to generate an audit record in the security event log.  If this flag is TRUE or if the AceFlags parameter specifies the FAILED_ACCESS_ACE_FLAG flag, the system records failed access attempts; otherwise, it does not.

 

Return Values

 

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 following are possible error values.

 

Return code

Description

ERROR_ALLOTTED_SPACE_EXCEEDED

The new ACE does not fit into the ACL. A larger ACL buffer is required.

ERROR_INVALID_ACL

The specified ACL is not properly formed.

ERROR_INVALID_FLAGS

The AceFlags parameter is invalid.

ERROR_INVALID_SID

The specified SID is not structurally valid.

ERROR_REVISION_MISMATCH

The specified revision is not known or is incompatible with that of the ACL.

ERROR_SUCCESS

The ACE was successfully added.

 

Table 58

 

If both ObjectTypeGuid and InheritedObjectTypeGuid are NULL, use the AddAuditAccessAceEx() function rather than AddAuditAccessObjectAce().  This is suggested because a SYSTEM_AUDIT_ACE is smaller and more efficient than a SYSTEM_AUDIT_OBJECT_ACE.

 

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] Pointer to an ACL structure from which to get ACE information.

pcCountOfExplicitEntries - [out] Pointer to a variable that receives the number of EXPLICIT_ACCESS structures returned in the pListOfExplicitEntries array.

pListOfExplicitEntries - [out] 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 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 59

 

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.

 

BuildExplicitAccessWithName()

 

Item

Description

Function

BuildExplicitAccessWithName().

Use

To initialize an EXPLICIT_ACCESS structure with data specified by the caller.  The trustee is identified by a name string.

Prototype

VOID BuildExplicitAccessWithName( PEXPLICIT_ACCESS pExplicitAccess, LPTSTR pTrusteeName,  DWORD AccessPermissions, ACCESS_MODE AccessMode, DWORD Inheritance );

Parameters

See below.

Return value

This function does not return a value.

Include file

<aclapi.h>

Remark

Implemented as Unicode and ANSI versions.

 

Table 60

 

pExplicitAccess - [in, out] Pointer to an EXPLICIT_ACCESS structure to initialize.  The BuildExplicitAccessWithName() function does not allocate any memory.  This parameter cannot be NULL.

pTrusteeName - [in] Pointer to a null-terminated string that contains the name of the trustee for the ptstrName member of the TRUSTEE structure.  The BuildExplicitAccessWithName() function sets the other members of the TRUSTEE structure as follows.

 

Value

Meaning

pMultipleTrustee

NULL

MultipleTrusteeOperation

NO_MULTIPLE_TRUSTEE

TrusteeForm

TRUSTEE_IS_NAME

TrusteeType

TRUSTEE_IS_UNKNOWN

 

Table 61

 

AccessPermissions - [in] Specifies an access mask for the grfAccessPermissions member of the EXPLICIT_ACCESS structure.  The mask is a set of bit flags that use the ACCESS_MASK format to specify the access rights that an ACE allows, denies, or audits for the trustee.  The functions that use the EXPLICIT_ACCESS structure do not convert, interpret, or validate the bits in this mask.

AccessMode - [in] Specifies an access mode for the grfAccessMode member of the EXPLICIT_ACCESS structure.  The access mode indicates whether the ACE allows, denies, or audits the specified rights.  For a DACL, this parameter can be one of the values from the ACCESS_MODE enumeration.  For a SACL, this parameter can be a combination of ACCESS_MODE values.

Inheritance - [in] Specifies an inheritance type for the grfInheritance member of the EXPLICIT_ACCESS structure.  This value is a set of bit flags that determine whether other containers or objects can inherit the ACE from the primary object to which the ACL is attached.  The value of this member corresponds to the inheritance portion (low-order byte) of the AceFlags member of the ACE_HEADER structure.  This parameter can be NO_INHERITANCE to indicate that the ACE is not inheritable, or it can be a combination of the following values:

 

Value

Meaning

CONTAINER_INHERIT_ACE

Other containers that are contained by the primary object inherit the ACE.

INHERIT_ONLY_ACE

The ACE does not apply to the primary object to which the ACL is attached, but objects contained by the primary object inherit the ACE.

NO_PROPAGATE_INHERIT_ACE

The OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE flags are not propagated to an inherited ACE.

OBJECT_INHERIT_ACE

Non container objects contained by the primary object inherit the ACE.

SUB_CONTAINERS_AND_OBJECTS_INHERIT

Both containers and non container objects that are contained by the primary object inherit the ACE.  This flag corresponds to the combination of the CONTAINER_INHERIT_ACE and OBJECT_INHERIT_ACE flags.

SUB_CONTAINERS_ONLY_INHERIT

Other containers that are contained by the primary object inherit the ACE.  This flag corresponds to the CONTAINER_INHERIT_ACE flag.

SUB_OBJECTS_ONLY_INHERIT

Non container objects contained by the primary object inherit the ACE.  This flag corresponds to the OBJECT_INHERIT_ACE flag.

 

Table 62

 

BuildSecurityDescriptor()

 

Item

Description

Function

BuildSecurityDescriptor().

Use

To allocate and initialize a new security descriptor.  This function can initialize the new security descriptor by merging specified security information with the information in an existing security descriptor.  If you do not specify an existing security descriptor, the function initializes a new security descriptor based on the specified security information.  The BuildSecurityDescriptor() function creates a self-relative security descriptor.  The self-relative format makes the security descriptor suitable for storing in a stream.

Prototype

DWORD BuildSecurityDescriptor( PTRUSTEE pOwner, PTRUSTEE pGroup, ULONG cCountOfAccessEntries, PEXPLICIT_ACCESS pListOfAccessEntries, ULONG cCountOfAuditEntries, PEXPLICIT_ACCESS pListOfAuditEntries, PSECURITY_DESCRIPTOR pOldSD, PULONG pSizeNewSD, PSECURITY_DESCRIPTOR* pNewSD );

Parameters

pOwner - [in] Pointer to a TRUSTEE structure that identifies the owner for the new security descriptor.  If the structure uses the TRUSTEE_IS_NAME form, BuildSecurityDescriptor() looks up the SID associated with the specified trustee name.  If this parameter is NULL, the function uses the owner SID from the original security descriptor pointed to by pOldSD.  If pOldSD is NULL, or if the owner SID in pOldSD is NULL, the owner SID is NULL in the new security descriptor.

pGroup - [in] Pointer to a TRUSTEE structure that identifies the primary group SID for the new security descriptor.  If the structure uses the TRUSTEE_IS_NAME form, BuildSecurityDescriptor() looks up the SID associated with the specified trustee name.  If this parameter is NULL, the function uses the group SID from the original security descriptor pointed to by pOldSD.  If pOldSD is NULL, or if the group SID in pOldSD is NULL, the group SID is NULL in the new security descriptor.

cCountOfAccessEntries - [in] Specifies the number of EXPLICIT_ACCESS structures in the pListOfAccessEntries array.

pListOfAccessEntries - [in] Pointer to an array of EXPLICIT_ACCESS structures that describe access control information for the DACL of the new security descriptor.  The function creates the new DACL by merging the information in the array with the DACL in pOldSD, if any.  If pOldSD is NULL, or if the DACL in pOldSD is NULL, the function creates a new DACL based solely on the information in the array.  If pListOfAccessEntries is NULL, the new security descriptor gets the DACL from pOldSD.  In this case, if pOldSD is NULL, or if the DACL in pOldSD is NULL, the new DACL is NULL.

cCountOfAuditEntries - [in] Specifies the number of EXPLICIT_ACCESS structures in the pListOfAuditEntries array.

pListOfAuditEntries - [in] Pointer to an array of EXPLICIT_ACCESS structures that describe audit control information for the SACL of the new security descriptor.  The function creates the new SACL by merging the information in the array with the SACL in pOldSD, if any.  If pOldSD is NULL, or the SACL in pOldSD is NULL, the function creates a new SACL based solely on the information in the array.  If pListOfAuditEntries is NULL, the new security descriptor gets the SACL from pOldSD.  In this case, if pOldSD is NULL, or the SACL in pOldSD is NULL, the new SACL is NULL.

pOldSD - [in] Pointer to an existing self-relative SECURITY_DESCRIPTOR structure and its associated security information.  The function builds the new security descriptor by merging the specified owner, group, access control, and audit-control information with the information in this security descriptor.  This parameter can be NULL.

pSizeNewSD - [in] Pointer to a variable that receives the size, in bytes, of the security descriptor.

pNewSD - [in] Pointer to a variable that receives a pointer to the new security descriptor. The function allocates memory for the new security descriptor.  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 63

 

The BuildSecurityDescriptor() function is intended for trusted servers that implement or expose security on their own objects.  The function uses self-relative security descriptors suitable for serializing into a stream and storing to disk, as a trusted server might require.

 

AllocateAndInitializeSid()

 

Item

Description

Function

AllocateAndInitializeSid().

Use

To allocate and initialize a security identifier (SID) with up to eight sub authorities.

Prototype

BOOL AllocateAndInitializeSid( PSID_IDENTIFIER_AUTHORITY pIdentifierAuthority, BYTE nSubAuthorityCount, DWORD dwSubAuthority0, DWORD dwSubAuthority1, DWORD dwSubAuthority2, DWORD dwSubAuthority3, DWORD dwSubAuthority4, DWORD dwSubAuthority5, DWORD dwSubAuthority6, DWORD dwSubAuthority7, PSID* pSid );

Parameters

pIdentifierAuthority - [in] Pointer to a SID_IDENTIFIER_AUTHORITY structure.  This structure provides the top-level identifier authority value to set in the SID.

nSubAuthorityCount - [in] Specifies the number of sub authorities to place in the SID.  This parameter also identifies how many of the sub authority parameters have meaningful values.  This parameter must contain a value from 1 to 8.  For example, a value of 3 indicates that the sub authority values specified by the dwSubAuthority0, dwSubAuthority1, and dwSubAuthority2 parameters have meaningful values and to ignore the remainder.

  1. dwSubAuthority0 - [in] Sub authority value to place in the SID.

  2. dwSubAuthority1 - [in] Sub authority value to place in the SID.

  3. dwSubAuthority2 - [in] Sub authority value to place in the SID.

  4. dwSubAuthority3 - [in] Sub authority value to place in the SID.

  5. dwSubAuthority4 - [in] Sub authority value to place in the SID.

  6. dwSubAuthority5 - [in] Sub authority value to place in the SID.

  7. dwSubAuthority6 - [in] Sub authority value to place in the SID.

  8. dwSubAuthority7 - [in] Sub authority value to place in the SID.

 

pSid - [out] Pointer to a variable that receives the pointer to the allocated and initialized SID structure.

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 64

 

A SID allocated with the AllocateAndInitializeSid() function must be freed by using the FreeSid() function.  This function creates a SID with a 32-bit RID value.  For applications that require longer RID values, use CreateWellKnownSid().

 

FreeSid()

 

Item

Description

Function

FreeSid().

Use

To free a security identifier (SID) previously allocated by using the AllocateAndInitializeSid() function.

Prototype

PVOID FreeSid(PSID pSid);

Parameters

pSid - [in] Pointer to the SID structure to free.

Return value

This function does not return a value.

Include file

<windows.h>

Remark

 

 

Table 65

 

CreateWellKnownSid()

 

Item

Description

Function

CreateWellKnownSid().

Use

Creates a SID for predefined aliases.

Prototype

BOOL CreateWellKnownSid( WELL_KNOWN_SID_TYPE WellKnownSidType, PSID DomainSid, PSID pSid, DWORD* cbSid );

Parameters

WellKnownSidType - [in] Member of the WELL_KNOWN_SID_TYPE enumeration that specifies what the SID will identify.

DomainSid - [in, optional] Pointer to a SID that identifies the domain control to use when creating the SID.  Pass NULL to use the local computer.

pSid - [out] Pointer to memory where CreateWellKnownSid() will store the new SID.

cbSid - [in, out] Pointer to a DWORD that contains the number of bytes available at pSid.  The CreateWellKnownSid() function stores the number of bytes actually used at this location.

Return value

If the function succeeds, the return value is nonzero.  If the function fails, the return value is zero.  For extended error information, call GetLastError().

Include file

<windows.h>

Remark

 

 

Table 66

 

IsWellKnownSid()

 

Item

Description

Function

IsWellKnownSid().

Use

To compare a SID to a well known SID and returns TRUE if they match.

Prototype

BOOL IsWellKnownSid( PSID pSid, WELL_KNOWN_SID_TYPE WellKnownSidType );

Parameters

pSid - [in] Pointer to the SID to test.

WellKnownSidType - [in] Member of the WELL_KNOWN_SID_TYPE enumeration to compare with the SID at pSid.

Return value

Returns TRUE if the SID at pSid matches the well known SID indicated by WellKnownSidType.  Otherwise, returns FALSE.

Include file

<windows.h>

Remark

Implemented as Unicode and ANSI versions.

 

Table 67

 

SecureZeroMemory()

 

Item

Description

Function

SecureZeroMemory().

Use

To fill a block of memory with zeros.  It is designed to be a more secure version of ZeroMemory() macro.

Prototype

PVOID SecureZeroMemory( PVOID ptr, SIZE_T cnt );

Parameters

ptr - [in] Pointer to the starting address of the block of memory to fill with zeros.

cnt - [in] Size of the block of memory to fill with zeros, in bytes.

Return value

This function returns a pointer to the block of memory.

Include file

<windows.h>

Remark

-

 

Table 68

 

This function is defined as the RtlSecureZeroMemory() function.  Its implementation is provided inline. Use this function instead of ZeroMemory() when you want to ensure that your data will be overwritten promptly, as the compiler can optimize a call to ZeroMemory() by removing it entirely.  A call to SecureZeroMemory() will not be optimized. The following code fragment shows an instance where the use of SecureZeroMemory() would be used instead of ZeroMemory().

void Sample()

{

  WCHAR szPassword[MAX_PATH];

  // this function retrieves a password

  if(GetThePasswordFromUser(szPassword, MAX_PATH))

     UseThePassword(szPassword);

  // clear the password from memory

  SecureZeroMemory(szPassword, sizeof(szPassword));

}

 

If ZeroMemory() were called in this example instead of SecureZeroMemory(), the compiler could optimize the call because the szPassword buffer is not read from before it goes out of scope.  The password would remain on the application stack where it could be captured in a crash dump or probed by a malicious application.

 

RegCreateKeyEx()

 

Item

Description

Function

RegCreateKeyEx().

Use

To create the specified registry key. If the key already exists, the function opens it.

Prototype

LONG RegCreateKeyEx( HKEY hKey, LPCTSTR lpSubKey, DWORD Reserved, LPTSTR lpClass, DWORD dwOptions, REGSAM samDesired, LPSECURITY_ATTRIBUTES lpSecurityAttributes, PHKEY phkResult, LPDWORD lpdwDisposition );

Parameters

See below.

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.  You can use the FormatMessage() function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

Include file

<windows.h>

Remark

Implemented as Unicode and ANSI versions.

 

Table 69

 

hKey - [in] Handle to an open key.  The calling process must have KEY_CREATE_SUB_KEY access to the key.  This handle is returned by the RegCreateKeyEx() or RegOpenKeyEx() function or it can be one of the following predefined keys:

  1. HKEY_CLASSES_ROOT

  2. HKEY_CURRENT_CONFIG

  3. HKEY_CURRENT_USER

  4. HKEY_LOCAL_MACHINE

  5. HKEY_USERS

 

Windows Me/98/95:  This parameter can also be the following key: HKEY_DYN_DATA

 

lpSubKey - [in] Pointer to a null-terminated string specifying the name of a subkey that this function opens or creates.  The subkey specified must be a subkey of the key identified by the hKey parameter.  This parameter cannot be NULL. The subkey name specified by lpSubKey must not begin with the backslash character ('\').  If it does, ERROR_BAD_PATHNAME is returned.  Windows Me/98/95:  Beginning backslash characters in the subkey name specified by lpSubKey are ignored.

Reserved - Reserved; must be zero.

lpClass - [in] Pointer to a null-terminated string that specifies the class (object type) of this key.  This parameter may be ignored.  This parameter can be NULL.  This parameter is used for both local and remote registry keys. Windows Me/98/95:  This parameter is used only for remote registry keys; it is ignored for local registry keys.

dwOptions - [in] This parameter can be one of the following values.

 

Value

Meaning

REG_OPTION_NON_VOLATILE

This key is not volatile; this is the default.  The information is stored in a file and is preserved when the system is restarted.  The RegSaveKey() function saves keys that are not volatile.

REG_OPTION_VOLATILE

All keys created by the function are volatile.  The information is stored in memory and is not preserved when the corresponding registry hive is unloaded.  For HKEY_LOCAL_MACHINE, this occurs when the system is shut down.  For registry keys loaded by the RegLoadKey() function, this occurs when the corresponding RegUnLoadKey() is performed.  The RegSaveKey() function does not save volatile keys.  This flag is ignored for keys that already exist.

Windows Me/98/95:  This value is ignored.  If it is specified, the RegCreateKeyEx() function creates nonvolatile keys and returns ERROR_SUCCESS.

REG_OPTION_BACKUP_RESTORE

If this flag is set, the function ignores the samDesired parameter and attempts to open the key with the access required to backup or restore the key.  If the calling thread has the SE_BACKUP_NAME privilege enabled, the key is opened with the ACCESS_SYSTEM_SECURITY and KEY_READ access rights.  If the calling thread has the SE_RESTORE_NAME privilege enabled, the key is opened with the ACCESS_SYSTEM_SECURITY and KEY_WRITE access rights.  If both privileges are enabled, the key has the combined access rights for both privileges. Windows Me/98/95:  This value is not supported.

 

Table 70

 

samDesired - [in] Access mask that specifies the access rights for the key.

lpSecurityAttributes - [in] Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes.  If lpSecurityAttributes is NULL, the handle cannot be inherited.  The lpSecurityDescriptor member of the structure specifies a security descriptor for the new key.  If lpSecurityAttributes is NULL, the key gets a default security descriptor.  The ACLs in a default security descriptor for a key are inherited from its direct parent key.

phkResult - [out] Pointer to a variable that receives a handle to the opened or created key.  When you no longer need the returned handle, call the RegCloseKey() function to close it.

lpdwDisposition - [out] Pointer to a variable that receives one of the following disposition values:

 

Value

Meaning

REG_CREATED_NEW_KEY

The key did not exist and was created.

REG_OPENED_EXISTING_KEY

The key existed and was simply opened without being changed.

 

Table 71

 

If lpdwDisposition is NULL, no disposition information is returned. The key that the RegCreateKeyEx() function creates has no values.  An application can use the RegSetValueEx() function to set key values.  An application cannot create a key that is a direct child of HKEY_USERS or HKEY_LOCAL_MACHINE.  An application can create subkeys in lower levels of the HKEY_USERS or HKEY_LOCAL_MACHINE trees.  If your service or application impersonates different users, do not use this function with HKEY_CURRENT_USER.  Instead, call the RegOpenCurrentUser() function.

 

HeapAlloc()

 

Item

Description

Function

HeapAlloc().

Use

To allocate a block of memory from a heap.  The allocated memory is not movable.

Prototype

LPVOID HeapAlloc( HANDLE hHeap, DWORD dwFlags, SIZE_T dwBytes );

Parameters

See below.

Return value

If the function succeeds, the return value is a pointer to the allocated memory block.  If the function fails and you have not specified HEAP_GENERATE_EXCEPTIONS, the return value is NULL.  If the function fails and you have specified HEAP_GENERATE_EXCEPTIONS, the function may generate the following exceptions:

  1. STATUS_NO_MEMORY - The allocation attempt failed because of a lack of available memory or heap corruption.

  2. STATUS_ACCESS_VIOLATION - The allocation attempt failed because of heap corruption or improper function parameters.

 

Heap corruption can lead to either exception.  It depends upon the nature of the heap corruption.  If the function fails, it does not call SetLastError().  An application cannot call GetLastError() for extended error information.

Include file

<windows.h>

Remark

-

 

Table 72

 

hHeap - [in] Handle to the heap from which the memory will be allocated.  This handle is returned by the HeapCreate() or GetProcessHeap() function.

dwFlags - [in] Heap allocation control.  Specifying any of these values will override the corresponding value specified when the heap was created with HeapCreate(). This parameter can be one or more of the following values.

 

Value

Meaning

HEAP_GENERATE_EXCEPTIONS

The system will raise an exception to indicate a function failure, such as an out-of-memory condition, instead of returning NULL.

HEAP_NO_SERIALIZE

Serialized access will not be used for this allocation.  To ensure that serialized access is disabled for all calls to this function, specify HEAP_NO_SERIALIZE in the call to HeapCreate().  In this case, it is not necessary to additionally specify HEAP_NO_SERIALIZE in this function call. This value should not be specified when accessing the process heap. The system may create additional threads within the application's process, such as a CTRL+C handler, that simultaneously access the process heap.

HEAP_ZERO_MEMORY

The allocated memory will be initialized to zero.  Otherwise, the memory is not initialized to zero.

 

Table 73

 

dwBytes - [in] Number of bytes to be allocated. If the heap specified by the hHeap parameter is a "non-growable" heap, dwBytes must be less than 0x7FFF8.  You create a non-growable heap by calling the HeapCreate() function with a nonzero value. If HeapAlloc() succeeds, it allocates at least the amount of memory requested.  To determine the actual size of the allocated block, use the HeapSize() function.  To free a block of memory allocated by HeapAlloc(), use the HeapFree() function. Memory allocated by HeapAlloc() is not movable.  The address returned by HeapAlloc() is valid until the memory block is freed or reallocated; the memory block does not need to be locked.  Because the system cannot compact a private heap, it can become fragmented.  Applications that allocate large amounts of memory in various allocation sizes can use the low-fragmentation heap to reduce heap fragmentation.

Serialization ensures mutual exclusion when two or more threads attempt to simultaneously allocate or free blocks from the same heap.  There is a small performance cost to serialization, but it must be used whenever multiple threads allocate and free memory from the same heap.  Setting the HEAP_NO_SERIALIZE value eliminates mutual exclusion on the heap.  Without serialization, two or more threads that use the same heap handle might attempt to allocate or free memory simultaneously, likely causing corruption in the heap.  The HEAP_NO_SERIALIZE value can, therefore, be safely used only in the following situations:

  1. The process has only one thread.

  2. The process has multiple threads, but only one thread calls the heap functions for a specific heap.

  3. The process has multiple threads, and the application provides its own mechanism for mutual exclusion to a specific heap.

 

Windows Me/98/95:  The heap managers are designed for memory blocks smaller than four megabytes.  If you expect your memory blocks to be larger than one or two megabytes, you can avoid significant performance degradation by using the VirtualAlloc() or VirtualAllocEx() function instead.

 

HeapFree()

 

Item

Description

Function

HeapFree().

Use

To free a memory block allocated from a heap by the HeapAlloc() or HeapReAlloc() function.

Prototype

BOOL HeapFree( HANDLE hHeap, DWORD dwFlags, LPVOID lpMem );

Parameters

hHeap - [in] Handle to the heap whose memory block is to be freed.  This handle is a returned by either the HeapCreate() or GetProcessHeap() function.

dwFlags - [in] Heap free options.  Specifying the following value overrides the corresponding value specified in the flOptions parameter when the heap was created by using the HeapCreate() function.

  • HEAP_NO_SERIALIZE - Serialized access will not be used.  To ensure that serialized access is disabled for all calls to this function, specify HEAP_NO_SERIALIZE in the call to HeapCreate().  In this case, it is not necessary to additionally specify HEAP_NO_SERIALIZE in this function call.  Do not specify this value when accessing the process heap.  The system may create additional threads within the application's process, such as a CTRL+C handler, that simultaneously access the process heap.

lpMem - [in] Pointer to the memory block to be freed.  This pointer is returned by the HeapAlloc() or HeapReAlloc() function.

Return value

If the function succeeds, the return value is nonzero.  If the function fails, the return value is zero.  An application can call GetLastError() for extended error information.

Include file

<windows.h>

Remark

You should not refer in any way to memory that has been freed by HeapFree().  After that memory is freed, any information that may have been in it is gone forever.  If you require information, do not free memory containing the information.  Function calls that return information about memory such as HeapSize() may not be used with freed memory, as they may return bogus data.

 

Table 74

 

HeapSize()

 

Item

Description

Function

HeapSize().

Use

To retrieve the size of a memory block allocated from a heap by the HeapAlloc() or HeapReAlloc() function.

Prototype

SIZE_T HeapSize( HANDLE hHeap, DWORD dwFlags, LPCVOID lpMem );

Parameters

hHeap - [in] Handle to the heap in which the memory block resides. This handle is returned by either the HeapCreate() or GetProcessHeap() function.

dwFlags - [in] Heap size options.  Specifying the following value overrides the corresponding value specified in the flOptions parameter when the heap was created by using the HeapCreate() function.

  • HEAP_NO_SERIALIZE - Serialized access will not be used.  To ensure that serialized access is disabled for all calls to this function, specify HEAP_NO_SERIALIZE in the call to HeapCreate().  In this case, it is not necessary to additionally specify HEAP_NO_SERIALIZE in this function call.  This value should not be specified when accessing the process heap.  The system may create additional threads within the application's process, such as a CTRL+C handler, that simultaneously access the process heap.

lpMem - [in] Pointer to the memory block whose size the function will obtain.  This is a pointer returned by the HeapAlloc() or HeapReAlloc() function.

Return value

If the function succeeds, the return value is the size of the allocated memory block, in bytes.  If the function fails, the return value is (SIZE_T) -1.  The function does not call SetLastError().  An application cannot call GetLastError() for extended error information.

Include file

<windows.h>

Remark

-

 

Table 75

 

HeapReAlloc()

 

Item

Description

Function

HeapReAlloc().

Use

To reallocate a block of memory from a heap.  This function enables you to resize a memory block and change other memory block properties.  The allocated memory is not movable.

Prototype

LPVOID HeapReAlloc( HANDLE hHeap, DWORD dwFlags, LPVOID lpMem, SIZE_T dwBytes );

Parameters

See below.

Return value

If the function succeeds, the return value is a pointer to the reallocated memory block.  If the function fails and you have not specified HEAP_GENERATE_EXCEPTIONS, the return value is NULL.  If the function fails and you have specified HEAP_GENERATE_EXCEPTIONS, the function may generate the following exceptions return code:

  1. STATUS_NO_MEMORY - The reallocation attempt failed for lack of available memory.

  2. STATUS_ACCESS_VIOLATION - The reallocation attempt failed because of heap corruption or improper function parameters.

 

If the function fails, it calls SetLastError().  An application can call GetLastError() for extended error information.

Include file

<windows.h>

Remark

-

 

Table 76

 

hHeap - [in] Handle to the heap from which the memory is to be reallocated.  This handle is a returned by either the HeapCreate() or GetProcessHeap() function.

dwFlags - [in] Heap reallocation options.  Specifying a value overrides the corresponding value specified in the flOptions parameter when the heap was created by using the HeapCreate() function.  This parameter can be one or more of the following values.

 

Value

Meaning

HEAP_GENERATE_EXCEPTIONS

The operating-system raises an exception to indicate a function failure, such as an out-of-memory condition, instead of returning NULL.

HEAP_NO_SERIALIZE

Serialized access will not be used.  To ensure that serialized access is disabled for all calls to this function, specify HEAP_NO_SERIALIZE in the call to HeapCreate.  In this case, it is not necessary to additionally specify HEAP_NO_SERIALIZE in this function call.  This value should not be specified when accessing the process heap.  The system may create additional threads within the application's process, such as a CTRL+C handler, that simultaneously access the process heap.

HEAP_REALLOC_IN_PLACE_ONLY

There can be no movement when reallocating a memory block.  If this value is not specified, the function may move the block to a new location.  If this value is specified and the block cannot be resized without moving, the function fails, leaving the original memory block unchanged.

HEAP_ZERO_MEMORY

If the reallocation request is for a larger size, the additional region of memory beyond the original size is initialized to zero.  The contents of the memory block up to its original size are unaffected.

 

Table 77

 

lpMem - [in] Pointer to the block of memory that the function reallocates.  This pointer is returned by an earlier call to the HeapAlloc() or HeapReAlloc() function.

dwBytes - [in] New size of the memory block, in bytes.  A memory block's size can be increased or decreased by using this function.  If the heap specified by the hHeap parameter is a "non-growable" heap, dwBytes must be less than 0x7FFF8.  You create a non-growable heap by calling the HeapCreate() function with a nonzero value.

If HeapReAlloc() succeeds, it allocates at least the amount of memory requested.  To determine the actual size of the reallocated block, use the HeapSize() function.  If HeapReAlloc() fails, the original memory is not freed, and the original handle and pointer are still valid.  HeapReAlloc() is guaranteed to preserve the content of the memory being reallocated, even if the new memory is allocated at a different location.  The process of preserving the memory content involves a memory copy operation that is potentially very large.  To free a block of memory allocated by HeapReAlloc(), use the HeapFree() function.

 

AccessCheck()

 

Item

Description

Function

AccessCheck().

Use

To determine whether a security descriptor grants a specified set of access rights to the client identified by an access token.  Typically, server applications use this function to check access to a private object.

Prototype

BOOL AccessCheck( PSECURITY_DESCRIPTOR pSecurityDescriptor, HANDLE ClientToken, DWORD DesiredAccess, PGENERIC_MAPPING GenericMapping, PPRIVILEGE_SET PrivilegeSet, LPDWORD PrivilegeSetLength, LPDWORD GrantedAccess, LPBOOL AccessStatus );

Parameters

pSecurityDescriptor - [in] Pointer to a SECURITY_DESCRIPTOR structure against which access is checked.

ClientToken - [in] Handle to an impersonation token that represents the client that is attempting to gain access.  The handle must have TOKEN_QUERY access to the token; otherwise, the function fails with ERROR_ACCESS_DENIED.

DesiredAccess - [in] Access mask that specifies the access rights to check.  This mask must have been mapped by the MapGenericMask() function to contain no generic access rights.  If this parameter is MAXIMUM_ALLOWED, the function sets the GrantedAccess access mask to indicate the maximum access rights the security descriptor allows the client.

GenericMapping - [in] Pointer to the GENERIC_MAPPING structure associated with the object for which access is being checked.

PrivilegeSet - [out] Pointer to a PRIVILEGE_SET structure that receives the privileges used to perform the access validation.  If no privileges were used, the function sets the PrivilegeCount member to zero.

PrivilegeSetLength - [in] Specifies the size, in bytes, of the buffer pointed to by the PrivilegeSet parameter.

GrantedAccess - [out] Pointer to an access mask that receives the granted access rights.  If AccessStatus is set to FALSE, the function sets the access mask to zero.  If the function fails, it does not set the access mask.

AccessStatus - [out] Pointer to a variable that receives the results of the access check.  If the security descriptor allows the requested access rights to the client identified by the access token, AccessStatus is set to TRUE.  Otherwise, AccessStatus is set to FALSE, and you can call GetLastError() to get extended error information.

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 78

 

The AccessCheck() function compares the specified security descriptor with the specified access token and indicates, in the AccessStatus parameter, whether access is granted or denied.  If access is granted, the requested access mask becomes the object's granted access mask.  If the security descriptor's DACL is NULL, the AccessStatus parameter returns TRUE, which indicates that the client has the requested access. The AccessCheck() function fails with ERROR_INVALID_SECURITY_DESCR if the security descriptor does not contain owner and group SIDs. The AccessCheck() function does not generate an audit.  If your application requires audits for access checks, use functions such as AccessCheckAndAuditAlarm(), AccessCheckByTypeAndAuditAlarm(), AccessCheckByTypeResultListAndAuditAlarm(), or AccessCheckByTypeResultListAndAuditAlarmByHandle(), instead of AccessCheck().

 

InitializeSecurityDescriptor()

 

Item

Description

Function

InitializeSecurityDescriptor().

Use

To initialize a new security descriptor.

Prototype

BOOL InitializeSecurityDescriptor( PSECURITY_DESCRIPTOR pSecurityDescriptor, DWORD dwRevision );

Parameters

pSecurityDescriptor - [out] Pointer to a SECURITY_DESCRIPTOR structure that the function initializes.

dwRevision - [in] Specifies the revision level to assign to the security descriptor.  This parameter must be SECURITY_DESCRIPTOR_REVISION.

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 79

 

The InitializeSecurityDescriptor() function initializes a security descriptor in absolute format, rather than self-relative format.  The InitializeSecurityDescriptor() function initializes a security descriptor to have no SACL, no DACL, no owner, no primary group, and all control flags set to FALSE (NULL).  Thus, except for its revision level, it is empty.

 

---------------------------Access Control Functions---------------------------

 

 

 

Further reading and digging:

 

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

  2. Microsoft Visual C++.

  3. MSDN library.

  4. Other related C topics: Function, Array, Pointer, String and Structure, enum, typedef.

  5. Notation used in MSDN is Hungarian Notation instead of CamelCase and is discussed in C & C++ Notations.

  6. Windows data type information is in Windows Data types.

 

 

 

 

 

 

 

 

 

| Previous | Main | Next | Site Index | Download | Disclaimer | Privacy |