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

디바이스 및 중간 드라이버는 이 매개 변수를 0으로 설정합니다.

[in, optional] Class

키의 개체 클래스를 포함하는 유니코드 문자열에 대한 포인터입니다. 이 정보는 구성 관리자에서 사용됩니다.

[in] CreateOptions

다음 플래그의 호환 조합으로 지정된 키를 만들거나 열 때 적용할 옵션을 지정합니다.

CreateOptions 플래그	Description
REG_OPTION_VOLATILE	시스템이 다시 부팅될 때 키가 유지되지 않습니다.
REG_OPTION_NON_VOLATILE	시스템이 다시 부팅될 때 키가 유지됩니다.
REG_OPTION_CREATE_LINK	새로 만든 키는 기호 링크입니다. 이 플래그는 디바이스 및 중간 드라이버에서 사용되지 않습니다.
REG_OPTION_BACKUP_RESTORE	백업 및 복원 작업을 허용하는 특별한 권한으로 키를 만들거나 열어야 합니다. 이 플래그는 디바이스 및 중간 드라이버에서 사용되지 않습니다.

[out, optional] Disposition

새 키가 만들어졌는지 아니면 기존 키가 열렸는지를 나타내는 값을 수신하는 변수에 대한 포인터입니다.

처리 값	Description
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 액세스를 위해 열려 있어야 합니다.

지정된 키가 이미 있는 경우 해당 키가 열리고 해당 값이 어떤 식으로든 영향을 받지 않습니다.

키가 생성될 때 ObjectAttributes에서 지정한 보안 특성은 ZwCreateKey 및 ZwOpenKey에 대한 후속 호출에서 지정된 DesiredAccess가 부여되는지 여부를 결정합니다.

호출자가 시스템 스레드 컨텍스트에서 실행되고 있지 않으면 호출자가 만드는 핸들이 프라이빗 핸들인지 확인해야 합니다. 그렇지 않으면 드라이버가 실행 중인 컨텍스트의 프로세스에서 핸들에 액세스할 수 있습니다. 자세한 내용은 개체 핸들을 참조하세요.

레지스트리 키 작업에 대한 자세한 내용은 드라이버에서 레지스트리 사용을 참조하세요.

이 함수에 대한 호출이 사용자 모드에서 발생하는 경우 "ZwCreateKey" 대신 "NtCreateKey"라는 이름을 사용해야 합니다.

Windows 커널의 NtCreateKey 루틴은 커널 모드 드라이버에서 직접 액세스할 수 없습니다.

커널 모드 드라이버에서 호출하는 경우 Windows 네이티브 시스템 서비스 루틴의 NtXxx 및 ZwXxx 버전은 입력 매개 변수를 처리하고 해석하는 방식으로 다르게 동작할 수 있습니다. 루틴의 NtXxx 버전과 ZwXxx 버전 간의 관계에 대한 자세한 내용은 네이티브 시스템 서비스 루틴의 Nt 및 Zw 버전 사용을 참조하세요.

요구 사항

요구 사항	값
대상 플랫폼	유니버설
헤더	wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 규정 준수 규칙	HwStorPortProhibitedDDIs(storport), IrqlZwPassive(wdm), PowerIrpDDis(wdm), ZwRegistryCreate(storport), ZwRegistryCreate(storport), ZwRegistryCreate(wdm), ZwRegistryOpen(wdm)