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 |