OBJECT_ATTRIBUTES structure (ntdef.h)

Article
02/29/2024

La structure OBJECT_ATTRIBUTES spécifie les attributs qui peuvent être appliqués à des objets ou des handles d’objet par des routines qui créent des objets et/ou retournent des handles à des objets.

Syntaxe

typedef struct _OBJECT_ATTRIBUTES {
  ULONG           Length;
  HANDLE          RootDirectory;
  PUNICODE_STRING ObjectName;
  ULONG           Attributes;
  PVOID           SecurityDescriptor;
  PVOID           SecurityQualityOfService;
} OBJECT_ATTRIBUTES;

Membres

Length

Nombre d’octets de données contenues dans cette structure. La macro InitializeObjectAttributes définit ce membre sur sizeof(OBJECT_ATTRIBUTES).

RootDirectory

Handle facultatif dans le répertoire de l’objet racine pour le nom de chemin spécifié par le membre ObjectName . Si RootDirectory a la valeur NULL, ObjectName doit pointer vers un nom d’objet complet qui inclut le chemin d’accès complet à l’objet cible. Si RootDirectory n’est pas,NULLObjectName spécifie un nom d’objet relatif au répertoire RootDirectory . Le handle RootDirectory peut faire référence à un répertoire de système de fichiers ou à un répertoire d’objets dans l’espace de noms du gestionnaire d’objets.

ObjectName

Pointeur vers une chaîne Unicode qui contient le nom de l’objet pour lequel un handle doit être ouvert. Il doit s’agir d’un nom d’objet complet ou d’un nom de chemin d’accès relatif au répertoire spécifié par le membre RootDirectory .

Attributes

Masque de bits d’indicateurs qui spécifient des attributs de handle d’objet. Ce membre peut contenir un ou plusieurs des indicateurs du tableau suivant.

Indicateur	Signification
OBJ_INHERIT	Ce handle peut être hérité par les processus enfants du processus actuel.
OBJ_PERMANENT	Cet indicateur s’applique uniquement aux objets nommés dans le gestionnaire d’objets. Par défaut, ces objets sont supprimés lorsque tous les handles ouverts sont fermés. Si cet indicateur est spécifié, l’objet n’est pas supprimé lorsque tous les descripteurs ouverts sont fermés. Les pilotes peuvent utiliser la routine ZwMakeTemporaryObject pour rendre un objet permanent non permanent.
OBJ_EXCLUSIVE	Si cet indicateur est défini et que la structure OBJECT_ATTRIBUTES est passée à une routine qui crée un objet, l’objet est accessible exclusivement. Autrement dit, une fois qu’un processus ouvre un tel handle à l’objet, aucun autre processus ne peut ouvrir de handles à cet objet. Si cet indicateur est défini et que la structure OBJECT_ATTRIBUTES est passée à une routine qui crée un handle d’objet, l’appelant demande un accès exclusif à l’objet pour le contexte de processus dans lequel le handle a été créé. Cette demande ne peut être accordée que si l’indicateur OBJ_EXCLUSIVE a été défini lors de la création de l’objet.
OBJ_CASE_INSENSITIVE	Si cet indicateur est spécifié, une comparaison qui ne respecte pas la casse est utilisée lors de la correspondance entre le nom pointé par le membre ObjectName et les noms d’objets existants. Sinon, les noms d’objets sont comparés à l’aide des paramètres système par défaut.
OBJ_OPENIF	Si cet indicateur est spécifié, à l’aide du handle d’objet, à une routine qui crée des objets et si cet objet existe déjà, la routine doit ouvrir cet objet. Sinon, la routine qui crée l’objet retourne un code NTSTATUS de STATUS_OBJECT_NAME_COLLISION.
OBJ_OPENLINK	Si un handle d’objet, avec cet indicateur défini, est passé à une routine qui ouvre des objets et si l’objet est un objet de lien symbolique, la routine doit ouvrir l’objet de lien symbolique lui-même, plutôt que l’objet auquel le lien symbolique fait référence (qui est le comportement par défaut).
OBJ_KERNEL_HANDLE	Le handle est créé dans le contexte de processus système et est accessible uniquement à partir du mode noyau.
OBJ_FORCE_ACCESS_CHECK	La routine qui ouvre le handle doit appliquer toutes les vérifications d’accès pour l’objet, même si le handle est ouvert en mode noyau.
OBJ_DONT_REPARSE	Si cet indicateur est défini, aucun point d’analyse n’est suivi lors de l’analyse du nom de l’objet associé. Si des réparations sont rencontrées, la tentative échoue et retourne un résultat STATUS_REPARSE_POINT_ENCOUNTERED . Cela peut être utilisé pour déterminer s’il existe des points d’analyse dans le chemin d’accès de l’objet, dans les scénarios de sécurité.
OBJ_IGNORE_IMPERSONATED_DEVICEMAP	Un mappage d’appareils est un mappage entre les noms d’appareils DOS et les appareils dans le système, et est utilisé lors de la résolution des noms DOS. Des mappages d’appareils distincts existent pour chaque utilisateur dans le système, et les utilisateurs peuvent gérer leurs propres mappages d’appareils. En règle générale, pendant l’emprunt d’identité, la carte d’appareil de l’utilisateur emprunté est utilisée. Toutefois, lorsque cet indicateur est défini, le mappage des appareils de l’utilisateur du processus est utilisé à la place.
OBJ_VALID_ATTRIBUTES	Réservé.

SecurityDescriptor

Spécifie un descripteur de sécurité (SECURITY_DESCRIPTOR) pour l’objet lors de sa création. Si SecurityDescriptor a la valeur NULL, l’objet reçoit les paramètres de sécurité par défaut. Consultez DACL pour un nouvel objet.

SecurityQualityOfService

Qualité de service facultative à appliquer à l’objet lors de sa création. Utilisé pour indiquer le niveau d’emprunt d’identité de sécurité et le mode de suivi du contexte (dynamique ou statique). Actuellement, la macro InitializeObjectAttributes définit ce membre sur NULL.

Remarques

Utilisez la macro InitializeObjectAttributes pour initialiser les membres de la structure OBJECT_ATTRIBUTES . Notez que InitializeObjectAttributes initialise le membre SecurityQualityOfService sur NULL. Si vous devez spécifier une valeur non-NULL , définissez le membre SecurityQualityOfService après l’initialisation.

Pour appliquer les attributs contenus dans cette structure à un objet ou un handle d’objet, passez un pointeur vers cette structure vers une routine qui accède aux objets ou retourne des handles d’objet, comme ZwCreateFile ou ZwCreateDirectoryObject.

Tous les membres de cette structure sont en lecture seule. Si un membre de cette structure est un pointeur, l’objet vers lequel ce membre pointe est également en lecture seule. Les membres et objets en lecture seule peuvent être utilisés pour acquérir des informations pertinentes, mais ne doivent pas être modifiés. Pour définir les membres de cette structure, utilisez la macro InitializeObjectAttributes .

Les routines de pilote qui s’exécutent dans un contexte de processus autre que celui du processus système doivent définir l’indicateur OBJ_KERNEL_HANDLE pour le membre Attributes (à l’aide de la macro InitializeObjectAttributes ). Cela limite l’utilisation d’un handle ouvert pour cet objet aux processus exécutés uniquement en mode noyau. Sinon, le handle est accessible par le processus dans le contexte dans lequel le pilote est en cours d’exécution.