MmSecureVirtualMemory routine

The MmSecureVirtualMemory routine secures a user-space memory address range so that it cannot be freed and its protection type cannot be made more restrictive.

Syntax


HANDLE MmSecureVirtualMemory(
  _In_ PVOID  Address,
  _In_ SIZE_T Size,
  _In_ ULONG  ProbeMode
);

Parameters

Address [in]

The beginning of the user virtual address range to secure.

Size [in]

The size, in bytes, of the virtual address range to secure.

ProbeMode [in]

The most restrictive protection type that is allowed. Use PAGE_READWRITE to specify that address range must remain both readable and writable, or use PAGE_READONLY to specify the address range must only remain readable.

Return value

On success, MmSecureVirtualMemory returns an opaque pointer value that the driver passes to the MmUnsecureVirtualMemory routine to unsecure the memory address range. If the routine is unable to secure the memory address range, it returns NULL.

Remarks

MmSecureVirtualMemory can be used to avoid certain race conditions on user-mode buffers. For example, if a driver checks to see if the buffer is writable, but then the originating user-mode process changes the buffer to be read-only before the driver can write to the buffer, then a race condition can result. A driver that uses MmSecureVirtualMemory is guaranteed that if the requested protection mode is available, it cannot be changed until the driver calls MmUnsecureVirtualMemory. The routine also protects against the originating user-mode process freeing the buffer. Here are a few guidelines about calling those routines:

  • If a driver calls MmSecureVirtualMemory and does not call MmUnsecureVirtualMemory, the memory is automatically unsecured when the process terminates.

  • If the driver calls MmUnsecureVirtualMemory, it must call it in the context of the process in which the memory was originally secured, and before that process terminates.

  • Typically drivers need to reference the process when they secure the memory, then later call KeStackAttachProcess to switch to the context of that process before calling MmUnsecureVirtualMemory.

  • To detect process termination drivers can use PsSetCreateProcessNotifyRoutine. Alternatively, the process can submit an IRP with a cancel routine that is invoked by the I/O manager when the process is exiting. In the cancel routine the driver can attach to the process and call MmUnsecureVirtualMemory.

While calling MmSecureVirtualMemory on an address range prevents the address range from being freed or from having its protection changed, it does not protect against other types of raised exceptions. (For example, it does not protect against an exception raised when the system finds a bad disk block in the page file.) Therefore, drivers must still wrap any memory accesses in a try/except block. Therefore, we recommend that drivers do not use this function. For more information, see Handling Exceptions.

Requirements

Target platform

Universal

Version

Available starting with Windows 2000.

Header

Ntddk.h (include Ntddk.h)

Library

NtosKrnl.lib

DLL

NtosKrnl.exe

IRQL

<=APC_LEVEL

DDI compliance rules

IrqlMmApcLte, HwStorPortProhibitedDDIs

See also

MmUnsecureVirtualMemory

 

 

Send comments about this topic to Microsoft

Show: