Функция ObOpenObjectByPointer (ntifs.h)

Статья
08/07/2023

Функция ObOpenObjectByPointer открывает объект, на который ссылается указатель, и возвращает дескриптор объекту .

Синтаксис

NTSTATUS ObOpenObjectByPointer(
  [in]           PVOID           Object,
  [in]           ULONG           HandleAttributes,
  [in, optional] PACCESS_STATE   PassedAccessState,
  [in]           ACCESS_MASK     DesiredAccess,
  [in, optional] POBJECT_TYPE    ObjectType,
  [in]           KPROCESSOR_MODE AccessMode,
  [out]          PHANDLE         Handle
);

Параметры

[in] Object

Указатель на открываемый объект.

[in] HandleAttributes

Битовая маска флагов, указывающих требуемые атрибуты для дескриптора объекта. Если вызывающий объект не выполняется в контексте системного процесса, эти флаги должны включать OBJ_KERNEL_HANDLE. Этот параметр является необязательным и может быть равен нулю. В противном случае это сочетание одного или нескольких следующих значений.

Flag	Значение
OBJ_EXCLUSIVE	Объект должен быть открыт для монопольного доступа. Если этот флаг установлен и вызов ObOpenObjectByPointer завершается успешно, объект невозможно предоставить общий доступ и открыть его снова, пока не будет закрыт дескриптор. Этот флаг несовместим с флагом OBJ_INHERIT. Этот флаг недопустим для объектов файлов.
OBJ_FORCE_ACCESS_CHECK	Для объекта применяются все проверки доступа, даже если объект открывается в режиме ядра. Если этот флаг указан, значение параметра AccessMode игнорируется.
OBJ_INHERIT	Дескриптор может наследоваться дочерними процессами текущего процесса. Этот флаг несовместим с флагом OBJ_EXCLUSIVE.
OBJ_KERNEL_HANDLE	Доступ к дескриптору можно получить только в режиме ядра. Этот флаг необходимо указать, если вызывающий объект не выполняется в контексте системного процесса.

[in, optional] PassedAccessState

Указатель на структуру ACCESS_STATE , содержащую контекст субъекта объекта, предоставленные типы доступа и остальные требуемые типы доступа. Этот параметр является необязательным и может иметь значение NULL. В процедуре создания диспетчеризации этот указатель можно найти в разделе IrpSp-Parameters.Create.SecurityContext-AccessState>>, где IrpSp — это указатель на собственное расположение стека вызывающего объекта в IRP. (Дополнительные сведения см. в разделе IRP_MJ_CREATE.)

[in] DesiredAccess

ACCESS_MASK значение, указывающее требуемый доступ к объекту. Этот параметр является необязательным и может быть равен нулю.

[in, optional] ObjectType

Указатель на тип объекта. Если значение AccessMode равно KernelMode, этот параметр является необязательным и может иметь значение NULL. В противном случае он должен иметь значение *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsThreadType, *SeTokenObjectType или *CmKeyObjectType.

Примечание

Тип объекта SeTokenObjectType поддерживается в Windows XP, а тип объекта CmKeyObjectType поддерживается в Windows 7.

[in] AccessMode

Режим доступа, используемый для проверка доступа. Этот параметр является обязательным и должен иметь значение UserMode или KernelMode:

Если параметр AccessMode имеет значение KernelMode, система всегда разрешает запрошенный доступ независимо от того, какой ограниченный доступ был задан ранее драйвером (например, доступ был ограничен в предыдущем вызове POB_PRE_OPERATION_CALLBACK обратного вызова).
Если AccessMode имеет значение UserMode, запрошенный доступ сравнивается с предоставленным доступом для объекта .

[out] Handle

Указатель на переменную, выделенную вызывающим объектом, которая получает дескриптор объекта .

Возвращаемое значение

ObOpenObjectByPointer возвращает STATUS_SUCCESS или соответствующее значение NTSTATUS, например одно из следующих значений:

Код возврата	Описание
STATUS_ACCESS_DENIED	Вызывающий объект не имеет необходимого доступа для открытия дескриптора для объекта . Это код ошибки.
STATUS_INSUFFICIENT_RESOURCES	ObOpenObjectByPointer обнаружил сбой выделения пула. Это код ошибки.
STATUS_INVALID_PARAMETER	В параметре HandleAttributes указано недопустимое значение флага. Это код ошибки.
STATUS_OBJECT_TYPE_MISMATCH	Объект, на который указывает параметр Object , не был типом, указанным в параметре ObjectType . Это код ошибки.
STATUS_PRIVILEGE_NOT_HELD	У вызывающего объекта не было необходимых привилегий для создания дескриптора с доступом, указанным в параметре DesiredAccess . Это код ошибки.
STATUS_QUOTA_EXCEEDED	Вызывающий объект выполняется в контексте процесса, квоты памяти которого недостаточно для выделения дескриптора объекта. Это код ошибки.
STATUS_UNSUCCESSFUL	Не удалось создать дескриптор объекта. Это код ошибки.

Если параметр Object указывает на файловый объект (т. е. структуру FILE_OBJECT), метод ObOpenObjectByPointer можно вызывать только после создания хотя бы одного дескриптора для объекта файла. Вызывающие объекты могут проверка элемент Flags структуры FILE_OBJECT, на которую указывает параметр Object. Если установлен флаг FO_HANDLE_CREATED, это означает, что для объекта файла создан один или несколько дескрипторов, поэтому можно с уверенностью вызывать ObOpenObjectByPointer.

Любой дескриптор, полученный путем вызова ObOpenObjectByPointer , в конечном итоге должен быть освобожден путем вызова ZwClose.

Подпрограммы драйвера, выполняемые в контексте процесса, отличном от контекста системного процесса, должны задать флаг OBJ_KERNEL_HANDLE в параметре HandleAttributes . Это ограничивает использование дескриптора, возвращаемого ObOpenObjectByPointer , процессами, работающими в режиме ядра. В противном случае дескриптор может получить доступ к процессу, в контексте которого выполняется драйвер.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	ntifs.h (включая Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL