ZwOpenKey

The ZwOpenKey routine opens an existing key in the registry.

NTSTATUS 
  ZwOpenKey(
    OUT PHANDLE  KeyHandle,
    IN ACCESS_MASK  DesiredAccess,
    IN POBJECT_ATTRIBUTES  ObjectAttributes
    );

Parameters

KeyHandle

Pointer to a returned handle for the key specified in ObjectAttributes if this call is successful. The driver must close the handle with ZwClose once the handle is no longer in use.

DesiredAccess

Specifies the ACCESS_MASK value that expresses access rights to the key desired. If the caller is not running in the system process context, it must set the OBJ_KERNEL_HANDLE attribute for ObjectAttributes. For a description of possible values for this parameter, see ZwCreateKey.

ObjectAttributes

Pointer to the initialized object attributes of the key being opened. For more information, see the description of ZwCreateKey.

Headers

Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

Return Value

ZwOpenKey returns STATUS_SUCCESS if the given key was opened. Otherwise, it can return an error status, including the following:

STATUS_INVALID_HANDLE
STATUS_ACCESS_DENIED

Comments

ZwOpenKey or ZwCreateKey must be called before any of the Zw...Key routines that require an input KeyHandle.

If the specified key does not exist or the DesiredAccess requested is not allowed, ZwOpenKey returns an error status, and the KeyHandle remains invalid.

ZwOpenKey ignores the security information in the input ObjectAttributes. Access rights for a key object can be set only when the key is created.

Driver routines that run in a process context other than that of the system process must set the OBJ_KERNEL_HANDLE attribute for the ObjectAttributes parameter of ZwOpenFile. This restricts the use of the handle returned by ZwOpenFile to processes running only in kernel mode. Otherwise, the handle can be accessed by the process in whose context the driver is running. Drivers can call InitializeObjectAttributes to set the OBJ_KERNEL_HANDLE attribute as follows.

InitializeObjectAttributes(&ObjectAttributes, NULL, OBJ_KERNEL_HANDLE, NULL, NULL);

Callers of ZwOpenKey must be running at IRQL = PASSIVE_LEVEL.

See Also

ACCESS_MASK, InitializeObjectAttributes, ZwCreateKey, ZwDeleteKey, ZwEnumerateKey, ZwEnumerateValueKey, ZwFlushKey, ZwQueryKey, ZwQueryValueKey, ZwSetValueKey