Función NtQueryInformationToken (ntifs.h)

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 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 los 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 enumeran 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 NtQueryInformationToken .
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 es de 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.

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

Valor devuelto

NtQueryInformationToken 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_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.

Comentarios

La rutina NtQueryInformationToken puede ser utilizada por un sistema de archivos o un controlador de filtro 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 NtQueryInformationToken, 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.

Debido a la naturaleza de las propiedades del token (como el usuario del token, el grupo principal del token, 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 sea 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 versiones NtXxx y ZwXxx de una rutina de Servicios del sistema nativo de Windows se pueden comportar 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, PowerIrpDDis

Consulte también

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