Función NtQueryInformationToken (ntifs.h)

Artículo
12/22/2024

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

Sintaxis

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryInformationToken(
  [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 acceso TOKEN_QUERY_SOURCE. Para todos los demás valores de TokenInformationClass, el identificador debe tener acceso TOKEN_QUERY. 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 de la TOKEN_INFORMATION_CLASS tipo enumerado que identifica el tipo de información que se va a recuperar. Los valores posibles de este parámetro se muestran en la columna TokenInformationClass Value de la tabla que se muestra en la descripción del parámetro tokenInformation de .

[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 el daCL de predeterminado 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 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 NtQueryInformationToken.
tokenOwner	El búfer recibe una estructura de TOKEN_OWNER que contiene el propietario predeterminado siD 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 de	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 es de Terminal Services, el identificador de sesión es cero.
tokenSource de	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 de	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 Token Information 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 TokenInformation búfer. Si se cumple alguna de las condiciones siguientes, no se devuelve ningún dato en el búfer de tokenInformation de :

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 TokenDefaultDacly no hay ninguna DACL predeterminada establecida para el token. En este caso, ReturnLength recibe cero.

ReturnLength no se puede NULL. Vea Comentarios para obtener más información.

Valor devuelto

NtQueryInformationToken devuelve STATUS_SUCCESS o un estado de error adecuado. Entre los códigos de estado de error posibles 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_ACCESS_VIOLATION	returnLength era NULL o no se puede escribir para recibir la longitud real de la información a la que apunta TokenInformation.
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.

Observaciones

La rutina de NtQueryInformationToken puede ser utilizada por un controlador de filtro de sistema de archivos o sistema de archivos para determinar el siD del autor de la llamada que inició la solicitud durante el procesamiento de IRP_MJ_CREATE. Si se especifica tokenUser para el parámetro TokenInformationClass pasado a NtQueryInformationToken , se devuelve una estructura 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 .

Debido a la naturaleza de las propiedades del token (como el usuario del token, el grupo principal de tokens, los privilegios, etc., donde su contenido puede variar en cada token), returnLength no es opcional; es decir, no puede ser NULL. Esto se debe a que el SID es una estructura de longitud variable, mientras que un privilegio específico puede existir en un token, pero no en otro (el recuento de privilegios puede ser diferente para cada token). Es responsabilidad del autor de la llamada consultar primero el tamaño de longitud necesario necesario para asignar memoria para dar cabida a la información del token solicitada antes de realizar la consulta real. Dicho esto, también es responsabilidad del autor de la llamada proporcionar una variable ReturnLength válida que es grabable y no NULL. En un escenario de caso NULL, la función genera una excepción de infracción de acceso.

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 ntQueryInformationToken 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 NtXxx y Zwversiones de Xxx de una rutina de Servicios del sistema nativo de Windows 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 de NtXxx y ZwXxx de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows XP
de la plataforma de destino de	Universal
encabezado de	ntifs.h (incluya Ntifs.h)
biblioteca de	NtosKrnl.lib
DLL de	NtosKrnl.exe
irQL	PASSIVE_LEVEL
reglas de cumplimiento de DDI	HwStorPortProhibitedDIs, PowerIrpDDis