NtOpenProcessToken function (ntifs.h)

Article
02/22/2024

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

Syntax

__kernel_entry NTSYSCALLAPI NTSTATUS NtOpenProcessToken(
  [in]  HANDLE      ProcessHandle,
  [in]  ACCESS_MASK DesiredAccess,
  [out] PHANDLE     TokenHandle
);

Parameters

[in] ProcessHandle

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.

[in] DesiredAccess

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.

[out] TokenHandle

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

Return value

NtOpenProcessToken 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_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

To specify attributes for the access token handle, use NtOpenProcessTokenEx instead.

The handle can be accessed by the process in whose context the driver is running.

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

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 NtXxx and ZwXxx 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 NtXxx and ZwXxx versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

Requirements

Requirement	Value
Header	ntifs.h
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL