RegistryCallback routine

A filter driver's RegistryCallback routine can monitor, block, or modify a registry operation.

Syntax

C++

EX_CALLBACK_FUNCTION RegistryCallback;NTSTATUS RegistryCallback(  _In_      PVOID CallbackContext,  _In_opt_  PVOID Argument1,  _In_opt_  PVOID Argument2){ ... }

Parameters

CallbackContext [in]

The value that the driver passed as the Context parameter to CmRegisterCallback orCmRegisterCallbackEx when it registered this RegistryCallback routine.

Argument1 [in, optional]

A REG_NOTIFY_CLASS-typed value that identifies the type of registry operation that is being performed and whether the RegistryCallback routine is being called before or after the registry operation is performed.

Argument2 [in, optional]

A pointer to a structure that contains information that is specific to the type of registry operation. The structure type depends on the REG_NOTIFY_CLASS-typed value for Argument1, as shown in the following table. For information about which REG_NOTIFY_CLASS-typed values are available for which operating system versions, see REG_NOTIFY_CLASS.

REG_NOTIFY_CLASS ValueStructure TypeRegNtDeleteKeyREG_DELETE_KEY_INFORMATIONRegNtPreDeleteKeyREG_DELETE_KEY_INFORMATIONRegNtPostDeleteKeyREG_POST_OPERATION_INFORMATIONRegNtSetValueKeyREG_SET_VALUE_KEY_INFORMATIONRegNtPreSetValueKeyREG_SET_VALUE_KEY_INFORMATIONRegNtPostSetValueKeyREG_POST_OPERATION_INFORMATIONRegNtDeleteValueKeyREG_DELETE_VALUE_KEY_INFORMATIONRegNtPreDeleteValueKeyREG_DELETE_VALUE_KEY_INFORMATIONRegNtPostDeleteValueKeyREG_POST_OPERATION_INFORMATIONRegNtSetInformationKeyREG_SET_INFORMATION_KEY_INFORMATIONRegNtPreSetInformationKeyREG_SET_INFORMATION_KEY_INFORMATIONRegNtPostSetInformationKeyREG_POST_OPERATION_INFORMATIONRegNtRenameKeyREG_RENAME_KEY_INFORMATIONRegNtPreRenameKeyREG_RENAME_KEY_INFORMATIONRegNtPostRenameKeyREG_POST_OPERATION_INFORMATIONRegNtEnumerateKeyREG_ENUMERATE_KEY_INFORMATIONRegNtPreEnumerateKeyREG_ENUMERATE_KEY_INFORMATIONRegNtPostEnumerateKeyREG_POST_OPERATION_INFORMATIONRegNtEnumerateValueKeyREG_ENUMERATE_VALUE_KEY_INFORMATIONRegNtPreEnumerateValueKeyREG_ENUMERATE_VALUE_KEY_INFORMATIONRegNtPostEnumerateValueKeyREG_POST_OPERATION_INFORMATIONRegNtQueryKeyREG_QUERY_KEY_INFORMATIONRegNtPreQueryKeyREG_QUERY_KEY_INFORMATIONRegNtPostQueryKeyREG_POST_OPERATION_INFORMATIONRegNtQueryValueKeyREG_QUERY_VALUE_KEY_INFORMATIONRegNtPreQueryValueKeyREG_QUERY_VALUE_KEY_INFORMATIONRegNtPostQueryValueKeyREG_POST_OPERATION_INFORMATIONRegNtQueryMultipleValueKeyREG_QUERY_MULTIPLE_VALUE_KEY_INFORMATIONRegNtPreQueryMultipleValueKeyREG_QUERY_MULTIPLE_VALUE_KEY_INFORMATIONRegNtPostQueryMultipleValueKeyREG_POST_OPERATION_INFORMATIONRegNtPreCreateKeyREG_PRE_CREATE_KEY_INFORMATIONRegNtPreCreateKeyExREG_CREATE_KEY_INFORMATION**RegNtPostCreateKeyREG_POST_CREATE_KEY_INFORMATIONRegNtPostCreateKeyExREG_POST_OPERATION_INFORMATIONRegNtPreOpenKeyREG_PRE_OPEN_KEY_INFORMATION**RegNtPreOpenKeyExREG_OPEN_KEY_INFORMATIONRegNtPostOpenKeyREG_POST_OPEN_KEY_INFORMATIONRegNtPostOpenKeyExREG_POST_OPERATION_INFORMATIONRegNtKeyHandleCloseREG_KEY_HANDLE_CLOSE_INFORMATIONRegNtPreKeyHandleCloseREG_KEY_HANDLE_CLOSE_INFORMATIONRegNtPostKeyHandleCloseREG_POST_OPERATION_INFORMATIONRegNtPreFlushKeyREG_FLUSH_KEY_INFORMATIONRegNtPostFlushKeyREG_POST_OPERATION_INFORMATIONRegNtPreLoadKeyREG_LOAD_KEY_INFORMATIONRegNtPostLoadKeyREG_POST_OPERATION_INFORMATIONRegNtPreUnLoadKeyREG_UNLOAD_KEY_INFORMATIONRegNtPostUnLoadKeyREG_POST_OPERATION_INFORMATIONRegNtPreQueryKeySecurityREG_QUERY_KEY_SECURITY_INFORMATIONRegNtPostQueryKeySecurityREG_POST_OPERATION_INFORMATIONRegNtPreSetKeySecurityREG_SET_KEY_SECURITY_INFORMATIONRegNtPostSetKeySecurityREG_POST_OPERATION_INFORMATIONRegNtCallbackObjectContextCleanupREG_CALLBACK_CONTEXT_CLEANUP_INFORMATIONRegNtPreRestoreKeyREG_RESTORE_KEY_INFORMATIONRegNtPostRestoreKeyREG_RESTORE_KEY_INFORMATIONRegNtPreSaveKeyREG_SAVE_KEY_INFORMATIONRegNtPostSaveKeyREG_SAVE_KEY_INFORMATIONRegNtPreReplaceKeyREG_REPLACE_KEY_INFORMATIONRegNtPostReplaceKeyREG_REPLACE_KEY_INFORMATION

 

** Starting with Windows 7, the actual data structure passed in when the notify class isRegNtPreCreateKeyEx or RegNtPreOpenKeyEx is the V1 version of this structure,REG_CREATE_KEY_INFORMATION_V1 or REG_OPEN_KEY_INFORMATION_V1, respectively. Check theReserved member to determine the version of the structure.

Version numberStructure name0REG_CREATE_KEY_INFORMATION and REG_OPEN_KEY_INFORMATION1REG_CREATE_KEY_INFORMATION_V1 and REG_OPEN_KEY_INFORMATION_V1

 

Return value

Windows XP and Windows Server 2003:

If the RegistryCallback routine returns STATUS_SUCCESS, the configuration manager continues processing the registry operation.

If the RegistryCallback routine returns a status value for which NT_SUCCESS(status) equals FALSE, the configuration manager stops processing the registry operation and returns the specified return value to the calling thread.

Windows Vista and later:

If the RegistryCallback routine returns STATUS_SUCCESS, the configuration manager continues processing the registry operation.

If the RegistryCallback routine returns STATUS_CALLBACK_BYPASS, the configuration manager stops processing the registry operation and returns STATUS_SUCCESS to the calling thread.

If the RegistryCallback routine returns a status value for which NT_SUCCESS(status) equals FALSE (except for STATUS_CALLBACK_BYPASS), the configuration manager stops processing the registry operation and returns the specified return value to the calling thread.

For more information about when a RegistryCallback routine should return each of these status values, seeFiltering Registry Calls.

Remarks

To be notified of registry operations, a kernel-mode component (such as the driver component of an antivirus software package) can call CmRegisterCallback or CmRegisterCallbackEx to register a RegistryCallbackroutine.

The RegistryCallback routine can inspect the contents of the input and output buffers that are supplied for registry operations. A registry operation can be initiated by a user-mode application that calls a user-mode registry routine (such as RegCreateKeyEx or RegOpenKeyEx) or by a driver that calls a kernel-mode registry routine (such as ZwCreateKey or ZwOpenKey). An input buffer is a memory buffer supplied by the initiator from which the registry reads input data for the operation. An output buffer is a buffer supplied by the initiator into which the registry writes output data requested by the initiator.

Before calling the RegistryCallback routine, the kernel probes (to verify alignment and accessibility) all members of the Argument2 structures that point to output buffers in user-mode memory, but does not capture user-mode output buffers in system memory. The callback routine must enclose any access of an output buffer in atry/except block. If the callback routine needs to pass an output buffer pointer to a system routine (for example, ZwOpenKey), and the buffer is in user-mode memory, the callback routine must first capture the buffer.

The handling of input buffers depends on the Windows version. Starting with Windows 8, the kernel captures all input buffers pointed to by members of the Argument2 structures in system memory before calling theRegistryCallback routine. In versions of Windows before Windows 8, the kernel probes all members of theArgument2 structures that point to input buffers in user-mode memory, but captures only some of these buffers in system memory. In these earlier versions of Windows, the callback routine must enclose any access of an input buffer in a try/except block. Additionally, if the callback routine needs to pass an input buffer pointer to a system routine (for example, ZwOpenKey), and the buffer is in user-mode memory, the callback routine must first capture the buffer.

The following table summarizes the requirements for buffer accesses by the RegistryCallback routine.

Buffer typeWindows versionBuffer pointer passed to callback routineSafe for callback routine to directly access?Safe to pass to system routines (such asZwOpenKey)?User-mode inputWindows 8 and laterPoints to captured data.YesYesUser-mode inputWindows 7 and earlierPoints to captured data or original user-mode buffer.No. Must read under try/except.No. Must allocate kernel memory, copy data from the original buffer under try/except, and pass the copied data to the system routine.User-mode outputAllPoints to original user-mode buffer.No. Must write under try/except.No. Must allocate kernel memory, pass kernel memory to the system routine, and copy the results back to the original buffer under try/except.Kernel-mode input and outputAllPoints to original kernel-mode buffer.YesYes

 

For more information about RegistryCallback routines and registry filter drivers, see Filtering Registry Calls.

A RegistryCallback executes at IRQL = PASSIVE_LEVEL and in the context of the thread that is performing the registry operation.

Examples

To define a RegistryCallback callback routine, you must first provide a function declaration that identifies the type of callback routine you're defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define a RegistryCallback callback routine that is named MyRegistryCallback, use the EX_CALLBACK_FUNCTION type as shown in this code example:

EX_CALLBACK_FUNCTION MyRegistryCallback;

Then, implement your callback routine as follows:

_Use_decl_annotations_NTSTATUS   MyRegistryCallback(    PVOID  CallbackContext,    PVOID  Argument1,    PVOID  Argument2     )  {      // Function body  }

The EX_CALLBACK_FUNCTION function type is defined in the Wdm.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the _Use_decl_annotations_ annotation to your function definition. The _Use_decl_annotations_ annotation ensures that the annotations that are applied to the EX_CALLBACK_FUNCTION function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for WDM Drivers. For information about _Use_decl_annotations_, see Annotating Function Behavior.

Requirements

Version

Supported starting with Windows XP (see Return Value section).

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

IRQL

Called at PASSIVE_LEVEL (see Remarks section).

See also

CmRegisterCallback

CmUnRegisterCallback

ProbeForRead

REG_NOTIFY_CLASS

ZwOpenKey