NtOpenProcess - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers 
#ifndef _NTPSAPI_H
//
// Processes
//
#if (PHNT_MODE != PHNT_MODE_KERNEL)

/**
 * Opens an existing process object.
 *
 * \param ProcessHandle A pointer to a handle that receives the process object handle.
 * \param DesiredAccess The access rights desired for the process object.
 * \param ObjectAttributes A pointer to an OBJECT_ATTRIBUTES structure that specifies the attributes of the new process.
 * \param ClientId Optional. A pointer to a CLIENT_ID structure that specifies the client ID of the process to be opened.
 * \return NTSTATUS Successful or errant status.
 * \sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntddk/nf-ntddk-ntopenprocess
 */
NTSYSCALLAPI
NTSTATUS
NTAPI
NtOpenProcess(
    _Out_ PHANDLE ProcessHandle,
    _In_ ACCESS_MASK DesiredAccess,
    _In_ PCOBJECT_ATTRIBUTES ObjectAttributes,
    _In_opt_ PCLIENT_ID ClientId
    );

#endif
#endif

View code on GitHub
#ifndef _NTZWAPI_H

NTSYSCALLAPI
NTSTATUS
NTAPI
ZwOpenProcess(
    _Out_ PHANDLE ProcessHandle,
    _In_ ACCESS_MASK DesiredAccess,
    _In_ PCOBJECT_ATTRIBUTES ObjectAttributes,
    _In_opt_ PCLIENT_ID ClientId
    );

#endif

View code on GitHub
// ntddk.h

__kernel_entry NTSYSCALLAPI NTSTATUS NtOpenProcess(
  [out]          PHANDLE            ProcessHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] PCLIENT_ID         ClientId
);
View the official Windows Driver Kit DDI reference
// ntddk.h

NTSYSAPI NTSTATUS ZwOpenProcess(
  [out]          PHANDLE            ProcessHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] PCLIENT_ID         ClientId
);
View the official Windows Driver Kit DDI reference

NtDoc

Opens a handle to an existing process. This function is documented in Windows Driver Kit here and here.

Parameters

Access masks

Access mask Use
PROCESS_TERMINATE Terminating the process via NtTerminateProcess.
PROCESS_CREATE_THREAD Creating threads in the process via NtCreateThread and NtCreateThreadEx.
PROCESS_SET_SESSIONID Unused
PROCESS_VM_OPERATION Performing various memory operations such as NtAllocateVirtualMemory, NtProtectVirtualMemory, NtMapViewOfSection.
PROCESS_VM_READ Reading the process's memory via NtReadVirtualMemory
PROCESS_VM_WRITE Writing to the process's memory via NtWriteVirtualMemory
PROCESS_DUP_HANDLE Duplicating and closing process handles via NtDuplicateObject.
PROCESS_CREATE_PROCESS Specifying the process as the parent in NtCreateProcess and NtCreateUserProcess.
PROCESS_SET_QUOTA Adjusting quota limits via NtSetInformationProcess.
PROCESS_SET_INFORMATION Setting most information classes via NtSetInformationProcess.
PROCESS_QUERY_INFORMATION Querying most information classes via NtQueryInformationProcess and NtQueryVirtualMemory.
PROCESS_SUSPEND_RESUME Suspending and resuming all threads in the process via NtSuspendProcess and NtResumeThread.
PROCESS_QUERY_LIMITED_INFORMATION Querying some information classes via NtQueryInformationProcess and NtQueryVirtualMemory. The system automatically includes this right if the caller requests PROCESS_QUERY_INFORMATION.
PROCESS_SET_LIMITED_INFORMATION Setting some information classes via NtSetInformationProcess. The system automatically includes this right if the caller requests PROCESS_SET_INFORMATION.
PROCESS_ALL_ACCESS All of the above plus standard rights.

Remarks

This function bypasses some access checks if the caller has the SeDebugPrivilege enabled.

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

Instead of opening the current process, consider using the NtCurrentProcess pseudo-handle.

Related Win32 API

See also

Edit description on GitHub

Windows Driver Kit DDI reference (nf-ntddk-ntopenprocess)

Description

The ZwOpenProcess routine opens a handle to a process object and sets the access rights to this object.

Parameters

ProcessHandle [out]

A pointer to a variable of type HANDLE. The ZwOpenProcess routine writes the process handle to the variable that this parameter points to.

DesiredAccess [in]

An ACCESS_MASK value that contains the access rights that the caller has requested to the process object.

ObjectAttributes [in]

A pointer to an OBJECT_ATTRIBUTES structure that specifies the attributes to apply to the process object handle. The ObjectName field of this structure must be set to NULL. For more information, see the following Remarks section.

ClientId [in, optional]

A pointer to a client ID that identifies the thread whose process is to be opened. This parameter must be a non-NULL pointer to a valid client ID. For more information, see the following Remarks section.

Return value

ZwOpenProcess returns STATUS_SUCCESS if the call is successful. Possible return values include the following error status codes:

Return code Description
STATUS_INVALID_PARAMETER_MIX The caller either supplied an object name or failed to supply a client ID.
STATUS_INVALID_CID The specified client ID is not valid.
STATUS_INVALID_PARAMETER The requested access rights are not valid for a process object.
STATUS_ACCESS_DENIED The requested access rights cannot be granted.

Remarks

As is the case with kernel handles opened by other system service calls such as ZwCreateKey and ZwCreateFile, the caller is responsible for calling ZwClose to close the handle when it is no longer required.

The ClientId parameter must point to a client ID that identifies the thread whose process is to be opened. In addition, the ObjectName field of the structure pointed to by ObjectAttributes must be set to NULL.

If the call to this function occurs in user mode, you should use the name "NtOpenProcess" instead of "ZwOpenProcess".

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

OBJECT_ATTRIBUTES

Using Nt and Zw Versions of the Native System Services Routines

View the official Windows Driver Kit DDI reference

Edit description on GitHub

Windows Driver Kit DDI reference (nf-ntddk-zwopenprocess)

Description

The ZwOpenProcess routine opens a handle to a process object and sets the access rights to this object.

Parameters

ProcessHandle [out]

A pointer to a variable of type HANDLE. The ZwOpenProcess routine writes the process handle to the variable that this parameter points to.

DesiredAccess [in]

An ACCESS_MASK value that contains the access rights that the caller has requested to the process object.

ObjectAttributes [in]

A pointer to an OBJECT_ATTRIBUTES structure that specifies the attributes to apply to the process object handle. The ObjectName field of this structure must be set to NULL. For more information, see the following Remarks section.

ClientId [in, optional]

A pointer to a client ID that identifies the thread whose process is to be opened. This parameter must be a non-NULL pointer to a valid client ID. For more information, see the following Remarks section.

Return value

ZwOpenProcess returns STATUS_SUCCESS if the call is successful. Possible return values include the following error status codes.

Return code Description
STATUS_INVALID_PARAMETER_MIX The caller either supplied an object name or failed to supply a client ID.
STATUS_INVALID_CID The specified client ID is not valid.
STATUS_INVALID_PARAMETER The requested access rights are not valid for a process object.
STATUS_ACCESS_DENIED The requested access rights cannot be granted.

Remarks

The ClientId parameter must point to a client ID that identifies the thread whose process is to be opened. In addition, the ObjectName field of the structure pointed to by ObjectAttributes must be set to NULL.

If the call to this function occurs in user mode, you should use the name "NtOpenProcess" instead of "ZwOpenProcess".

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

OBJECT_ATTRIBUTES

Using Nt and Zw Versions of the Native System Services Routines

View the official Windows Driver Kit DDI reference

Edit description on GitHub

NTinternals.net (undocumented.ntinternals.net)

This function is documented in Windows Driver Kit here and here.

AccessMask

ObjectAttributes

For standard processes, all fields of ObjectAttributes should be NULL.

ClientId

Process id and thread id must be fill with valid values.

Documented by

See also

Edit description on GitHub