NtEnumerateKey - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers 
#ifndef _NTREGAPI_H

/**
 * Retrieves one direct subkey by index. This enumerates keys, not value entries;
 * use NtEnumerateValueKey for values. Returned metadata belongs to the selected
 * child, not the parent represented by KeyHandle.
 *
 * \param[in] KeyHandle Parent key handle with KEY_ENUMERATE_SUB_KEYS access.
 * \param[in] Index Zero-based index. STATUS_NO_MORE_ENTRIES ends enumeration.
 * Indices are not stable identifiers: mutations can change which child an index
 * selects, and repeated calls need not return the same child.
 * \param[in] KeyInformationClass KeyBasicInformation, KeyNodeInformation or
 * KeyFullInformation (0 through 2). Other selectors return STATUS_INVALID_PARAMETER
 * on the native/WoW64 paths, including classes accepted by NtQueryKey.
 * \param[out] KeyInformation Caller-owned output buffer. NULL with Length = 0
 * supports sizing for an existing index. Prefer naturally aligned storage;
 * the native entry requires 4-byte alignment for a nonempty output buffer.
 * \param[in] Length Output capacity in bytes, not WCHARs.
 * \param[out] ResultLength Required pointer. Receives the complete required byte
 * size on success or either short-buffer status. It can exceed Length, and
 * NameLength/ClassLength remain full lengths on overflow. Bound every read by
 * capacity; no terminator is appended. Enumeration end is not a sizing result.
 * \return STATUS_SUCCESS, STATUS_BUFFER_TOO_SMALL if the fixed prefix cannot
 * fit, STATUS_BUFFER_OVERFLOW for a partial record, STATUS_NO_MORE_ENTRIES at
 * the end, or another error status. No key handle is returned or retained.
 * \remarks The WoW64 thunk realigns output not aligned to 8 bytes by
 * copying Length bytes from the caller into temporary storage before the native
 * call, then copying Length bytes back regardless of status. This path therefore
 * reads the caller's storage as well as writing it; use readable/writable storage.
 * Unlike NtQueryKey's thunk, an unaligned non-NULL buffer with Length = 0 returns
 * STATUS_NO_MEMORY before the syscall. Use NULL for zero-length size discovery.
 * Do not generalize this behavior to the separate value-enumeration thunk.
 * Registry filters, transactions, layered keys and virtualization can affect the
 * enumeration; there is no stable multi-call snapshot guarantee.
 * \sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/wdm/nf-wdm-zwenumeratekey
 */
_Kernel_entry_
NTSYSCALLAPI
NTSTATUS
NTAPI
NtEnumerateKey(
    _In_ HANDLE KeyHandle,
    _In_ ULONG Index,
    _In_ KEY_INFORMATION_CLASS KeyInformationClass,
    _Out_writes_bytes_to_opt_(Length, *ResultLength) PVOID KeyInformation,
    _In_ ULONG Length,
    _Out_ PULONG ResultLength
    );

#endif

View code on GitHub
#ifndef _NTZWAPI_H

_Kernel_entry_
NTSYSCALLAPI
NTSTATUS
NTAPI
ZwEnumerateKey(
    _In_ HANDLE KeyHandle,
    _In_ ULONG Index,
    _In_ KEY_INFORMATION_CLASS KeyInformationClass,
    _Out_writes_bytes_to_opt_(Length, *ResultLength) PVOID KeyInformation,
    _In_ ULONG Length,
    _Out_ PULONG ResultLength
    );

#endif

View code on GitHub
// wdm.h

NTSYSAPI NTSTATUS ZwEnumerateKey(
  [in]            HANDLE                KeyHandle,
  [in]            ULONG                 Index,
  [in]            KEY_INFORMATION_CLASS KeyInformationClass,
  [out, optional] PVOID                 KeyInformation,
  [in]            ULONG                 Length,
  [out]           PULONG                ResultLength
);
View the official Windows Driver Kit DDI reference

NtDoc

No description available.

Edit description on GitHub

Windows Driver Kit DDI reference (nf-wdm-zwenumeratekey)

Description

The ZwEnumerateKey routine returns information about a subkey of an open registry key.

Parameters

KeyHandle [in]

Handle to the registry key that contains the subkeys to be enumerated. The handle is created by a successful call to ZwCreateKey or ZwOpenKey.

Index [in]

The index of the subkey that you want information for. If the key has n subkeys, the subkeys are numbered from 0 to n-1.

KeyInformationClass [in]

Specifies a KEY_INFORMATION_CLASS enumeration value that determines the type of information to be received by the KeyInformation buffer. Set KeyInformationClass to one of the following values:

If any value not in this list is specified, the routine returns error code STATUS_INVALID_PARAMETER.

KeyInformation [out, optional]

Pointer to a caller-allocated buffer that receives the requested information. The KeyInformationClass parameter determines the type of information provided.

Length [in]

Specifies the size, in bytes, of the KeyInformation buffer.

ResultLength [out]

Pointer to a variable that receives the size, in bytes, of the registry-key information. If ZwEnumerateKey returns STATUS_SUCCESS, you can use the value of this variable to determine the amount of data returned. If the routine returns STATUS_BUFFER_OVERFLOW or STATUS_BUFFER_TOO_SMALL, you can use the value of this variable to determine the size of buffer required to hold the key information.

Return value

ZwEnumerateKey returns STATUS_SUCCESS on success, or the appropriate NTSTATUS error code on failure. Possible error code values include:

Return code Description
STATUS_BUFFER_OVERFLOW The buffer supplied is too small, and only partial data has been written to the buffer. *ResultLength is set to the minimum size required to hold the requested information.
STATUS_BUFFER_TOO_SMALL The buffer supplied is too small, and no data has been written to the buffer. *ResultLength is set to the minimum size required to hold the requested information.
STATUS_INVALID_PARAMETER The KeyInformationClass parameter is not a valid KEY_INFORMATION_CLASS value.
STATUS_NO_MORE_ENTRIES The Index value is out of range for the registry key specified by KeyHandle. For example, if a key has n subkeys, then for any value greater than n-1 the routine returns STATUS_NO_MORE_ENTRIES.

Remarks

The handle must have been opened with KEY_ENUMERATE_SUB_KEYS access. This is accomplished by passing KEY_ENUMERATE_SUB_KEYS, KEY_READ, or KEY_ALL_ACCESS as the DesiredAccess parameter to ZwCreateKey or ZwOpenKey.

The Index parameter is simply a way to select among subkeys of the key referred to by the KeyHandle. Two calls to ZwEnumerateKey with the same Index are not guaranteed to return the same result.

For more information about working with registry keys, see Using the Registry in a Driver.

If the call to this function occurs in user mode, you should use the name "NtEnumerateKey" instead of "ZwEnumerateKey".

For calls from kernel-mode drivers, the NtXxx and ZwXxx versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the NtXxx and ZwXxx versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

See also

KEY_BASIC_INFORMATION

KEY_FULL_INFORMATION

KEY_INFORMATION_CLASS

KEY_NODE_INFORMATION

RtlCheckRegistryKey

RtlCreateRegistryKey

RtlDeleteRegistryValue

RtlQueryRegistryValues

RtlWriteRegistryValue

ZwCreateKey

ZwEnumerateValueKey

ZwOpenKey

View the official Windows Driver Kit DDI reference

Edit description on GitHub

NTinternals.net (undocumented.ntinternals.net)

This function is documented in Windows Driver Kit.

See ZwEnumerateKey in NT DDK or 2000 DDK for detailed description.

See also

Edit description on GitHub