Edit

WdmlibIoValidateDeviceIoControlAccess function (wdmsec.h)

  • Article

The WdmlibIoValidateDeviceIoControlAccess function verifies that the sender of an IRP_MJ_DEVICE_CONTROL or IRP_MJ_FILE_SYSTEM_CONTROL IRP has the specified access to the device object.

Syntax

NTSTATUS WdmlibIoValidateDeviceIoControlAccess(
  [in] PIRP  Irp,
  [in] ULONG RequiredAccess
);

Parameters

[in] Irp

Specifies the IRP on which to perform the access check.

[in] RequiredAccess

Specifies the type of access to the device object that the request sender must have. The caller can specify one or more of the following flags.

Value Meaning
FILE_READ_ACCESS
 The request sender must have read access to the device object
FILE_WRITE_ACCESS
 The request sender must have write access to the device object.

Return value

WdmlibIoValidateDeviceIoControlAccess returns an NTSTATUS value. Possible return values include:

Return code Description
STATUS_SUCCESS
 The request sender has the necessary access to the device object.
STATUS_ACCESS_DENIED
 The request sender does not have the necessary access to the device object.
STATUS_INVALID_PARAMETER
 The specified parameters are invalid. For example, if the routine is passed an IRP that is not an IRP_MJ_DEVICE_CONTROL or IRP_MJ_FILE_SYSTEM_CONTROL IRP, it returns STATUS_INVALID_PARAMETER.

Remarks

WdmlibIoValidateDeviceIoControlAccess allows drivers to perform dynamic access checks for IOCTLs. Use this routine to require more restrictive access than that specified in the IOCTL's definition. If the routine returns STATUS_ACCESS_DENIED, then the driver can complete the request with the STATUS_ACCESS_DENIED status value.

For example, if an IOCTL is defined with a RequiredAccess value of FILE_ANY_ACCESS, then by default any request sender with SYNCHRONIZE access to the device object can send the IOCTL. Use WdmlibIoValidateDeviceIoControlAccess to require more stringent security at run time. For more information about the RequiredAccess value of an IOCTL, see Defining I/O Control Codes.

The access checks are only performed if the RequestorMode member of the IRP structure is UserMode. If RequestorMode is KernelMode, the routine automatically returns STATUS_SUCCESS.

Requirements

Requirement Value
Minimum supported client Available in Windows Server 2003 and later versions of Windows. Drivers that must also work for Windows 2000 and Windows XP can instead link to Wdmsec.lib to use this routine. (The Wdmsec.lib library first shipped with the Windows XP Service Pack 1 [SP1] and Windows Server 2003 editions of the Driver Development Kit [DDK] and now ships with the Windows Driver Kit [WDK].)
Target Platform Universal
Header wdmsec.h (include Wdmsec.h, Wdm.h, Ntddk.h, Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL Any level

See also

IRP