NtOpenKeyEx - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
#ifndef _NTREGAPI_H
/**
* Opens an existing key with explicit open options; it does not create a missing key. OpenOptions = 0 is
* equivalent to NtOpenKey on the native path.
*
* \param[out] KeyHandle Required caller-owned output; close successful handles with NtClose. Initialize it to
* NULL before calling and consume it only on success.
* \param[in] DesiredAccess Requested key rights and optional WOW64 view infoclass, not a creation-option mask.
* Existing key security still controls granted access.
* \param[in] ObjectAttributes Initialized counted native or relative key path. The native user-mode path
* requires 4-byte alignment of this structure and 2-byte alignment of a nonempty name buffer. Prefer natural
* alignment. Security information here does not replace the existing key's security.
* \param[in] OpenOptions 0 or supported REG_OPTION_* open flags. The entry admits only bits 0x4
* (BACKUP_RESTORE), 0x8 (OPEN_LINK) and 0x10 (DONT_VIRTUALIZE), mask 0x1C. VOLATILE (0x1) and CREATE_LINK
* (0x2) are creation flags, not valid open options. Backup/restore requires its special privilege checks;
* admission by the bit mask does not guarantee success.
* \return STATUS_SUCCESS or failure. Invalid option bits return STATUS_INVALID_PARAMETER_4 before the native
* helper clears KeyHandle.
* \remarks Consequently native invalid-option failures can preserve the handle output, while the WoW64
* wrapper copies back its NULL temporary result. Missing-name failures with valid inputs leave NULL on
* ordinary paths. Do not generalize one failure's output behavior to all earlier capture errors. WoW64 path
* construction/tag updates and registry filters/layers/virtualization can affect lookup; view selection is
* not established solely by structure width.
* \sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/wdm/nf-wdm-zwopenkeyex
*/
_Kernel_entry_
NTSYSCALLAPI
NTSTATUS
NTAPI
NtOpenKeyEx(
_Out_ PHANDLE KeyHandle,
_In_ ACCESS_MASK DesiredAccess,
_In_ POBJECT_ATTRIBUTES ObjectAttributes,
_In_ ULONG OpenOptions
);
View code on GitHub#ifndef _NTZWAPI_H
_Kernel_entry_
NTSYSCALLAPI
NTSTATUS
NTAPI
ZwOpenKeyEx(
_Out_ PHANDLE KeyHandle,
_In_ ACCESS_MASK DesiredAccess,
_In_ POBJECT_ATTRIBUTES ObjectAttributes,
_In_ ULONG OpenOptions
);
View code on GitHub// wdm.h
NTSYSAPI NTSTATUS ZwOpenKeyEx(
[out] PHANDLE KeyHandle,
[in] ACCESS_MASK DesiredAccess,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
[in] ULONG OpenOptions
);
View the official Windows Driver Kit DDI referenceThis function is documented in Windows Driver Kit.
The ZwOpenKeyEx routine opens an existing registry key.
KeyHandle [out]A pointer to a HANDLE variable into which the routine writes the handle to the key.
DesiredAccess [in]Specifies the type of access to the key that the caller requests. This parameter is an ACCESS_MASK value. For more information, see the description of the DesiredAccess parameter of the ZwCreateKey routine.
ObjectAttributes [in]A pointer to the object attributes of the key being opened. This parameter points to an OBJECT_ATTRIBUTES structure that must have been previously initialized by the InitializeObjectAttributes routine. The caller must specify the name of the registry key as the ObjectName parameter in the call to InitializeObjectAttributes. If the caller is not running in a system thread context, it must set the OBJ_KERNEL_HANDLE attribute when it calls InitializeObjectAttributes.
OpenOptions [in]Specifies the options to apply when opening the key. Set this parameter to zero or to the bitwise OR of one or more of the following REG_OPTION_XXX flag bits:
| OpenOptions flag | Description |
|---|---|
| REG_OPTION_OPEN_LINK | The key is a symbolic link. This flag is not used by device and intermediate drivers. |
| REG_OPTION_BACKUP_RESTORE | The key should be opened with special privileges that allow backup and restore operations. This flag is not used by device and intermediate drivers. |
ZwOpenKeyEx returns STATUS_SUCCESS if the call succeeds in opening the key. Possible error return values include the following:
| Return code | Description |
|---|---|
| STATUS_INVALID_PARAMETER_4 | The OpenOptions parameter specifies invalid options. |
| STATUS_OBJECT_PATH_SYNTAX_BAD | The registry path in the object attributes is invalid. |
| STATUS_OBJECT_NAME_NOT_FOUND | The registry key name in the object attributes was not found. |
| STATUS_OBJECT_TYPE_MISMATCH | The named registry key is a symbolic link, but the REG_OPTION_OPEN_LINK flag bit is not set in OpenOptions. |
| STATUS_ACCESS_DENIED | The caller did not have the required access rights to open a handle for the named registry key. |
| STATUS_INSUFFICIENT_RESOURCES | A memory allocation operation failed. |
This routine supplies a handle with which the caller can access a registry key. If the specified key does not exist, the routine returns an error status value and does not supply a key handle.
The ZwOpenKey routine is similar to ZwOpenKeyEx but does not accept an OpenOptions parameter. The OpenOptions parameter of ZwOpenKeyEx enables the caller to open a key that is a symbolic link, or to open a key for backup and restore operations. A call to ZwOpenKeyEx with OpenOptions = 0 is equivalent to a call to ZwOpenKey.
After the handle pointed to by KeyHandle is no longer in use, the driver must call ZwClose to close it.
ZwOpenKeyEx ignores the security information in the structure that the ObjectAttributes parameter points to.
If the kernel-mode caller is not running in a system thread context, it must ensure that any handles it creates are kernel handles. Otherwise, the handle can be accessed by the process in whose context the driver is running. For more information, see Object Handles.
For more information about working with registry keys in kernel mode, see Using the Registry in a Driver.