Fonction NtQueryInformationToken (ntifs.h)

La routine NtQueryInformationToken récupère un type d’informations spécifié sur un jeton d’accès. Le processus appelant doit disposer de droits d’accès appropriés pour obtenir les informations.

Syntaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryInformationToken(
  [in]  HANDLE                  TokenHandle,
  [in]  TOKEN_INFORMATION_CLASS TokenInformationClass,
  [out] PVOID                   TokenInformation,
  [in]  ULONG                   TokenInformationLength,
  [out] PULONG                  ReturnLength
);

Paramètres

[in] TokenHandle

Gérez un jeton d’accès à partir duquel les informations doivent être récupérées. Si TokenInformationClass est défini sur TokenSource, le handle doit avoir un accès TOKEN_QUERY_SOURCE. Pour toutes les autres valeurs TokenInformationClass , le handle doit avoir un accès TOKEN_QUERY. Pour plus d’informations sur les droits d’accès pour les objets de jeton d’accès, consultez la section Sécurité de la documentation du Kit de développement logiciel (SDK) Windows.

[in] TokenInformationClass

Valeur du type énuméré TOKEN_INFORMATION_CLASS identifiant le type d’informations à récupérer. Les valeurs possibles pour ce paramètre sont répertoriées dans la colonne TokenInformationClass Value de la table indiquée dans la description du paramètre TokenInformation .

[out] TokenInformation

Pointeur vers une mémoire tampon allouée par l’appelant qui reçoit les informations demandées sur le jeton. La structure placée dans cette mémoire tampon dépend de la valeur de TokenInformationClass, comme indiqué dans le tableau suivant. Toutes les structures doivent être alignées sur une limite 32 bits.

Valeur TokenInformationClass Effet sur la mémoire tampon TokenInformation
TokenDefaultDacl La mémoire tampon reçoit une structure TOKEN_DEFAULT_DACL contenant la liste de contrôle d’accès par défaut pour les objets nouvellement créés.
TokenGroups La mémoire tampon reçoit une structure TOKEN_GROUPS contenant les comptes de groupe associés au jeton.
TokenImpersonationLevel La mémoire tampon reçoit une valeur SECURITY_IMPERSONATION_LEVEL indiquant le niveau d’emprunt d’identité du jeton. Si le jeton d’accès n’est pas un jeton d’emprunt d’identité, l’appel à NtQueryInformationToken échoue.
TokenOwner La mémoire tampon reçoit une structure TOKEN_OWNER contenant le SID de propriétaire par défaut pour les objets nouvellement créés.
TokenPrimaryGroup La mémoire tampon reçoit une structure TOKEN_PRIMARY_GROUP contenant le SID de groupe principal par défaut pour les objets nouvellement créés.
TokenPrivileges La mémoire tampon reçoit une structure TOKEN_PRIVILEGES contenant les privilèges du jeton.
TokenSessionId La mémoire tampon reçoit une valeur 32 bits spécifiant l’identificateur de session Terminal Services associé au jeton. Si le jeton est associé à la session de console Terminal Server, l’identificateur de session est égal à zéro. Un identificateur de session non zéro indique une session cliente Terminal Services. Dans un environnement non Terminal Services, l’identificateur de session est égal à zéro.
TokenSource La mémoire tampon reçoit une structure TOKEN_SOURCE contenant la source du jeton. TOKEN_QUERY_SOURCE l’accès est nécessaire pour récupérer ces informations.
TokenStatistics La mémoire tampon reçoit une structure TOKEN_STATISTICS contenant diverses statistiques de jeton.
TokenType La mémoire tampon reçoit une valeur TOKEN_TYPE indiquant si le jeton est un jeton principal ou emprunt d’identité.
TokenUser La mémoire tampon reçoit une structure TOKEN_USER contenant le compte d’utilisateur du jeton.

[in] TokenInformationLength

Longueur, en octets, de la mémoire tampon TokenInformation allouée à l’appelant.

[out] ReturnLength

Pointeur vers une variable allouée par l’appelant qui reçoit la longueur réelle, en octets, des informations retournées dans la mémoire tampon TokenInformation . Si l’une des conditions suivantes est vraie, aucune donnée n’est retournée dans la mémoire tampon TokenInformation :

  • La taille de la structure d’informations de jeton demandée est supérieure à TokenInformationLength. Dans ce cas, ReturnLength reçoit le nombre réel d’octets nécessaires pour stocker les informations demandées.

  • La valeur de TokenInformationClass est TokenDefaultDacl et il n’y a pas de daCL par défaut établi pour le jeton. Dans ce cas, ReturnLength reçoit zéro.

ReturnLength ne peut pas être NULL. Pour plus d’informations, consultez les remarques.

Valeur retournée

NtQueryInformationToken retourne STATUS_SUCCESS ou un état d’erreur approprié. Les codes d’état d’erreur possibles sont les suivants :

Code de retour Description
STATUS_ACCESS_DENIED TokenHandle n’a pas eu l’accès requis.
STATUS_BUFFER_TOO_SMALL La taille de la structure d’informations de jeton demandée est supérieure à TokenInformationLength. Le nombre d’octets requis est retourné dans ReturnLength.
STATUS_ACCESS_VIOLATION ReturnLength a été NULL ou n’a pas été accessible en écriture pour recevoir la longueur réelle des informations pointées par TokenInformation.
STATUS_INVALID_HANDLE TokenHandle n’était pas un handle valide.
STATUS_INVALID_INFO_CLASS TokenInformationClass n’était pas une classe d’informations de jeton valide.
STATUS_OBJECT_TYPE_MISMATCH TokenHandle n’était pas un handle de jeton.

Remarques

La routine NtQueryInformationToken peut être utilisée par un pilote de filtre de système de fichiers ou de système de fichiers pour déterminer le SID de l’appelant qui a lancé la requête pendant IRP_MJ_CREATE traitement. Si TokenUser est spécifié pour le paramètre TokenInformationClass passé à NtQueryInformationToken, une structure TOKEN_USER est retournée dans la mémoire tampon pointée par le paramètre TokenInformation . Cette mémoire tampon retournée contient une structure SID_AND_ATTRIBUTES avec le SID utilisateur.

En raison de la nature des propriétés du jeton (par exemple, l’utilisateur de jeton, le groupe principal de jeton, les privilèges, etc., où leur contenu peut varier sur chaque jeton), ReturnLength n’est pas facultatif ; autrement dit, il ne peut pas être NULL. Cela est dû au fait que SID est une structure de longueur variable, tandis qu’un privilège spécifique peut exister dans un jeton, mais pas dans un autre (le nombre de privilèges peut être différent pour chaque jeton). Il incombe à l’appelant d’interroger d’abord la taille de longueur requise nécessaire pour allouer de la mémoire pour prendre en charge les informations de jeton demandées avant d’effectuer la requête réelle. Cela dit, il est également à la responsabilité de l’appelant de fournir une variable ReturnLength valide qui est accessible en écriture et non NULL. Dans un scénario de cas NULL, la fonction déclenche une exception de violation d’accès.

Pour plus d’informations sur la sécurité et le contrôle d’accès, consultez la documentation sur ces rubriques dans le Kit de développement logiciel (SDK) Windows.

Notes

Si l’appel à la fonction NtQueryInformationToken se produit en mode utilisateur, vous devez utiliser le nom « NtQueryInformationToken » au lieu de « ZwQueryInformationToken ».

Pour les appels à partir de pilotes en mode noyau, les versions NtXxx et ZwXxx d’une routine Windows Native System Services peuvent se comporter différemment de la façon dont elles gèrent et interprètent les paramètres d’entrée. Pour plus d’informations sur la relation entre les versions NtXxx et ZwXxx d’une routine, consultez Using Nt and Zw Versions of the Native System Services Routines.

Spécifications

   
Client minimal pris en charge Windows XP
Plateforme cible Universal
En-tête ntifs.h (include Ntifs.h)
Bibliothèque NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
Règles de conformité DDI HwStorPortProhibitedDDIs, PowerIrpDDis

Voir aussi

ACL

IRP_MJ_CREATE

SECURITY_IMPERSONATION_LEVEL

SID

SID_AND_ATTRIBUTES

SeQueryInformationToken

TOKEN_DEFAULT_DACL

TOKEN_GROUPS

TOKEN_INFORMATION_CLASS

TOKEN_OWNER

TOKEN_PRIMARY_GROUP

TOKEN_PRIVILEGES

TOKEN_SOURCE

TOKEN_STATISTICS

TOKEN_TYPE

TOKEN_USER

ZwSetInformationToken