ZwCreateKey 函数 (wdm.h)

项目
03/08/2023

ZwCreateKey 例程创建新的注册表项或打开现有注册表项。

语法

NTSYSAPI NTSTATUS ZwCreateKey(
  [out]           PHANDLE            KeyHandle,
  [in]            ACCESS_MASK        DesiredAccess,
  [in]            POBJECT_ATTRIBUTES ObjectAttributes,
                  ULONG              TitleIndex,
  [in, optional]  PUNICODE_STRING    Class,
  [in]            ULONG              CreateOptions,
  [out, optional] PULONG             Disposition
);

参数

[out] KeyHandle

指向 HANDLE 变量的指针，该变量接收键的句柄。

[in] DesiredAccess

指定一个 ACCESS_MASK 值，该值确定对对象的请求访问权限。除了为所有类型的对象定义的访问权限 (请参阅 ACCESS_MASK) ，调用方还可以指定以下一个或多个特定于对象目录的访问权限：

DesiredAccess 标志	允许调用方执行此操作
KEY_QUERY_VALUE	读取键值。
KEY_SET_VALUE	写入键值。
KEY_CREATE_SUB_KEY	为密钥创建子项。
KEY_ENUMERATE_SUB_KEYS	读取密钥的子项。
KEY_CREATE_LINK	创建指向密钥的符号链接。设备和中间驱动程序不使用此标志。
KEY_NOTIFY	当密钥的名称、值或属性发生更改时，请求接收通知。有关详细信息，请参阅 ZwNotifyChangeKey。

调用方还可以指定以下常量之一，这些常量组合了多个ACCESS_MASK标志。

一直	由这些ACCESS_MASK标志组成
KEY_READ	STANDARD_RIGHTS_READ、KEY_QUERY_VALUE、KEY_ENUMERATE_SUB_KEYS 和 KEY_NOTIFY
KEY_WRITE	STANDARD_RIGHTS_WRITE、KEY_SET_VALUE和KEY_CREATE_SUB_KEY
KEY_EXECUTE	与 KEY_READ 相同。
KEY_ALL_ACCESS	STANDARD_RIGHTS_ALL、KEY_QUERY_VALUE、KEY_SET_VALUE、KEY_CREATE_SUB_KEY、KEY_ENUMERATE_SUB_KEYS、KEY_NOTIFY和KEY_CREATE_LINK

[in] ObjectAttributes

指向 OBJECT_ATTRIBUTES 结构的指针，该结构指定对象名称和其他属性。使用 InitializeObjectAttributes 初始化此结构。如果调用方未在系统线程上下文中运行，则必须在调用 InitializeObjectAttributes 时设置 OBJ_KERNEL_HANDLE 属性。

TitleIndex

设备和中间驱动程序将此参数设置为零。

[in, optional] Class

指向包含密钥对象类的 Unicode 字符串的指针。此信息由配置管理器使用。

[in] CreateOptions

指定在创建或打开键时要应用的选项，指定为以下标志的兼容组合。

CreateOptions 标志	说明
REG_OPTION_VOLATILE	重新启动系统时，不会保留密钥。
REG_OPTION_NON_VOLATILE	重新启动系统时，会保留密钥。
REG_OPTION_CREATE_LINK	新创建的键是符号链接。设备和中间驱动程序不使用此标志。
REG_OPTION_BACKUP_RESTORE	应使用允许备份和还原操作的特殊权限创建或打开密钥。设备和中间驱动程序不使用此标志。

[out, optional] Disposition

指向一个变量的指针，该变量接收一个值，该值指示是创建新键还是打开了现有键。

处置值	说明
REG_CREATED_NEW_KEY	已创建新密钥。
REG_OPENED_EXISTING_KEY	已打开现有密钥。

返回值

ZwCreateKey 在成功时返回STATUS_SUCCESS，或在失败时返回相应的 NTSTATUS 错误代码。

注解

ZwCreateKey 提供调用方可用于操作注册表项的句柄。有关详细信息，请参阅在驱动程序中使用注册表。

不再使用 KeyHandle 指向的句柄后，驱动程序必须调用 ZwClose 来关闭它。

可通过两种替代方法指定要使用 ZwCreateKey 创建或打开的文件的名称：

作为完全限定的路径名，在输入 ObjectAttributes 的 ObjectName 成员中提供。注册表项的路径名以 \Registry 开头。
作为相对于另一个注册表项的路径名，由输入 ObjectAttributes 的 RootDirectory 成员中的句柄表示。

如果 ObjectAttributes 指定的键不存在，则例程将尝试创建密钥。若要成功尝试，新密钥必须是 RootDirectory 引用的密钥的直接子项，并且 RootDirectory 引用的密钥必须已打开才能KEY_CREATE_SUB_KEY访问。

如果指定的键已存在，则会打开它，并且其值不会以任何方式受到影响。

创建密钥时由 ObjectAttributs 指定的安全属性确定是否在后续调用 ZwCreateKey 和 ZwOpenKey 时授予指定的 DesiredAccess。

如果调用方未在系统线程上下文中运行，它必须确保它创建的任何句柄都是专用句柄。否则，运行驱动程序的上下文的进程可以访问句柄。有关详细信息，请参阅对象句柄。

有关使用注册表项的详细信息，请参阅在驱动程序中使用注册表。

如果在用户模式下调用此函数，则应使用名称“NtCreateKey”而不是“ZwCreateKey”。

内核模式驱动程序无法直接访问 Windows 内核中的 NtCreateKey 例程。

对于来自内核模式驱动程序的调用，Windows 本机系统服务例程的 NtXxx 和 ZwXxx 版本在处理和解释输入参数的方式上的行为可能有所不同。有关例程的 NtXxx 和 ZwXxx 版本之间的关系的详细信息，请参阅使用本机系统服务例程的 Nt 和 Zw 版本。

要求

要求	值
目标平台	通用
标头	wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 符合性规则	HwStorPortProhibitedDDI (storport) 、 IrqlZwPassive (wdm) 、 PowerIrpDDis (wdm) 、 ZwRegistryCreate (storport) 、ZwRegistryCreate (storport) ， ZwRegistryCreate (wdm) ， ZwRegistryOpen (wdm)