NtDuplicateObject - NtDoc

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

/**
 * The NtDuplicateObject routine creates a handle that is a duplicate of the specified source handle.
 *
 * @param SourceProcessHandle A handle to the source process for the handle being duplicated.
 * @param SourceHandle The handle to duplicate.
 * @param TargetProcessHandle A handle to the target process that is to receive the new handle. This parameter is optional and can be specified as NULL if the DUPLICATE_CLOSE_SOURCE flag is set in Options.
 * @param TargetHandle A pointer to a HANDLE variable into which the routine writes the new duplicated handle. The duplicated handle is valid in the specified target process. This parameter is optional and can be specified as NULL if no duplicate handle is to be created.
 * @param DesiredAccess An ACCESS_MASK value that specifies the desired access for the new handle.
 * @param HandleAttributes A ULONG that specifies the desired attributes for the new handle.
 * @param Options A set of flags to control the behavior of the duplication operation.
 * @return NTSTATUS Successful or errant status.
 * @sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-zwduplicateobject
 */
NTSYSCALLAPI
NTSTATUS
NTAPI
NtDuplicateObject(
    _In_ HANDLE SourceProcessHandle,
    _In_ HANDLE SourceHandle,
    _In_opt_ HANDLE TargetProcessHandle,
    _Out_opt_ PHANDLE TargetHandle,
    _In_ ACCESS_MASK DesiredAccess,
    _In_ ULONG HandleAttributes,
    _In_ ULONG Options
    );

#endif
#endif

View code on GitHub
#ifndef _NTZWAPI_H

NTSYSCALLAPI
NTSTATUS
NTAPI
ZwDuplicateObject(
    _In_ HANDLE SourceProcessHandle,
    _In_ HANDLE SourceHandle,
    _In_opt_ HANDLE TargetProcessHandle,
    _Out_opt_ PHANDLE TargetHandle,
    _In_ ACCESS_MASK DesiredAccess,
    _In_ ULONG HandleAttributes,
    _In_ ULONG Options
    );

#endif

View code on GitHub
// ntifs.h

NTSYSAPI NTSTATUS ZwDuplicateObject(
  [in]            HANDLE      SourceProcessHandle,
  [in]            HANDLE      SourceHandle,
  [in, optional]  HANDLE      TargetProcessHandle,
  [out, optional] PHANDLE     TargetHandle,
  [in]            ACCESS_MASK DesiredAccess,
  [in]            ULONG       HandleAttributes,
  [in]            ULONG       Options
);
View the official Windows Driver Kit DDI reference

NtDoc

Allows copying handles across process boundaries and opening additional handles pointing to the same underlying kernel object. This function is documented in Windows Driver Kit.

Parameters

Supported flags

Remarks

This function offers a wide range of modes of operation:

  1. Duplicate or reopen handles within the calling process. This function allows making copies of existing handles with different access/attributes.
  2. Copying handles from other processes.
  3. Copying handles into other processes.
  4. Closing handles in other processes.

Note that this function performs an access check against the security descriptor of the source handle only when the Options parameter does not include the DUPLICATE_SAME_ACCESS flag.

Related Win32 API

See also

Edit description on GitHub

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

ZwDuplicateObject function

Description

The ZwDuplicateObject routine creates a handle that is a duplicate of the specified source handle.

Parameters

SourceProcessHandle [in]

A handle to the source process for the handle being duplicated.

SourceHandle [in]

The handle to duplicate.

TargetProcessHandle [in, optional]

A handle to the target process that is to receive the new handle. This parameter is optional and can be specified as NULL if the DUPLICATE_CLOSE_SOURCE flag is set in Options.

TargetHandle [out, optional]

A pointer to a HANDLE variable into which the routine writes the new duplicated handle. The duplicated handle is valid in the specified target process. This parameter is optional and can be specified as NULL if no duplicate handle is to be created.

DesiredAccess [in]

An ACCESS_MASK value that specifies the desired access for the new handle.

HandleAttributes [in]

A ULONG that specifies the desired attributes for the new handle. For more information about attributes, see the description of the Attributes member in OBJECT_ATTRIBUTES.

Options [in]

A set of flags to control the behavior of the duplication operation. Set this parameter to zero or to the bitwise OR of one or more of the following flags.

Flag name Description
DUPLICATE_SAME_ATTRIBUTES Instead of using the HandleAttributes parameter, copy the attributes from the source handle to the target handle.
DUPLICATE_SAME_ACCESS Instead of using the DesiredAccess parameter, copy the access rights from the source handle to the target handle.
DUPLICATE_CLOSE_SOURCE Close the source handle.

Return value

ZwDuplicateObject returns STATUS_SUCCESS if the call is successful. Otherwise, it returns an appropriate error status code.

Remarks

The source handle is evaluated in the context of the specified source process. The calling process must have PROCESS_DUP_HANDLE access to the source process. The duplicate handle is created in the handle table of the specified target process. The calling process must have PROCESS_DUP_HANDLE access to the target process.

By default, the duplicate handle is created with the attributes specified by the HandleAttributes parameter, and with the access rights specified by the DesiredAccess parameter. If necessary, the caller can override one or both defaults by setting the DUPLICATE_SAME_ATTRIBUTES and DUPLICATE_SAME_ACCESS flags in the Options parameter.

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

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.

See Microsoft SDK for description of DuplicateHandle Win32 API.

Documented by

Edit description on GitHub