NtOpenProcessTokenEx - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers 
#ifndef _NTSEAPI_H

/**
 * The NtOpenProcessTokenEx routine opens the access token associated with a process, and returns a handle that can be used to access that token.
 *
 * @param ProcessHandle Handle to the process whose access token is to be opened. The handle must have PROCESS_QUERY_INFORMATION access.
 * @param DesiredAccess ACCESS_MASK structure specifying the requested types of access to the access token.
 * @param HandleAttributes Attributes for the created handle. Only OBJ_KERNEL_HANDLE is currently supported.
 * @param TokenHandle Pointer to a caller-allocated variable that receives a handle to the newly opened access token.
 * @return NTSTATUS Successful or errant status.
 * @sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-ntopenprocesstokenex
 */
NTSYSCALLAPI
NTSTATUS
NTAPI
NtOpenProcessTokenEx(
    _In_ HANDLE ProcessHandle,
    _In_ ACCESS_MASK DesiredAccess,
    _In_ ULONG HandleAttributes,
    _Out_ PHANDLE TokenHandle
    );

#endif

View code on GitHub
#ifndef _NTZWAPI_H

NTSYSCALLAPI
NTSTATUS
NTAPI
ZwOpenProcessTokenEx(
    _In_ HANDLE ProcessHandle,
    _In_ ACCESS_MASK DesiredAccess,
    _In_ ULONG HandleAttributes,
    _Out_ PHANDLE TokenHandle
    );

#endif

View code on GitHub
// ntifs.h

__kernel_entry NTSYSCALLAPI NTSTATUS NtOpenProcessTokenEx(
  [in]  HANDLE      ProcessHandle,
  [in]  ACCESS_MASK DesiredAccess,
  [in]  ULONG       HandleAttributes,
  [out] PHANDLE     TokenHandle
);
View the official Windows Driver Kit DDI reference
// ntifs.h

NTSYSAPI NTSTATUS ZwOpenProcessTokenEx(
  [in]  HANDLE      ProcessHandle,
  [in]  ACCESS_MASK DesiredAccess,
  [in]  ULONG       HandleAttributes,
  [out] PHANDLE     TokenHandle
);
View the official Windows Driver Kit DDI reference

NtDoc

Opens a handle to a primary token of a process. This function is documented in Windows Driver Kit here and here.

Parameters

Access masks

Access mask Use
TOKEN_ASSIGN_PRIMARY Allows creating processes with this token and assigning the token as primary via NtSetInformationProcess with ProcessAccessToken.
TOKEN_DUPLICATE Allows duplicating the token via NtDuplicateToken.
TOKEN_IMPERSONATE Allows impersonating the token via NtSetInformationThread with ThreadImpersonationToken.
TOKEN_QUERY Allows querying most information classes via NtQueryInformationToken.
TOKEN_QUERY_SOURCE Allows querying TokenSource via NtQueryInformationToken.
TOKEN_ADJUST_PRIVILEGES Allows adjusting token privileges via NtAdjustPrivilegesToken
TOKEN_ADJUST_GROUPS Allows adjusting token privileges via NtAdjustGroupsToken
TOKEN_ADJUST_DEFAULT Allows setting most information classes via NtSetInformationToken.
TOKEN_ADJUST_SESSIONID Allows setting TokenSessionId via NtSetInformationToken.
TOKEN_ALL_ACCESS_P All of the above except for the TOKEN_ADJUST_SESSIONID right, plus standard rights.
TOKEN_ALL_ACCESS All of the above plus standard rights.

Remarks

To avoid retaining unused resources, call NtClose to close the returned handle when it is no longer required.

Instead of opening the current process token for query, consider using the NtCurrentProcessToken pseudo-handle on Windows 8 and above.

If you don't want to specify custom handle attributes, you can use NtOpenProcessToken.

Related Win32 API

See also

Edit description on GitHub

Windows Driver Kit DDI reference (nf-ntifs-ntopenprocesstokenex)

NtOpenProcessTokenEx function

Description

The NtOpenProcessTokenEx routine opens the access token associated with a process, and returns a handle that can be used to access that token.

Parameters

ProcessHandle [in]

Handle to the process whose access token is to be opened. The handle must have PROCESS_QUERY_INFORMATION access. Use the NtCurrentProcess macro, defined in Ntddk.h, to specify the current process.

DesiredAccess [in]

ACCESS_MASK structure specifying the requested types of access to the access token. These requested access types are compared with the token's discretionary access-control list (DACL) to determine which accesses are granted or denied.

HandleAttributes [in]

Attributes for the access token handle. Only OBJ_KERNEL_HANDLE is currently supported. If the caller is not running in the system process context, it must specify OBJ_KERNEL_HANDLE for this parameter.

TokenHandle [out]

Pointer to a caller-allocated variable that receives a handle to the newly opened access token.

Return value

NtOpenProcessTokenEx returns STATUS_SUCCESS or an appropriate error status. Possible error status codes include the following:

Return code Description
STATUS_ACCESS_DENIED ProcessHandle did not have PROCESS_QUERY_INFORMATION access.
STATUS_INSUFFICIENT_RESOURCES A new token handle could not be allocated.
STATUS_INVALID_HANDLE ProcessHandle was not a valid handle.
STATUS_INVALID_PARAMETER The specified HandleAttributes did not include OBJ_KERNEL_HANDLE.
STATUS_OBJECT_TYPE_MISMATCH ProcessHandle was not a process handle.
STATUS_PRIVILEGE_NOT_HELD The caller does not have the privilege (SeSecurityPrivilege) necessary to create a token handle with the access specified in the DesiredAccess parameter.
STATUS_QUOTA_EXCEEDED The process's memory quota is not sufficient to allocate the token handle.
STATUS_UNSUCCESSFUL The token handle could not be created.

Remarks

Any handle obtained by calling NtOpenProcessTokenEx must eventually be released by calling NtClose.

Driver routines that run in a process context other than that of the system process must set the OBJ_KERNEL_HANDLE attribute for the HandleAttributes parameter of NtOpenProcessTokenEx. This restricts the use of the handle returned by NtOpenProcessTokenEx to processes running in kernel mode. Otherwise, the handle can be accessed by the process in whose context the driver is running.

For more information about security and access control, see Windows security model for driver developers and the documentation on these topics in the Windows SDK.

For calls from kernel-mode drivers, the Nt*Xxx* and Zw*Xxx* versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the Nt*Xxx* and Zw*Xxx* versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

See also

ACCESS_MASK

ACL

PsDereferencePrimaryToken

NtClose

NtOpenThreadTokenEx

View the official Windows Driver Kit DDI reference

Edit description on GitHub

Windows Driver Kit DDI reference (nf-ntifs-zwopenprocesstokenex)

ZwOpenProcessTokenEx function

Description

The ZwOpenProcessTokenEx routine opens the access token associated with a process.

Parameters

ProcessHandle [in]

Handle to the process whose access token is to be opened. The handle must have PROCESS_QUERY_INFORMATION access. Use the NtCurrentProcess macro, defined in Ntddk.h, to specify the current process.

DesiredAccess [in]

ACCESS_MASK structure specifying the requested types of access to the access token. These requested access types are compared with the token's discretionary access-control list (DACL) to determine which accesses are granted or denied.

HandleAttributes [in]

Attributes for the access token handle. Only OBJ_KERNEL_HANDLE is currently supported. If the caller is not running in the system process context, it must specify OBJ_KERNEL_HANDLE for this parameter.

TokenHandle [out]

Pointer to a caller-allocated variable that receives a handle to the newly opened access token.

Return value

ZwOpenProcessTokenEx returns STATUS_SUCCESS or an appropriate error status. Possible error status codes include the following:

Return code Description
STATUS_ACCESS_DENIED ProcessHandle did not have PROCESS_QUERY_INFORMATION access.
STATUS_INSUFFICIENT_RESOURCES A new token handle could not be allocated.
STATUS_INVALID_HANDLE ProcessHandle was not a valid handle.
STATUS_INVALID_PARAMETER The specified HandleAttributes did not include OBJ_KERNEL_HANDLE.
STATUS_OBJECT_TYPE_MISMATCH ProcessHandle was not a process handle.
STATUS_PRIVILEGE_NOT_HELD The caller does not have the privilege (SeSecurityPrivilege) necessary to create a token handle with the access specified in the DesiredAccess parameter.
STATUS_QUOTA_EXCEEDED The process's memory quota is not sufficient to allocate the token handle.
STATUS_UNSUCCESSFUL The token handle could not be created.

Remarks

ZwOpenProcessTokenEx opens the access token associated with a process and returns a handle for that token.

Any handle obtained by calling ZwOpenProcessTokenEx must eventually be released by calling ZwClose.

Driver routines that run in a process context other than that of the system process must set the OBJ_KERNEL_HANDLE attribute for the HandleAttributes parameter of ZwOpenProcessTokenEx. This restricts the use of the handle returned by ZwOpenProcessTokenEx to processes running in kernel mode. Otherwise, the handle can be accessed by the process in whose context the driver is running.

For more information about security and access control, see Windows security model for driver developers and the documentation on these topics in the Windows SDK.

[!NOTE] If the call to the ZwOpenProcessTokenEx function occurs in user mode, you should use the name "NtOpenProcessTokenEx" instead of "ZwOpenProcessTokenEx".

For calls from kernel-mode drivers, the Nt*Xxx* and Zw*Xxx* versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the Nt*Xxx* and Zw*Xxx* versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

See also

ACCESS_MASK

ACL

PsDereferencePrimaryToken

Using Nt and Zw Versions of the Native System Services Routines

ZwClose

ZwOpenThreadTokenEx

View the official Windows Driver Kit DDI reference

Edit description on GitHub