Função NtQueryInformationToken (ntifs.h)

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 um token de acesso do qual as informações devem ser recuperadas. Se TokenInformationClass estiver definido como TokenSource, o identificador deverá ter TOKEN_QUERY_SOURCE acesso. Para todos os outros valores tokenInformationClass , o identificador deve ter TOKEN_QUERY acesso. 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 por 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 estar 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 não 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 por chamador que recebe o comprimento real, em bytes, das informações retornadas no buffer TokenInformation . Se qualquer 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.

Valor retornado

NtQueryInformationToken retorna STATUS_SUCCESS ou um status de erro apropriado. Os códigos de status de erro possíveis 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 consultar primeiro o tamanho necessário 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 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 do modo kernel, as versões NtXxx e ZwXxx de uma rotina do Windows Native System Services 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 de serviços nativos do sistema.

Requisitos

   
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 de DDI HwStorPortProhibitedDDIs, PowerIrpDDis

Confira também

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