Função NtQueryInformationToken (ntifs.h)

Artigo
02/26/2024

A rotina NtQueryInformationToken recupera um tipo especificado de informações sobre um token de acesso. O processo de chamada deve ter direitos de acesso apropriados para obter as informações.

Sintaxe

__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

Manipule para um token de acesso do qual as informações devem ser recuperadas. Se TokenInformationClass estiver definido como TokenSource, o identificador deverá ter acesso TOKEN_QUERY_SOURCE. Para todos os outros valores TokenInformationClass , o identificador deve ter acesso TOKEN_QUERY. Para obter mais informações sobre direitos de acesso para objetos de token de acesso, consulte a seção Segurança da documentação do SDK do Windows.

[in] TokenInformationClass

Um valor do TOKEN_INFORMATION_CLASS tipo enumerado que identifica o tipo de informação a ser recuperado. Os valores possíveis para esse parâmetro são listados na coluna Valor TokenInformationClass da tabela mostrada na descrição do parâmetro TokenInformation .

[out] TokenInformation

Ponteiro para um buffer alocado pelo chamador que recebe as informações solicitadas sobre o token. A estrutura colocada nesse buffer depende do valor de TokenInformationClass, conforme mostrado na tabela a seguir. Todas as estruturas devem ser alinhadas em um limite de 32 bits.

Valor tokenInformationClass	Efeito no buffer TokenInformation
TokenDefaultDacl	O buffer recebe uma estrutura TOKEN_DEFAULT_DACL que contém a DACL padrão para objetos recém-criados.
TokenGroups	O buffer recebe uma estrutura TOKEN_GROUPS que contém as contas de grupo associadas ao token.
TokenImpersonationLevel	O buffer recebe um valor SECURITY_IMPERSONATION_LEVEL indicando o nível de representação do token. Se o token de acesso não for um token de representação, a chamada para NtQueryInformationToken falhará.
TokenOwner	O buffer recebe uma estrutura TOKEN_OWNER que contém o SID de proprietário padrão para objetos recém-criados.
TokenPrimaryGroup	O buffer recebe uma estrutura TOKEN_PRIMARY_GROUP que contém o SID do grupo primário padrão para objetos recém-criados.
TokenPrivileges	O buffer recebe uma estrutura TOKEN_PRIVILEGES que contém os privilégios do token.
TokenSessionId	O buffer recebe um valor de 32 bits especificando o identificador de sessão dos Serviços de Terminal associado ao token. Se o token estiver associado à sessão de console do Terminal Server, o identificador de sessão será zero. Um identificador de sessão diferente de zero indica uma sessão de cliente dos Serviços de Terminal. Em um ambiente de Serviços não Terminais, o identificador de sessão é zero.
TokenSource	O buffer recebe uma estrutura TOKEN_SOURCE que contém a origem do token. TOKEN_QUERY_SOURCE acesso é necessário para recuperar essas informações.
TokenStatistics	O buffer recebe uma estrutura TOKEN_STATISTICS que contém várias estatísticas de token.
Tokentype	O buffer recebe um valor TOKEN_TYPE indicando se o token é um token primário ou de representação.
TokenUser	O buffer recebe uma estrutura TOKEN_USER que contém a conta de usuário do token.

[in] TokenInformationLength

Comprimento, em bytes, do buffer TokenInformation alocado pelo chamador.

[out] ReturnLength

Ponteiro para uma variável alocada pelo chamador que recebe o comprimento real, em bytes, das informações retornadas no buffer TokenInformation . Se uma das seguintes condições for verdadeira, nenhum dado será retornado no buffer TokenInformation :

O tamanho da estrutura de informações de token solicitada é maior que TokenInformationLength. Nesse caso, ReturnLength recebe o número real de bytes necessários para armazenar as informações solicitadas.
O valor de TokenInformationClass é TokenDefaultDacl e não há nenhum DACL padrão estabelecido para o token. Nesse caso, ReturnLength recebe zero.

ReturnLength não pode ser NULL. Consulte Comentários para obter mais informações.

Retornar valor

NtQueryInformationToken retorna STATUS_SUCCESS ou um erro apropriado status. Os possíveis códigos de status de erro incluem o seguinte:

Código de retorno	Descrição
STATUS_ACCESS_DENIED	TokenHandle não tinha o acesso necessário.
STATUS_BUFFER_TOO_SMALL	O tamanho da estrutura de informações de token solicitada é maior que TokenInformationLength. O número de bytes necessários é retornado em ReturnLength.
STATUS_ACCESS_VIOLATION	ReturnLength era NULL ou não era gravável para receber o comprimento real das informações apontadas por TokenInformation.
STATUS_INVALID_HANDLE	TokenHandle não era um identificador válido.
STATUS_INVALID_INFO_CLASS	TokenInformationClass não era uma classe de informações de token válida.
STATUS_OBJECT_TYPE_MISMATCH	TokenHandle não era um identificador de token.

Comentários

A rotina NtQueryInformationToken pode ser usada por um sistema de arquivos ou driver de filtro do sistema de arquivos para determinar o SID do chamador que iniciou a solicitação durante IRP_MJ_CREATE processamento. Se TokenUser for especificado para o parâmetro TokenInformationClass passado para NtQueryInformationToken, uma estrutura TOKEN_USER será retornada no buffer apontado pelo parâmetro TokenInformation . Esse buffer retornado contém uma estrutura SID_AND_ATTRIBUTES com o SID do usuário.

Devido à natureza das propriedades do token (como usuário de token, grupo primário de token, privilégios etc., em que seu conteúdo pode variar em cada token), ReturnLength não é opcional; ou seja, não pode ser NULL. Isso ocorre porque o SID é uma estrutura de comprimento variável, enquanto um privilégio específico pode existir em um token, mas não em outro (a contagem de privilégios pode ser diferente para cada token). É responsabilidade do chamador primeiro consultar o tamanho de comprimento necessário para alocar memória para acomodar as informações de token solicitadas antes de fazer a consulta real. Dito isso, também é responsabilidade do chamador fornecer uma variável ReturnLength válida que seja gravável e não NULL. Em um cenário de caso NULL, a função gera uma exceção de violação de acesso.

Para obter mais informações sobre segurança e controle de acesso, consulte Modelo de segurança do Windows para desenvolvedores de driver e a documentação sobre esses tópicos no SDK do Windows.

Observação

Se a chamada para a função NtQueryInformationToken ocorrer no modo de usuário, você deverá usar o nome "NtQueryInformationToken" em vez de "ZwQueryInformationToken".

Para chamadas de drivers no modo kernel, as versões NtXxx e ZwXxx de uma rotina dos Serviços do Sistema Nativo do Windows podem se comportar de forma diferente na maneira como lidam e interpretam parâmetros de entrada. Para obter mais informações sobre a relação entre as versões NtXxx e ZwXxx de uma rotina, consulte Usando versões Nt e Zw das rotinas dos Serviços de Sistema Nativo.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP
Plataforma de Destino	Universal
Cabeçalho	ntifs.h (inclua Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regras de conformidade da DDI	HwStorPortProhibitedDDIs, PowerIrpDDis