Función ZwQueryInformationToken (ntifs.h)

Artículo
02/26/2024

La rutina ZwQueryInformationToken recupera un tipo especificado de información sobre un token de acceso. El proceso de llamada debe tener los derechos de acceso adecuados para obtener la información.

Sintaxis

NTSYSAPI NTSTATUS ZwQueryInformationToken(
  [in]  HANDLE                  TokenHandle,
  [in]  TOKEN_INFORMATION_CLASS TokenInformationClass,
  [out] PVOID                   TokenInformation,
  [in]  ULONG                   TokenInformationLength,
  [out] PULONG                  ReturnLength
);

Parámetros

[in] TokenHandle

Identificador de un token de acceso desde el que se va a recuperar la información. Si TokenInformationClass está establecido en TokenSource, el identificador debe tener TOKEN_QUERY_SOURCE acceso. Para todos los demás valores de TokenInformationClass , el identificador debe tener TOKEN_QUERY acceso. Para obtener más información sobre los derechos de acceso para objetos de token de acceso, consulte la sección Seguridad de la documentación de Windows SDK.

[in] TokenInformationClass

Valor del TOKEN_INFORMATION_CLASS tipo enumerado que identifica el tipo de información que se va a recuperar. Los valores posibles para este parámetro se muestran en la columna TokenInformationClass Value de la tabla que se muestra en la descripción del parámetro TokenInformation .

[out] TokenInformation

Puntero a un búfer asignado por el autor de la llamada que recibe la información solicitada sobre el token. La estructura que se coloca en este búfer depende del valor de TokenInformationClass, como se muestra en la tabla siguiente. Todas las estructuras deben alinearse en un límite de 32 bits.

Valor de TokenInformationClass	Efecto en el búfer tokenInformation
TokenDefaultDacl	El búfer recibe una estructura de TOKEN_DEFAULT_DACL que contiene la DACL predeterminada para los objetos recién creados.
TokenGroups	El búfer recibe una estructura de TOKEN_GROUPS que contiene las cuentas de grupo asociadas al token.
TokenImpersonationLevel	El búfer recibe un valor de SECURITY_IMPERSONATION_LEVEL que indica el nivel de suplantación del token. Si el token de acceso no es un token de suplantación, se produce un error en la llamada a ZwQueryInformationToken .
TokenOwner	El búfer recibe una estructura de TOKEN_OWNER que contiene el SID de propietario predeterminado para los objetos recién creados.
TokenPrimaryGroup	El búfer recibe una estructura de TOKEN_PRIMARY_GROUP que contiene el SID de grupo principal predeterminado para los objetos recién creados.
TokenPrivileges	El búfer recibe una estructura de TOKEN_PRIVILEGES que contiene los privilegios del token.
TokenSessionId	El búfer recibe un valor de 32 bits que especifica el identificador de sesión de Terminal Services asociado al token. Si el token está asociado a la sesión de consola de Terminal Server, el identificador de sesión es cero. Un identificador de sesión distinto de cero indica una sesión de cliente de Terminal Services. En un entorno que no sea terminal Services, el identificador de sesión es cero.
TokenSource	El búfer recibe una estructura TOKEN_SOURCE que contiene el origen del token. TOKEN_QUERY_SOURCE acceso es necesario para recuperar esta información.
TokenStatistics	El búfer recibe una estructura de TOKEN_STATISTICS que contiene varias estadísticas de token.
TokenType	El búfer recibe un valor de TOKEN_TYPE que indica si el token es un token principal o de suplantación.
TokenUser	El búfer recibe una estructura de TOKEN_USER que contiene la cuenta de usuario del token.

[in] TokenInformationLength

Longitud, en bytes, del búfer TokenInformation asignado por el autor de la llamada.

[out] ReturnLength

Puntero a una variable asignada por el autor de la llamada que recibe la longitud real, en bytes, de la información devuelta en el búfer TokenInformation . Si se cumple alguna de las condiciones siguientes, no se devuelve ningún dato en el búfer TokenInformation :

El tamaño de la estructura de información del token solicitado es mayor que TokenInformationLength. En este caso, ReturnLength recibe el número real de bytes necesarios para almacenar la información solicitada.
El valor de TokenInformationClass es TokenDefaultDacl y no hay ninguna DACL predeterminada establecida para el token. En este caso, ReturnLength recibe cero.

Valor devuelto

ZwQueryInformationToken devuelve STATUS_SUCCESS o un estado de error adecuado. Entre los posibles códigos de estado de error se incluyen los siguientes:

Código devuelto	Descripción
STATUS_ACCESS_DENIED	TokenHandle no tenía el acceso necesario.
STATUS_BUFFER_TOO_SMALL	El tamaño de la estructura de información del token solicitado es mayor que TokenInformationLength. El número de bytes necesarios se devuelve en ReturnLength.
STATUS_INVALID_HANDLE	TokenHandle no era un identificador válido.
STATUS_INVALID_INFO_CLASS	TokenInformationClass no era una clase de información de token válida.
STATUS_OBJECT_TYPE_MISMATCH	TokenHandle no era un identificador de token.

Comentarios

La rutina ZwQueryInformationToken puede ser utilizada por un controlador de filtro del sistema de archivos o del sistema de archivos para determinar el SID del autor de la llamada que inició la solicitud durante IRP_MJ_CREATE procesamiento. Si se especifica TokenUser para el parámetro TokenInformationClass pasado a ZwQueryInformationToken, se devuelve una estructura de TOKEN_USER en el búfer al que apunta el parámetro TokenInformation . Este búfer devuelto contiene una estructura de SID_AND_ATTRIBUTES con el SID de usuario.

Para obtener más información sobre la seguridad y el control de acceso, consulte Modelo de seguridad de Windows para desarrolladores de controladores y la documentación sobre estos temas en Windows SDK.

Nota

Si la llamada a la función ZwQueryInformationToken se produce en modo de usuario, debe usar el nombre "NtQueryInformationToken" en lugar de "ZwQueryInformationToken".

En el caso de las llamadas desde controladores en modo kernel, las versiones NtXxx y ZwXxx de una rutina de Windows Native System Services pueden comportarse de forma diferente en la forma en que controlan e interpretan los parámetros de entrada. Para obtener más información sobre la relación entre las versiones NtXxx y ZwXxx de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP
Plataforma de destino	Universal
Encabezado	ntifs.h (incluya Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)