Fonction ObOpenObjectByPointer (ntifs.h)

Article
08/07/2023

La fonction ObOpenObjectByPointer ouvre un objet référencé par un pointeur et retourne un handle à l’objet.

Syntaxe

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
);

Paramètres

[in] Object

Pointeur vers l’objet à ouvrir.

[in] HandleAttributes

Masque de bits d’indicateurs spécifiant les attributs souhaités pour le handle d’objet. Si l’appelant n’est pas en cours d’exécution dans le contexte du processus système, ces indicateurs doivent inclure OBJ_KERNEL_HANDLE. Ce paramètre est facultatif et peut être égal à zéro. Sinon, il s’agit d’une combinaison OR’ed d’une ou plusieurs des valeurs suivantes.

Indicateur	Signification
OBJ_EXCLUSIVE	L’objet doit être ouvert pour un accès exclusif. Si cet indicateur est défini et que l’appel à ObOpenObjectByPointer réussit, l’objet ne peut pas être partagé et ne peut pas être rouvert tant que le handle n’est pas fermé. Cet indicateur n’est pas compatible avec l’indicateur OBJ_INHERIT. Cet indicateur n’est pas valide pour les objets de fichier.
OBJ_FORCE_ACCESS_CHECK	Toutes les vérifications d’accès doivent être appliquées pour l’objet, même si l’objet est ouvert en mode noyau. Si cet indicateur est spécifié, la valeur du paramètre AccessMode est ignorée.
OBJ_INHERIT	Le handle peut être hérité par les processus enfants du processus actuel. Cet indicateur est incompatible avec l’indicateur OBJ_EXCLUSIVE.
OBJ_KERNEL_HANDLE	Le handle est accessible uniquement en mode noyau. Cet indicateur doit être spécifié si l’appelant n’est pas en cours d’exécution dans le contexte du processus système.

[in, optional] PassedAccessState

Pointeur vers une structure de ACCESS_STATE contenant le contexte de l’objet de l’objet, les types d’accès accordés et les types d’accès souhaités restants. Ce paramètre est facultatif et peut être NULL. Dans une routine de répartition de création, ce pointeur se trouve dans IrpSp-Parameters.Create.SecurityContext-AccessState>>, où IrpSp est un pointeur vers l’emplacement de pile de l’appelant dans l’IRP. (Pour plus d’informations, consultez IRP_MJ_CREATE.)

[in] DesiredAccess

ACCESS_MASK valeur spécifiant l’accès souhaité à l’objet. Ce paramètre est facultatif et peut être égal à zéro.

[in, optional] ObjectType

Pointeur vers le type d’objet. Si la valeur d’AccessMode est KernelMode, ce paramètre est facultatif et peut être NULL. Sinon, il doit s’agir de *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsThreadType, *SeTokenObjectType ou *CmKeyObjectType.

Notes

Le type d’objet SeTokenObjectType est pris en charge avec Windows XP et le type d’objet CmKeyObjectType est pris en charge avec Windows 7.

[in] AccessMode

Mode d’accès à utiliser pour le case activée d’accès. Ce paramètre est obligatoire et doit être UserMode ou KernelMode :

Si AccessMode est KernelMode, le système autorise toujours l’accès demandé, quel que soit l’accès restreint précédemment défini sur un pilote (par exemple, l’accès restreint lors d’un appel antérieur à POB_PRE_OPERATION_CALLBACK rappel).
Si AccessMode est UserMode, l’accès demandé est comparé à l’accès accordé pour l’objet.

[out] Handle

Pointeur vers une variable allouée par l’appelant qui reçoit un handle vers l’objet.

Valeur retournée

ObOpenObjectByPointer retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, par exemple :

Code de retour	Description
STATUS_ACCESS_DENIED	L’appelant n’avait pas l’accès requis pour ouvrir un handle pour l’objet. Il s’agit d’un code d’erreur.
STATUS_INSUFFICIENT_RESOURCES	ObOpenObjectByPointer a rencontré un échec d’allocation de pool. Il s’agit d’un code d’erreur.
STATUS_INVALID_PARAMETER	Une valeur d’indicateur non valide a été spécifiée dans le paramètre HandleAttributes . Il s’agit d’un code d’erreur.
STATUS_OBJECT_TYPE_MISMATCH	L’objet pointé vers par le paramètre Object n’était pas du type spécifié dans le paramètre ObjectType . Il s’agit d’un code d’erreur.
STATUS_PRIVILEGE_NOT_HELD	L’appelant n’avait pas le privilège requis pour créer un handle avec l’accès spécifié dans le paramètre DesiredAccess . Il s’agit d’un code d’erreur.
STATUS_QUOTA_EXCEEDED	L’appelant s’exécute dans le contexte d’un processus dont le quota de mémoire n’est pas suffisant pour allouer le handle d’objet. Il s’agit d’un code d’erreur.
STATUS_UNSUCCESSFUL	Impossible de créer le handle d’objet. Il s’agit d’un code d’erreur.

Remarques

Si le paramètre Object pointe vers un objet fichier (c’est-à-dire une structure FILE_OBJECT), ObOpenObjectByPointer ne peut être appelé qu’après la création d’au moins un handle pour l’objet fichier. Les appelants peuvent case activée le membre Flags de la structure FILE_OBJECT vers laquelle pointe le paramètre Object. Si l’indicateur FO_HANDLE_CREATED est défini, cela signifie qu’un ou plusieurs handles ont été créés pour l’objet de fichier. Il est donc sûr d’appeler ObOpenObjectByPointer.

Tout handle obtenu en appelant ObOpenObjectByPointer doit finalement être libéré en appelant ZwClose.

Les routines de pilotes qui s’exécutent dans un contexte de processus autre que celui du processus système doivent définir l’indicateur OBJ_KERNEL_HANDLE dans le paramètre HandleAttributes . Cela limite l’utilisation du handle retourné par ObOpenObjectByPointer aux processus s’exécutant en mode noyau. Sinon, le handle est accessible par le processus dans lequel le pilote est en cours d’exécution.