A filter driver's RegistryCallback routine can monitor, block, or modify a registry operation.
Syntax
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 Value Structure Type RegNtDeleteKey REG_DELETE_KEY_INFORMATION RegNtPreDeleteKey REG_DELETE_KEY_INFORMATION RegNtPostDeleteKey REG_POST_OPERATION_INFORMATION RegNtSetValueKey REG_SET_VALUE_KEY_INFORMATION RegNtPreSetValueKey REG_SET_VALUE_KEY_INFORMATION RegNtPostSetValueKey REG_POST_OPERATION_INFORMATION RegNtDeleteValueKey REG_DELETE_VALUE_KEY_INFORMATION RegNtPreDeleteValueKey REG_DELETE_VALUE_KEY_INFORMATION RegNtPostDeleteValueKey REG_POST_OPERATION_INFORMATION RegNtSetInformationKey REG_SET_INFORMATION_KEY_INFORMATION RegNtPreSetInformationKey REG_SET_INFORMATION_KEY_INFORMATION RegNtPostSetInformationKey REG_POST_OPERATION_INFORMATION RegNtRenameKey REG_RENAME_KEY_INFORMATION RegNtPreRenameKey REG_RENAME_KEY_INFORMATION RegNtPostRenameKey REG_POST_OPERATION_INFORMATION RegNtEnumerateKey REG_ENUMERATE_KEY_INFORMATION RegNtPreEnumerateKey REG_ENUMERATE_KEY_INFORMATION RegNtPostEnumerateKey REG_POST_OPERATION_INFORMATION RegNtEnumerateValueKey REG_ENUMERATE_VALUE_KEY_INFORMATION RegNtPreEnumerateValueKey REG_ENUMERATE_VALUE_KEY_INFORMATION RegNtPostEnumerateValueKey REG_POST_OPERATION_INFORMATION RegNtQueryKey REG_QUERY_KEY_INFORMATION RegNtPreQueryKey REG_QUERY_KEY_INFORMATION RegNtPostQueryKey REG_POST_OPERATION_INFORMATION RegNtQueryValueKey REG_QUERY_VALUE_KEY_INFORMATION RegNtPreQueryValueKey REG_QUERY_VALUE_KEY_INFORMATION RegNtPostQueryValueKey REG_POST_OPERATION_INFORMATION RegNtQueryMultipleValueKey REG_QUERY_MULTIPLE_VALUE_KEY_INFORMATION RegNtPreQueryMultipleValueKey REG_QUERY_MULTIPLE_VALUE_KEY_INFORMATION RegNtPostQueryMultipleValueKey REG_POST_OPERATION_INFORMATION RegNtPreCreateKey REG_PRE_CREATE_KEY_INFORMATION RegNtPreCreateKeyEx REG_CREATE_KEY_INFORMATION** RegNtPostCreateKey REG_POST_CREATE_KEY_INFORMATION RegNtPostCreateKeyEx REG_POST_OPERATION_INFORMATION RegNtPreOpenKey REG_PRE_OPEN_KEY_INFORMATION** RegNtPreOpenKeyEx REG_OPEN_KEY_INFORMATION RegNtPostOpenKey REG_POST_OPEN_KEY_INFORMATION RegNtPostOpenKeyEx REG_POST_OPERATION_INFORMATION RegNtKeyHandleClose REG_KEY_HANDLE_CLOSE_INFORMATION RegNtPreKeyHandleClose REG_KEY_HANDLE_CLOSE_INFORMATION RegNtPostKeyHandleClose REG_POST_OPERATION_INFORMATION RegNtPreFlushKey REG_FLUSH_KEY_INFORMATION RegNtPostFlushKey REG_POST_OPERATION_INFORMATION RegNtPreLoadKey REG_LOAD_KEY_INFORMATION RegNtPostLoadKey REG_POST_OPERATION_INFORMATION RegNtPreUnLoadKey REG_UNLOAD_KEY_INFORMATION RegNtPostUnLoadKey REG_POST_OPERATION_INFORMATION RegNtPreQueryKeySecurity REG_QUERY_KEY_SECURITY_INFORMATION RegNtPostQueryKeySecurity REG_POST_OPERATION_INFORMATION RegNtPreSetKeySecurity REG_SET_KEY_SECURITY_INFORMATION RegNtPostSetKeySecurity REG_POST_OPERATION_INFORMATION RegNtCallbackObjectContextCleanup REG_CALLBACK_CONTEXT_CLEANUP_INFORMATION RegNtPreRestoreKey REG_RESTORE_KEY_INFORMATION RegNtPostRestoreKey REG_RESTORE_KEY_INFORMATION RegNtPreSaveKey REG_SAVE_KEY_INFORMATION RegNtPostSaveKey REG_SAVE_KEY_INFORMATION RegNtPreReplaceKey REG_REPLACE_KEY_INFORMATION RegNtPostReplaceKey REG_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 number Structure name 0 REG_CREATE_KEY_INFORMATION and REG_OPEN_KEY_INFORMATION 1 REG_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 type | Windows version | Buffer pointer passed to callback routine | Safe for callback routine to directly access? | Safe to pass to system routines (such asZwOpenKey)? |
|---|---|---|---|---|
| User-mode input | Windows 8 and later | Points to captured data. | Yes | Yes |
| User-mode input | Windows 7 and earlier | Points 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 output | All | Points 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 output | All | Points to original kernel-mode buffer. | Yes | Yes |
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 |
|
| IRQL |
Called at PASSIVE_LEVEL (see Remarks section). |
See also
- CmRegisterCallback
- CmUnRegisterCallback
- ProbeForRead
- REG_NOTIFY_CLASS
- ZwOpenKey