ZwCreateKey

The ZwCreateKey routine opens an existing key or creates a new key in the registry.

NTSTATUS 
  ZwCreateKey(
    OUT PHANDLE  KeyHandle,
    IN ACCESS_MASK  DesiredAccess,
    IN POBJECT_ATTRIBUTES  ObjectAttributes,
    IN ULONG  TitleIndex,
    IN PUNICODE_STRING  Class  OPTIONAL,
    IN ULONG  CreateOptions,
    OUT PULONG  Disposition  OPTIONAL
    );

Parameters

KeyHandle

Pointer to a returned handle for a newly created or existing key 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 the type of access that the caller requires to the key. The set of system-defined DesiredAccess flags determines the following specific access rights for key objects.

DesiredAccess Flags	Meaning
KEY_QUERY_VALUE	Value entries for the key can be read.
KEY_SET_VALUE	Value entries for the key can be written.
KEY_CREATE_SUB_KEY	Subkeys for the key can be created.
KEY_ENUMERATE_SUB_KEYS	All subkeys for the key can be read.
KEY_NOTIFY	This flag is irrelevant to device and intermediate drivers, and to other kernel-mode code.
KEY_CREATE_LINK	A symbolic link to the key can be created. This flag is irrelvant to device and intermediate drivers.

Callers of ZwCreateKey can specify one or a compatible combination of the following for any key object.

DesiredAccess to Key Values	Maps to DesiredAccess Flags
KEY_READ	STANDARD_RIGHTS_READ, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, and KEY_NOTIFY
KEY_WRITE	STANDARD_RIGHTS_WRITE, KEY_SET_VALUE, and KEY_CREATE_SUBKEY
KEY_EXECUTE	KEY_READ. This value is irrelevant to device and intermediate drivers.
KEY_ALL_ACCESS	STANDARD_RIGHTS_ALL, KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUBKEY, KEY_NOTIFY and KEY_CREATE_LINK

The STANDARD_RIGHTS_XXX are predefined system values used to enforce security on system objects.

ObjectAttributes

Pointer to the initialized object attributes of the key being opened or created. An ObjectName string for the key must be specified. If a RootDirectory handle also is supplied, the given name is relative to the key represented by the handle. Any given name must be within the object name space allocated to the registry, meaning that all names must begin with \Registry. RootHandle, if present, must be a handle to the root directory object, to \Registry, or to a key under \Registry. If the caller is not running in the system process context, it must set the OBJ_KERNEL_HANDLE attribute for ObjectAttributes. For more information, see InitializeObjectAttributes.

TitleIndex

Device and intermediate drivers should set this parameter to zero.

Class

Pointer to the object class of the key. To the Configuration Manager, this is just a Unicode string.

CreateOptions

Specifies options to be applied when creating a key, as a compatible combination of the following.

Value	Meaning
REG_OPTION_VOLATILE	Key is not to be stored across boots.
REG_OPTION_NON_VOLATILE	Key is preserved when the system is rebooted.
REG_OPTION_CREATE_LINK	The created key is a symbolic link. This value is irrelevant to device and intermediate drivers.
REG_OPTION_BACKUP_RESTORE	Key is being opened or created with special privileges allowing backup/restore operations. This value is irrelevant to device and intermediate drivers.

Disposition

Pointer to a variable that receives a value indicating whether a new key was created in the \Registry tree or an existing one opened.

Value	Meaning
REG_CREATED_NEW_KEY	A new key object was created.
REG_OPENED_EXISTING_KEY	An existing key object was opened.

Headers

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

Return Value

ZwCreateKey returns STATUS_SUCCESS if the given key was created or opened, or the appropriate error status on failure.

Comments

If the key specified by ObjectAttributes does not exist, an attempt is made to create it. For this attempt to succeed, the new key must be a direct subkey of the key referred to by KeyHandle, and the given KeyHandle must have been opened for KEY_CREATE_SUB_KEY access.

If the specified key already exists, it is opened and its value is not affected in any way.

The security attributes specified by ObjectAttributes when a key is created determine whether the specified DesiredAccess is granted on subsequent calls to ZwCreateKey and ZwOpenKey.

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 ZwCreateKey. This restricts the use of the handle returned by ZwCreateKey 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 ZwCreateKey must be running at IRQL = PASSIVE_LEVEL.

See Also

ACCESS_MASK, InitializeObjectAttributes, ZwClose, ZwDeleteKey, ZwEnumerateKey, ZwEnumerateValueKey, ZwFlushKey, ZwOpenKey, ZwQueryValueKey, ZwSetValueKey