Fonction ZwQueryInformationToken (ntifs.h)

Article
03/08/2023

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

Syntaxe

NTSYSAPI NTSTATUS ZwQueryInformationToken(
  [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 TOKEN_QUERY_SOURCE accès. Pour toutes les autres valeurs TokenInformationClass , le handle doit avoir TOKEN_QUERY accès. 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 TOKEN_INFORMATION_CLASS type énuméré identifiant le type d’informations à récupérer. Les valeurs possibles pour ce paramètre sont répertoriées dans la colonne Valeur TokenInformationClass de la table indiquée dans la description du paramètre TokenInformation .

[out] TokenInformation

Pointeur vers une mémoire tampon allouée à 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 à ZwQueryInformationToken échoue.
TokenOwner	La mémoire tampon reçoit une structure TOKEN_OWNER contenant le SID 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 des services Terminal Server 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 différent de zéro indique une session cliente des services Terminal Server. 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 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 un jeton d’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 aucun DACL par défaut n’est établi pour le jeton. Dans ce cas, ReturnLength reçoit zéro.

Valeur retournée

ZwQueryInformationToken retourne STATUS_SUCCESS ou une status d’erreur appropriée. Les codes de status d’erreur possibles incluent les éléments suivants :

Code de retour	Description
STATUS_ACCESS_DENIED	TokenHandle n’avait pas 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_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 ZwQueryInformationToken peut être utilisée par un système de fichiers ou un pilote de filtre de système de fichiers pour déterminer le SID de l’appelant qui a lancé la demande pendant IRP_MJ_CREATE traitement. Si TokenUser est spécifié pour le paramètre TokenInformationClass passé à ZwQueryInformationToken, une structure TOKEN_USER est retournée dans la mémoire tampon vers laquelle pointe le paramètre TokenInformation . Cette mémoire tampon retournée contient une structure SID_AND_ATTRIBUTES avec le SID utilisateur.

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

Notes

Si l’appel à la fonction ZwQueryInformationToken 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 dans 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 Utilisation des versions Nt et Zw des routines des services système natifs.

Configuration requise

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